Authentication Profiles

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:

DBCode opens your browser to the authorization server
You authenticate with your identity provider
The authorization server redirects back to DBCode with an authorization code
DBCode exchanges the code for access and refresh tokens
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:

DBCode sends the client ID and secret directly to the token endpoint
The authorization server returns an access token
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
Token to Send	Optional	Optional	Access Token (default) or ID Token

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

Sending the ID Token

Some servers expect the OpenID Connect ID token instead of the access token. Set Token to Send to ID Token and include the openid scope. DBCode then sends the ID token and renews it when the ID token itself expires.

Manual Token Clearing

To force re-authentication:

Edit the profile and save (clears cached tokens)
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

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