Subject identifiers#

Subject identifiers(defined in OpenID Connect Core SPEC) are unique identifiers generated by Janssen Server(i.e. OpenId Provider) for an end-user. Subject identifiers are unique per Janssen Server instance and it is shared with the client (or clients) via ID token or access token. Whether the same subject identifier is used for the same end-user across multiple clients depends on the kind of subject identifier configured for a particular client.

Types of Subject Identifiers#

Janssen Server supports the subject identifier types public and pairwise, as specified in OpenID Connect specification, and the ephemeral type, as specified in OpenID Connect Ephemeral Subject Identifier 1.0. The ephemeral type is disabled by default. See Ephemeral Subject Identifiers to enable it. For a particular Janssen Server deployment, the supported types are listed in the response of Janssen Server's well-known configuration endpoint is given below.

https://janssen.server.host/jans-auth/.well-known/openid-configuration

The subject_types_supported claim in the response specifies the list of all the supported types.

More details about both types are given in this section of specification.

Public Subject Identifiers#

Public subject identifiers are identifiers that the server generates and assigns to each subject. These identifiers are unique for each server deployment. All the clients that are configured to use a public type subject identifier will be supplied this same identifier for a given subject by the Janssen Server.

Sharing common subject identifiers across multiple clients may enable clients to correlate data about a particular subject. If this is an unwanted situation, then the client should use pairwise subject identifiers.

By default, the Janssen Server uses the subject attribute inum as the subject identifier.

Customizing Subject Identifier Attribute#

At the server level, the administrator specifies which subject attribute should be used as subject identifiers. This can be done by updating the value of openidSubAttribute Janssen Server property.

At the client level, this can be further customized. If a client uses public type subject identifier, the client can configure the subject attribute that should be used as a subject identifier. This should be done at the client registration time.

To enable client level customization, the Janssen Server property publicSubjectIdentifierPerClientEnabled should be set to true and also the desired attribute should be part of the list defined by the Janssen Server property subjectIdentifiersPerClientSupported. Both these properties can be set by the administrator using TUI.

Pairwise Subject Identifiers#

When a client chooses to use pairwise subject identifier, the Janssen Server generates and attaches a new identifier to all the subjects requested by the client. This identifier is consistently used for the subject-client pair and never used for any other clients configured on the Janssen Server. If multiple clients are using pairwise type subject identifiers, then the same subject will have different identifiers for each subject.

Since every client has a different identifier for the same subject, the clients can't match identifiers and correlate information about a subject out of the band.

Pairwise Identifier Generation#

Janssen Server uses host name string from redirect URI or sector identifier, local user ID, and a salt string as initial inputs to generate pairwise identifiers. This input is then signed with the HS256 signing algorithm to generate a pairwise identifier.

Sector identifier configuration influences how pairwise identifiers are calculated. See this document for more details.

Ephemeral Subject Identifiers#

An ephemeral subject identifier is a random value that stays constant for one authentication session and differs for every new authentication request. A client can't link two visits of the same end-user, and colluding clients can't link two authentication responses.

Janssen Server implements OpenID Connect Ephemeral Subject Identifier 1.0.

Enabling#

The ephemeral type is disabled by default. To enable it:

1. Add ephemeral to the subjectTypesSupported property. The value is then advertised in subject_types_supported of the well-known configuration.
2. Register the client with "subject_type": "ephemeral", for example via Dynamic Client Registration.

Example discovery response fragment:

"subject_types_supported": ["public", "pairwise", "ephemeral"]

Behavior#

• Janssen Server generates the identifier with a cryptographically secure random generator. It has 256 bits of entropy and is encoded as base64url.
• The identifier is created when the authorization grant is created and stored in the grant attributes. The ID token, UserInfo response, access token, introspection response and refresh token flow of that grant all return the same sub.
• A new authentication request creates a new grant and a new identifier. Janssen Server never reuses a value.
• No sector identifier is required for clients with the ephemeral type.
• Grants without an end-user, such as client_credentials, have no ephemeral identifier. Their sub is the client_id, as for other subject types.
• Back-channel logout is not supported for these clients, because a logout_token cannot carry a stable sub. Registration and client update requests that set backchannel_logout_uri on an ephemeral client are rejected with invalid_client_metadata. Logout skips the back-channel call for such clients if one is already stored. The check also runs on the final client, after any update dynamic client registration script has run.
• A client update that switches a client to ephemeral can remove the stored backchannel_logout_uri in the same request. Send backchannel_logout_uri with an empty value. If the request omits the parameter, Janssen Server keeps the stored value.
• A token issued before the client switched to ephemeral has no stored identifier. Janssen Server rejects such a token as invalid instead of returning a different sub on each call.
• Janssen Server also rejects a token that has a stored identifier but whose end-user no longer exists. It does not fall back to the client_id as sub.

Properties#

Janssen Server allows customization concerning subject identifiers using the properties below:

• subjectTypesSupported
• defaultSubjectType
• shareSubjectIdBetweenClientsWithSameSectorId
• openidSubAttribute
• publicSubjectIdentifierPerClientEnabled
• subjectIdentifiersPerClientSupported
• skipAuthorizationForOpenIdScopeAndPairwiseId
• pairwiseCalculationKey
• pairwiseCalculationSalt
• pairwiseIdType

Want to contribute?#

If you have content you'd like to contribute to this page in the meantime, you can get started with our Contribution guide.