Tokens and scopes

Understand token based authentication and master the use of scopes to add fine grained control to your applications.

As mentioned in the Application Types page, there are two types of tokens issued by GrantID:

  • Identity tokens: contain information about an user.
  • Access tokens: contain information about what a user can do or access. It may also contain user information.

The Identity Token


The identity token is normally issued when a user logs in an application configured in GrantID. The only format supported for this type of token is the JWT format.

Here's an example of what the token payload looks like:

{
  "nbf": 1486127418,
  "exp": 1486127718,
  "iss": "https://mysub.grantid.com",
  "aud": "my-app",
  "nonce": "636382263039998929.YTc2NTM0NWQtNjA5Ni00YWE5LTk0NjgtMGZlZWYyZjczYWYxOWE0NTE1MjYtZGRkOS00YmRmLTg3ZjYtNDM3NmZjNDgxMzEy",
  "iat": 1486127417,
  "c_hash": "Rzz43NRKEt5UIFJ6kyJ_jw",
  "sid": "eb051224b1d407911946fe341ccdc769",
  "sub": "26cf5325-23b4-47a3-af5b-a5211e386da8",
  "auth_time": 1486127409,
  "name": "John Doe",
  "email": "john.doe@email.com",
  "phone": "+5500000000000",
  "amr": [
    "pwd"
  ]
}

It's outside the scope of this guide to explain each of those properties so we'll focus on a few important ones:

  1. sub: the unique Id of the authenticated user.
  2. name: the name of the user.
  3. email: the email of the user.
  4. phone: the phone number of the user.

In the GrantID Management console, user informations are refered to as claims.

The claims that are inserted in the Identity Token can be configured by setting which Identity Scopes are allowed to be requested by an application.

The image below shows how to select the allowed Identity Scopes in the Application Settings page:

An Identity Scope has a name, display name and a set of claims. GrantID provides a couple of default scopes that include basic user claims:

Name Display Name Claims
openid User identifier sub
profile User profile name, email, phone
name Name name
email Email email
phone Phone number phone

Note that the application, when redirecting to GrantID, must request the scopes that correspond to the claims it wants to be inside the token.

The Identity Token displayed in the beginning of this section was issued by requesting the "openid" and "profile" scopes.

Adding Custom Information


At any given time, you may need that additional information about the users are stored in GrantID. To do so, you need to add a custom claims that correspond to the informations you want to add.

Go to your subscription's home page and select the Scopes tab. In the Custom Claims, section click the button to add a New Claim:

Fill the information to create the new Claim:

Now, go to the Custom Identification Scopes section in the same page. There, you can create a custom identification scope and select the claim you've just created as well as other claims available:

Finally, return to the Application Settings page and note that the created scope now appears as an option in the Allowed Identification Scopes:

Requiring Custom Information


In the last section, you've learned how to create custom claims and identity scopes. But if an user does not have a value that corresponds to that claim stored in GrantID, there won't be any information to add in the Identity Token.

Adding the value for a custom claim can be done in two ways: using our REST API or by configuring the claim to be required in the application. Only the latter will be presented in this section.

Go to the Application Settings page and find a section named Required Claims. If you have custom claims registered in the application's subscription it will present them as the image shows:

When you mark custom claims as required, GrantID will change the behavior of two process:

  • Sign up: when a user signs up (from the configured application) he will be required to fill information about all of the custom claims marked.
  • Log in: after the login (requested by the configured application), if the user does not have a value to any of the custom claims marked as required, he will be redirected to a special page to fill the missing information.

The Access Token


The Access Token purpose is to grant an user or application access to a certain resource or action.

  • User Access Tokens are generally issued when a user logs in applications of type Implicit, Code or Hybrid just as the Identity Tokens.
  • Application Access Tokens, on the other hand, are normally issued by applications of type Client Credentials.

Access Tokens may be generated in two different formats: JWT and Reference, as discussed in the following sections.

JWT Access Token


Here's an example of the payload of a JWT Access Token:

{
  "nbf": 1486127410,
  "exp": 1486130410,
  "iss": "https://mysub.grantid.com",
  "aud": "https://mysub.grantid.com",
  "client_id": "my-app",
  "sub": "26cf5325-23b4-47a3-af5b-a5211e386da8",
  "auth_time": 1486127409,
  "scope": [
    "openid",
    "profile"
  ],
  "amr": [
    "pwd"
  ]
}

It is quite similar to the Identity Token, but instead of having user information, it has the scope property which indicates all of the scopes granted to the holder of the token.

Note that the scopes in the presented token are actually Identity Scopes. They are included so that the holder of the token can retrieved information about the user by accessing the User Info Endpoint:

GET /connect/userinfo
Host: mysub.grantid.com
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/json

{
    "sub": "26cf5325-23b4-47a3-af5b-a5211e386da8",
    "name": "John Doe",
    "email": "john.doe@email.com",
    "phone": "+5500000000000"
}

In order to protect a resource, you need to define API Scopes which are grouped by API Connections. Let's assume that one of your applications is a library website and that your users need to be able to view the books they have checked out.

Go to the Subscription Home page and find the API Connections section:

Select the New API connection button and provide a name and display name:

An API Scope is automatically added when the API Connection is created. The scope's name may not be changed as it must correspond to the connection's name:

Create a new scope named "library-api-checked-books":

After the API Scope is configured, you need to allow the scope to be granted to users of an application. This is done in the Application Settings Page:

Just as with Identity Scopes, the API Scopes need to be requested by the application during login.

After the settings are saved, the created API Scope will be added to the Access Token after a user logs in.

The last step is changing the library website so it checks if the Access Token provided by the user contains the required API Scope (library-api-checked-books).

Reference Token


This type of Access Token is an Id string like the one below:

a7b37cdcb8cdf7dd93ad103898f6c4f3d4c0dbf3499b96d1c2710eb8cf914b53

When using Reference Tokens, the application who wants to validate them must call the GrantID Introspection endpoint:

POST  /connect/introspect
Host: mysub.grantid.com
Content-Type: application/x-www-form-urlencoded

token=a7b37cdcb8cdf7dd93ad103898f6c4f3d4c0dbf3499b96d1c2710eb8cf914b53&
token_type_hint=access_token&client_id=<Api_Connection>&
client_secret=<Api_Connection_Secret>
HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": true,
  "nbf": 1486127410,
  "exp": 1486130410,
  "iss": "https://mysub.grantid.com",
  "aud": ["https://mysub.grantid.com", "<Api_Connection>"],
  "client_id": "my-app",
  "sub": "26cf5325-23b4-47a3-af5b-a5211e386da8",
  "auth_time": 1486127409,
  "amr": "pwd",
  "scope": "<Api_Connection> scope1 scope2"
}
  • The client_id parameter is the name of the API Connection whose scopes the application wants to validate.

    Only the scopes contained in the API Connection will be returned in the response.

  • The client_secret parameter is a API Connection secret that can be generated in the API Connections section of the Subscription Home page:
  • The active property in the response indicates if the token is valid. If it isn't valid, the other properties will not be returned.

The instrospection endpoint may also be used with a JWT token by sending it as the token parameter.

This is useful when the application that needs to validate the token is developed in a language that does not have available libraries for JWT validation.