Subject

​

What the subject is

The subject is the identifier of the end-user (the resource owner) on whose behalf a code or token is issued. Your authorization server generates the subject and passes it to the Authlete API as the subject request parameter. First, your authorization server passes the subject to Authlete after user authentication, and Authlete binds the subject it receives to the code and tokens it issues (Figure 1). Next, when Authlete issues tokens in exchange for that code, it returns the subject as a value carried in the ID token and the JWT access token (Figure 2). When a resource server introspects an access token, Authlete also returns the subject bound to that access token (Figure 3). Authlete also uses the bound subject to filter the list of tokens and to control the tokens it issues.

​

Relationship to the OAuth/OIDC specifications

Authlete’s subject corresponds to sub in the following elements of the OAuth/OIDC specifications: OpenID Connect Core 1.0, Section 5.7 names sub and iss together as the only claims a client can rely on as a stable identifier for the end-user, and says that email, phone_number and preferred_username must not be used as one. Because sub is never reassigned, a client can store it against the user account it manages and recognize the same user on later logins. Your authorization server generates an end-user identifier with these properties and passes it to Authlete as the subject request parameter. Authlete emits the value it receives as the sub of the elements above.

​

Division of responsibilities

The subject is divided between your authorization server and Authlete as follows.

​

Authorization server

• Establishes who the end-user is. Authlete is not involved in this step. The authorization server may authenticate the user itself (a login form, passkeys), rely on an existing session, or accept an authentication result from an external identity provider through federation.
• Determines the subject that represents that user. Use a value that satisfies the properties above: something that never changes and is never reused, such as an internal account ID. An e-mail address or a display name does not qualify, because it can change. When authentication is delegated to an external identity provider, map its result to your own account identifier rather than forwarding the provider’s identifier as it is: it is unique and stable within that provider, not necessarily within your issuer.
• Passes the subject to an issuing API (e.g. Issue Authorization Response). Any other information about the user that an ID token or UserInfo response should carry is passed as claims. Authlete has no user store and derives nothing from the subject.

​

Authlete

• Checks the format of the subject. Issue Authorization Response in Authlete 3.0 checks the following requirements (the other issuing APIs apply the same length limit):

  Requirement	Detail
  Non-empty	The API fails with server_error when the subject parameter is missing or empty, because that is a defect in the authorization server, not in the client’s request.
  At most 255 characters	Longer values fail in the same way. This is the limit OpenID Connect Core places on sub.
  Printable ASCII only	Other characters fail in the same way.

• Binds the subject to the authorization code and tokens it issues.
• Returns the subject in tokens and API responses. Authlete emits it as the sub claim of ID tokens, the sub of UserInfo responses, the sub of JWT access tokens, the sub member of standard introspection responses, and the subject field of its own introspection API (see the following sections).

​

How the subject flows

​

Sent by the authorization server

Once it has identified the end-user, your authorization server sends a request containing the subject to an issuing (flow-completing) API:

​

Returned by Authlete

The subject passed to Authlete appears in the following tokens and responses:

• Access tokens are bound to the subject, which comes back as the result of token introspection and as a value carried in JWT access tokens.
  • Introspection: Process Introspection Request returns it as subject, and Process OAuth 2.0 Introspection Request returns it as the RFC 7662 sub member, so a resource server can tell whose token it received.
  • JWT access tokens: carry it as sub. Authlete’s JWT access tokens use the claim names of RFC 9068 but do not conform to that profile; see the “JWT Access Token” section of JWTs in OAuth and OpenID Connect.
  • A token issued by the client credentials grant has no subject: standard introspection omits sub, and a JWT access token carries "sub": null.
• ID tokens carry the subject as the sub claim.
  • Issue Authorization Response, Complete Device Authorization and Complete Backchannel Authentication also accept a sub request parameter, which sets a value other than the subject (the access token stays bound to the subject). This keeps the actual subject hidden from client applications. See Adding Claims to ID Token.
• UserInfo responses, like ID tokens, carry the subject as the sub claim.
  • Likewise, the sub parameter of Issue UserInfo Response sets a value other than the subject.

​

Working with tokens by subject

Once a subject is bound to a token, the following APIs and settings use the subject to work with that end-user’s tokens:

• Process Introspection Request takes subject as an optional parameter. When it is given and does not match the subject bound to the access token, Authlete returns action=FORBIDDEN, so a resource server can require that a token belong to a specific user.
• List Issued Tokens filters issued tokens by subject.
• Single Access Token Per Subject keeps only the newest access token valid for each subject.

All of these compare the subject exactly, so pass the same identifier for the same end-user every time.

​

Handling pairwise subject identifiers

​

What pairwise subject identifiers are

OpenID Connect Core defines two subject identifier types for the sub claim: The specification does not define how a pairwise subject identifier is derived. It does require that the provider calculate a unique sub for each sector identifier and that the value not be reversible by any party other than the provider (Section 8.1).

​

What Authlete does

Given an identifier that is unique within your authorization server, Authlete derives the per-client sub value as follows.

1. Determine the client’s sector identifier. It is the host of the client’s sector_identifier_uri if one is registered, otherwise the host shared by all of its redirect URIs. If the client has neither a sector_identifier_uri nor a single redirect URI host, no sector identifier can be derived, and Authlete uses the subject as sub unchanged.
2. Determine the sub value. Authlete computes a hash from the sector identifier, the service, the subject and other inputs, and uses it as sub, encoded in URL-safe Base64 without padding (a 43-character string). The same user therefore always gets the same sub at the same client (and at other clients in the same sector), while different clients and different services get different values.

The conversion applies wherever Authlete emits an identifier for the user to the client: the sub of ID tokens from every flow (including CIBA, the device flow, ID token reissuance and Native SSO), of UserInfo responses and of logout tokens. The access token, on the other hand, stays bound to the subject your authorization server passed, so introspection’s subject and a JWT access token’s sub return that value.

​

Configuration

The subject identifier type is set per client: Subject Type (subjectType, PUBLIC or PAIRWISE) in the client settings. For a pairwise client whose redirect URIs span more than one host, also register Sector Identifier URI (sectorIdentifierUri), or Authlete cannot derive a sector identifier and falls back to the public behavior.

​

See Also

• Request and Response
• Two-Step API Calls
• Adding Claims to ID Token
• Enabling Single Access Token