Skip to main content
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 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: 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 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

2

Create the database user

As the master user, create the login and grant it rds_iam:
rds_iam turns off a role’s password login, so never grant it to the master user. With database roles, 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:
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:
With database roles, 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):
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:
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. 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, 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:
Note each identity’s client ID and object ID; the next steps use both:
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:
With database roles (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:
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:
Then set it to VECTOR,PG_TRGM plus every extension that printed, comma-separated:
With an empty list, use --value VECTOR,PG_TRGM.Then, as the Entra administrator, connected to the Tracecat database, create them (see pgvector for the version Tracecat needs):
5

Configure Tracecat

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:

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: the migrations Job logs in directly, as migrator with a token of its own (see 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. 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.

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.
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. List the service accounts of the pods the chart labels, with the same chart reference, version and values you install with:
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. 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:
<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):
3

Configure Tracecat

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:
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 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.