OAuth2

OAuth2 flow customization options

Dex provides a range of configurable options that empower you to fine-tune and personalize various aspects of the authentication and user flow.

Flow Customization

Customize OAuth2 settings to align with your authentication requirements.

oauth2:
  grantTypes: [ "authorization_code" ]
  responseTypes: [ "code" ]
  skipApprovalScreen: true
  alwaysShowLoginScreen: false

Authentication flow

  • responseTypes - allows you to configure the desired auth flow (Authorization Code Flow, Implicit Flow, or Hybrid Flow) based on different values. See the table below for valid configuration options.
responseTypes valueflow
codeAuthorization Code Flow
id_tokenImplicit Flow
id_token tokenImplicit Flow
code id_tokenHybrid Flow
code tokenHybrid Flow
code id_token tokenHybrid Flow
Examples of the different flows and their behavior can be found in the official openid spec.

User flow

Customizing the user flow allows you to influence how users login into your application.

  • skipApprovalScreen - controls the need for user approval before sharing data with connected applications. If enabled, users must approve data sharing with every auth flow.
  • alwaysShowLoginScreen - whether to always display the login screen. If only one authentication method is enabled, the default behavior is to go directly to it. For connected IdPs, this redirects the browser away from the application to upstream provider, such as the Google login page.

Configurable Grants

Dex supports various OAuth2 and OpenID Connect grant types. You can control which grant types are available by configuring the grantTypes setting.

oauth2:
  grantTypes:
    - "authorization_code"
    - "refresh_token"
    - "urn:ietf:params:oauth:grant-type:token-exchange"

Available grant types

The following grant types can be enabled or disabled:

Grant TypeDescriptionSpecial Configuration
authorization_codeAuthorization Code Flow - recommended for web and mobile applications-
refresh_tokenRefresh Token Grant - allows clients to obtain new access tokens without user interaction-
passwordResource Owner Password Credentials Flow - deprecated and less secureRequires passwordConnector to be set
client_credentialsClient Credentials Flow - for server-to-server communicationRequires feature flag: DEX_CLIENT_CREDENTIAL_GRANT_ENABLED_BY_DEFAULT=true
urn:ietf:params:oauth:grant-type:token-exchangeToken Exchange Grant (RFC 8693) - allows clients to exchange tokens from external identity providers-
urn:ietf:params:oauth:grant-type:device_codeDevice Code Grant (RFC 8628) - for devices with limited input capabilities-

Default behavior

If the grantTypes field is not specified, Dex enables these default grant types:

  • authorization_code
  • refresh_token
  • urn:ietf:params:oauth:grant-type:token-exchange

Examples

Enable only Authorization Code flow:

oauth2:
  grantTypes: [ "authorization_code" ]

Enable client credentials grant for server-to-server authentication:

Set the required environment variable, client credentials grant is enabled by default:

export DEX_CLIENT_CREDENTIAL_GRANT_ENABLED_BY_DEFAULT=true

Enable password grant (not recommended):

oauth2:
  passwordConnector: local  # Required for password grant

Password grants involve clients directly sending a user’s credentials (username and password) to the authorization server (dex), acquiring access tokens without the need for an intermediate authorization step.

Enable Implicit Flow:

Implicit flow is configured via responseTypes, not grantTypes:

oauth2:
  responseTypes: [ "id_token", "token" ]

Configuration options

  • grantTypes - list of enabled grant types (see Configurable Grants section above). To enable password grants, ensure "password" is included in this list.
  • passwordConnector - specifies the connector’s id that is used for password grants