Skip to content
Connect2id

Pairwise subject IDs

The Connect2id server can issue ID tokens with pairwise end-user IDs. What is their purpose?

  • Confidentiality – To hide (encrypt) the end-user ID from the client / relying party. This may be useful if the identifier used in your identity system contains sensitive or personal information, for example the user’s email address.

  • Prevent correlation – As part of a strategy to minimise the possibility of linking user identities across clients / relying parties. The Connect2id server will issue each client / relying party registered for pairwise IDs with an ID token that has a different unique subject ID for the same end-user.

    For example, client_id=123 receives an ID token with sub=AAA and client_id=456 receives sub=BBB for the same user.

    In order for that strategy to work the client must not be provided with user attributes that would otherwise enable linking, such as the user’s email address. And even then correlation may still be possible, if third-party cookies are enabled in browsers, or other work-arounds get employed.

1. How to find out if an OpenID provider supports pairwise subjects?

If an OpenID provider supports pairwise IDs it will indicate that in the published metadata, by including the value pairwise in the subject_types field (public means regular IDs):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer"                  : "https://c2id.com",
  "subject_types_supported" : [ "public", "pairwise" ],
  ...
}

2. Registering a client for pairwise subjects

2.1 Simple case

Clients to be issued with pairwise subject IDs must be explicitly registered for that, by setting the optional subject_type parameter to pairwise. The default action is to register the client for plain (public) IDs.

Here is an example minimal registration:

POST /clients HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "redirect_uris" : [ "https://client.example.org/callback" ],
  "subject_type"  : "pairwise"
}

Important: The computation of the pairwise ID uses the host component of the registered redirection ID as input parameter. If the client updates its redirection URI and the host components changes with that, the issued IDs for all end-users will also change!

Redirection URI: https://client.example.org/callback
Host component: client.example.org

2.2 Allowing for change of host component

If you anticipate changes of the host component, or have to register multiple redirection URIs with different host components, you need to create a JSON document containing a single array of all registered redirection URIs.

Example JSON document:

[
  "https://abc.example.org/callback",
  "https://def.example.org/callback",
  "https://ghi.example.org/callback"
]

Make the JSON document available at an HTTPS URL that can be accessed by the Connect2id server, within the configured HTTP connect and read timeouts.

The host component of URL of that document will be used to compute the pairwise IDs. Pass it in the client registration by setting the sector_identifier_uri parameter:

POST /clients HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "redirect_uris"         : [ "https://client.example.org/callback" ],
  "subject_type"          : "pairwise",
  "sector_identifier_uri" : "https://example.org/redirect-uris.json"
}

You can check out our client registration guide for more examples.

3. How does the Connect2id server implement pairwise IDs?

The Connect2id server takes the plain end-user ID and applies deterministic AES/SIV-mode encryption to it. For the encryption it uses the configured secret 256-bit key with ID subject-encrypt that is found in the server JWK set.

Important: If the subject encryption key gets changed, all issued pairwise IDs will change too! Make sure it’s properly backed up, while keeping it secure of course.

4. JWT-encoded access tokens

If a client registered for pairwise IDs gets issued with a JWT-encoded access token, the access token will always automatically get encrypted after signing. The access token is encrypted with the configured AES key found in the server JWK set.

This is done to prevent the client from finding out the plain end-user ID by inspecting the sub parameter of the signed JWT.

If you have resource servers that expect JWT-encoded access tokens the AES key must be shared with them in order to decrypt the token.

5. Reversing a pairwise ID

For debugging or other needs the pairwise ID can be reversed (decrypted) to find out the underlying end-user ID. This requires the subject encryption key.

5.1 Command line tool

We provide a simple command line tool to encrypt / decrypt pairwise IDs:

https://bitbucket.org/connect2id/pairwise-subject-codec/src/master/

The download section has a compiled JAR for the tool.

5.2 Java OpenID Connect SDK

You can also utilise the OpenID Connect SDK, check out the SIVAESBasedPairwiseSubjectCodec class.