Blog »

Connect2id server 12.0 supports issue of access tokens with pairwise subjects

2021-06-23

This new major release of the Connect2id server brings an almost total rework of the system for pairwise subject identifiers. Those are essential in preventing leakage of identity information via end-user identifiers in the issued tokens and UserInfo responses, by encrypting any data in them and making correlation based on their values very difficult.

The changes and new features:

  1. Access tokens can now also be minted with a pairwise sub (linked to the token audience).

  2. OpenID provider managed sector ID URNs, for deployments that seek tight control over the sector IDs. The use of URNs also relieves relying parties from the need to host the sector JSON documents.

  3. Uniform length of the pairwise identifiers, to prevent information about the length of the local user ID from leaking. This is achieved by the introduction of a new configuration property to specify a padding of the IDs to some predetermined length.

    Note, if you choose to switch to uniform pairwise IDs this will invalidate (reset) all previously issued ones (by older Connect2id server versions). The release notes has a discussion on this, including how to disable padding to keep the old format.

The pairwise subject identifiers, how to configure and integrate them, is explained fully in our updated guide.

Another change in Connect2id server 12.0 is the ability to issue access and refresh tokens without a scope. This is intended for deployments that need to handle OAuth 2.0 Rich Authorisation Requests (RAR). This is currently possible via the custom token response plugin interface. A future release will bring native support.

The upgrade to Connect2id server 12.0 from an earlier version involves a change in the database schema to accomodate the new features. If you use an SQL database, such as MySQL or PostgreSQL, the Connect2id server at startup will automatically create new table columns where necessary. If you use an LDAP backend a manual schema update needs to be performed. Deployments with DynamoDB, it being effectively schema-less, don't necessitate any such changes.

The complete list of changes, bug fixes and database schema related instructions can be found in the release notes below.

Download

Standard Connect2id server edition

Apache Tomcat package with Connect2id server 12.0: Connect2id-server.zip

SHA-256: ca706e557e8beefa49ebab184be0a8f43b8f3ac78f44ac8a59d9d7f280e3b1e4

Connect2id server 12.0 WAR package: c2id.war

SHA-256: c208db9d559296df788c92d138cc0a132bb9a5739a7705b99dab334e19ab7b49

Multi-tenant edition

Apache Tomcat package with Connect2id server 12.0: Connect2id-server-mt.zip

SHA-256: ca5b64c30e85dbcd39772dd89a9418373b0ff2a46db3f0127b293905b6f94eda

Connect2id server 12.0 WAR package: c2id-multi-tenant.war

SHA-256: 635d379bf910483c6c39f6cf7ff708102aa61b9a39777a82ba60e46ad643a6a3

Questions?

Contact Connect2id support.

Release notes

12.0 (2021-06-09)

