ℹ️
This feature requires an Enterprise or higher plan to use

👍
Connection Auth Rules are only available native cloud agent deployments with self-hosted credentials. The generic agent is not supported.
This is an advanced feature intended for customers who need to customize how credentials are passed to their connection. Most connections work without it

Connection Auth Rules control how credentials are resolved and passed to the database driver when Monte Carlo connects through an agent. The default auth handling for each connector covers standard use cases (user/password, key-pair auth, common SSL options). An auth rule configuration lets you override or extend that handling when your credentials are shaped differently, for example when using a custom OAuth token endpoint, non-standard credential field names, or an authentication method that requires additional pre-processing.

How it works

When Monte Carlo establishes a connection through an agent, it resolves the self-hosted credentials using the connection auth rules configured for that connection. The agent processes the credentials through the rule, executing any transform steps in order, then applying the mapper, and passes the resulting connection arguments to the database driver

The pipeline has two components:

Component	Purpose
`steps`	Ordered list of pre-processing transforms (e.g. fetch an OAuth token, decode a PEM key)
`mapper`	Maps raw or derived credential fields to driver connection arguments using Jinja2 templates

Configuration format

A config is a JSON object stored per connection. The minimal form includes only the mapper:

{
  "mapper": {
    "host": "{{ raw.hostname }}",
    "port": "{{ raw.port }}",
    "dbname": "{{ raw.database }}",
    "user": "{{ raw.svc_account }}",
    "password": "{{ raw.svc_password }}"
  }
}

With transform steps:

{
  "steps": [ ... ],
  "mapper": { ... }
}

Mapper templates

Each value in the mapper is a Jinja2 template string. Use raw.<field> to reference any field from the stored credentials:

{
  "mapper": {
    "host": "{{ raw.host }}",
    "port": "{{ raw.port }}",
    "database": "{{ raw.database }}"
  }
}

Values produced by transform steps are available as derived.<key>:

{
  "mapper": {
    "token": "{{ derived.oauth_token }}"
  }
}

Transform steps

Steps run before the mapper and produce values in the derived namespace. Each step has:

Field	Required	Description
`type`	yes	The transform to run (see table below)
`input`	yes	Template expressions passed to the transform
`output`	yes	Maps transform outputs to `derived` keys, referenced as `derived.<key>` in `field_map`
`field_map`	no	Connection argument entries contributed by this step

Available transform types

Type	Description
`oauth`	Acquires an OAuth 2.0 access token (`client_credentials` or `password` grant)
`load_private_key`	Decodes a PEM private key string to DER bytes for key-pair auth
`tmp_file_write`	Writes credential data (e.g. a certificate) to a temp file, producing a file path
`resolve_ssl_options`	Builds an SSL configuration from a credential dict — writes CA data to a temp file and creates an `SSLContext`
`fetch_remote_file`	Downloads a file from a URL or cloud storage bucket to a local temp path
`generate_jwt`	Signs a HS256 JWT for authentication
`write_ini_file`	Writes key-value pairs to a temporary INI file and produces a file path
`resolve_redshift_credentials`	Exchanges an IAM identity for temporary Redshift `DbUser` / `DbPassword` via `GetClusterCredentials`

oauth

Fetches an access token from an OAuth 2.0 authorization server.

Input fields:

oauth — template resolving to an object with: client_id, client_secret, access_token_endpoint, grant_type ("client_credentials" or "password"), and optionally scope, username, password (password grant)

Output fields:

token — derived key where the access token string is stored

{
  "type": "oauth",
  "input": { "oauth": "{{ raw.oauth }}" },
  "output": { "token": "oauth_token" },
  "field_map": {
    "token": "{{ derived.oauth_token }}",
    "authenticator": "oauth"
  }
}

load_private_key

Decodes a PEM-encoded private key to unencrypted DER bytes for connectors such as Snowflake.

Input fields:

pem — template resolving to a PEM key string
password — passphrase for encrypted keys (omit for unencrypted)

Output fields:

private_key — derived key where the DER bytes are stored

{
  "type": "load_private_key",
  "input": {
    "pem": "{{ raw.private_key_pem }}",
    "password": "{{ raw.private_key_passphrase }}"
  },
  "output": { "private_key": "private_key_der" },
  "field_map": { "private_key": "{{ derived.private_key_der }}" }
}

tmp_file_write

Writes string or binary data to a temporary file on the agent host. Useful when a driver requires a file path (e.g. a trust store or CA certificate) rather than inline data.

Input fields:

contents — template resolving to the file contents (string or bytes)
file_suffix — optional file extension (e.g. ".pem")

Output fields:

path — derived key where the temp file path is stored

{
  "type": "tmp_file_write",
  "input": {
    "contents": "{{ raw.ca_cert_data }}",
    "file_suffix": ".pem"
  },
  "output": { "path": "ca_cert_path" },
  "field_map": { "sslTrustStore": "{{ derived.ca_cert_path }}" }
}

resolve_ssl_options

