Enabling OAUTH2 and OIDC Authentication¶

Enable workload identity mode¶

Set the following parameters in your provider configuration:

OAUTH2_CONFIG = [{
    'OAUTH2_NAME': 'entra-workload-identity',
    'OAUTH2_DISPLAY_NAME': 'Microsoft Entra ID',
    'OAUTH2_CLIENT_ID': '<Application (client) ID>',
    'OAUTH2_CLIENT_SECRET': None,  # not required
    'OAUTH2_CLIENT_AUTH_METHOD': 'workload_identity',
    'OAUTH2_WORKLOAD_IDENTITY_TOKEN_FILE':
        '/var/run/secrets/azure/tokens/azure-identity-token',
    'OAUTH2_SERVER_METADATA_URL':
        'https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration',
    'OAUTH2_SCOPE': 'openid email profile',
}]

With this configuration:

• pgAdmin will not require OAUTH2_CLIENT_SECRET.

• pgAdmin will not use PKCE for this provider.

• During the token exchange, pgAdmin will send:

  • client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer

  • client_assertion=<projected service account JWT>

Azure App Registration setup¶

In Microsoft Entra ID:

• Create an App registration for pgAdmin.

• Configure a Redirect URI to <http/https>://<pgAdmin Server URL>/oauth2/authorize.

• In Certificates & secrets, you do not need to create a client secret for workload identity.

Federated credential (workload identity) configuration¶

Add a Federated credential to the App registration:

• Issuer: your AKS cluster OIDC issuer URL.

• Subject: system:serviceaccount:<namespace>:<serviceaccount-name>

• Audience: typically api://AzureADTokenExchange

AKS ServiceAccount example¶

Example ServiceAccount for AKS Workload Identity:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: pgadmin
  namespace: pgadmin
  annotations:
    azure.workload.identity/client-id: "<Application (client) ID>"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pgadmin
  namespace: pgadmin
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: pgadmin

Using OIDC with Discovery Metadata (Recommended)¶

When using OIDC providers, configure the OAUTH2_SERVER_METADATA_URL parameter to enable automatic discovery and ID token validation:

OAUTH2_CONFIG = [{
    'OAUTH2_NAME': 'my-oidc-provider',
    'OAUTH2_DISPLAY_NAME': 'My OIDC Provider',
    'OAUTH2_CLIENT_ID': 'your-client-id',
    'OAUTH2_CLIENT_SECRET': 'your-client-secret',
    'OAUTH2_SERVER_METADATA_URL': 'https://provider.example.com/.well-known/openid-configuration',
    'OAUTH2_SCOPE': 'openid email profile',
    # OAUTH2_USERINFO_ENDPOINT is optional when using OIDC
    # Token and authorization URLs are discovered automatically
}]

With this configuration:

• pgAdmin will use the OIDC discovery endpoint to automatically find token and authorization URLs

• User identity will be extracted from ID token claims (sub, email, preferred_username)

• The userinfo endpoint will only be called as a fallback if ID token lacks required claims

• ID token will be automatically validated using the provider’s public keys

Using OIDC as a Public Client (No Client Secret) with PKCE¶

If your OAuth/OIDC application is configured as a public client (no client secret), pgAdmin can still perform interactive user login using Authorization Code + PKCE.

OAUTH2_CONFIG = [{
    'OAUTH2_NAME': 'my-oidc-public',
    'OAUTH2_DISPLAY_NAME': 'My OIDC Provider (Public Client)',
    'OAUTH2_CLIENT_ID': 'your-client-id',
    # Public client: omit OAUTH2_CLIENT_SECRET or set it to None/empty.
    'OAUTH2_CLIENT_SECRET': None,
    'OAUTH2_SERVER_METADATA_URL': 'https://provider.example.com/.well-known/openid-configuration',
    'OAUTH2_SCOPE': 'openid email profile',
    # PKCE is mandatory for public clients
    'OAUTH2_CHALLENGE_METHOD': 'S256',
    'OAUTH2_RESPONSE_TYPE': 'code',
}]

With this configuration:

• pgAdmin enforces PKCE (challenge method + response type)

• The token exchange is performed without a client secret

Username Resolution for OIDC¶

When OAUTH2_SERVER_METADATA_URL is configured (OIDC mode), pgAdmin will resolve the username in the following order:

1. OAUTH2_USERNAME_CLAIM (if configured) - checks ID token first, then userinfo

2. email claim from ID token or userinfo endpoint

3. preferred_username claim from ID token (standard OIDC claim)

4. sub claim from ID token (always present in OIDC, used as last resort)

Example with custom username claim:

OAUTH2_CONFIG = [{
    # ... other config ...
    'OAUTH2_USERNAME_CLAIM': 'preferred_username',
    # pgAdmin will use 'preferred_username' from ID token for the username
}]

Example without custom claim (uses automatic fallback):

OAUTH2_CONFIG = [{
    # ... other config ...
    # No OAUTH2_USERNAME_CLAIM specified
    # pgAdmin will try: email -> preferred_username -> sub
}]

Additional Claims Authorization with OIDC¶

When using OAUTH2_ADDITIONAL_CLAIMS with OIDC providers, pgAdmin will:

1. Check the ID token claims first (more secure, no additional network call)

2. Fall back to userinfo endpoint response if needed

Example:

OAUTH2_CONFIG = [{
    # ... other config ...
    'OAUTH2_ADDITIONAL_CLAIMS': {
        'groups': ['admin-group', 'pgadmin-users'],
        'roles': ['database-admin']
    },
    # pgAdmin will check these claims in ID token first,
    # then userinfo endpoint if not found
}]

Legacy OAuth2 Configuration (Without OIDC)¶

For providers that don’t support OIDC discovery, configure all endpoints manually:

OAUTH2_CONFIG = [{
    'OAUTH2_NAME': 'github',
    'OAUTH2_DISPLAY_NAME': 'GitHub',
    'OAUTH2_CLIENT_ID': 'your-client-id',
    'OAUTH2_CLIENT_SECRET': 'your-client-secret',
    'OAUTH2_TOKEN_URL': 'https://github.com/login/oauth/access_token',
    'OAUTH2_AUTHORIZATION_URL': 'https://github.com/login/oauth/authorize',
    'OAUTH2_API_BASE_URL': 'https://api.github.com/',
    'OAUTH2_USERINFO_ENDPOINT': 'user',
    'OAUTH2_SCOPE': 'user:email',
    # No OAUTH2_SERVER_METADATA_URL - pure OAuth2 mode
}]

In this mode, user identity is retrieved only from the userinfo endpoint.