> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Database IAM login

> Log Tracecat in to PostgreSQL and Redis with AWS IAM or Microsoft Entra ID tokens instead of a stored password.

With `TRACECAT__DB_AUTH_MODE` set to `aws_iam` or `azure_entra`, each Tracecat service signs a short-lived token with its cloud identity and sends it as the database password. Every new connection gets a valid token, so no service holds a database password. The default, `password`, keeps the existing password login. [Redis](#redis) has the same modes in `REDIS_AUTH_MODE`.

## Settings

A token mode connects with these variables and refuses to start if `TRACECAT__DB_PASS`, `TRACECAT__DB_PASS__ARN` or `TRACECAT__DB_URI` is set:

| Variable | Value |
| - | - |
| `TRACECAT__DB_AUTH_MODE` | `aws_iam` or `azure_entra` |
| `TRACECAT__DB_USER` | The database user, such as `app` |
| `TRACECAT__DB_ENDPOINT` | The host Tracecat connects to: the database, or PgDog |
| `TRACECAT__DB_PORT` | Its port, such as `5432` (or `6432` for PgDog) |
| `TRACECAT__DB_NAME` | The database name, such as `tracecat` |
| `TRACECAT__DB_SSLMODE` | `require`, `verify-ca` or `verify-full` |

`require` encrypts the connection without checking the server's certificate, and `verify-ca` checks the certificate's CA but not the host name, so any certificate from that CA passes. Only `verify-full` checks that the server is the host you named. For a direct connection to the database, use `verify-full` and point `PGSSLROOTCERT` at the CA bundle, such as the [RDS global bundle](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem) or `/etc/ssl/certs/ca-certificates.crt` for Azure.

`aws_iam` also reads `TRACECAT__DB_AWS_REGION` (default `AWS_REGION`) and `TRACECAT__DB_AWS_IAM_HOST` / `TRACECAT__DB_AWS_IAM_PORT`, the RDS endpoint the token is signed for (default `TRACECAT__DB_ENDPOINT` / `TRACECAT__DB_PORT`). `azure_entra` reads `TRACECAT__DB_AZURE_CLIENT_ID`, the managed identity's client ID (default `AZURE_CLIENT_ID`).

## Amazon RDS

**1. Turn on IAM database authentication**

```bash theme={null}
aws rds modify-db-instance --db-instance-identifier <instance-id> \
  --enable-iam-database-authentication --apply-immediately
```

**2. Create the database user**

As the master user, create the login and grant it `rds_iam`:

```sql theme={null}
CREATE ROLE app LOGIN;
GRANT rds_iam TO app;
```

`rds_iam` turns off a role's password login, so never grant it to the master user. With [database roles](https://docs.tracecat.com/self-hosting/database-roles.md), `tracecat db roles upgrade --login aws_iam` creates `app`, `migrator` and `agent_runtime` and grants them `rds_iam` for you.

**3. Allow each service's IAM role to connect**

Look up the instance's resource ID, which looks like `db-ABCDEFGHIJKLMNOPQRSTUVWXYZ`:

```bash theme={null}
aws rds describe-db-instances --db-instance-identifier <instance-id> \
  --query 'DBInstances[0].DbiResourceId' --output text
```

Attach this statement to every IAM role a Tracecat service runs as (IRSA or Pod Identity on EKS, the task role on ECS). The resource is the `rds-db` user ARN, not the instance ARN:

```json theme={null}
{
  "Effect": "Allow",
  "Action": "rds-db:connect",
  "Resource": "arn:aws:rds-db:<region>:<account-id>:dbuser:<DbiResourceId>/app"
}
```

With [database roles](https://docs.tracecat.com/self-hosting/database-roles.md), give the migrations Job's role the same statement for `/migrator` instead of `/app`. Never use `dbuser:<DbiResourceId>/*` or share one policy between the two roles.

Every pod or task on the `app` role can then log in as `app`, including executors that run workflow actions. Never grant it to the node's instance role: every pod on the node could then log in as `app`. On EKS, set `AWS_EC2_METADATA_DISABLED=true` on Tracecat's pods so a pod without its own identity fails instead of signing with the node role (the Helm chart sets it).

**4. Configure Tracecat**

Download the RDS CA bundle and mount it into every Tracecat container, here at `/etc/tracecat/rds-global-bundle.pem` (a Kubernetes ConfigMap or Secret volume, or an ECS bind mount):

```bash theme={null}
curl -fsSLo rds-global-bundle.pem https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
```

```bash theme={null}
TRACECAT__DB_AUTH_MODE=aws_iam
TRACECAT__DB_USER=app
TRACECAT__DB_ENDPOINT=<instance-id>.<hash>.<region>.rds.amazonaws.com
TRACECAT__DB_PORT=5432
TRACECAT__DB_NAME=tracecat
TRACECAT__DB_SSLMODE=verify-full
PGSSLROOTCERT=/etc/tracecat/rds-global-bundle.pem
TRACECAT__DB_AWS_REGION=<region>
```

Tracecat signs each token locally with the service's AWS credentials and reuses it for 10 minutes of its 15-minute life. RDS checks the token only at login, so open connections outlive it.

## Azure Database for PostgreSQL

**1. Turn on Microsoft Entra authentication**

On the flexible server, enable Microsoft Entra authentication and set an Entra administrator. On AKS, turn on the cluster's OIDC issuer and Workload Identity:

```bash theme={null}
az aks update --name <cluster-name> --resource-group <resource-group> \
  --enable-oidc-issuer --enable-workload-identity
```

**2. Create a managed identity for Tracecat**

Create a user-assigned managed identity for `app` and federate it with each Kubernetes service account that Tracecat's services run as (Workload Identity), never the migrations Job's. With the Helm chart, [list them from the render](#azure-workload-identity). Give the `app` identity no Azure role beyond its database and cache logins: the API, MCP server, tool gateway and the executors that run workflow code all hold it. With [database roles](https://docs.tracecat.com/self-hosting/database-roles.md), create two more the same way: one for `migrator`, federated with the migrations Job's service account, and one for `agent_runtime`, with no federated credential. Give no one rights to use, assign or federate the `agent_runtime` identity. Run this once per identity and service account, with a credential name unique to each:

```bash theme={null}
az identity federated-credential create --name <service-account> \
  --identity-name <identity-name> --resource-group <resource-group> \
  --issuer <aks-oidc-issuer-url> \
  --subject system:serviceaccount:<namespace>:<service-account>
```

Note each identity's client ID and object ID; the next steps use both:

```bash theme={null}
az identity show --name <identity-name> --resource-group <resource-group> \
  --query '{clientId: clientId, objectId: principalId}'
```

Label the pods `azure.workload.identity/use: "true"` and give them the client ID, in `TRACECAT__DB_AZURE_CLIENT_ID` or the service account annotation `azure.workload.identity/client-id`. Never assign the identity to the node pool: every pod on the node could then log in as `app`. Set `AZURE_TOKEN_CREDENTIALS=WorkloadIdentityCredential` so a pod without its projected token fails instead of using the node's managed identity (the Helm chart sets it).

**3. Create the database users**

As the Entra administrator, connected to the `postgres` database, map each database role to the object ID of the identity that logs in as it. Without database roles, create `app` only:

```sql theme={null}
SELECT * FROM pgaadauth_create_principal_with_oid('app', '<app-object-id>', 'service', false, false);
```

With [database roles](https://docs.tracecat.com/self-hosting/database-roles.md) (`tracecat db roles upgrade --login azure_entra`), create all three login roles instead; role setup then grants their privileges. `migrator` maps to the migrations Job's identity and `app` to the services' identity. The agent runtime logs in as `app` too. Role setup needs `agent_runtime` to exist, but nothing logs in as it yet, so map it to its own identity that no workload uses:

```sql theme={null}
SELECT * FROM pgaadauth_create_principal_with_oid('migrator', '<migrations-object-id>', 'service', false, false);
SELECT * FROM pgaadauth_create_principal_with_oid('app', '<app-object-id>', 'service', false, false);
SELECT * FROM pgaadauth_create_principal_with_oid('agent_runtime', '<runtime-object-id>', 'service', false, false);
```

Tracecat 1.5.0-alpha.3 and earlier refuse the membership these calls give the Entra administrator in each role. On those versions, run `REVOKE app, migrator, agent_runtime FROM "<entra-admin>";` before role setup.

**4. Allow Tracecat's extensions**

Azure only creates extensions that the server's `azure.extensions` parameter lists, and migrations need `vector` and `pg_trgm`. Setting the parameter replaces the whole list, so read it first:

```bash theme={null}
az postgres flexible-server parameter show --resource-group <resource-group> \
  --server-name <server-name> --name azure.extensions --query value --output tsv
```

Then set it to `VECTOR,PG_TRGM` plus every extension that printed, comma-separated:

```bash theme={null}
az postgres flexible-server parameter set --resource-group <resource-group> \
  --server-name <server-name> --name azure.extensions --value VECTOR,PG_TRGM,<existing-extensions>
```

With an empty list, use `--value VECTOR,PG_TRGM`.

Then, as the Entra administrator, connected to the Tracecat database, create them (see [pgvector](https://docs.tracecat.com/self-hosting/pgvector.md) for the version Tracecat needs):

```sql theme={null}
CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA public;
CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public;
```

**5. Configure Tracecat**

```bash theme={null}
TRACECAT__DB_AUTH_MODE=azure_entra
TRACECAT__DB_USER=app
TRACECAT__DB_ENDPOINT=<server-name>.postgres.database.azure.com
TRACECAT__DB_PORT=5432
TRACECAT__DB_NAME=tracecat
TRACECAT__DB_SSLMODE=verify-full
PGSSLROOTCERT=/etc/ssl/certs/ca-certificates.crt
TRACECAT__DB_AZURE_CLIENT_ID=<app-client-id>
AZURE_TOKEN_CREDENTIALS=WorkloadIdentityCredential
```

Tracecat gets tokens from `DefaultAzureCredential`, which caches each token and renews it before it expires.

If `app`, `migrator` or `agent_runtime` had a password before, clear it as the admin once the token login works, since Azure keeps password login on for these roles. Then unset `TRACECAT__DB_APP_PASSWORD`, `TRACECAT__DB_MIGRATOR_PASSWORD` and `TRACECAT__DB_AGENT_RUNTIME_PASSWORD` and delete them wherever you store them. Without database roles, run only the `app` statement:

```sql theme={null}
ALTER ROLE app PASSWORD NULL;
ALTER ROLE migrator PASSWORD NULL;
ALTER ROLE agent_runtime PASSWORD NULL;
```

## Kubernetes with PgDog

The Helm chart's `externalPostgres.auth.mode` takes `awsIam` or `azureWorkloadIdentity`. Every Tracecat workload, the agent runtime included, then logs in to PgDog with a token, which PgDog passes through to the database. PgDog's user takes `auth_type = "external_token"`: PgDog checks each new token once by logging in to the database with it, as `pgdog.serverUser`, so `serverUser` must be the workloads' username. The token modes need [database roles](https://docs.tracecat.com/self-hosting/database-roles.md): the migrations Job logs in directly, as `migrator` with a token of its own (see [Migrations](#migrations)), and no workload needs `externalPostgres.auth.existingSecret`. Once the token login works, delete that Secret from the cluster and rotate the admin's password, and keep the admin login with whoever manages the database. Delete any old `externalPostgres.auth.appSecret` and `migrations.migrator.passwordSecret` Secrets too, along with whatever provisions them. On Azure, also [clear the roles' old passwords](#azure-database-for-postgresql).

Both modes need:

* PgDog v0.1.65 or newer, which has the token-cache fix (pgdog#1989). Set `pgdog.image.tag` if your chart's default is older.
* `externalPostgres.sslMode: require`, and `externalPostgres.tls.verifyCA` with the database's CA in `caCert`. PgDog verifies the database with that CA; the chart rejects `verify-ca` and `verify-full` with PgDog.
* `agentRuntime.durable.database.dsnSecret` left empty, so the agent runtime logs in as the workloads do.
* An agent runtime image (`agentRuntime.image.tag`) with token login. Check with the Tracecat team that your chart's default includes it.

The agent runtime's executor signs the runtime's tokens and hands each runtime the current one, so code running in a runtime's sandbox could use that token to log in to the database directly as `app` until it expires.

Clients reach PgDog over TLS that doesn't verify PgDog's certificate. A token taken from that hop logs in to the database until it expires (15 minutes for an RDS token, up to about 24 hours for an Entra ID token), and through PgDog for up to 15 minutes longer: PgDog accepts a token for 15 minutes after each check with the database, then checks it again. Limit who can reach PgDog's port with a Kubernetes NetworkPolicy that admits only Tracecat's pods.

### RDS IAM

The chart signs the tokens for `externalPostgres.host`, so set it to the RDS endpoint.

```yaml theme={null}
externalPostgres:
  host: <instance-id>.<hash>.<region>.rds.amazonaws.com
  sslMode: require
  auth:
    mode: awsIam
    awsIam:
      username: app
  tls:
    verifyCA: true
    caCert: |
      ...RDS CA bundle...

pgdog:
  enabled: true
  serverAuth: rds_iam
  serverUser: app
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::<account-id>:role/tracecat-pgdog

migrations:
  migrator:
    enabled: true
    login: aws_iam
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::<account-id>:role/tracecat-migrator
```

### Azure Workload Identity

Azure maps each Entra identity to one Postgres role, and PgDog checks the workloads' tokens as `serverUser`. So the workloads and PgDog share the one identity mapped to `app`, with a federated credential for each service account. The migrations Job uses `migrator`'s own identity.

```yaml theme={null}
externalPostgres:
  host: <server-name>.postgres.database.azure.com
  sslMode: require
  auth:
    mode: azureWorkloadIdentity
    azureWorkloadIdentity:
      username: app
      clientId: <app-client-id>
  tls:
    verifyCA: true
    caCert: |
      ...DigiCert Global Root G2 and Microsoft RSA Root Certificate Authority 2017...

pgdog:
  enabled: true
  serverAuth: azure_workload_identity
  serverUser: app

migrations:
  migrator:
    enabled: true
    login: azure_entra
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: <migrator-client-id>
```

The chart labels every pod that logs in this way with `azure.workload.identity/use: "true"` and passes `clientId` to the workloads and PgDog in the environment, so their service accounts need no annotation. Get `caCert` from Microsoft's [TLS certificates for Azure Database for PostgreSQL](https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-networking-ssl-tls).

List the service accounts of the pods the chart labels, with the same chart reference, version and values you install with:

```bash theme={null}
helm template <release> oci://<ecr-registry-url>/tracecat --version <chart-version> \
  --namespace <namespace> -f values.yaml \
  | yq -N 'select(.spec.template.metadata.labels."azure.workload.identity/use" == "true")
      | .spec.template.spec.serviceAccountName' \
  | sort -u
```

With the release name `tracecat`, that prints names such as `tracecat-api`, `tracecat-app`, `tracecat-migrations` and `tracecat-pgdog`. Federate the `migrator` identity with the one that ends in `-migrations`, which `migrations.serviceAccount.annotations` annotates, and the `app` identity with each of the others.

## Migrations

Without database roles, the migrations Job logs in with `externalPostgres.auth.existingSecret`. With them, it logs in as `migrator` (`migrations.migrator`, with `login: aws_iam` or `login: azure_entra` for a token of its own) and never as the admin; see [Database roles](https://docs.tracecat.com/self-hosting/database-roles.md). The token modes need `migrations.migrator`. The `tracecat-admin migrate` commands take a password URI only.

## Redis

With `REDIS_AUTH_MODE` set to `aws_iam` or `azure_entra`, Tracecat logs in to Redis with a token from its cloud identity and renews it before it expires. Tracecat then needs a `rediss://` URL with no username or password.

### Azure Managed Redis

**1. Create the cache**

Create the cache with TLS on (`Encrypted`). Entra authentication works over TLS only, and Microsoft turns it on by default. Tracecat's Redis client needs the `EnterpriseCluster` clustering policy. A new cache can start with access keys off:

```bash theme={null}
az redisenterprise create --cluster-name <cache-name> \
  --resource-group <resource-group> --location <region> --sku <sku> \
  --client-protocol Encrypted --clustering-policy EnterpriseCluster \
  --access-keys-auth Disabled --port 10000
```

`<sku>` is a size such as `Balanced_B1`. On an existing cache, keep access keys on until every client logs in with Entra ID, then turn them off on its `default` database: turning them off closes every open connection.

**2. Allow the app identity**

Assign the default access policy to the object ID of the identity mapped to `app` (see [Azure Database for PostgreSQL](#azure-database-for-postgresql)):

```bash theme={null}
az redisenterprise database access-policy-assignment create \
  --cluster-name <cache-name> --resource-group <resource-group> \
  --database-name default --access-policy-assignment-name tracecatApp \
  --access-policy-name default --object-id <app-object-id>
```

**3. Configure Tracecat**

```bash theme={null}
REDIS_AUTH_MODE=azure_entra
REDIS_URL=rediss://<cache-name>.<region>.redis.azure.net:10000
REDIS_AZURE_CLIENT_ID=<app-client-id>
AZURE_TOKEN_CREDENTIALS=WorkloadIdentityCredential
```

With the Helm chart, list the components that log in this way. Components you don't list keep `externalRedis.auth.existingSecret`'s URL; once you list every component, remove it from your values and delete the Secret. `clientId` defaults to `externalPostgres.auth.azureWorkloadIdentity.clientId`:

```yaml theme={null}
externalRedis:
  auth:
    azureWorkloadIdentity:
      components: [api, worker, backgroundWorker, agentWorker, mcp, executor, agentExecutor, runtimeWorker, runtimeExecutor, toolGateway]
      host: <cache-name>.<region>.redis.azure.net
      port: 10000
```

On Azure Cache for Redis, turn on Microsoft Entra authentication and add a data access policy assignment for the same object ID, then turn off access keys once every client logs in with Entra ID. Its host is `<cache-name>.redis.cache.windows.net` and its TLS port is `6380`.

### Amazon ElastiCache

`aws_iam` logs each component in as its own ElastiCache IAM user, on a replication group (ElastiCache Serverless isn't supported). Set `REDIS_AWS_IAM_USER_ID`, `REDIS_AWS_IAM_REPLICATION_GROUP_ID` and `REDIS_AWS_REGION`; the Helm chart sets them per component from `externalRedis.auth.awsIam`. Once every component logs in with IAM, remove the password user from the cache's user group so the old URL stops working. See [Environment variables](https://docs.tracecat.com/self-hosting/environment-variables.md) for their formats.

## Limitations

* The AWS Fargate Terraform doesn't set `TRACECAT__DB_AUTH_MODE` yet; Fargate deployments keep password login.
* Self-hosted Temporal still logs in to its own database with a password. Give it its own database role and Secret, never the admin's. A fully passwordless install needs Temporal Cloud or another external Temporal.

## Related pages

* See [Kubernetes](https://docs.tracecat.com/self-hosting/kubernetes.md) for the rest of the Helm chart's PostgreSQL and Redis settings.
* See [Database roles](https://docs.tracecat.com/self-hosting/database-roles.md) to set up `app`, `migrator` and read-only roles.
* See [Environment variables](https://docs.tracecat.com/self-hosting/environment-variables.md) for every database and Redis setting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.