Summary

  • Uniform pairwise subject IDs

    Adds support for issuing pairwise subject identifiers with a uniform string length which is not affected by the length of the local (system) subject identifiers. This measure is intended to prevent leaking information about the length of the local subject identifiers. Uniformity is configured with a new "op.pairwiseSubjects.padLocalSubjectsToLength" property. It specifies a length to which a local subject identifier will be padded before input to the pairwise codec (SIV mode deterministic AES encryption). For uniform pairwise subject lengths the property should be set to the maximum expected length of the local subjects. Subject IDs longer than the configured length will result in a pairwise encoding that is proportionally longer.

    Setting the property to -1 (negative integer) disables padding, which is the behaviour of the pairwise codec in previous Connect2id server versions.

    Example pairwise IDs for local subjects "alice", "bob" and "claire" with no padding:

    myzM-ARj7vYBH9NOIog9Sf5xklhU_rkLenu8mOtfLv6L Q20o2EYNsamhlOh2RbteNp7Te7AilmMPVk3cyhmCBA rNW4ByxEQd06rNCLLMvH2-d1WRumrJcSrmDGA6FlvtxeGw

    With padding up to 10 characters:

    pxXoRPqPpLy3fBbLNV22KRCghztrFMtGV3AxDnQH_erfB4dwZ_0 s10h_EEMtYHaNSZuMBznfvupKqC2mznkIGnmxRevffJGo4ybRrM uLfwVCpRUu1ltEeXqRt_Yik7SN5-yKabYwXan-xYCwgJlDZubSA

    Important: Changing the padding length will reset all previously issued pairwise subject identifiers!

    Configuration choices for "op.pairwiseSubjects.padLocalSubjectsToLength":

    • Configure a length to issue uniform pairwise subject IDs: if pairwise subjects have never been issued or to benefit from the new improved security. In the latter case don't forget to notify the relying parties of the reset!

    • No padding: to ensure backward compatibility if pairwise subjects have already been issued and a reset is not desirable. Also, if the local subjects have a uniform length, for example when based on a GUUID which has a constant length of 37 characters.

  • OpenID provider managed sector IDs

    Connect2id server deployments that need to issue ID tokens and UserInfo responses with pairwise (pseudonymous) subject (end-user) identifiers to two or more OpenID relying parties under single administrative control can now do so without requiring the relying parties to host a JSON document for the "sector_identifier_uri" client registration parameter. A single OpenID relying party can also choose to register a "sector_identifier_uri" to ensure the pairwise "sub" values in the received ID tokens and UserInfo responses remain consistent if its registered redirection URI changes in future. See OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1, section 5, for an explanation of the "sector_identifier_uri" parameter and its validation.

    For such relying parties an OpenID provider can now manage the sector IDs internally, in some a database or portal, by assigning unique sector ID URNs to them prior to registration. Those URNs will not get resolved and validated in the same way a standard https URL in the "sector_identifier_uri" parameter gets, by downloading a JSON document from the URL. Instead, the URN will be used to provide the sector ID directly. The expected URN format is urn:c2id:sector_id:<id> where <id> represents the sector ID assigned to a relying party or group of relying parties.

    To use this feature the new "op.reg.enableProviderManagedSectorIDs" configuration property must be turned on. The client registration POST or PUT request must be authorised with a master API token or one-time registration token with a "client-reg:set-sector-id-urn" scope value. Unauthorised requests (if open registration is allowed) cannot use sector ID URNs.

  • Access tokens with pairwise subjects

    The Connect2id server can now optionally issue access tokens with a subject (end-user) identifier made pairwise for the token's intended audience (resource server).

    Use tokens with a pairwise subject:

    • To keep the local (system) end-user ID confidential from the resource servers, as privacy measure, especially if the subject identifier represents or contains personal information, such as the user's email address or social security number.

    • To minimise the possibility for resource servers to link or correlate the identity of users. The pairwise identifier for a given subject (end-user) in an access token will be different, unique and not-reversible for each resource server (token audience).

    The Connect2id server computes the pairwise identifier for an access token by applying strong deterministic SIV AES based encryption over the concatenation of the token audience and the local subject identifier.

    pairwise_sub = SIVAES(aud|local_sub)

    The algorithm is identical to the one the Connect2id server uses to compute pairwise subject identifiers for ID tokens and UserInfo responses and uses the same "subject-encrypt" AES key from the configured server JWK set.

    JWT-encoded as well identifier-based access tokens are supported.

    Note, to issue access tokens with a pairwise subject the token authorisation must specify an explicit token audience for the intended resource server(s). If the audience is a list of multiple values the first one will be used to compute the pairwise subject. This enables the issue of tokens with a pairwise subject where there are multiple audiences as aliases specified, for example the resource indicator, e.g. "https://api.example.com", as primary audience and the resource server client ID, e.g. "Zoo0rah0", to enable token introspection at the Connect2id server endpoint with an audience restriction check on the client_id.

    Also note that access tokens with a pairwise subject that grant release of OpenID claims at the UserInfo endpoint, as only or additional scope, need not specify the UserInfo endpoint or the OpenID provider issuer URL as audience.

    If required for audit purposes a pairwise subject identifier can be decrypted (reversed) with the Connect2id server's configured "subject-encrypt" JSON Web Key (JWK). See https://bitbucket.org/connect2id/pairwise-subject-codec/ .

  • Allows issue of the access and refresh tokens without a scope, to ease handling of OAuth 2.0 Rich Authorisation Requests (RAR). See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar-05

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.pairwiseSubjects.padLocalSubjectsToLength -- New configuration property to enable output of pairwise subject identifiers with a uniform string length which is not affected by the length of the local (system) subject identifier. Intended to prevent leaking information about the length of the local subject identifiers. Uniformity is achieved by padding local subject identifiers up to the specified length, which should be the maximum expected length of the local subjects. Subjects longer than the configured length will result in a pairwise encoding that is proportionally longer.

      -1 (negative integer) disables padding.

      Important note: Changing the padding length will reset all previously issued pairwise subject identifiers!

    • op.reg.enableProviderManagedSectorIDs -- New configuration property to enable registration of OpenID provider managed sector identifiers for the computation of pairwise subject (end-user) identifiers. A managed sector ID can be registered with the "sector_identifier_uri" set to a URN with the format urn:c2id:sector_id:<id>. The registration requires a master API token or a one-time registration token with a "client-reg:set-sector-id-urn" scope value. The default value is false (disabled).

  • /WEB-INF/infinispan-*-{mysql|postgres95|sqlserver|h2}.xml

    • Adds new "ats" (access token subject type) columns to the "id_access_tokens" and "long_lived_authorizations" tables. In existing Connect2id server deployments with an SQL RDBMS the server will automatically add the new columns (with an appropriate default value) on startup.

  • /WEB-INF/infinispan-*-ldap.xml

    • Adds new "authzAccessTokenSubjectType" attribute to the "oauth2IdAccessToken" and "oauth2Authz" object classes. Connect2id server deployments with an LDAP v3 backend database (such as OpenLDAP or OpenDJ) need to update the LDAP schema manually to version 1.17 see https://bitbucket.org/connect2id/server-ldap-schemas/src/1.17/ , the OpenLDAP schema diff https://bitbucket.org/connect2id/server-ldap-schemas/diff/ src/main/resources/oidc-authz-schema-openldap.ldif?at=1.17 &diff1=4c78a00734bfeb9abdd4c9dec76d9fbc51216faa &diff2=cdfdb912753b17a0fed7c08aa500be53cb767cd7 and the OpenDJ schema diff https://bitbucket.org/connect2id/server-ldap-schemas/diff/ src/main/resources/oidc-authz-schema-opendj.ldif?at=1.17 &diff1=4c78a00734bfeb9abdd4c9dec76d9fbc51216faa &diff2=cdfdb912753b17a0fed7c08aa500be53cb767cd7

