Token Concepts

The primary role of the Token Service is to enable customers to protect data in their APIs. After authentication, clients send OAuth access tokens to APIs, which use the token scopes and claims to apply authorization rules.

Consistent User Identity

When a user authenticates and access tokens are issued, a user identifier (subject claim) is included in the access tokens. Authentication actions enable each application to receive a consistent User ID, regardless of the authentication method(s) used.

JSON Web Tokens (JWTs)

APIs receive access tokens as JSON Web Tokens (JWTs), which provide the data needed for authorization in a cryptographically verifiable format, after which this data can be trusted. The workflow for APIs then requires only simple code:

• Use a library to verify that the token is cryptographically valid and not expired
• Check that the user has access to view or change an area of data
• Apply domain-specific business rules to control access to data

Scopes

OAuth scopes are a way of separating your data according to the area of data and level of access to it, as described in Scope Best Practices. We support advanced options here, such as Prefix Scopes in Open Banking APIs hosted by banks.

Claims

APIs use claims to implement the real business authorization. In most real-world systems, this requires the capability to reach out from the Authorization Server to your APIs at the time of token issuance, to include domain-specific claims in the JWT. See the Custom Claims Tutorial for a worked example.

Opaque Access Tokens

JWTs are easily readable via tools, so we recommend against using them directly in internet clients. Instead, it is more secure to return unreadable tokens that do not reveal any private data. You may consider one of the following patterns with opaque tokens.

Phantom Token Approach

The Phantom Token Approach combines the benefits of opaque and structured tokens. When clients send opaque tokens, they are then introspected by a Reverse Proxy, which results in a JWT forwarded to APIs. See the Phantom Token Approach article for further details.

Split Token Approach

In the Split Token Approach, the access token is ultimately a JWT that is split into two parts. The client only receives an opaque part of the token and the plain part is sent to an API Gateway. When clients send their opaque tokens, the API Gateway can then assemble the complete token and forward it to the APIs. See the Split Token Approach article for a detailed description of the pattern.

Scalable Security Model

Our API security recommendations scale well to a microservices architecture, where APIs can forward the JWT when calling each other. Each API must then quickly verify the JWT before using the claims received in it. This makes the API platform secure against man-in-the-middle attacks.

Entitlement Management

The Curity Identity Server can be integrated with an Entitlement Management System if needed. This enables enterprises to externalize key authorization rules from code, so that they can be governed by security administrators instead.

Sender Constrained Tokens

For Financial-Grade API connections we support the use of sender constrained access tokens. This typically involves Mutual TLS connections and adding a verifiable public key claim to issued JWTs. This ensures that if an access token is somehow stolen, it cannot be successfully replayed by a malicious party.

Token Composition

By far, the most common use for an access token is to access your company's own data via APIs and be in full control of claims issued. In addition, it is sometimes useful to be able to sign in via an external authenticator and then access resources from external APIs:

• If a user signs in via Google, a Google token might be used to access the user's Google documents
• If a user signs in to a Merchant App via App2App Authentication, a bank token may be needed to complete an Open Banking transaction

We support various Token Sharing Approaches, and the Embedded Token option would be the best fit for these use cases.

Customization

During token issuing, claims can be issued in a dynamic manner via a Claims Value Provider. Javascript code can be used to decide what claims to add to tokens based on runtime conditions. An example might be to issue a custom claim called authentication_level based on factors used to authenticate. The API could then deny access to high privilege operations, such as payments, unless Strong Customer Authentication was used.

Conclusion

Tokens are the mechanism by which your APIs will protect your business data. Many companies need a scalable solution to cover multiple microservices. When companies follow Curity's security guidance, this requires only simple code.

Next we will drill into Data Concepts to cover the different types of data that the Curity Identity Server can manage for you.