OpenID Connect

The Curity Security Token Server supports OpenID Connect. This is enabled by enabling openid configuration for the token profile that should support it. This enables the use of ID Tokens which represents 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.

../_images/oidc-disable.png

Fig. 144 Disabled OpenID Connect as shown in the GUI

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 in Fig. 145

../_images/oidc-enabled.png

Fig. 145 Enabling OpenID Connect in the admin GUI

When OpenID Connect is enabled, the following options can also be configured:

id-token-ttl
Path :/profiles/profile{id, type}/settings/authorization-server/openid-connect/id-token-ttl

The amount of time that an ID token should be valid for

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, which are by requesting scopes and by requesting individual claims through the claims request parameter. As specified by OpenID Connect, the claims parameter is a JSON document which has the option to request each claim individually, as opposed to the claim sets that are specified by the OpenID scopes.

Given that 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 given that the client is allowed to request them.

The claims request parameter is used to establish which claims from the profile data must be included in an ID token or in the user info response.

There is access control applied on the claims that can be requested by clients. This access control is based on the 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 that 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, in case 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 that are 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 will be different for that same user to a different client. The intent is that different clients will not be able to link their databases with each other and create a bigger user profile than the user might expect.

The OpenID Connect specification describes a way to express 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 URI’s: if all the redirect URI’s 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")

In case 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")

Note

Mobile Connect requires a sector identifier to be a URL even for statically registered clients. To conform to this profile, an administrator should use a URL instead of some other value. Be aware that the configuration is not validated for such a case.

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, as explained in the previous paragraph. If this is desired, you can explicitly set the Sector Identifier that is used to calculate a pseudonym for the subject.

Caution

Be careful when changing a Sector Identifier on an existing client, as the result will be that all users will be assigned a new subject identifier; the client will not be able to find out which new subject identifier referred to which old subject identifier.

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 setup 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 URI’s will be used. If that fails because none or there are more than one different host names found in the redirect URI’s, an error will occur.

Sector Identifier for Dynamic Client Registration

When doing Dynamic Client Registration, a client can not 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 getting 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 that is referred to in the sector_identifier_uri location. It will verify the document as specified in the OpenID Connect Dynamic Client Registration specification.

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 Registration Based on a Template Client 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")