How to implement the Implicit Grant
The Implicit Grant is an OAuth 2.0 flow that client-side apps use in order to access an API. In this document we will work through the steps needed in order to implement this: get the user's authorization, get a token and access an API using the token.
Before you begin this tutorial, do the following:
First, your app should get consent from the user to invoke the API on their behalf. Auth0 will authenticate the user and obtain consent, unless consent has been previously given.
To initiate the flow, send the user to the authorization URL:
audience: The unique identifier of the API the app wants to access. Use the Identifier value on the Settings tab for the API you created as part of the prerequisites for this tutorial.
scope: The scopes which you want to request authorization for. These must be separated by a space. You can request any of the standard OIDC scopes about users, such as
read:contacts). Note that user's consent will be requested, every time the
scopevalue changes. The custom scopes must conform to a namespaced format. For more information on this, refer to the Namespacing Custom Claims panel.
response_type: Indicates the type of credentials returned in the response. For this flow you can either use
tokento get only an Access Token,
id_tokento get only an ID Token (if you don't plan on accessing an API), or
id_token tokento get both an ID Token and an Access Token.
client_id: Your application's Client ID. You can find this value at your Application's Settings.
redirect_uri: The URL to which the Auth0 will redirect the user's browser after authorization has been granted by the user. The Access Token (and optionally an ID Token) will be available in the hash fragment of this URL. This URL must be specified as a valid callback URL under your Application's Settings.
state: An opaque value the application adds to the initial request that Auth0 includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks. For more information, see State Parameter.
nonce: A string value which will be included in the response from Auth0, used to prevent token replay attacks. It is required for
2. Extract the Access Token
After Auth0 has redirected back to the app, the hash fragment of the URL contains the following parameters:
id_token: contains an ID Token and is present if the request parameter
response_typeincluded the value
id_token, or the
scoperequest parameter the value
access_token: contains an Access Token and is present if the request parameter
response_typeincluded the value
token_type: denotes the type of the Access Token
expires_in: the lifetime in seconds of the Access Token. For example, the value
3600denotes that the Access Token will expire in one hour from the time the response was generated
state: present in the response if the
stateparameter was present in the request. Holds the exact value received from the client in the request.
You can extract the
access_token, and other parameters, from the hash fragment of the URL:
3. Call the API
Once you have the
access_token you can use it to make calls to the API, by passing it as a Bearer Token in the
Authorization header of the HTTP request:
4. Verify the Token
Once your API receives a request with a Bearer
access_token, the first thing to do is to validate the token. This consists of a series of steps, and if any of these fails then the request must be rejected.
For details on the validations that should be performed by the API, refer to Verify Access Tokens.
Optional: Customize the Tokens
You can use Rules to change the returned scopes of the Access Token and/or add claims to it (and the ID Token) with a script like this:
Namespacing Custom Claims
Auth0 returns profile information in a structured claim format as defined by the OIDC specification. This means that 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. For example, if you choose the namespace
https://foo.com/ and you want to add a custom claim named
myclaim, you would name the claim
https://foo.com/myclaim, instead of
myclaim. You can add namespaced claims using Rules.
If you wish to execute special logic unique to the Implicit grant, you can look at the
context.protocol property in your rule. If the value is
oidc-implicit-profile, then the rule is running during the Implicit grant.
Optional: Silent Authentication
If you need to authenticate your users without a login page (for example, when the user is already logged in via SSO scenario) or get a new
access_token (thus simulate refreshing an expired token), you can use Silent Authentication.
For details on how to implement this, refer to Silent Authentication.
For an example implementation see the SPA + API architecture scenario.
This is a series of tutorials that describe a scenario for a fictitious company. The company wants to implement a single-page web app that the employees can use to send their timesheets to the company's Timesheets API using OAuth 2.0. The tutorials are accompanied by a sample that you can access in GitHub.