Builds an SSL configuration from a structured credential dict. Writes CA certificate data to a deterministic temp file when present, and optionally constructs a Python ssl.SSLContext for drivers that accept one directly.

Input fields:

ssl_options — template resolving to an object with any of the following:
- ca_data — PEM string for the certificate authority (used for server verification)
- cert_data — PEM string for the client certificate
- key_data — PEM string for the client private key
- key_password — passphrase for an encrypted private key
- ca — path to a CA PEM file (alternative to ca_data)
- skip_cert_verification — skip certificate and identity validation (default false)
- verify_cert — verify the server certificate (default true)
- verify_identity — verify the server hostname (default true)
- disabled — disable SSL entirely (default false)

Output fields (all optional — omit any you don't need):

ssl_options — the resolved SSL options object; access its attributes as derived.<key>.ca_path, etc.
ca_path — path to the CA cert file written to disk (only set when ca_data is present and SSL is not disabled)
ssl_context — a Python ssl.SSLContext for drivers that accept one directly (only built when cert_data is present)

{
  "type": "resolve_ssl_options",
  "input": { "ssl_options": "{{ raw.ssl_options }}" },
  "output": { "ca_path": "ssl_ca_path" },
  "field_map": { "ssl_ca_cert": "{{ derived.ssl_ca_path }}" }
}

fetch_remote_file

Downloads a file from a remote URL or cloud storage bucket to a local temp path on the agent host. Useful when a driver requires a file path (e.g. a CA certificate or keystore) and the file is stored remotely rather than inline in credentials.

Input fields:

url — template resolving to a URL or storage key (required)
mechanism — "url" (default) or a platform storage mechanism (e.g. "s3")
sub_folder — optional subdirectory hint for temp file placement

Output fields:

path — derived key where the local file path is stored

{
  "type": "fetch_remote_file",
  "input": {
    "url": "{{ raw.ca_cert_url }}",
    "mechanism": "url"
  },
  "output": { "path": "ca_cert_path" },
  "field_map": { "ssl_ca_cert": "{{ derived.ca_cert_path }}" }
}

generate_jwt

Generates a signed HS256 JWT for authentication.

Input fields:

username — Tableau username embedded in the token's subject claim
client_id — Connected App client UUID
secret_id — Connected App secret UUID
secret_value — Connected App secret value used to sign the token
expiration_seconds — token lifetime in seconds (optional, default 300)

Output fields:

token — derived key where the signed JWT string is stored

{
  "type": "generate_jwt",
  "input": {
    "username": "{{ raw.tableau_user }}",
    "client_id": "{{ raw.client_id }}",
    "secret_id": "{{ raw.secret_id }}",
    "secret_value": "{{ raw.secret_value }}"
  },
  "output": { "token": "jwt" },
  "field_map": { "jwt": "{{ derived.jwt }}" }
}

write_ini_file

Writes key-value pairs to a temporary INI file on the agent host. Useful when a driver requires a config file path rather than inline connection arguments (e.g. Looker).

Input fields:

section — the INI section name (required, e.g. "Looker")
any additional keys — rendered as key=value lines under the section; fields that resolve to null are omitted

Output fields:

path — derived key where the temp file path is stored

{
  "type": "write_ini_file",
  "input": {
    "section": "Looker",
    "base_url": "{{ raw.base_url }}",
    "client_id": "{{ raw.client_id }}",
    "client_secret": "{{ raw.client_secret }}"
  },
  "output": { "path": "looker_ini_path" },
  "field_map": { "ini_file_path": "{{ derived.looker_ini_path }}" }
}

resolve_redshift_credentials

Calls the AWS Redshift GetClusterCredentials API to exchange an IAM identity for short-lived database credentials.

Input fields:

cluster_identifier — Redshift cluster identifier
db_user — IAM database user
db_name — target database name
auto_create — whether to auto-create the user (default true)
aws_region — optional AWS region override

Output fields:

user — derived key for the temporary DbUser
password — derived key for the temporary DbPassword

{
  "type": "resolve_redshift_credentials",
  "input": {
    "cluster_identifier": "{{ raw.cluster_identifier }}",
    "db_user": "{{ raw.db_user }}",
    "db_name": "{{ raw.db_name }}",
    "aws_region": "{{ raw.aws_region }}"
  },
  "output": {
    "user": "federated_user",
    "password": "federated_password"
  },
  "field_map": {
    "user": "{{ derived.federated_user }}",
    "password": "{{ derived.federated_password }}"
  }
}

Examples

Snowflake with OAuth token acquisition

{
  "steps": [
    {
      "type": "oauth",
      "input": { "oauth": "{{ raw.oauth }}" },
      "output": { "token": "oauth_token" },
      "field_map": {
        "token": "{{ derived.oauth_token }}",
        "authenticator": "oauth"
      }
    }
  ],
  "mapper": {
    "user": "{{ raw.user }}",
    "account": "{{ raw.account }}",
    "warehouse": "{{ raw.warehouse }}",
    "database": "{{ raw.database }}",
    "role": "{{ raw.role }}"
  }
}