Migrate from Legacy Authentication Flows

When using Lock versions below 11 and Auth0.js version below 9, you could use legacy authentication flows that are deprecated. Auth0 recommends that you migrate code from older versions of Auth0.js and Lock to the new OIDC-conformant APIs.

Legacy applications used Refresh Tokens and the refreshToken() function as a way to get new tokens upon expiration (an example of this is below).

In auth0.js v9 and Lock 11 you need to use Silent Authentication and checkSession()(an example of this is below).

Legacy applications used an ID token to invoke APIs. This is a bad practice, and we recommend that you only use access tokens.

To call an API, you will need to specify the API identifier as the audience parameter when initializing auth0.js or Lock.

If you specify an audience, then the OIDC flow will be triggered and the user profile data returned by Auth0 in ID tokens or from /userinfo will be OIDC conformant. If your application is using any non-standard claim from the user profile, it will break.

See the Calling an API section of our SPA Quickstarts for more information on how to call APIs from SPAs. You will also need to migrate your backend API implementation to use Access Tokens. See API Quickstarts for instructions on how to do this.

The legacy authentication flows that allow ID Tokens and the /userinfo endpoint to include the complete user profile are being deprecated. Make sure the Legacy User Profile toggle is turned off after completing the migration to the new OIDC-conformant APIs.

When using the legacy authentication flows, the entire user profile is returned in ID Tokens and from /userinfo, as demonstrated below.

The new user profile conforms to the OIDC specification, which allows for certain standard claims to be available in the response.

The contents will vary depending on which scopes are requested. You will need to adjust the scopes you request when configuring Auth0.js or Lock so all the claims you need are available in your application. Note that you can add custom claims to return whatever data you want (for example, user metadata).

Another approach to get the full user profile is to use the Management API (instead of getting the profile through the authentication flow) as described in the next section.

In the legacy flows, the Management API supported authentication with an ID Token. This approach has been deprecated, and now you need to call it with an Access Token.

To get an Access Token, you need to ask Auth0 for one using the https://{yourDomain}/api/v2/ audience. Auth0 does not currently support specifying two audiences when authenticating, so you will need to still use your application's API audience when initializing Lock or auth0.js. Once the user is authenticated, you can use checkSession to retrieve a Management API access_token, and then call the getUser() endpoint.

You can ask for the following scopes:

• read:current_user

• update:current_user_identities

• create:current_user_metadata

• update:current_user_metadata

• delete:current_user_metadata

• create:current_user_device_credentials

• delete:current_user_device_credentials

You could get a consent_required error when calling checkSession(). If you do, make sure you have Allow Skipping User Consent enabled for the Management API and that you are not running from localhost.