As mentioned in the Application Types page, there are two types of tokens issued by GrantID:
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:
It's outside the scope of this guide to explain each of those properties so we'll focus on a few important ones:
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:
|profile||User profile||name, email, 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.
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:
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:
The Access Token purpose is to grant an user or application access to a certain resource or action.
Access Tokens may be generated in two different formats: JWT and Reference, as discussed in the following sections.
Here's an example of the payload of a JWT Access Token:
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:
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).
This type of Access Token is an Id string like the one below:
When using Reference Tokens, the application who wants to validate them must call the GrantID Introspection endpoint: