742 VIEWS
Pinterest LinkedIn LINE

As many of you may know, I serve as an outside director of Authlete12 Despite that, I had not kept up with the latest developments, so I decided to learn from a video of Mr. Morikawa’s recent seminar. Another reason is that, for the past several weeks, the FAPI WG has been wrestling with how to write implementation guidance on behavior during refresh-token rotation.

In the video, Mr. Morikawa introduced Authlete features that enable OAuth and OIDC profiling. The main topics are as follows:

  1. What profiling means: selecting among OAuth/OIDC specification options and making detailed configuration choices.
  2. Introduction to Authlete: a Web API service for building OAuth/OIDC authorization servers and identity providers.
  3. Token-issuance context: token lifecycle management and the circumstances behind issuance.
  4. Client characteristics: managing client attributes as key-value pairs and using them in authorization decisions.
  5. Scope management: fine-grained management of scopes and flexible authorization requests using RAR3.
  6. Assurance of entities and messages
    • Client authentication: support for multiple authentication methods.
    • Request and response protection: support for PKCE, PAR, and JARM.
  7. Resource-owner intent: improving security and user experience.
  8. Characteristics of issued tokens: configuring and managing validity periods, attributes, and proof of possession (mTLS and DPoP).
  9. Post-issuance token management: rotation and refresh-token idempotency.
  10. Token Revocation API: an introduction to a new API for invalidating tokens.

Below, I will examine each topic in a little more detail. As usual, this summary makes extensive use of Otio AI. It also includes some material that supplements the original video.4 As always, I would appreciate being told about any errors.

Watch this video on YouTube.
Playing the video connects to YouTube.

What Is Profiling? (0:48)

Profiling means making the detailed configuration choices required when applying OAuth or OIDC in practice. Specifically, it includes selecting the necessary options provided by the specifications, deciding which later extensions to use, and making various decisions even outside the specifications’ scope. User authentication and scope configuration are typical examples. Profiling includes the following:

  • The work of making detailed configurations and choices needed to apply OAuth/OIDC in practice.
  • Selecting what is needed from the options defined by the specifications and deciding how to use extension specifications.
  • Making many decisions outside the specifications’ scope as well (for example, user authentication and scope configuration).
  • Defining details such as scope names and structure.

Introduction to Authlete (1:35)

Authlete is a service that provides, through Web APIs, the components needed to build authorization servers and identity providers. It enables developers to implement complex OAuth/OIDC protocol processing and token lifecycle management more easily. Its main features include the following:

  1. Provided as Web APIs:
    • Authlete provides authorization-server functions as Web APIs. Developers can therefore invoke authorization processing easily from their own applications.
  2. Authorization engine and OIDC engine:
    • Authorization servers and identity providers are often described as an “authorization engine” or “OIDC engine.” This reflects Authlete’s flexibility in supporting multiple specifications and profiles that can be freely selected and implemented.
  3. OAuth/OIDC Components as a Service:
    • Authlete has increasingly been introduced as “OAuth/OIDC Components as a Service.” This means that it goes beyond merely providing APIs and comprehensively supplies the components required to build and operate an authorization server.
  4. Protocol processing and token lifecycle management:
    • Authlete checks the parameters of an authorization request it receives and indicates the next step based on the result. This flow includes examining the request information and, if there is no problem, issuing tokens and managing their lifecycle.
  5. Support for diverse specifications and profiles:
    • Authlete supports the implementation of many OAuth/OIDC specifications and profiles. Developers can freely select and implement the specifications best suited to their use cases.
  6. Knowledge Base:
    • Authlete operates a Knowledge Base that publishes information about Authlete’s features and how to use them. It also provides non-users with information useful for designing and implementing OAuth/OIDC servers.

Authlete offers a comprehensive solution for easily building and operating authorization servers and identity providers. Its ability to support various specifications and profiles gives developers considerable freedom.

Token-Issuance Context (03:42)

The circumstances and background—the context—leading to token issuance consist of many different factors. Understanding this context clarifies how access control and authorization processes are constructed. The principal elements are as follows:

  1. Client characteristics:
    • The authorization server manages many client attributes, such as whether a client is a first-party or third-party application, a confidential or public client, and a web or native application.
    • Authlete manages client attributes as key-value pairs and uses them when making authorization decisions in response to authorization requests.
  2. Scopes:
    • Scopes describe permissions to operate on resources, but because they are defined as simple strings, detailed permission management can sometimes be difficult with scopes alone.
    • Authlete provides scope attributes, allowing arbitrary information to be associated with a scope as key-value pairs. It can also restrict which scopes each client may request.
  3. Assurance of entities and messages:
    • This includes client authentication and request/response protection, such as PKCE, PAR, and JARM.
    • It supports configuration of client-authentication methods and ways to protect request parameters.
  4. Resource-owner intent:
    • The scopes requested in an authorization request can be presented to the end user, who can choose which scopes to permit. This can also be implemented using Authlete’s APIs.
  5. Token lifecycle:
    • Authlete manages the lifecycle of access and refresh tokens from issuance through use, renewal, invalidation, and deletion.
    • It also provides functions for configuring each token’s validity period by authorization server, scope, and client.
  6. Proof of possession (PoP):
    • Using mTLS or DPoP provides a mechanism for proving that the party using an access token is its legitimate holder.

