How to implement the Implicit Grant

This tutorial will help you implement the Implicit Grant. If you are looking for some theory on the flow refer to Call APIs from Client-side Web Apps.

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.

1. Get the User's Authorization

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:

https://YOUR_AUTH0_DOMAIN/authorize?
  audience=YOUR_API_AUDIENCE&
  scope=YOUR_SCOPE&
  response_type=YOUR_RESPONSE_TYPE&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback&
  nonce=YOUR_CRYPTOGRAPHIC_NONCE
  state=YOUR_OPAQUE_VALUE

Where:

  • audience: The unique identifier of the API the app wants to access. Use the value of the Identifier field at your API Settings. If you can't see this page, enable the Enable APIs Section toggle at Account Settings > Advanced.

  • 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 profile and email, custom claims that must conform to a namespaced format (see panel below for more info), or any scopes supported by the target API (for example, read:contacts). Note that user's consent will be requested, every time the scope value changes.

    Custom claims namespaced format

    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.

  • response_type: Indicates the type of credentials returned in the response. For this flow you can either use token, to get only an access_token, or id_token token, to get both an id_token and an access_token.

  • client_id: Your application's Client ID. You can find this value at your Client'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 Client's Settings.

  • state: An opaque value the client adds to the initial request that Auth0 includes when redirecting back to the client. This value must be used by the client to prevent CSRF attacks, click here to learn more.

  • nonce: A string value which will be included in the response from Auth0, used to prevent token replay attacks. It is required for response_type=id_token token.

For example:

<a href="https://YOUR_AUTH0_DOMAIN/authorize?scope=appointments%20contacts&audience=appointments:api&response_type=id_token%20token&client_id=YOUR_CLIENT_ID&redirect_uri=https://YOUR_APP/callback">
  Sign In
</a>

2. Extract the Access Token

After Auth0 has redirected back to the app, you can extract the access_token from the hash fragment of the URL:

function getParameterByName(name) {
  var match = RegExp('[#&]' + name + '=([^&]*)').exec(window.location.hash);
  return match && decodeURIComponent(match[1].replace(/\+/g, ' '));
}

function getAccessToken() {
  return getParameterByName('access_token');
}

function getIdToken() {
  return getParameterByName('id_token');
}

$(function () {
  var access_token = getAccessToken();

  // Optional: an id_token will be returned by Auth0
  // if your response_type argument contained id_token
  var id_token = getIdToken();

  // Use the access token to make API calls
  // ...
});

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:

// Use the access token to make API calls
$('#get-appointments').click(function(e) {
  e.preventDefault();

  $.ajax({
    cache: false,
    url: "http://localhost:7001/api/appointments",
    headers: { "Authorization": "Bearer " + access_token }
  });
});

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:

function(user, context, callback) {

  // add custom claims to access token and ID token
  context.accessToken['http://foo/bar'] = 'value';
  context.idToken['http://fiz/baz'] = 'some other value';

  // change scope
  context.accessToken.scope = ['array', 'of', 'strings'];

  callback(null, user, context);
}

Namespacing Custom Claims

You must properly namespace your custom claims with URI format to avoid conflicting with spec claims.

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.

Keep reading

 Implicit Grant overview
 How to protect your SPA against replay attacks
 Silent authentication for SPAs
 How to configure an API in Auth0
 Why you should always use access tokens to secure an API
 Single Page App Quickstarts
 ID Token
 Access Token
 Client Authentication for Client-side Web Apps
 Authentication API: GET /authorize
 The OAuth 2.0 protocol
 The OpenID Connect protocol
 Tokens used by Auth0
 RFC 6749: The OAuth 2.0 Authorization Framework