4 mins read

Security Tokens - Get Access, ID, Refresh Tokens

Utilize different types of security tokens: access (JWT or opaque), ID, and refresh tokens.

OAuth Security Token Service

Cloudentity authorization servers are capable of minting and issuing different types of security tokens:

Each token type can be configured according to the organization needs.

Access Tokens for Client Authentication

Access token is used by the client application for making API calls to access specific resources on behalf of their owner. Which particular resource the client can access is determined by scopes included in the token payload. A token with relevant scopes attached allows the client to access a specific resources and/or perform particular actions.

You can choose between two types of access tokens:

  • JSON Web Tokens (JWT)

    JWT is an open standard that provides a secure way for authenticating data owners and transmitting information between parties using the JSON format. JWT is sent in the HTTP request with a digital signature. It can be signed using a secret (with the HMAC algorithm) or a public/private key pair (with RSA or ECDSA).

    To create a digital signature, Cloudentity signs JWT with its private key. When the client application gets the JWT from Cloudentity, it can verify if the JWT is signed by Cloudentity by using the public key of Cloudentity. Since the digital signature uses the private key of Cloudentity, the only party that could create the signature is Cloudentity, which proves the legitimacy of the JWT.

  • Opaque Tokens

    The opaque token is a random unique string of characters issued by the Cloudentity authorization server. It is one of the possible formats that access tokens or refresh tokens can take. The opaque token does not pass any identifiable information on the user so it’s impossible for the resource server to make any authorization decisions based on the opaque token itself. The opaque contains an identifier to information stored on the authorization server. To validate the token and retrieve the information on the token and the user, the resource server calls the authorization server and requests the token introspection.

ID Tokens

Utilize ID tokens to provide applications with user information. The ID token is a security token that includes claims regarding the authentication of the user by the Cloudentity authorization server with the use of an OAuth client application. The ID token may also include other requested claims. It is created on the Cloudentity authorization server’s side to encode the user’s authentication information. Unlike access tokens intended to be consumed by the resource server, ID tokens are intended to be consumed by the third-party application.

ID Token Encryption

A client can choose to receive encrypted ID Tokens. The client that receives the encrypted ID Token can choose what information to share with the browser, for example via an API call. It also prevents the browser from leaking Personally Identifiable Information (PII) and protects against the ID Token being logged and having its content exposed. This is also a requirement for Financial-grade API (FAPI).

ID Token Encryption is done following the JSON Web Encryption specification - RFC-7516.

There are two serialization mechanisms for JWEs as per RFC7516:

  • a compact, URL-safe serialization called the JWE Compact Serialization
  • a JSON serialization called the JWE JSON Serialization.

Cloudentity uses the JWE Compact Serialization.

To enable ID Token Encryption in Cloudentity the client must provide a public key to be used for encrypting the Content Encryption KEY (CEK) using their public key. Cloudentity encrypts the ID Token using this public key and the ID Token encryption algorithm configured at client level.

Refresh Tokens

Refresh tokens are long-lived tokens used to acquire a new access token when the present access token gets invalid or expires. They enable the client to get a new access token without prompting the user.

Refresh tokens are long-lasting artifacts. They are long-lived tokens with TTLs up to a few years.

In Cloudentity, there are TTLs for refresh tokens predefined per workspace (authorization server).

Signing Keys

You can configure your signing keys in your workspace settings. You can set up the automatic key rotation mechanism there. You can manually rotate key for security purposes. In this case, you can either rotate the key currently in use or rotate and revoke the key.

Cloudentity stores up to 8 rotated keys and up to 16 revoked keys.

Cloudentity supports two types of algorithms to sign tokens: ECDSA and RSA. By default, authorization servers use the ECDSA algorithm to sign tokens except servers of the Workforce type that use the RSA algorithm. You can choose your key type when rotating keys. If you set your key, for example, to be of the RSA type, all next rotated keys are of the type you had chosen.

Changing signing algorithm type

Updated: Sep 28, 2023