Web API

  • /clients

    • Adds support for registering OpenID relying parties for pairwise subject identifiers where the "sector_identifier_uri" parameter is a URN for a sector ID that is managed by the OpenID provider. The expected URN format is urn:c2id:sector_id:<id>. The OpenID provider must manage the assignment of the URN sector IDs to relying parties prior to registration and ensure that the ID stays unique for a given OpenID relying party, unless the sector ID is allowed to be shared by two more relying parties, typically when those are under single administrative control. To register URN sector IDs the "op.reg.enableProviderManagedSectorIDs" configuration property must be enabled. The registration must be authorised with a master API token or a one-time registration token with a "client-reg:set-sector-id-urn" scope value.

    • Will return an "invalid_client_metadata" OAuth 2.0 error with a suitable description message when the client registration request is not authorised for a "preferred_client_id", "preferred_client_secret" or custom "data" parameter. Previously those parameters will be silently scrubbed from the registration request if not authorised (by means of the master API token or a specific one-time registration token).

  • /token

    • Supports issue of access tokens with a pairwise subject identifier encoded for the token audience as sector identifier. If the token has multiple audiences the first audience value in the list is taken as the sector identifier. Access tokens for releasing OpenID claims at the UserInfo endpoint that have pairwise subject need not include the UserInfo endpoint or the OpenID issuer URL in its audience.

  • /token/introspect

    • Supports introspection of access tokens with a pairwise subject identifier. The standard "sub" (subject) field will be set to the pairwise identifier.

  • /token/revoke

    • Supports revocation of access tokens with a pairwise subject identifier.

  • /userinfo

    • Supports access tokens with a pairwise subject identifier. Note, access tokens for OpenID claims that have a pairwise subject identifier need not include the UserInfo endpoint or the OpenID issuer URL in its audience.

  • /authz-sessions/rest/v3/

    • Consent prompt: Adds new optional "sub_type" member of type string with values "PUBLIC" (default) or "PAIRWISE" to the "access_token" JSON object. When set to "PAIRWISE" the Connect2id server will issue an access token with a pairwise subject identifier. This requires the consent to specify a token "audience" (if multiple audience values are set the first in the list will used to compute the pairwise identifier).

    • Consent: The consent can now specify an empty or null "scope" to enable handling of Rich Authorisation Requests (RAR). In this case the issued access and refresh tokens will not contain a scope. Previously a consent PUT with an empty scope would cause an "access_denied" OAuth error to be returned to the client. Integrations must now explicitly trigger an "access_denied" OAuth 2.0 error via the authorisation session web API.

  • /direct-authz/rest/v2/

    • Direct authorisation request: Adds new optional "sub_type" member of type string with values "PUBLIC" (default) or "PAIRWISE" to the "access_token" JSON object. When set to "PAIRWISE" the Connect2id server will issue an access token with a pairwise subject identifier. This requires the request to specify a token "audience" (if multiple audience values are set the first in the list will used to compute the pairwise identifier).

  • /authz-store/rest/v3/

    • OAuth 2.0 / OpenID Connect authorisation object: Adds new optional "ats" (access token subject type) member of type string with values "PUBLIC" (default) or "PAIRWISE".

