OpenID Connect#

The Curity Security Token Server supports OpenID Connect. This is enabled by enabling

for the token profile that should support it. This enables the use of ID Tokens which represent user authentications. When this mode is enabled, clients can also get more information about a user via the user info endpoint. Metadata can also be exposed when this option is enabled.

OpenID Connect is disabled by default, but can be enabled for any OAuth profile. To do so using the admin GUI, go to OAuth → $PROFILE_NAME → General and then enable the Open ID Connect option as shown below:

Metadata#

The OpenID Connect Specification defines a metadata endpoint which can be optionally enabled.

This endpoint is located at /.well-known/openid-configuration under the anonymous endpoint.

See OpenID Connect Metadata for details.

The “claims” Request Parameter#

There are two ways to request profile data to be included in the ID token or the response of the user info endpoint:

• By requesting scopes
• By requesting individual claims through the claims request parameter

As specified by OpenID Connect, the claims parameter is a JSON document which allows each claim to be requested individually, as opposed to the claim sets specified by OpenID scopes. If OpenID Connect is enabled on the profile, claims request parameter support is enabled by default. The claims mapping subsystem will automatically map these claims to the tokens, provided the client is allowed to request them. The claims request parameter establishes which claims from the profile data must be included in an ID token or in the user info response.

There is access control applied to the claims that can be requested by clients, based on allowed scopes. These scopes represent a set of claims, and by allowing these scopes to be requested by a client, this also allows the claims they represent to be requested through the claims parameter. However, the scope itself does not have to be requested when using the claims parameter.

For example, if the client does not allow the profile scope to be requested, yet there is a request for the picture claim, this request will be rejected because it is not mapped to a scope that the client is configured with.

Note that requesting the acr claim with a specific value will result in requiring authentication to be performed with that particular acr.

Issuing Pseudonymous Subject Identifiers#

By default, when a user authenticates, the authenticated subject is passed along unmodified in tokens issued to the client. In environments where different clients should not be able to share properties bound to a subject amongst each other, it is possible to issue pseudonymous subject identifiers. These pseudonyms will be the same for one user to a client, but different for that same user to a different client. The intent is that different clients will not be able to link their databases and create a bigger user profile than the user might expect.

describes how to issue pseudonymous subject identifiers. Pseudonyms are called Pairwise Pseudonymous Identifiers (PPIDs) because they are based on the pair of Subject Identifier and Sector Identifier. If a sector identifier is not explicitly set, it is derived for each client, based on its registered redirect URIs: if all the redirect URIs share the same host component, then this shared host component is used as the sector identifier. If there is no redirect URI or if there are multiple redirect URIs with different host components, then it is required to configure a sector identifier for the client explicitly.

Example: A client does not configure a value for sector identifier, but it has registered redirect URI https://www.example.com/cb. In case a pairwise pseudonym is calculated, this is done by taking the host component (www.example.com) of this redirect URI and feeding it into the algorithm. When a user has authenticated as teddie, then the pseudonym to be issued is calculated like:

pseudonymize('teddie', 'www.example.com')

If the client has multiple redirect URIs registered, e.g. https://www.example.com/cb and https://another.example.com/cb, it is required for the client to also register a Sector Identifier. Say the Sector Identifier is registered as Sector Zort, then the pseudonym to be issued is calculated like:

pseudonymize('teddie', 'Sector Zort')

Client Settings#

A client will always be issued a non-pseudonym, unless it is enabled to issue Pairwise Pseudonyms for that client. Once enabled, no more unprocessed subject identifiers will be issued.

Different clients will be issued different pseudonyms for the same user, unless multiple clients share the same Sector Identifier. If this is desired, you can explicitly set the Sector Identifier that is used to calculate a pseudonym for the subject.

Profile Settings#

There is a setting on the profile that indicates whether it is required to issue pairwise pseudonyms to clients. This setting is particularly useful in case a profile is set up for dynamic client registration : when the profile requires pairwise pseudonyms, a new non-templatized client must be registered with a subject_type=pairwise parameter, or it will be rejected upon registration.

To calculate the issued pseudonym, the same logic applies to configured clients as well as dynamically registered clients: by default the explicitly configured Sector Identifier value will be used in the pair of Subject Identifier and Subject Identifier. In case there is no configured sector identifier, the hostname of the configured redirect URI or URIs will be used. If that fails because none or there are more than one different host names found in the redirect URIs, an error will occur.

Sector Identifier for Dynamic Client Registration#

When doing Dynamic Client Registration, a client cannot just say which Sector Identifier it wants to use. The reason for that is to protect users from clients that want to join a sector, and thereby get issued with the same pairwise pseudonyms as every other client in that sector, without anyone checking that! Instead, a mechanism is in place that will verify whether a sector identifier can be accepted, which is based on the sector_identifier_uri parameter.

Curity supports this approach, and will fetch the document from the location referred to in the sector_identifier_uri location. It will verify the document as specified in the

.

You can use the sector-identifier-lookup-http-client configuration option of Dynamic Client Registration settings to change the HTTP client that must be used to look up the sector_identifier_uri document.

When the request is accepted, the hostname component of the sector_identifier_uri will be used as Sector Identifier. For example, if a client registers with the parameters subject_type=pairwise and sector_identifier_uri=https://my.example.com/sector-info, pairwise pseudonyms are calculated as:

pseudonymize('teddie', 'my.example.com')

Templatized Dynamic Client Registration#

As dynamic client registration templatized registers a client based on only a reference to the client template, it could lead to all registered clients using the same Sector Identifier, which effectively reduces a pairwise pseudonym into a regular pseudonym. In this case, however, Curity will use the client’s ID of a dynamically registered template client as the sector identifier. Note that this is only the case when the client template is configured to issue pairwise pseudonyms.

Example: A dynamically registered client based on a client template was issued the id 192-riw-1uc. In this case, the pairwise pseudonym for user teddie is calculated like this:

pseudonymize('teddie', '192-riw-1uc')