Introducing OIDC Conformant Authentication

As part of our efforts to improve security and standards-based interoperability, we have implemented several new features in our authentication flows and made changes to existing ones. This document will present an overview of these changes, explain why they were made and point you to other detailed tutorials to help you adopt these changes.

We will start by reviewing the new features, continue with what changed and how you can distinguish which authentication flow is used (the latest or the legacy). Towards the end of this doc, you can find a summarizing table and links for further reading.

If you are new to Auth0, go through the What’s New section of this doc. There you can find all the cool new features we introduced, like the ability to create APIs, call them from services, or enable external parties or partners to access protected resources at your API in a secure way. Then head off to the How to use the new flows section and make sure that your new implementation follows our latest, and more secure, authentication pipeline.

If you are already using Auth0 in your app, you should read the complete doc. We have taken great care to make sure that we do not break our existing customers with this new OIDC conformant implementation, however you should be aware of all changes and new features, and how you can use them (or avoid doing so). It goes without saying that we strongly encourage you to adopt this authentication pipeline, to improve your app’s security.

Note, that if you are integrating Auth0 as a SAML or WS-Federation identity provider to your application (i.e. not through OIDC/OAuth), then you do not need to make any changes.

What's New

APIs Section in the Dashboard

You can now define your resource server APIs as entities separate from clients using our new APIs dashboard area.

APIs Dashboard

This lets you decouple your resource server APIs from the client applications that consume them and also lets you define third-party clients that you might not control or even fully trust (keep reading for more info).

For more information on APIs, their role in OAuth and how to configure an API in Auth0 Dashboard, refer to APIs Overview.

Third-Party Clients

Up until recently we were treating every client as first-party client. This means that all clients were considered trusted. Now you have the option to define a client as either first-party or third-party.

Third-party clients, are clients that are controlled by different people or organizations who most likely should not have administrative access to your Auth0 domain. They enable external parties or partners to access protected resources at your API in a secure way. A practical application of third-party clients is the creation of "developer centers", which allow users to obtain credentials in order to integrate their applications with your API. Similar functionality is provided by well-known APIs such as Facebook, Twitter, Github, and many others.

So far, third-party clients cannot be created from the dashboard. They must be created through the management API. We have also implemented Dynamic Client Registration functionality. All clients registered through that will be third-party clients.

For more information, refer to User consent and third-party clients.

Calling APIs from a Service (machine-to-machine)

We implemented the OAuth 2.0 Client Credentials grant which allows clients to authenticate as themselves (i.e. not on behalf of any user), in order to programatically and securely obtain access to an API.

For more information on the Client Credentials grant, refer to Calling APIs from a Service.

What is Changing

Calling APIs with Access Tokens

Historically, protecting resources on your API has been accomplished using ID tokens issued to your users after they authenticate in your applications. From now on, you should only use access tokens when calling APIs. ID tokens should only be used by the client to verify that the user is authenticated and get basic user information. The main reason behind this change is security. For details on refer to Why you should always use Access Tokens to secure an API.

For more information, refer to Calling your APIs with Auth0 tokens.

User Profile Claims and Scope

Historically, you were able to define and request arbitrary application-specific claims. From now on, your client can request any of the standard OIDC scopes, as defined by the OIDC Specification, or any scopes supported by your API.

In order to add custom claims to ID tokens or access tokens, they must conform to a namespaced format to avoid possible collisions with standard OIDC claims.

To customize the tokens, use Hooks for Client Credentials, and Rules for the rest of the grants:

For more information, refer to User profile claims and scope.

Single Sign On (SSO)

Initiating an SSO session must now happen only from an Auth0-hosted page and not from client applications. This means that for SSO to work, users must be redirected to an Auth0-hosted login page and redirected to your application once authentication is complete.

Support for SSO from client applications is planned for a future release.

Not all OAuth 2.0 grants support SSO at the moment:

OAuth 2.0 Grant Supports SSO?
Authorization Code Yes
Authorization Code (PKCE) Yes
Implicit Yes
Resource Owner Password No

For more information, refer to OIDC Single sign-on.

Authorization Code Grant

Some changes were introduced in the implementation of Authorization Code grant:

  • The device request parameter has been removed.
  • The audience request parameter has been introduced. This denotes the target API for which the token should be issued.
  • The returned access token is a JWT, valid for calling the /userinfo endpoint and the API specified by the audience parameter.
  • A refresh token will be returned only if the offline_access scope was granted.

For more information, refer to Authorization Code grant.

Implicit Grant

