Delegation tokens are tokens used to call another API.
id_token can be exchanged for another token, called a Delegation token, that can be used to call either other application APIs registered as clients in the same Auth0 tenant or APIs represented by some types of application Addons registered in the same Auth0 tenant.
The type of the delegation token will vary depending on the target API with which it will be used. For example, if it will be used for an application/API registered in Auth0, it will be a JWT token. If the delegation token is for an application AddOn, it will vary by provider. For example, if issued for Azure blob storage, it will be a SAS (Shared Access Signature). If the delegation token is for the Firebase add on , it will be a JWT.
Further information available at: Delegation token request.
How to get a delegation token
id_token for an authenticated user can be used with the
/delegation endpoint to request a delegation token for a particular target. The target can be either another application/API registered in Auth0 or an application Addon configured in Auth0. The Addons for which this can be done are those that are not SAML or WS-Fed Addons and the Addon must be configured in Auth0 with secrets obtained from the Addon service, such as Firebase. Instructions for setting up the secrets are available from the Addon configuration page for each Addon. The secrets are used to sign the delegation token so that the Addon API can validate and trust the token.
Further information available at: Delegation endpoint.
How to control contents of a delegation token
The delegation endpoint allows the setting of several parameters which will govern the contents of the delegation token, including the
scope, the API to be called (
api_type) and an additional free-form area for additional parameters.
For customer application APIs registered in Auth0, the validity of a delegation token issued for that target is governed by the JWT Expiration (seconds) value. This is set for each application in Applications > Settings.
For APIs registered as Addons in Auth0, the validity period of the token will vary by individual Addon. The documentation available from the provider of any Addon API should be consulted for further information on tokens and expirations.
Renewing the token
When a delegation token expires, the delegation endpoint can be used to obtain a token.
Termination of tokens
The ability to revoke a delegation token will vary by individual Addon. The documentation available from the provider of any Addon API should be consulted for further information on whether a token can be revoked and if so, how to do it.
The delegation tokens for customer APIs registered in Auth0 cannot be revoked. A best practice, therefore, is to set the JWT expiration duration to a relatively short value.
Consider the following scenario. You have two web applications: appA and appB. They both need to talk to the same backend API, apiC. The steps you should follow for this configuration would be:
- Register appA and appB in Auth0. Now each app has its own client secret.
- Register your backend API apiC in Auth0. Now the API has its own client secret as well.
- Navigate to the Applications, select apiC and click on Settings > Show Advanced Settings > OAuth. In the Allowed APPs / APIs field set the applications appA and appB. This will set these two apps as clients that are allowed to make delegation requests to apiC. You have to set the client ID of your two apps in this field, separated by comma or newline.
- In your implementation, the applications appA and appB would invoke an Auth0 method (lock or SDK call) to authenticate a user and request an
- The applications appA and appB would then use the delegation endpoint to exchange the original
id_tokenfor a new token with which to call apiC.
- The generated delegation token will be signed with the target API's (apiC) client secret. The target API should validate that signature. Some information on validating tokens is here.
A delegation token should be obtained and used when a client program needs to call the API of either a) another application/API registered in Auth0 or b) the API for an Application Addon, such as Firebase or SAP, registered and configured in Auth0, in the same tenant as the calling program.
For granularity of access control, it is good to set up different applications/APIs with different secrets, so that a delegation token can be issued uniquely for each application/API.
Tokens should be issued with a short timeframe for expiration, where configurable.