Using Pairwise Pseudonymous Identifiers

We recommend reading the introduction to pairwise pseudonymous identifiers (PPIDs) before starting this tutorial.

Support for PPIDs

PPID support can be identified in the OpenID Connect metadata by looking at the subject_types_supported and seeing the value pairwise. In the Curity Identity Server this is always enabled with OpenID Connect, but is optional to configure for clients. It is possible to set a system wide requirement that enforces that all clients are configured to require PPID in the General settings of the Token profile.

Configuring Sectors

Suppose you need to add two clients that will share user information in the OAuth profile. For the clients to share user information, you need to place them in the same sector by setting use-pairwise-subject-identifiers and sector-identifier when adding clients in the OAuth profile.

The following example shows an OAuth profile excerpt that groups clients cloud_app_1 and cloud_app_1_mobile_app in a sector and sets the sector ID as cloud_app but www_1 is not in the same sector and will use obtain another identifier.

Web UIXML

In the Curity Identity Server Web UI, PPIDs and sectors can be set for each client in a manner similar to the following figure:

A sector ID only needs to be configured like this when:

• The client has multiple redirect URIs configured and
• The hosts of those redirect URIs are not the same.

So, if only one redirect URI is configured for a client, like www_1, then a sector ID need not be configured. Even if multiple redirect URIs are defined, a sector ID is still not needed if the host name of those redirects URIs are the same.

Dynamic Clients

When non-templatized Dynamic Client Registration (DCR) is enabled, an app may request the use of PPIDs when registering. It knows that this is supported by examining the OpenID Connect metadata and finding this value:

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

If an OAuth profile has been configured to require the use of PPID, then the public element of the list will not be present. In any case, the client will receive a PPID by registering as a non-templatized client using the subject_type client metadata with a value of pairwise. (Templatized, dynamic clients will use the PPID settings of the template and cannot influence this during registration.) When non-templatized, dynamic clients include multiple redirects URIs in the registration request and any of those have different host names, a sector_identifier_uri must also be included. Such a registration request will look similar to this:

{
  "subject_type":"pairwise",
  "redirect-uris":[
    "https://localhost:8080/cloud_app", 
    "https://example.com/cloud_app"],
  "sector_identifier_uri":"https://localhost:8080/cloud_app"
}

Accepting such a request is potentially dangerous and could allow a rogue actor to join a sector of victim client(s). If such an attack is successful, the perpetrator could learn about Alice's true identity or at least her pseudonymous ID as known to the victim client(s). To avoid this, the dynamic client's sector ID is derived from a sector ID URL provided in the registration request. The eventual sector ID that is used will be the host portion of this URL but it must first be validated. This validation occurs by making an HTTPS request to the URL to obtain a JSON array. This array must contain all redirect URIs of the new dynamic client. This interaction is shown in the following figure:

Conclusion

In this howto guide we walked through how to configure static clients and register dynamic clients with PPID enabled. PPID solves an importance privacy concern that many organizations have when it comes to sharing information with 3rd party clients. The Curity Identity Server comes with PPID enabled by default for public clients and optionally set for other clients.