Delegation Tokens
By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate.
A delegation token should be obtained and used when an application needs to call the API of an Application Add-on, such as Firebase or SAP, registered and configured in Auth0, in the same tenant as the calling program.
Given an existing token, this endpoint will generate a new token signed with the target application's secret. This is used to flow the identity of the user from the application to an API.
The type of the delegation token varies depending on the provider. For example, if it is issued for Azure Blob Storage, it will be an SAS (Shared Access Signature). If it is for the Firebase Add-on, it will be a JWT.
The 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 an application Add-on configured in Auth0. The Add-ons for which this can be done are those that are not SAML or WS-Fed Add-ons. The Add-on must be configured in Auth0 with secrets obtained from the Add-on service, such as Firebase. Instructions for setting up the secrets are available from the Add-on configuration page for each Add-on. The secrets are used to sign the delegation token so that the Add-on API can validate and trust the token.
The delegation endpoint allows you to set several parameters which govern the contents of the delegation token including the target, the scope, the API to be called (api_type), and an additional free-form area for additional parameters.
Auth0.js example
For an example on how to get a new token for an Add-on that you have activated, using Auth0.js, refer to Delegation Token Request. Note that this example is for version 7 of the Auth0.js library; delegation is not supported in version 8 of Auth0.js.
Validity period and termination
The validity period and the ability to revoke a delegation token, varies by individual Add-on. The documentation available from the provider of any Add-on API should be consulted for further information.
Use Delegation tokens with public applications
There is an important caveat to note when using the delegation endpoint with Public Applications.
If you call the /token endpoint from a Public Application, the ID Token will be forcibly signed using RS256, even if the JsonWebToken Signature Algorithm in the Application settings is configured as HS256.
If you then subsequently call the delegation endpoint with that ID Token, it will fail if the Application's JsonWebToken Signature Algorithm was configured as HS256. This is because delegation performs validation according to the Application's settings, but the ID Token was issued with a different algorithm because of the forced algorithm change.
It is therefore important that if you intend to use delegation with a Public Application, that you configure the JsonWebToken Signature Algorithm of your application as RS256.