Pairwise Subject Identifiers

By default, when a user authenticates, the authenticated subject is passed along unmodified in tokens issued to clients. In environments where different clients should not be able to share properties bound to a subject, it is possible to issue pseudonymous subject identifiers. These pseudonyms remain consistent for one user within a specific client but differ for that same user across different clients. The intent is to prevent clients from linking their databases to create larger user profiles than users might expect.

Pairwise subject identifiers are called Pairwise Pseudonymous Identifiers (PPIDs) in the OpenID Connect specification because they are based on the pair of subject identifier and sector identifier.

Use Cases#

Pairwise subject identifiers enhance user privacy and security across various scenarios by preventing user tracking and protecting personally identifiable information.

Common use cases include:

• Privacy Protection: Replace user identifiers containing PII (email addresses, employee numbers, social security numbers) with opaque, random identifiers that cannot be traced back to the user’s real identity
• Prevent Cross-Application Tracking: Issue unique identifiers to each client application, making it impossible for different clients to collude or correlate user behavior across applications
• Security Breach Mitigation: Limit the impact of security breaches by ensuring that compromised client applications only expose meaningless pseudonymous identifiers rather than actual user PII
• Regulatory Compliance: Support GDPR and other privacy regulations by minimizing the exposure of personal data to third-party applications and services
• Multi-Tenant Environments: Enable different departments, business units, or organizations to access user data without revealing the user’s identity across organizational boundaries
• Federated Identity Scenarios: Protect user privacy when federating identity across multiple service providers by ensuring each provider receives a unique, unlinkable identifier for the same user

Getting Started#

To enable Pairwise Subject Identifier, sign in to the Admin UI and navigate to Profiles → Token Service → General.

Go to the section OpenID Connect, enable OpenID Connect, and toggle the option Require Pairwise Subject Identifiers.

Variations#

Pairwise subject identifiers are calculated based on a pair of subject identifier and sector identifier. The sector identifier determines how pseudonyms are generated and whether multiple clients receive the same or different pseudonyms for a user.

Automatic Sector Identifier Derivation#

If a sector identifier is not explicitly set, it is automatically derived from each client’s registered redirect URIs. When all redirect URIs share the same host component, that shared host is used as the sector identifier.

For example, a client that does not configure a sector identifier value but has registered redirect URI https://www.example.com/cb will use the host component www.example.com as the sector identifier. When user teddie authenticates, the pseudonym is calculated as:

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

Explicit Sector Identifiers#

Multiple clients can be grouped into sectors by explicitly configuring a sector identifier. Clients sharing the same sector identifier receive identical pseudonyms for the same user, enabling legitimate data sharing between related applications.

For example, when a client has multiple redirect URIs and is configured with sector identifier Sector Zort, the pseudonym for user teddie is calculated as:

pseudonymize("teddie", "Sector Zort")

This approach is useful when multiple clients need to access shared resources like user preferences, products, shopping carts, or medical records.

Client Configuration#

A client will always be issued a non-pseudonymous identifier unless it is enabled to issue pairwise pseudonyms. Once enabled, no more unprocessed subject identifiers will be issued to that client.

Different clients will be issued different pseudonyms for the same user, unless multiple clients share the same sector identifier. If you want multiple clients to receive the same pseudonym for a user, explicitly set the same sector identifier for those clients.

Profile Configuration#

The token profile includes a setting that indicates whether it is required to issue pairwise pseudonyms to clients. This setting is particularly useful for Dynamic Client Registration scenarios: when the profile requires pairwise pseudonyms, a newly registered non-templatized client must include subject_type=pairwise in its registration request, or it will be rejected.

Dynamic Client Registration#

For dynamically registered clients, sector identifiers are handled differently to prevent unauthorized clients from joining existing sectors:

Non-Templatized Registration: When doing Dynamic Client Registration, a client cannot arbitrarily specify which sector identifier it wants to use. This restriction protects users from clients that want to join a sector and obtain the same pairwise pseudonyms as other clients in that sector without proper authorization.

Instead, a verification mechanism is in place based on the sector_identifier_uri parameter. The Curity Identity Server fetches and validates the document from the sector_identifier_uri location according to the OpenID Connect Dynamic Client Registration specification. When the request is accepted, the hostname component of the sector_identifier_uri becomes the sector identifier.

For example, if a client registers with parameters subject_type=pairwise and sector_identifier_uri=https://my.example.com/sector-info, pairwise pseudonyms are calculated as:

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

Configure the sector-identifier-lookup-http-client option in Dynamic Client Registration settings to specify which HTTP client handles sector identifier URI lookups.

Templatized Registration: Registration based on a template client could lead to all registered clients using the same sector identifier, effectively reducing a pairwise pseudonym into a regular pseudonym. To prevent this, The Curity Identity Server uses the dynamically registered client’s unique ID as the sector identifier when the client template is configured to issue pairwise pseudonyms.

For example, a dynamically registered client based on a template with ID 192-riw-1uc calculates pseudonyms as:

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

Learn More#

To configure and implement pairwise subject identifiers:

• Review the OpenID Connect Core specification for technical details on subject identifier types and pairwise pseudonymous identifiers
• Explore the Using Pairwise Pseudonymous Identifiers for step-by-step configuration instructions
• Learn about Privacy and GDPR Using OAuth for privacy compliance best practices
• See the Clients documentation for client configuration options
• Consult the OpenID Connect Dynamic Client Registration specification for sector identifier validation details