Migrating 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. This document describes how to migrate code from older versions of Auth0.js and Lock to the new OIDC-conformant APIs.
Legacy applications used Access TokenRefresh 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).
Check the Silent Authentication documentation for more information on how to fully implement it in different SPA frameworks.
Restrictions on Refresh Token Usage
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. For more information on how to deal with this issue, refer to the User Profiles section.
You can check 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. You can look at our API Quickstarts for instructions on how to do this.
Get a Refresh Token
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), as described in this example.
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.
Use a Refresh Token
User Profile with Management API
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://YOUR_DOMAIN/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:
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. Check the consent documentation for more information.