Authentication methods

How auth_method works

Each target in your configuration selects one auth_method. The method changes only how the credential is obtained — the read-only, least-privilege role is identical for every method. Whatever method you choose, Signals still authenticates as the Signals role, a LOGIN role granted pg_monitor.

• Credentials are never disclosed. No token, fetched secret, or key material is ever written to logs, errors, audit events, metrics, the local database, or any export. Only non-secret metadata is emitted.
• Credentials are never stored or cached for the cloud-identity methods. aws_rds_iam, azure_entra, and gcp_cloudsql_iammint a short-lived credential from the collector's ambient cloud identity at connect time — the target config carries no password, password file, or pgpass reference.
• Cloud methods require strict TLS. Any method that sends a token or a fetched password to the server requires sslmode: verify-full plus sslrootcert_file in every environment.

The read-only role is created once and reused by every method below:

CREATE ROLE signals LOGIN;          -- add PASSWORD only for the password / secret_store methods
GRANT pg_monitor TO signals;

Amazon RDS / Aurora

Four options are available for Amazon RDS and Aurora PostgreSQL, from a locally supplied password through to fully passwordless IAM auth and two cloud-vault backends.

1. password

The credential is a password supplied locally via exactly one of password_env, password_file, or pgpass_file.

  - name: rds-prod
    host: mydb.abc123.us-east-1.rds.amazonaws.com
    port: 5432
    dbname: appdb
    user: signals
    auth_method: password           # default — may be omitted
    sslmode: verify-full
    sslrootcert_file: /etc/ssl/certs/rds-global-bundle.pem
    password_file: /run/secrets/signals_password

2. aws_rds_iam (passwordless)

The collector's ambient AWS identity (EC2 instance profile, ECS task role, EKS IRSA / Pod Identity, or the local credential chain in dev) mints a 15-minute RDS IAM auth token used as the connection password. Enable IAM auth on the role:

CREATE ROLE signals LOGIN;     -- no password
GRANT rds_iam TO signals;      -- enables RDS IAM authentication
GRANT pg_monitor TO signals;

Allow the collector's principal to connect with an rds-db:connect IAM action scoped to the Signals db user:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "rds-db:connect",
    "Resource": "arn:aws:rds-db:<region>:<account-id>:dbuser:<db-resource-id>/signals"
  }]
}

<db-resource-id> is the instance/cluster DbiResourceId (e.g. db-ABCDEFGH…), not the DB identifier. The distinguishing config fields:

  - name: rds-prod
    host: mydb.abc123.us-east-1.rds.amazonaws.com
    user: signals
    auth_method: aws_rds_iam
    region: us-east-1              # optional; inferred from AWS_REGION / IMDS when omitted
    sslmode: verify-full          # required
    sslrootcert_file: /etc/ssl/certs/rds-global-bundle.pem
    # no password_* / pgpass_file — token methods are passwordless

region is optional; when it is neither configured nor in the environment, startup warns and the region is resolved from instance metadata at connect time.

3. secret_store — AWS Secrets Manager

Keep a normal password role's password in AWS Secrets Manager; Signals fetches it at connect time using its ambient workload identity. The backend is inferred from the shape of secret_ref — a secretsmanager ARN selects Secrets Manager, and the region is taken from the ARN.

  - name: selfmanaged-prod
    host: db.internal
    user: signals
    auth_method: secret_store
    secret_ref: arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/signals-AbCdEf
    secret_json_key: password     # optional; extract one key from a JSON secret
    sslmode: verify-full          # required
    sslrootcert_file: /etc/ssl/certs/db-ca.pem

IAM permission required: secretsmanager:GetSecretValue on that one secret. Set secret_json_key: password for JSON secrets like an AWS RDS-managed {"username":"…","password":"…"}; omit it when the secret value is the password.

4. secret_store — AWS SSM Parameter Store

The same secret_store method, but with an ssm ARN — a SecureString parameter holds the encrypted value directly. The ssm ARN service segment selects the Parameter Store backend, and the region is taken from the ARN.

  - name: selfmanaged-prod
    host: db.internal
    user: signals
    auth_method: secret_store
    secret_ref: arn:aws:ssm:us-east-1:123456789012:parameter/prod/signals/password
    sslmode: verify-full          # required
    sslrootcert_file: /etc/ssl/certs/db-ca.pem

IAM permissions required: ssm:GetParameter, plus kms:Decrypt for a SecureString (fetched with WithDecryption=true). A plain String works too.

Azure Database for PostgreSQL (Flexible Server)

Two options: passwordless Entra token auth, or a fetched password held in Azure Key Vault.

azure_entra (passwordless)

The collector's ambient Azure identity (Managed Identity on VM/VMSS, AKS workload identity, or the local Azure credential chain in dev) obtains an Entra OAuth2 token used as the connection password. Map the PG role to the Entra principal as an Entra administrator; the PG role name must match the Entra principal name:

SELECT * FROM pgaadauth_create_principal('signals', false, false);
GRANT pg_monitor TO signals;

  - name: azure-flex-prod
    host: myserver.postgres.database.azure.com
    user: signals                       # must equal the Entra principal name
    auth_method: azure_entra
    azure_client_id: 00000000-0000-0000-0000-000000000000  # optional; user-assigned MI disambiguation
    sslmode: verify-full                # required
    sslrootcert_file: /etc/ssl/certs/DigiCertGlobalRootCA.crt.pem