Through these elements, Authlete supports complex authorization processes and token lifecycle management. Its varied configuration options and functions for authorization decisions and token management let developers select and implement the arrangement best suited to their applications.

Client Characteristics (05:20)

Client characteristics play an important role when an authorization server issues tokens. The following elements are considered:

  1. Controlling organization:
    • The distinction between first-party applications and third-party applications.
    • A first-party application is managed directly by the developer, while a third-party application is provided by another party.
  2. Client type:
    • The distinction between confidential clients and public clients.
    • A confidential client can securely hold a client secret (for example, a server-side application).
    • A public client cannot securely hold a client secret (for example, a native application or single-page application).
  3. Application type:
    • Characteristics vary according to whether the client is a web application, native application, or single-page application (SPA), among other forms.
  4. Client-attribute management:
    • Authlete lets you manage arbitrary attributes for each client as key-value pairs.
    • This allows authorization requests to be handled flexibly according to the information configured as client attributes.
  5. Processing authorization requests:
    • The authorization server refers to the client ID in an authorization request received from a client and checks the client attributes associated with it.
    • It uses this client-attribute information to make the authorization decision.

Example Client-Attribute Configuration

In Authlete’s management console, client attributes can be configured as follows:

  • Key: affiliation
  • Value: partner

Based on this information, the authorization server can apply processing specific to a particular client.

Examples

  • First-party client (an in-house application): permit requests for highly privileged scopes.
  • Third-party client (an external application): permit only limited scopes.

This is an overview of client characteristics and how to manage and use them. For details, see the client-attributes Knowledge Base article.

Scope Management (07:02)

In OAuth and OIDC, a scope is a parameter that represents permission to access a resource. Scope management is important because configuring and restricting scopes controls the extent of access available to users and clients. Authlete provides several scope-management features:

  1. Basic scope structure:
    • Scope parameter: A scope is defined as a simple string and included in a request to ask for a particular permission. A scope name alone, however, may not express the permission in sufficient detail.
  2. Structuring scopes:
    • Scope attributes: Authlete provides a scope-attribute function that associates arbitrary information with a scope as key-value pairs. This makes it possible to manage detailed scope metadata.
    • Example scope:
      • Scope name: read_profile
      • Scope attribute: a key-value pair (for example, key level and value high)
    The management-console UI can be used to configure each scope in detail.
  3. Per-client scope restrictions:
    • Authlete can restrict which scopes each client may request, allowing fine-grained control over the scopes available to a particular client.
    • Example: Client A is permitted only the read_profile scope, while Client B is permitted the read_profile and edit_profile scopes.
  4. Dynamic scopes:
    • Dynamic scopes: This technique parameterizes scope names. For example, a scope name and additional information can be combined as in consent:12345.
    • Regular expressions: Regular expressions can be applied to scope names to generate names dynamically that meet specified requirements. In Authlete, dynamic scopes can be managed by specifying a regular expression as a scope attribute.
  5. Rich Authorization Requests (RAR):
    • RAR (Rich Authorization Requests): An extension specification that enables authorization requests more detailed and flexible than scopes. It uses the authorization_details parameter to specify finer-grained access rights.
    • Authlete allows RAR settings to be configured per client, enabling detailed permission management.

Scope-Management Configuration Example

In Authlete’s management console, scopes and attributes can be configured as follows:

  • Scope name: read_profile
  • Attribute key: level
  • Attribute value: high

This enables detailed management of the read_profile scope.

Assurance of Entities and Messages (10:06)

Client Authentication (10:50)

Client authentication is essential for secure communication between a client and an authorization server. A confidential client, in particular, is required to authenticate at the token endpoint. This includes the following:

1. Choosing an Authentication Method

  • The principal client-authentication methods are:
    • Client secret: The most basic method, using a client ID and client secret (equivalent to a password).
    • Client certificate (mTLS): A client certificate is used to establish mutual TLS and authenticate the client.
    • JWT-based authentication: Client authentication using a JSON Web Token (JWT).
    • Other methods: Some clients may require device-specific methods.

2. Configuration in Authlete

  • Authlete lets a service (authorization server) define the set of client-authentication methods it supports. This determines which methods the authorization server permits.
  • Client configuration: The authentication method used by each client is configured individually. This permits an appropriate method to be selected for each client while maintaining the required security level.