Some changes were introduced in the implementation of Implicit grant:

  • The device request parameter has been removed.
  • The audience request parameter has been introduced. This denotes the target API for which the token should be issued.
  • The response_type request parameter indicates whether we want to receive both an access token and ID token. If using response_type=id_token, we will return only an ID token.
  • Refresh tokens are not allowed. Use prompt=none instead.
  • The nonce request parameter must be a cryptographically secure random string. After validating the ID token, the client must validate the nonce to mitigate replay attacks. Requests made without a nonce parameter will be rejected.
  • The returned access token is a JWT, valid for calling the /userinfo endpoint and the API specified by the audience parameter.
  • ID tokens will be signed asymmetrically using RS256.

For more information, refer to Implicit grant.

Resource Owner Password Grant

Some changes were introduced in the implementation of Resource Owner Password grant:

  • The device request parameter has been removed.
  • The audience request parameter has been introduced. This denotes the target API for which the token should be issued.
  • The endpoint to execute token exchanges is /oauth/token.
  • Auth0's own grant type is used to authenticate users from a specific connection (realm). The standard OIDC password grant is also supported, but it does not accept Auth0-specific parameters such as realm.
  • The returned access token is a JWT, valid for calling the /userinfo endpoint and the API specified by the audience parameter.
  • The ID token will be forcibly signed using RS256 if requested by a public client.
  • A refresh token will be returned only if the offline_access scope was granted.

For more information, refer to Resource Owner Password Credentials exchange.

Delegation

Delegation is used for many operations:

  • Exchanging an ID token issued to one client for a new one issued to a different client
  • Using a refresh token to obtain a fresh ID token
  • Exchanging an ID token for a third-party API token, such as Firebase or AWS.

Given that ID tokens should no longer be used as API tokens and that refresh tokens should be used only at the token endpoint, this endpoint is now considered deprecated.

At the moment there is no OIDC-compliant mechanism to obtain third-party API tokens. In order to facilitate a gradual migration to the new authentication pipeline, delegation can still be used to obtain third-party API tokens. This will be deprecated in future releases.

For more information, refer to Delegation.

Passwordless

Our new implementation does not support passwordless authentication. We are currently evaluating this feature and our approach. We plan on supporting this in future releases.

Other Authentication API endpoints

  • /tokeninfo: With the new implementation, this endpoint is disabled.

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

  • /oauth/access_token: The /oauth/access_token endpoint, used on native social authentication on mobile devices (for example, use the Facebook SDK and then this endpoint to create the user in Auth0), is now disabled. The alternative is to open the browser to do social authentication, which is what Google and Facebook are recommending since last year.

  • /oauth/ro: Replaced in favor of password grant. This should be used only by highly trusted clients, with the current exception of native apps (not with SPAs). It's best use is to be called from the server-side of a regular web app or perhaps the backend API of a SPA.

How to use the new flows

To use the new pipeline, at least one of the following should apply:

  • The client is flagged as OIDC Conformant, or
  • The audience parameter is set in the /authorize or /token endpoints

If none of these applies, then the legacy flows will be used.

To mark your client as OIDC Conformant: go to Dashboard > click Clients > select your client > go to Settings > click the Show advanced settings link at the end > click OAuth > toggle the OIDC Conformant flag.

OIDC Conformant flag

To use the audience param instead, configure your app to send it when initiating an authorization request.

Legacy vs New

Legacy OIDC
Define APIs in the Dashboard Not Supported Supported
Third-party Clients Not Supported Supported
Client Credentials Grant This grant does not exist in the legacy pipeline, but the Resource Owner Password Credentials exchange can be used to simulate it by creating a "service user". We strongly discourage the latter approach in favor of using Client Credentials, since it allows defining fine-grained permissions for each API client. Supported
Token used to call an API ID Token Access Token
Add arbitrary claims in Tokens Supported Supported. The namespaced format has to be used.
SSO Supported Not supported for Resource Owner grant. For the rest, the users must be redirected to an Auth0-hosted login page.
Access Token format Opaque string JWT for customer APIs, opaque string for /userinfo only
Authenticate users from a specific connection (realm) Supported (using /oauth/ro) New password-realm extension grant
Passwordless Supported Not supported at the moment, will be in future releases
/tokeninfo endpoint Supported Disabled
/delegation endpoint Supported Should only be used to obtain third-party API tokens. A new mechanism will be provided in future releases.
/oauth/access_token endpoint Supported Disabled, an alternative will be added in future releases
/userinfo endpoint Supported Supported. Responses will conform to the OIDC specification, similar to the contents of ID tokens.
Refresh Tokens with Implicit Grant Supported Deprecated. Silent authentication should be used instead.
/ssodata endpoint and getSSOData() method from Lock/auth0.js Supported Deprecated. Silent authentication should be used instead.
Implicit Grant requests without nonce parameter set Supported Will be rejected.
device parameter (used to obtain refresh tokens) Supported Not supported. /oauth/token should be used instead with "grant_type": "refresh_token"
/oauth/ro endpoint Supported Replaced with Password Grant

Keep Reading