Pairwise Subject Identifiers

Pairwise subject identifiers let a client application receive an opaque sub value that is unique for that user and client sector. This prevents relying parties from correlating the same ProAuth user across unrelated client applications.

Pairwise subjects are opt-in per client app. Existing clients use public subjects by default and continue to receive the ProAuth user GUID as sub.

Client configuration

Set SubjectType on the client app:

Value	Behavior
Public	Emits the ProAuth user GUID as sub. This is the default.
Pairwise	Emits a deterministic opaque sub derived for the tenant, issuer, sector, and ProAuth user.

For Management API v2, configure subjectType and, optionally, sectorIdentifierUri on client app create, update, or patch requests.

Changing a live client from Public to Pairwise changes the sub value seen by the relying party. Treat this as a breaking identity-contract change because the relying party may no longer link the user to an existing local account.

Sector grouping

By default, a pairwise client uses the lower-cased host of its registered redirect URI as the sector identifier. If a pairwise client has no sectorIdentifierUri, all registered redirect URIs must use the same host.

Use sectorIdentifierUri when multiple clients should receive the same pairwise sub for the same user, or when one client has redirect URIs on multiple hosts. The URI must:

• use HTTPS
• not contain userinfo or a fragment
• pass ProAuth remote URI security validation
• return a JSON array of redirect URI strings
• contain every registered redirect URI exactly as stored on the client app

Example sector document:

[
  "https://app1.example.com/signin-oidc",
  "https://app2.example.net/signin-oidc"
]

All pairwise clients using https://sector.example.com/sector.json receive the same pairwise sub for the same ProAuth user, tenant, issuer, and tenant pairwise secret.

Secret and rotation

ProAuth stores a hidden tenant option named PairwiseSubjectSecret. The value is protected at rest and is created lazily the first time a pairwise subject is issued for the tenant.

The pairwise calculation is deterministic:

Base64Url(HMACSHA256(secret, UTF8(issuer + "\n" + tenantId + "\n" + sectorIdentifier + "\n" + localSubject)))

localSubject is the ProAuth user GUID. ProAuth keeps the real user id in internal token, session, audit, and revocation context, and only emits the pairwise subject externally.

Rotating PairwiseSubjectSecret, changing sectorIdentifierUri, or changing the redirect URI host used as the sector changes pairwise sub values. Plan these changes as breaking relying-party account-link migrations.

Back up and restore the tenant pairwise secret with the tenant database. Restoring a tenant without its original secret changes all pairwise subjects for that tenant.