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.

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:

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"
}