Sessions, Tokens, and Custom Claims

This document provides an overview of working with sessions, tokens, and custom claims in Next Identity.

Session Management

Next Identity Journeys Session

When a user successfully signs in and authenticates via Next Identity, a browser-based session is started. After that successful authentication, if the application calls the /authorize endpoint from that same user’s browser and the browser still has that session info stored, an authorization code will be returned. By default, this session lasts for 14 days.

📘

Security Note

A user will always be required to enter a password before changing security questions or their existing password.

Codes and Tokens

After successful sign-in by the user, they are redirected back to the redirect_uri defined in the call, and an authorization code is appended to the URL.

That authorization code would look like the following (see code parameter):

https://appauth-js.dev.nextreason.cloud/app/index.html#state=k0FfsuzmCn&code=96r7xjz8kjgj8z

authorization_code

This is a one-time use token with an actual size of 14 characters by default. It is returned by the first call (/authorize) and required on the second request (/token) in order to reach that API call and get a new pair of tokens.

id_token

This will be returned as a JSON Web Token or JWT.

📘

Technical Note

What you need to know about the id_token

• It has three distinct sections separated by a period: head, payload, and signature.
• The content is base64 encoded and this needs to be decoded to get the information being returned.
• The JWT signature is created using a private key and takes the header and the payload content to generate. So if the payload is changed, then the signature will no longer be valid.

Here is an example of a JWT:

{
    "token_type": "Bearer",
    "id_token": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2Rldi5bWU9VUiBET01BSU5dIiwic3ViIjoiYjMwNjQ3ZWYtN2YwMy00Y2UxLWFlOTEtOTQ3NmU0OWQwNjA1IiwiYXVkIjoiODk0NHJwc2FtNWNkM2twYjZ2cWFrdmFjcjZkdmdmcWYiLCJpYXQiOjE2MTAwNTI1MzAsImV4cCI6MTYxMTI2MjEzMCwibm9uY2UiOiJvQTBLN3hVU1JXOEIwWllNZ2szN3lvM0txYTdQaURFd0F2NllITURyV0dVQ0RQVDNLbyIsIm5hbWUiOiJKb2huIiwiZ2l2ZW5fbmFtZSI6IkpvaG4iLCJmYW1pbHlfbmFtZSI6IkpvbmVzIiwiZW1haWwiOiJqb2huLmpvbmVzQGVtYWlsLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwaG9uZV9udW1iZXJfdmVyaWZpZWQiOmZhbHNlLCJ1cGRhdGVkX2F0IjoiMjAyMS0wMS0wNyAyMDo0NDozNS4xNzY2MjUgKzAwMDAifQ.vdv2vnNEJduD0LVfdxqjQErCPR_Yyh2cPQBUTieEtJc",
    "access_token": "rb5bzkygqs5ahevp",
    "refresh_token": "h4zakujpack6qtfbyy8r",
    "expires_in": 3600
}

When the id_token is decoded, it will look like this:

{
  "iss": "https://[YOUR DOMAIN]",
  "sub": "b30647ef-7f03-4ce1-ae91-9476e49d0605",
  "aud": "8944rpsam5cd3kpb6vqakvacr6dvgfqf",
  "iat": 1610052530,
  "exp": 1611262130,
  "nonce": "yMLsS49XhyEcxJESP9YEN2QetYrVWVzPxJAvF7wkaDLWAn9PyK",
  "name": "John",
  "given_name": "John",
  "family_name": "Smith",
  "email": "[email protected]",
  "email_verified": true,
  "phone_number_verified": false,
  "updated_at": "2021-01-07 20:44:35.176625 +0000"
}

access_token

This is received on /token call as a header with an actual size of 16 characters by default.

refresh_token

This is received on /token call as a header, together with the access_token.

Scopes and Claims

OpenID Connect scopes are used by an application during authentication to authorize access to a user's details, like name and email. Each scope returns a set of user attributes, which are called claims. The scopes an application requests depend on which user attributes the application needs.

Token Scopes are a mechanism to limit an application's access to a user's account. An application can request one or more scopes and the access token issued to the application will be limited to the scopes granted.

Standard scopes

Custom scopes

Custom Scopes allow the application to attach additional authorizations to the token. They can be defined within the client configuration and be handed back in the token response based on what was requested. It is recommended to add custom scopes with a prefix, a scope name that makes sense, and a suffix ex: prefix:scope_name:suffix

Prefix

The prefix should denote the data source. For example, if Akamai is the source of the data being requested, you would append akamai to the scope name. If the source of data is an external service such as AWS Cognito, you would append cognito to the scope.

Scope Name

The scope name should be as human-readable as possible since its purpose is to be interpreted by downstream applications. If there is a certain group of data within Akamai then is being requested, the scope name might be something like social_profile.

Suffix

The suffix indicates the permissions that the application has by obtaining that token. Examples include read, write, delete, or * (all).

Example custom scope

akamai:social_profile:read

Custom claims

If Next Identity supports the data source, custom claims can also be associated with the scope. For example, Next Identity supports Akamai Identity Cloud as a data source, and therefore scopes associated with Akamai (prefix) can have claims outside of the standard returned in the JWT. Here is an example of Azure Active Directory as a data source. The database contains an attribute called companyName, associated with a user. So we would define a scope called: ad:user_custom:read. The client application can request that scope in the login or client credential call. Once the id_token is received and decoded, you will see that claim returned. In the below example, the client application requested the following claims:

openid email profile ad:user_custom (note that the suffix is optional in the request)

{
  "name": "John Smith",
  "nickname": "john.smith",
  "updated_at": "2017-03-30T15:13:40.474Z",
  "email": "[email protected]",
  "email_verified": false,
  "iss": "https://localhost.com",
  "sub": "USER-ID",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1490922820,
  "iat": 1490886820,
  "company_name": "Bizcorp"
}