SPI

  • Upgrades the Connect2id server SDK to com.nimbusds:c2id-server-sdk:4.36

  • com.nimbusds.openid.connect.provider.spi.tokens.AccessTokenAuthorization

    • Adds new getSubjectType method to return the SubjectType for the access token (PUBLIC or PAIRWISE). The default implementation returns null (not specified).

    • Adds new getLocalSubject method to return the local (system) subject identifier for an access token since the existing getSubject can return a pairwise identifier. The default implementation calls getSubject for a PUBLIC access token subject, else returns null.

  • com.nimbusds.openid.connect.provider.spi.tokens.MutableAccessTokenAuthorization

    • Adds new getSubjectType and withSubject methods for getting / setting the access token subject type (PUBLIC or PAIRWISE).

    • Adds new getLocalSubject and withLocalSubject methods for getting / setting the access token local subject identifier.

  • com.nimbusds.openid.connect.provider.spi.grants.AccessTokenSpec

    • Adds support for specifying an access token subject type (PUBLIC or PAIRWISE). When set to PAIRWISE the access token must specify an audience (if multiple audience values are set the first in the list will used to compute the pairwise identifier).

  • com.nimbusds.openid.connect.provider.spi.tokens.introspection.TokenIntrospectionResponseComposer

    • TokenIntrospectionResponseComposer SPI implementations can access the local (system) subject of access tokens with a pairwise subject identifier via the AccessTokenAuthorization.getLocalSubject method.

  • com.nimbusds.openid.connect.provider.spi.tokens.SelfContainedAccessTokenClaimsCodec

    • Connect2id server deployments with a SelfContainedAccessTokenClaimsCodec SPI implementation and which issue access tokens with pairwise subject identifiers should provide encoding / decoding for the AccessTokenAuthorization.getSubjectType and getLocalSubject methods.

Resolved issues

  • Fixes leading JSON array bracket output for a GET on the clients endpoint with no registered clients. The bug was introduced in 11.6.1 (issue server/679).

  • Enforces a string length limit of 10K chars when parsing JWT headers (after the BASE64URL decoding). The 10K chars should be sufficient to accommodate JWT headers with an X.509 certificate chain in the "x5c" header parameter (issue nimbus-jose-jwt/424).

  • Prevents StackOverflowError when parsing a JWT header with a very large number of nested JOSE objects (issue nimbus-jose-jwt/425).

  • Moves validation of configured signing RSA and EC keys from JWT issue time to Connect2id server startup to improve performance (issue server/673).

Dependency changes

  • Upgrades to com.nimbusds:c2id-server-sdk:4.36

  • Upgrades to com.nimbusds:oauth2-oidc-sdk:9.9

  • Upgrades to com.nimbusds:nimbus-jose-jwt:9.10

  • Upgrades to com.nimbusds:c2id-server-jwkset:1.19

  • Upgrades to com.nimbusds:oauth2-authz-store:17.1.1

  • Updates to com.nimbusds:oidc-session-store:14.5.1

  • Upgrades to com.nimbusds:c2id-server-ldap-schemas:1.17

  • Updates Infinispan to 9.4.23.Final.

  • Updates to org.cryptomator:siv-mode:1.4.2

  • Updates to com.google.crypto.tink:tink:1.6.0

  • Updates to com.unboundid:unboundid-ldapsdk:6.0.0