3. Functions Provided by Authlete

  • Enforcement: Authlete can enforce the use of authentication methods, including requiring a particular method for all clients.
  • Flexible configuration is possible at both the service and client levels, enabling authentication that meets the applicable security requirements.

4. Examples

  • Service configuration: In Authlete’s management console, configure the client-authentication methods supported by the authorization server, such as client_secret_basic, client_secret_post, and client_secret_jwt.
  • Client configuration: In each client’s configuration, select the method it will use from those above. For example, one client can use client_secret_basic while another uses client_secret_jwt.

Authlete also supports PKCE[RFC7636]5. Although it is not client authentication as such, PKCE is mandatory for public clients and is now regarded as required for other clients as well.

Request and Response Protection (12:02)

Authlete supports PKCE, PAR, and JARM for request and response protection.

PKCE (12:02)

Overview

  • Description: PKCE is an extension that secures OAuth 2.0 authorization-code flows. It was designed especially to improve security for public clients.
  • Why it was introduced: It reduces the risk that an authorization code will be stolen from a public client, such as a mobile or single-page application, that cannot securely hold a client secret.

How It Works

  • Code challenge: When making an authorization request, the client sends a parameter named code_challenge.
  • Code verifier: In the subsequent token request, the client sends a code_verifier. The authorization server compares it with the code_verifier‘s corresponding code_challenge and issues a token if they match.

Authlete Support

  • Enforcement: Authlete has a setting that enforces PKCE, for example by requiring it for every client.
  • Specifying the challenge method: A code-challenge method such as S256 can also be required.

PAR [RFC9126] (13:36)

Overview

  • Description: PAR is a specification for registering authorization-request parameters with the authorization server in advance and protecting them. It reduces security risks caused by sending an authorization request through the user agent (browser).
  • Why it was introduced: It prevents tampering that could occur when authorization-request parameters are exposed in the front end.

How It Works

  • Advance registration: Send all authorization-request parameters, including client authentication, to the authorization server in advance.
  • Request URI: The authorization server returns a request URI, which is then used to make the authorization request.

Authlete Support

  • Dedicated API: Authlete provides a dedicated API for processing PAR requests, making it easy for an authorization server to implement PAR.

JARM (14:43)

Overview

  • Description: JARM6 protects authorization responses in JWT format, ensuring their integrity and trustworthiness.
  • Why it was introduced: Encrypting and signing the authorization response prevents it from being altered in transit.

How It Works

  • JWT format: The authorization server returns the authorization response as a JWT (JSON Web Token). The JWT is signed and may also be encrypted.
  • Response validation: On receiving the response, the client validates the JWT and confirms its integrity and the legitimacy of its issuer.

Authlete Support

  • Multiple signing algorithms: Authlete supports multiple signing and encryption algorithms for JARM responses.
  • Configuration flexibility: JARM use can be configured per client.

Resource-Owner Intent (15:13)

Resource-owner intent refers to the process of making clear which scopes the resource owner—normally the end user—permits when an authorization request is made. Authlete can be used to construct flexible authorization flows that reflect that intent.

1. Basic Concept

  • User participation: Present the scopes included in the authorization request to the resource owner and let them choose which to permit.
  • Flexible consent: Letting the resource owner permit only particular scopes prevents excessive privileges from being granted.

2. Implementation

  • Using Authlete’s APIs: Authorization-request processing can be customized so that a resource owner reviews and selects scopes in a user interface (UI) built by the organization itself.
  • Knowledge Base guide: The Authlete Knowledge Base explains concrete implementation steps in detail.
    • Present the scopes requested in the authorization request to the end user.
    • The end user selects the scopes to permit.
    • Generate the final authorization response from that selection.

3. Example

  • Presenting the authorization request:
    1. Receive an authorization request from the client.
    2. Display the requested scopes, such as read_profile and edit_profile, to the resource owner in the UI.
    3. The resource owner selects particular scopes—for example, only read_profile.
  • Permitting scopes and returning the response:
    1. Determine the final scopes based on the resource owner’s selection.
    2. Generate an authorization response containing the selected scopes.
    3. Include only the selected scopes in the authorization token.

4. Using the Knowledge Base

  • Concrete code and guidance:
    • The Authlete Knowledge Base contains concrete API examples and code samples for implementing these processes.
    • It provides implementation details and step-by-step guides that can make development more efficient.

Designing an authorization flow that reflects the resource owner’s intent gives end users finer-grained control and can improve both security and user experience. Authlete’s functions make this process straightforward to implement.

We have now reached token issuance. Next, I will explain the characteristics of the tokens that are issued.

Characteristics of Issued Tokens (16:05)