azure_client_id is optional — also read from AZURE_CLIENT_ID, and not needed with a single or system-assigned identity. It disambiguates a user-assigned Managed Identity on a host that has more than one.

secret_store — Azure Key Vault

Keep a normal password role's password in Key Vault and point secret_ref at the vault URL; the backend is inferred from the URL shape.

  - name: selfmanaged-prod
    host: db.internal
    user: signals
    auth_method: secret_store
    secret_ref: https://<vault>.vault.azure.net/secrets/<name>
    sslmode: verify-full          # required
    sslrootcert_file: /etc/ssl/certs/db-ca.pem

Permission required: Key Vault Secrets User (get) on that one secret.

Google Cloud SQL

Two options: passwordless IAM database auth, or a fetched password held in GCP Secret Manager.

gcp_cloudsql_iam (passwordless)

The collector's Application Default Credentials (attached service account via Workload Identity on GCE/GKE/Cloud Run, or gcloud ADC in dev) obtain a Google OAuth2 token used as the connection password over a direct libpq connection with verify-full. Create the IAM database user:

# service account identity:
gcloud sql users create signals-collector@<project>.iam.gserviceaccount.com \
  --instance=<instance> --type=cloud_iam_service_account

# or a human/user identity:
gcloud sql users create user@example.com \
  --instance=<instance> --type=cloud_iam_user

Grant the collector's identity roles/cloudsql.instanceUser on the project. Grant pg_monitor to the IAM user — for a service account the PG role name is the email without the .gserviceaccount.com suffix:

GRANT pg_monitor TO "signals-collector@<project>.iam";

  - name: cloudsql-prod
    host: 10.0.0.5                           # private IP, or the proxy endpoint
    user: "signals-collector@<project>.iam"  # SA email without .gserviceaccount.com
    auth_method: gcp_cloudsql_iam
    sslmode: verify-full                     # required (direct libpq path)
    sslrootcert_file: /etc/ssl/certs/server-ca.pem

secret_store — GCP Secret Manager

Keep a normal password role's password in Secret Manager and point secret_ref at the resource path.

  - name: selfmanaged-prod
    host: db.internal
    user: signals
    auth_method: secret_store
    secret_ref: projects/<proj>/secrets/<name>/versions/latest
    sslmode: verify-full          # required
    sslrootcert_file: /etc/ssl/certs/db-ca.pem

Permission required: secretmanager.versions.access on that secret.

Self-managed PostgreSQL

For PostgreSQL you run yourself, two methods are available beyond the secret_store vault backends shown above: a locally supplied password, or mutual TLS with a client certificate.

password

A password supplied locally via exactly one of password_file, password_env, or pgpass_file.

CREATE ROLE signals LOGIN PASSWORD 'use-a-strong-secret';
GRANT pg_monitor TO signals;

  - name: prod-primary
    host: db.internal
    port: 5432
    dbname: appdb
    user: signals
    sslmode: verify-full
    sslrootcert_file: /etc/ssl/certs/db-ca.pem
    # auth_method: password   # default — may be omitted
    password_file: /run/secrets/signals_password

mtls

The collector presents a client X.509 certificate instead of a password or token. The cert/key are local PEM files; the database maps the cert to the role server-side via pg_hba.conf clientcert=verify-full and pg_ident.conf.

hostssl  appdb  signals  <collector-cidr>  cert  clientcert=verify-full

  - name: onprem-mtls
    host: db.internal
    user: signals
    auth_method: mtls
    sslcert: /etc/signals/client.crt        # PEM client certificate
    sslkey: /etc/signals/client.key         # PEM private key
    sslkey_passphrase_file: /etc/signals/key.pass  # optional; for an encrypted key
    sslmode: verify-full                    # required
    sslrootcert_file: /etc/signals/ca.pem   # verifies the server

The private key is read at connect time and never logged or exported. verify-full is required — a client certificate is only presented to a verified server.

TLS requirements

verify-full requires sslrootcert_file to point at the CA bundle that signs the server certificate.

• aws_rds_iam, azure_entra, gcp_cloudsql_iam, secret_store → verify-full, in every environment.
• password → in prod, verify-ca / verify-full (with sslrootcert_file); weaker only in dev/lab with SIGNALS_ALLOW_INSECURE_PG_TLS=true.

Common errors

Each error is actionable and redacted — the credential never appears:

• A token/secret method set with a password source → startup error. Token and secret methods are passwordless; remove password_file / password_env / pgpass_file.
• A method with sslmode weaker than verify-full → startup error in every environment.
• No ambient identity, or a denied mint/fetch → connect-time, target-scoped failure naming the identity sources tried and the required grant; other targets keep collecting. This is where a missing rds_iam grant, pgaadauth_create_principal mapping, IAM-user mapping, or vault permission shows up.
• secret_store without, or with an unrecognised, secret_ref → startup error naming the accepted ARN/URL/path forms.

See also

Task-oriented walkthrough: Configure authentication.

The authoritative upstream matrix is docs/database-connections.md in the Elevarq Signals repository.