Authentication Contracts
Relevant source files
The following files were used as context for generating this wiki page:
Authentication Contracts in the dbt adapters ecosystem define the structured requirements and protocols for establishing secure connections to various data warehouses. These contracts ensure that credentials, connection parameters, and authentication methods are handled consistently across different adapter implementations, such as Snowflake, Redshift, and BigQuery.
The framework provides a base set of connection contracts and extends them through adapter-specific authentication providers and credential dataclasses. This allows for diverse authentication methods including basic username/password, IAM roles, OAuth, and Workload Identity Federation (WIF).
Core Connection Framework
The foundation of authentication lies in the dbt-adapters base framework, which defines the core data structures for managing database connections.
Connection and Credentials Dataclasses
The system uses specialized dataclasses to represent the state and configuration of a connection. The Connection object tracks the lifecycle of a database session, while Credentials (defined in adapter-specific modules) hold the necessary secrets and identifiers.
| Component | Description |
|---|---|
| Connection | Represents an active or pending database connection, including its type, name, state, and the underlying driver handle. |
| Credentials | An abstract base (or adapter-specific implementation) containing fields like host, port, user, and password. |
| ConnectionState | An Enum representing the status: INIT, OPEN, or FAIL. |
Sources: dbt-adapters/src/dbt/adapters/contracts/connection.py:11-54, CLAUDE.md:chunk 1
The diagram above illustrates the relationship between the core connection object and its associated metadata. Sources: dbt-adapters/src/dbt/adapters/contracts/connection.py:11-54
Adapter-Specific Authentication Methods
Each adapter implements specific authentication providers to handle platform-unique security requirements.
Redshift Authentication Providers
The Redshift adapter utilizes an auth_providers.py module to manage complex AWS authentication flows. It supports basic credentials as well as IAM-based identity management.
- IAMRoleAuthProvider: Handles authentication using AWS IAM roles.
- BrowserIdentityCenterAuthProvider: Facilitates browser-based SSO via AWS IAM Identity Center.
Sources: CLAUDE.md:chunk 3, dbt-redshift/src/dbt/adapters/redshift/auth_providers.py
Snowflake Authentication Methods
Snowflake supports a wide array of authentication contracts, ranging from traditional password auth to modern federated identities.
| Method | Configuration Elements |
|---|---|
| OAuth | oauth_client_id, oauth_client_secret, token (refresh token). |
| Key Pair | private_key_path, private_key_passphrase. |
| Workload Identity | authenticator: workload_identity, workload_identity_provider: oidc, token. |
| External Browser | authenticator: externalbrowser for SSO flows. |
Sources: CLAUDE.md:chunk 3, dbt-snowflake/tests/functional/auth_tests/test_workload_identity_federation_oidc.py:97-108
This diagram shows how different Snowflake authentication methods converge on a shared set of session configuration parameters. Sources: CLAUDE.md:chunk 3, dbt-snowflake/tests/functional/auth_tests/test_workload_identity_federation_oidc.py:97-108
Workload Identity Federation (WIF)
Workload Identity Federation allows dbt to authenticate to cloud providers (like Snowflake or BigQuery) without storing long-lived secrets. It relies on short-lived OIDC tokens generated by identity providers like GitHub Actions.
OIDC Flow for Snowflake
In a WIF contract, the adapter expects a token (often an OIDC ID token) and a provider type. For example, in GitHub Actions, the workflow mimes a token with a specific audience (snowflakecomputing.com) which is then passed to the Snowflake driver.
# Profile configuration for WIF
dbt_profile_target = {
"type": "snowflake",
"authenticator": "workload_identity",
"workload_identity_provider": "oidc",
"token": _mint_github_oidc_token(),
}
Sources: dbt-snowflake/tests/functional/auth_tests/test_workload_identity_federation_oidc.py:97-108
Summary of Configuration Parameters
Authentication contracts are enforced through the profile configuration. Below are common parameters used across major adapters.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | The adapter type (e.g., snowflake, redshift, bigquery). |
user | string | Varies | The username for the database session. |
password | string | Varies | The password for basic authentication. |
method | string | Varies | The specific auth method (e.g., service-account, oauth, iam). |
token | string | No | A bearer token, refresh token, or OIDC token. |
Sources: CLAUDE.md:chunk 3, AGENTS.md:chunk 1
Authentication Contracts ensure that dbt can securely bridge the gap between local development or CI environments and high-security data platforms. By standardizing these contracts in dbt-adapters, the project maintains a robust and extensible security architecture.