Validity Period

  • How it is determined: A token’s validity period can be configured at the authorization-server, scope, and client levels. A particular validity period can also be supplied as a request parameter when the token is issued.
  • Precedence: When multiple conditions apply, the shortest validity period is used.
  • Configuration flexibility: Authlete allows each token’s validity period to be finely configured in seconds. It also provides an API that can change the period dynamically at issuance to meet particular conditions.

Token Attributes

  • Overview: Arbitrary attributes can be associated with a token as key-value pairs.
  • Typical attributes: Client ID, user identifier, scopes, client category, user roles, and so on.
  • Purpose: When a resource server validates a token, these attributes provide not only its active status but also detailed information about the token’s issuer and context.

For information on associating arbitrary properties with a token, see the Knowledge Base.

Passing Attributes to a Resource Server

  • Access-token format:
    • Reference token: The resource server introspects the token to obtain information.
    • Self-contained token: Attribute information is embedded directly in the token itself.
    • Hybrid approach: Combines the advantages of the 2 approaches above.

Proof of Possession

  • mTLS (mutual TLS):
    • Mechanism: A TLS client certificate authenticates the client, and the token is bound to that certificate. The authorization server verifies that the certificate was registered in advance, and the resource server likewise verifies the certificate.
    • See Issuing Certificate-Bound Access Tokens.
  • DPoP (Demonstrating Proof of Possession):
    • Mechanism: A public/private key pair is used to create a DPoP proof JWT, which is bound to the access token. This mechanism provides proof of possession at the application layer.
    • Configuration: Authlete can require DPoP on a per-client basis.
    • See Using DPoP.

Post-Issuance Token Management (22:38)

Continued Use and Rotation of Refresh Tokens

  • Continued use: Continue using the refresh token without changing its value.
  • Rotation (continued use disabled): Update the refresh token’s value and issue it as a new token. The value changes on each refresh.
  • Resetting the validity period: When updating a refresh token’s value, choose whether to reset its validity period. If reset, the validity period starts anew.
  • Inheriting the validity period: The new refresh token is given the old refresh token’s expiration time.
  • For details, see Configuring Continued Use of Refresh Tokens.

Refresh-Token Idempotency (24:27)

  • Concurrent token-refresh problem: When refresh-token values are configured to be updated, each token refresh changes the refresh token. If several token requests then arrive from multiple clients within a short period, all but the first fail with an invalid-token error.
  • Solution: Authlete mitigates this through its refresh-token idempotency setting. If multiple refresh requests use the same refresh token within a short period, the same new refresh token is returned for every request.

Token Revocation API (26:02)

The Token Revocation API can invalidate a particular token or all related tokens that meet specified conditions. This is important for maintaining security and preventing the use of unneeded tokens.

1. Basic Functions

  • Revoking an individual token: A particular access token or refresh token can be invalidated.
  • Conditional revocation: All tokens associated with a particular client or resource owner can be invalidated.

2. How to Request Revocation

  • Request from a client:
    • RFC 7009 compliant: This standard invalidates a token by specifying the value of an access or refresh token. Implementation: A client uses Authlete’s Token Revocation API to invalidate a particular token.
     POST /revoke HTTP/1.1
     Host: server.example.com
     Content-Type: application/x-www-form-urlencoded
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

     token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token
  • Request from a resource owner or authorization server:
    • Conditional revocation: Invalidate all access and refresh tokens associated with a client or resource owner in one operation.

    • API use: Authlete’s new Token Revocation API permits more flexible revocation conditions.
     POST /api/auth/token/revoke
     Host: api.authlete.com
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

     {          "subject": "resource owner identifier", 
          "client_id": "client ID"
     }

3. Examples

  • Example 1: When a user changes their password, revoke all access and refresh tokens associated with that user.
  • Example 2: If a client application is found to be acting maliciously, revoke all tokens associated with that client in one operation.

4. Expiration and Token Management

  • Expired tokens: Revocation principally concerns unexpired tokens, but expired tokens also require management, such as removal from the database.
  • Handling after revocation: A revoked token cannot be reused, and the resource server uses introspection to check whether a token is active.

Authlete’s Token Revocation API provides the flexibility and strong security needed for these varied scenarios, enabling safe and effective token management.

Summary

  • OAuth/OIDC profiling must take account of the circumstances leading to authorization, the information required by resource servers, lifecycle management, and security measures.
  • Best Current Practice (BCP) documents and profiles such as FAPI are useful references.
  • Authlete’s templates and API reference can also be consulted.

Footnotes

  1. Authlete supports highly secure OAuth/OIDC implementations and helps advance standards such as FAPI (Financial-grade API).
  2. I agreed to participate as an outside director in part because the company continually implements newly developed specifications.
  3. Rich Authorization Requests
  4. Otio is supposed to create materials using only the documents and other sources supplied to it. However, when a video is imported, GPT–4o transcribes it, and the system appears to fill in some information during that process.
  5. Pronounced “pixie.”
  6. JWT Secured Authorization Response Mode

Related posts