Skip to main content

Token Management

The primary goal of authenticating with remote systems is to ultimately use the resulting credentials (access tokens, API keys, etc) to interact with a remote server. Authentication is only a means to an end, providing a client with access to a remote Resource Server.

As a result, the Okta Client SDK features a central set of capabilities which validates, stores, secures, and maintains the lifecycle of these credentials to enable client applications to simply and securely access remote API resources.

Problem statement​

The primary goal of the token management system is to simplify the storage and retrieval of tokens, allowing developers to focus on their use-cases as opposed to fighting with the security and encryption lifecycle of these tokens. A lot of real-world concerns exist within the area of token storage, such as:

  • Multi-threaded access to shared resources
  • Data race conditions during asynchronous operations
  • Biometrics and secure storage requirements
  • Developer features for querying & differentiating tokens

Some of these are obvious, but there are a few important scenarios that should be called out explicitly.

Multi-token storage​

The Token object is the logical representation of the full details of a token response from an Authorization Server, including the access_token, refresh_token, id_token, and other values. It is intended to be an immutable object which can safely be passed across threading contexts, and avoiding race conditions. It also aims to ensure all token strings associated with a logical identity are consistently stored together.

There are scenarios where a developer will want to store / manage multiple sets of these tokens, keeping them alive/refreshed, to support advanced patterns such as multiuser apps, different sets of tokens with escalated scopes or permissions, or to manage tokens that reference different authroization servers altogether.

This token storage system therefore provides capabilities that enable the CRUD operations against secure storage, as well as advanced query features to simplify how develoeprs can filter out the appropriate token for their specific use-case.

Common concurrent operations​

Not only can developers store multiple sets of tokens, this token storage system supports the idea of a "default" token, simplifying common single-user applications. Tokens are often fetched, defaults assigned, and tokens refreshed all within a short period of time. Furthermore, developer applications are often quite complex, with different parts of their app performing multiple actions simultaneously.

As a result, this token storage system should be very stable and thread-safe, guaranteeing concurrent access to shared resources.

For example, when a token is refreshed, its current value is first fetched from storage to trigger a refresh operation, and then its value is merged and updated with the new response before being updated back in storage. During the runtime of an app, especially during application start/initialization, many concurrent operations are made to Token Storage which can result in data races that affect the stability of the SDK and the developer's app.

Feature design​

The public API surface area of this feature should be as convenient as possible for developers, ensuring that all access patterns support synchronous access. The primary capabilities are:

  1. Developer stores a Token with an optional set of tags and security options, returning a Credential that wraps it.
  2. Developer gets a single Token by its unique ID.
  3. Developer assigns tags to a Credential that can be used to fetch it later.
  4. Developer fetches an array of Credentials filtered using tags assigned to it.
  5. Developer fetches an array of Credentials filtered using claims present in the ID Token.
  6. Developer updates tags assigned to a Credential by setting them to the object's tags property.
  7. Developer removes a Credential from storage without revoking it.
  8. A Credential is automatically removed from storage when it is revoked.
  9. A Token is automatically updated in storage when it is refreshed.
  10. Only a single instance of a Credential should be created for a corresponding Token.

Architecture Design​

This consists of multiple capabilities and classes, but overall this area is described as the Token Management system. The primary components are:

NameDescription
CredentialWrapper that provides a runtime abstraction for a Token.
TokenImmutable value that represents a set of OAuth2 tokens.
TokenStorageImplements the secure storage of OAuth2 Token objects.
CredentialDataSourceFactory that produces Credential instances, ensuring consistent shared access to these Credential objects.
CredentialCoordinatorOrchestrates the relationship between the TokenStorage, CredentialDataSource, Token, and Credential objects.

Entity Relationship​