Adopt OIDC-Conformant Authentication

Auth0 is a certified OpenID Connect (OIDC) provider. As part of Auth0’s efforts to improve security and standards-based interoperability, we roll out new features exclusively on authentication flows that strictly conform to OIDC specifications.

We will explain the differences between the OIDC-conformant and legacy pipelines and provide suggestions on how to adapt your existing applications. If you are a developer and/or IT administrator who manages Auth0 integrations in your applications using the OAuth 2.0 Authorization Framework. This information is not applicable if you are using SAML or WS-Federation. All authentication flows are described through HTTP requests rather than in the context of any particular language or library implementation.

All new features target only the OIDC-conformant pipeline, and all legacy Auth0 SDK versions are deprecated, do not receive updates for new features or non-critical security issues, and will eventually be discontinued. In addition, all documentation, libraries, and examples outside of this guide apply to only the OIDC-conformant pipeline. Because of this, we strongly recommend adopting the OIDC-conformant pipeline even if you do not need to leverage any new features or functionality in the immediate future.

Apply the OIDC-conformant pipeline

Depending on the age of your tenant, you may have different options for applying the OIDC-conformant pipeline.

New tenants

If you create a new tenant using the Auth0 Dashboard, the OIDC-conformant pipeline is used by default. This has been a default setting for the Dashboard since early 2019.

You may still have manually disabled the OIDC Conformant setting, in which case you should follow our instructions for older tenants.

Older tenants

If you want to force all changes outlined in this guide at the same time for a given application so you can encounter all breaking changes during configuration rather than run time, you must:

  1. Go to Dashboard > Applications > Applications, and select the desired application.

  2. Scroll to Advanced Settings and go to the OAuth tab.

  3. Enable the OIDC Conformant toggle switch and click Save Changes.

Auth0 Dashboard Applications Advanced Settings OAuth Tab

If you want to use the OIDC-conformant pipeline on a per-authentication-request basis and your application needs to call an API with a JWT access token, initiate the request to the /social endpoint with an audience parameter.

If you want to use the OIDC-conformant pipeline on a per-authentication-request basis and your application doesn't need to call an API, use the following audience parameter:

https://YOUR_DOMAIN/userinfo

Differences

Enabling the OIDC-conformant pipeline results in the following changes to the legacy pipeline.

APIs

Applications and APIs (resources) should be defined as separate Auth0 entities. To learn more, read OIDC-Conformant Adoption: APIs.

Access tokens

  • APIs should be secured with access tokens instead of ID tokens. To learn more about the differences, read Tokens.

  • A defined set of standard claims about users can be returned in ID Tokens or in the response from /userinfo.

  • Custom claims must conform to a named format. To learn more, read Create Namespaced Custom Claims.

  • Responses from /userinfo will conform to the OIDC specification, similar to the contents of ID tokens

  • Scopes can be used to request either standard claims or custom API permissions.

To learn more, read OIDC-Conformant Adoptions: Access Tokens.

Authorization flows

  • Authorization Code Flow: Structural differences exist in the authentication request, authentication response, code exchange request, code exchange response, ID token structure, and access token structure.

  • Client Credentials Flow: New flow enabled, which allows applications to authenticate as themselves (rather than on behalf of a user) to programmatically and securely obtain access to an API.

  • Implicit Flow: Structural differences exist in the authentication request, authentication response, ID token structure, and access token structure. Specifically:

    • response_type=token only returns an access token. To get an ID token, use response_type=id_token or response_type=token id_token.

    • ID tokens will be signed asymmetrically using RS256.

    • Authentication requests made without a nonce parameter will be rejected. To learn more, read Mitigate Replay Attacks When Using Implicit Flow.

    • Refresh tokens will no longer be returned when using the Implicit Flow for authentication.

  • Resource Owner Password Flow: Structural differences exist in the authentication request, authentication response, ID token structure, and access token structure. Specifically:

    • the legacy resource owner endpoint is disabled, which also disables passwordless authentication for embedded login from that endpoint. To implement Passwordless with embedded login, you must use the Embedded Passwordless API or our SDKs, depending on your application type.

    • the device parameter is now considered invalid when requesting a refresh token using the offline_access scope.

Delegation

  • Deprecated: /delegation endpoint, except when used to get third-party API tokens.

  • OIDC-conformant applications cannot be the source or target of delegation requests.

To learn more, read OIDC-Conformant Adoption: Delegation.

Endpoints

  • Deprecated: /tokeninfo endpoint

  • Disabled: the /oauth/access_token endpoint (used for social authentication from native mobile applications).

  • Deprecated: /ssodata endpoint

  • Deprecated: /delegation endpoint except when used to get third-party API tokens.

Refresh tokens

  • Refresh tokens will no longer be returned when using the Implicit Flow for authentication.

  • Refresh tokens can be used for confidential applications, but refresh token rotation can increase security for most flows and should always be used for public applications when using the Authorization Code Flow with PKCE. To learn about confidential applications, read Confidential and Public Applications. To learn more about refresh token rotation, read, Refresh Token Rotation.

  • When getting new tokens, you should use the /oauth/token endpoint.

  • The device parameter is no longer needed when requesting a refresh token using the offline_access scope in authentication requests.

To learn more, read OIDC-Conformation Adoption: Refresh Tokens.

  • SSO can be performed only from Auth0 login pages, which means that you must employ Universal Login.

  • To determine whether users are logged in via SSO, you must use silent authentication. To learn more, read Configure Silent Authentication.

  • Deprecated: /ssodata endpoint and getSSOData() method from Lock/auth0.js.

To learn more, read OIDC-Conformant Adoption: Single Sign-On.

Additional features