OAuth2 / OIDC

OAuth2 with OpenID Connect (OIDC) support provides modern token-based authentication for database systems that support it. DBCode supports both interactive and non-interactive OAuth2 flows.

Supported Grant Types

Grant Type	Use Case	User Interaction
Authorization Code	Interactive user login	Browser redirect
Client Credentials	Service principals, machine-to-machine	None

Authorization Code Flow

The Authorization Code flow is designed for interactive authentication where a user logs in via their browser.

How it works:

1. DBCode opens your browser to the authorization server
2. You authenticate with your identity provider
3. The authorization server redirects back to DBCode with an authorization code
4. DBCode exchanges the code for access and refresh tokens
5. Tokens are securely stored and automatically refreshed

Features:

• Interactive browser-based authentication
• PKCE (Proof Key for Code Exchange) support for enhanced security
• Refresh token management for seamless reconnection
• Automatic token renewal before expiration

Best for:

• User-based authentication
• Interactive development environments
• When you need to authenticate as yourself

Client Credentials Flow

The Client Credentials flow is designed for service-to-service authentication without user interaction.

How it works:

1. DBCode sends the client ID and secret directly to the token endpoint
2. The authorization server returns an access token
3. No browser interaction required

Features:

• Direct token acquisition without browser
• Service principal / application authentication
• No refresh tokens (tokens re-acquired on expiry)
• Fully automated, no user prompts

Best for:

• Automated systems and CI/CD pipelines
• Service accounts and machine identities
• Non-interactive environments
• Scheduled jobs and background processes

Configuration Options

Grant Type

Select the OAuth2 flow that matches your authentication needs:

• Authorization Code: For interactive user authentication
• Client Credentials: For service principals and automation

Discovery Mode

Auto Discovery (Recommended)

• Provide a Discovery URL (OIDC discovery endpoint)
• DBCode automatically fetches authorization and token endpoints
• Example: https://auth.example.com/.well-known/openid-configuration

Manual Configuration

• Directly specify the authorization and token endpoints
• Use when the identity provider doesn’t support OIDC discovery

Required Fields

Field	Auth Code	Client Credentials	Description
Client ID	Required	Required	Application client identifier
Client Secret	Optional	Required	Application client secret
Discovery URL	Auto mode	Auto mode	OIDC discovery endpoint
Authorization Endpoint	Manual mode	N/A	OAuth2 authorization URL
Token Endpoint	Manual mode	Manual mode	OAuth2 token exchange URL
Scopes	Optional	Optional	Space or comma-separated list of OAuth2 scopes

Auto-Discovery

For OIDC-compliant providers, use the Auto-Discover button to automatically populate endpoints from your discovery URL. This fetches:

• Authorization endpoint
• Token endpoint
• Supported scopes
• Other OIDC configuration

Supported Databases

The following databases support OAuth2 authentication profiles:

• Trino - With OAuth2-enabled clusters
• Starburst - Enterprise Trino with OAuth2
• Databricks - With OAuth2 authentication enabled
• Snowflake - With external OAuth configuration

Configuration Examples

Trino with Authorization Code (Interactive)

{
  "name": "Trino Production",
  "type": "oauth2",
  "options": {
    "grantType": "authorization_code",
    "discoveryUrl": "https://auth.company.com/.well-known/openid-configuration",
    "clientId": "trino-client",
    "scopes": "openid profile email"
  }
}

Client secret (if required) stored in Secret Storage.

Starburst with Client Credentials (Service Principal)

{
  "name": "Starburst Service Account",
  "type": "oauth2",
  "options": {
    "grantType": "client_credentials",
    "discoveryUrl": "https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration",
    "clientId": "your-service-principal-client-id",
    "scopes": "api://starburst/.default"
  }
}

Client secret stored in Secret Storage. No browser interaction required.

Databricks with OAuth

{
  "name": "Databricks Workspace",
  "type": "oauth2",
  "options": {
    "grantType": "authorization_code",
    "authorizationEndpoint": "https://accounts.cloud.databricks.com/oidc/v1/authorize",
    "tokenEndpoint": "https://accounts.cloud.databricks.com/oidc/v1/token",
    "clientId": "databricks-oauth-client",
    "scopes": "all-apis offline_access"
  }
}

Azure AD / Entra ID

{
  "name": "Azure AD Service Principal",
  "type": "oauth2",
  "options": {
    "grantType": "client_credentials",
    "discoveryUrl": "https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration",
    "clientId": "your-app-registration-client-id",
    "scopes": "https://your-resource/.default"
  }
}

Token Management

Automatic Refresh

For Authorization Code flow, DBCode automatically:

• Caches valid access tokens to minimize authentication prompts
• Refreshes tokens before they expire using the refresh token
• Prompts for re-authentication only when the refresh token expires

Client Credentials Tokens

For Client Credentials flow:

• Tokens are acquired fresh when needed
• No refresh tokens (the grant type doesn’t support them)
• Tokens are cached until they expire

Manual Token Clearing

To force re-authentication:

1. Edit the profile and save (clears cached tokens)
2. Or disconnect and reconnect the database connection

Troubleshooting

”Failed to open browser for authentication”

Cause: Browser couldn’t be opened for OAuth2 authorization flow

Solutions:

• Check that you have a default browser configured
• Try running VS Code with appropriate permissions
• For remote development, ensure port forwarding is configured

”Client secret is required for client credentials flow”

Cause: Using Client Credentials grant type without providing a client secret

Solutions:

• Add the client secret to the profile configuration
• Store it in Secret Storage for security

Token Refresh Failures

Cause: Refresh token expired or invalidated

Solutions:

• Disconnect and reconnect to trigger new authorization flow
• Check that your refresh token hasn’t been revoked
• Verify OAuth2 configuration is still valid

”Token exchange failed”

Cause: Error during the code-to-token exchange

Solutions:

• Verify your client ID and secret are correct
• Check that the redirect URI is properly configured in your identity provider
• Ensure scopes are valid for your application registration

PKCE Errors

Cause: Identity provider doesn’t support PKCE or has it misconfigured

Solutions:

• DBCode uses PKCE by default for Authorization Code flow
• If your provider doesn’t support PKCE, contact your identity provider
• Most modern OAuth2 providers support PKCE

Security Best Practices

1. Use Client Credentials for automation: Don’t embed user credentials in automated systems
2. Store secrets securely: Always use Secret Storage for client secrets
3. Limit scopes: Request only the scopes your application needs
4. Use OIDC discovery: Auto-discovery ensures you’re using the correct endpoints
5. Rotate secrets regularly: Follow your organization’s secret rotation policies