Introduction

Whenever an application needs to authenticate a user or needs to obtain information about the user, various tokens are exchanged between the application and the CoreOne Authentication Service. As there are various kinds of tokens, there is usually some sort of confusion. This page tries to help you understand the various type of tokens and their intended use.

JSON Web Token (JWT)

A JSON Web Token is a standardized (RFC 7519) way of storing claims (i.e. your first or last name) in a signed token that contains a header, payload and a signature, encoded as a Base64 string. It is also the most common format to exchange any of the subsequent tokens.

An example of a JWT Token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI

Notice the three dots? They divide the token into the three party, header, payload and signature.

Access Token

Access tokens represent the credentials to access a protected resource such as your web application or an API. Any part of your system that needs authorization, can use access tokens issued by an authorization server such as the CoreOne Authentication Service. By passing the access token to the protected resource, the resource can verify the access token by verifying the signature in the JWT token.

This access token does not contain any information about the user except the ID (sub / subject).

Claims in access token

Certain claims can be limited by size in the access token, to avoid HTTP header oversize in some situations. Each claim type can be limited by setting the size limit in KB setting in the claim configuration user interface. Any value above 0 will limit the size.

If the size is reached on a claim type, the claim type claim_type_limit_reached is automatically added to the token. The claim contains a string or list of claim types that reached the limit. The claim type is still added but only filled with elements up to the limitation. It’s advised to load the data over the user info endpoint in this case. This behavior can help mitigate edge case, such as a user with several hundreds of delegations and an infrastructure that limits the HTTP header to 4 KB.

Identity Token

Whenever an application requires any information about the user that was authenticated, it should use the OpenID Connect Protocol to get an ID token. This ID token contains the requested information about a user such as the first or last name.

Refresh Token

Both the id token and the access token usually are only valid for a number of seconds as indicated in the exp claim. In order to prolong the access token, there is the concept of a refresh token that can be used to request a new access token without the users interaction. This allows an application to act on behalf of the user even beyond the users interaction. This is done by issuing a refresh token to the application. The application then can exchange that refresh token for a new access token.

Refresh Token Settings

Managing the lifetime of a refresh token is crucial for maintaining an application's security and usability. Here, the terms absolute and sliding refer to the refresh token's expiration settings.

Absolute expiration is a fixed period after which a token will expire, regardless of the user activity. Once set, the expiration time cannot be changed. This setting is crucial for scenarios where a strict policy on token lifetime is necessary due to security considerations.

For example, you might configure a refresh token to have an absolute expiration time of 30 days. Regardless of how often the user uses the token within those 30 days, it will expire at the end of that period.

Sliding expiration extends the expiration period of a token when newly issued (by the amount specified in the client configuration). This setting is useful for user experience, as active users do not need to re-authenticate or refresh their tokens as frequently.

For instance, if a sliding expiration is set for 5 days, and the user interacts with the application within those 5 days, the expiration time is reset to another 5 days from the last access, not exceeding a maximum limit if one is set (like 90 days).

Important: You can combine the absolute expiration period with the sliding expiration period. Note that the absolute expiration serves as a hard limit of the tokens total lifetime. That means, that the sliding mechanism can extend the tokens duration, as long as it doesn’t exceed the absolute expiration period.

Important: The clients needs to be explicitly authorized to request refresh tokens by setting AllowOfflineAccess to true.

Scenarios

E-Goverment: An example might be a user filling out a tax form. In this case, security is of high importance. The following settings might be helpful: Absolut for 4 hours and Sliding for 1 hour. In this case, requesting a new refresh and access token can be done 4 times, as the absolute expiration is set for 4 hours and the sliding setting is set for 1 hour.

Enterprise: An example might be an employee working with Atlassian Jira. In this case, security is of high importance, and so is user experience. The following settings might be helpful: Absolute for 8 hours and Sliding for 1 hour. In this case, requesting a new refresh and access token can be done 8 times, as the absolute expiration is set for 8 hours and the sliding setting is set for 1 hour.

Consumer: An example might be a regular user browsing a social media platform like Instagram. The user experience takes precedence. The following settings are recommended: Absolut for 1 Month and Sliding for 1 hour. These settings allow for a significant number of 720 requests for a new refresh and access token, as the absolute expiration is set for 1 Month (~approx. 720 hours) and the sliding setting is set for 1 hour.

Self-Contained vs Reference Token

Self-contained tokens are tokens that contain the claims inside a protected structure such as an JSON Web Token. The recipient of the token has all the information needed inside the token.

On the other hand, a reference token, or sometimes called opaque token, does not contain any information except the reference. This reference, an infeasible-to-guess id, can be used to access the token service in exchange for the required information by using a back-channel communication. Even though this requires additional calls to the token service, it offers greater security as the token service can immediately revoke tokens as the resource has to go through the resource service each time it needs to validate access.

To use the reference token, go into Admin UI; in the option “Access token type“, select the Reference option on the token tab.
In order to get the user claims, a call to the userinfo endpoint ({{idp_url}}/connect/userinfo) with a valid access token is needed.