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
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
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
access_token
This is received on /token
call as a header with an actual size of 16 characters by default.
Access Token Lifetime
The lifetime of an access token is configurable per client application. By default, the token expires 60 minutes after issuance. To adjust this setting, get in touch with your Next Identity consultant.
refresh_token
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
Scope | Claims |
---|---|
email , email_verified | |
address | street address , locality , country , region , postal_code |
profile | given_name , middle_name , family_name , birthdate , gender , updated_at |
phone | phone_number , phone_number_verified |
openid | sub , auth_time , acr |
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"
}
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"
}
Updated 9 months ago