Skip to content

Authentication Methods

Customer-Managed Prefect supports multiple authentication providers for enterprise Single Sign-On (SSO) integration. You can configure a single authentication method or enable multiple methods simultaneously, allowing users to choose their preferred provider during login.

Supported Providers

  • Okta - OAuth 2.0 / OpenID Connect
  • ADFS - Active Directory Federation Services
  • Entra - Microsoft Entra ID (formerly Azure AD)
  • PingFederate - Ping Identity PingFederate, OAuth 2.0 / OpenID Connect

Configuration

Authentication is configured for one or more providers via the global.authProvider section in your Helm values file.

Okta

global:
  authProvider:
    okta:
      clientID: ""           # OAuth 2.0 client ID from Okta application
      clientSecret: ""       # OAuth 2.0 client secret from Okta application
      authServerURL: ""      # Okta authorization server URL (e.g., https://your-domain.okta.com/oauth2/default)
      apiKey: ""            # Okta API key for management operations

ADFS (Active Directory Federation Services)

global:
  authProvider:
    adfs:
      clientID: ""           # ADFS application client ID
      clientSecret: ""       # ADFS application client secret
      clientAuthority: ""    # ADFS authority URL (e.g., https://adfs.your-domain.com/adfs)
      clientVerifySSL: ""    # Enable/disable SSL certificate verification
      scopes: ""              # Optional; space-delimited OAuth scopes (default: email allatclaims)
      emailField: ""         # Optional; claim name for the user's email (default: email)
      subField: ""           # Optional; claim name for the user's unique identifier (default: sub)

The scopes value is passed to ADFS as the OAuth scopes parameter. When omitted, Prefect uses email allatclaims. To request additional claims or target a specific ADFS resource (relying-party identifier), set a space-delimited list, for example:

scope: "openid email allatclaims https://api.example.com/.default"

The emailField and subField values control which ID token claims are used as the user's email address and unique identifier respectively. Some ADFS deployments use non-standard claim names (e.g., Email instead of email, or a custom identifier instead of sub). When omitted, Prefect uses email and sub.

Entra (Microsoft Entra ID)

global:
  authProvider:
    entra:
      clientID: ""                                         # Entra application (client) ID
      clientSecret: ""                                     # Entra client secret
      tenantID: ""                                        # Entra tenant ID
      clientVerifySSL: false                              # Enable/disable SSL certificate verification
      loginBaseURL: "https://login.microsoftonline.com/"  # Microsoft login endpoint

PingFederate

global:
  authProvider:
    pingfederate:
      clientID: ""           # PingFederate OAuth client ID
      clientSecret: ""       # PingFederate OAuth client secret
      baseURL: ""            # PingFederate runtime engine base URL, with no trailing slash (e.g., https://pingfederate.your-domain.com)
      clientVerifySSL: true  # Enable/disable SSL certificate verification

The OAuth endpoints are derived from baseURL:

Purpose Endpoint
Authorization {baseURL}/as/authorization.oauth2
Token {baseURL}/as/token.oauth2
Userinfo {baseURL}/idp/userinfo.openid

Login uses the authorization code flow with PKCE (S256) and requests the openid email profile scopes. The email and sub claims are required from the userinfo endpoint; given_name and family_name are optional.

PingFederate is often deployed on-premises with certificates issued by an internal CA. Set clientVerifySSL: false if the Prefect services do not trust that CA.

baseURL also identifies the PingFederate instance when linking users to their account, so changing it for an existing deployment prevents existing users from signing back in.

Single Provider Configuration

Here's a complete example using Okta:

global:
  authProvider:
    okta:
      clientID: "0oa2b3c4d5e6f7g8h9i0"
      clientSecret: "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789"
      authServerURL: "https://mycompany.okta.com/oauth2/default"
      apiKey: "00AbCdEfGhIjKlMnOpQrStUvWxYz0123456789"

Multiple Provider Configuration

To enable multiple authentication providers simultaneously, configure all desired providers in the Helm values file and set the PREFECT_CLOUD_AUTH_OAUTH_PROVIDERS environment variable to a comma-separated list of provider names.

Example: Multiple Providers

global:
  authProvider:
    # Configure all providers you want to enable
    okta:
      clientID: "0oa2b3c4d5e6f7g8h9i0"
      clientSecret: "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789"
      authServerURL: "https://mycompany.okta.com/oauth2/default"
      apiKey: "00AbCdEfGhIjKlMnOpQrStUvWxYz0123456789"
    adfs:
      clientID: "adfs-client-id"
      clientSecret: "adfs-client-secret"
      clientAuthority: "https://adfs.your-domain.com/adfs"
      clientVerifySSL: false
    entra:
      clientID: "entra-client-id"
      clientSecret: "entra-client-secret"
      tenantID: "entra-tenant-id"
      clientVerifySSL: false
    pingfederate:
      clientID: "pingfederate-client-id"
      clientSecret: "pingfederate-client-secret"
      baseURL: "https://pingfederate.your-domain.com"
      clientVerifySSL: true

Using Multiple Providers

When multiple providers are configured:

  • Users can select their preferred provider during login
  • The first configured provider is used as the default for account initialization and member creation
  • CLI commands that require a provider will accept an optional --provider parameter
  • API endpoints that create users can accept an optional provider query parameter

Provider Setup

Setting up Okta

  1. Create an OAuth 2.0 application in your Okta admin console
  2. Configure the redirect URI to point to your Customer-Managed Prefect instance
  3. Note the Client ID and Client Secret
  4. Create an API token for management operations
  5. Use the authorization server URL (typically https://your-domain.okta.com/oauth2/default)

Setting up ADFS

  1. Register a new application in your ADFS management console
  2. Configure OAuth 2.0 settings and redirect URIs
  3. Note the Client ID and Client Secret
  4. Use your ADFS authority URL (e.g., https://adfs.your-domain.com/adfs)
  5. If your deployment requires custom scopes or a resource identifier, set scope in Helm values (see the ADFS configuration section above)

Setting up Entra (Microsoft Entra ID)

  1. Register an application in the Azure portal under Microsoft Entra ID
  2. Create a client secret in the "Certificates & secrets" section
  3. Note the Application (client) ID and Directory (tenant) ID
  4. Configure redirect URIs in the "Authentication" section
  5. Grant necessary API permissions

Setting up PingFederate

  1. Create an OAuth client in the PingFederate administrative console
  2. Enable the Authorization Code grant type, and require PKCE with the S256 code challenge method
  3. Set the redirect URI to https://<your-prefect-host>/auth/pingfederate-callback
  4. Allow the openid, email, and profile scopes
  5. Configure the OpenID Connect policy so /idp/userinfo.openid releases the sub, email, given_name, and family_name claims
  6. Note the Client ID and Client Secret, and use the runtime engine base URL (e.g., https://pingfederate.your-domain.com) with no trailing slash