Connect2id server 10.1 with OpenID Connect federation and Identity Assurance / eKYC updates

2020-10-28

The second OpenID Connect Federation 1.0 interop, which took place in September, tested automatic federation clients, which are now fully supported by the Connect2id server. To find out what this new OpenID Connect extension is about and how it enables identity federations to be operated at virtually any scale, in hierarchical and mesh topologies of trust, revisit the Connect2id server 10.0 release announcement.

The second topic of this release is the Identity Assurance / eKYC extension. The Connect2id server will now accept a special case of requests for verified claims, those that involve multiple or different verifications. To simplify the processing of such requests we've been contemplating some changes to the authZ session API, in one of the next Connect2id server releases (feel free to chime in!). We'll continue updating the guide for IdA / eKYC providers with new examples and tips.

The underlying OAuth 2.0 / OpenID Connect SDK (v8.23) was also revised, for a nicer, immutable OO development when dealing with regular as well as verified claims.

For a full description of the new features, changes and bug fixes in Connect2id server 10.1 check the release notes below.

Download

Standard Connect2id server edition

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

SHA-256: cf8f58e3c1525a2aebd399090d09ded28f4f76f48586f3c84f70aa1bdaa7716d

Connect2id server 10.1 WAR package: c2id.war

SHA-256: d2a440e956959d1695dc3009c3b6b024f9291c773657d48a025ebba15e971a43

Multi-tenant edition

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

SHA-256: 333cd88a1b96d49b0c1b651fd43181a35fadec38a72e27bb178234fdc1ff4aa3

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

SHA-256: bf64cfdc26e040737017298faab5b6c3ebaf36253ba87a8bcdff12265cceed0e

Questions?

Contact Connect2id support.

Release notes

10.1 (2020-10-29)

Summary

Adds support for OpenID Connect Federation 1.0 (draft 12) automatic clients. Automatic clients don't register explicitly with the Connect2id server, instead they proceed directly to the authorisation endpoint, where they submit a signed request object (JWT) containing additional federation- specific claims, thus letting the request object also serve as an implicit authenticated registration request. The Connect2id server will perform the regular federation trust chain resolution and retrieve the client's metadata from its federation entity statement published at a well-known endpoint. The client registration will expire according to a configured policy - a set lifetime or the trust chain lifetime.

See https://openid.net/specs/openid-connect-federation-1_0-12.html.
Updates OpenID Connect for Identity Assurance 1.0 (draft 11) support to accept "claims" authentication request parameters where the "verified_claims" element is a JSON array. This is intended to enable requests for claims sets with different verification requirements (e.g. different trust frameworks). Previously such requests will result in a invalid_request error at the authorisation endpoint.

Example "claims" request for two verifications, using the "eidas_ial_substantial" and the "de_aml" trust frameworks:
```
{
"userinfo": {
  "verified_claims": [
    {
      "verification": {
        "trust_framework": {
          "value": "eidas_ial_substantial"
        }
      },
      "claims": {
        "given_name": null,
        "family_name": null
      }
    },
    {
      "verification": {
        "trust_framework": {
          "value": "de_aml"
        }
      },
      "claims": {
        "birthdate": null
      }
    }
  ]
}
}
```
The consent prompt in the authorisation session API will list the requested verified claims across all elements in the "verified_claims" JSON array.

Note that "claims" -> "verification" will only present the first requested "verification" element if multiple are found. Use the "claims" -> "raw_request" to obtain all verifications. A future version of the Connect2id server will update the consent prompt to simplify handling of verified claims requests with multiple verifications.

See https://openid.net/specs/openid-connect-4-identity-assurance-1_0-11.html, section 6.3.3.
Connect2id server deployments with an AWS DynamoDB backend can be configured to include a SHA-256 based message authentication code (HMAC) in each stored item to guarantee its integrity and authenticity while stored in the database.

Configuration

/WEB-INF/oidcProvider.properties
- op.federation.clientRegistrationTypes -- The configuration property for the supported OpenID Connect Federation 1.0 client registration types now allows for automatic as well as explicit registration.
- op.federation.autoClientAuthMethods.ar -- New configuration property specifying the supported methods for authenticating implicit registration requests of OpenID Connect Federation 1.0 automatic clients at the OAuth 2.0 authorisation endpoint. The only currently supported method is "request_object".
- op.federation.autoClientLifetime -- New configuration property for the lifetime of registered OpenID Connect Federation 1.0 automatic clients, in seconds. If zero or negative the lifetime will be determined by the trust chain expiration time. When explicitly set must not be shorter than 5 minutes (300 seconds) to allow sufficient time for the completion of a single OAuth 2.0 flow with an authorisation, token and UserInfo request by the registered relying party. The default lifetime is one hour (3600 seconds).
/WEB-INF/infinispan-*-dynamodb.xml
- Updates the DynamoDB store schema to v1.8 and adds the option to secure the integrity and authenticity of the stored DynamoDB items with a SHA-256 based Message Authentication Code (HMAC), appended to each item in a "_hmac#256" binary attribute. If a retrieved DynamoDB item is missing the "_hmac#256" attribute or its verification fails the Connect2id server will produce an HTTP 500 Internal Server Error, log the error with a "DS0131" code and increment the ".dynamoDB.invalidItemHmacCounter" metric.
  
  To enable this HMAC protection the Connect2id server must be configured with a secret 256 bit key (as BASE-64 encoded string) in the "dynamoDB.hmacSHA256Key" Java system property.
  
  The HMAC protection must be enabled for newly provisioned or empty DynamoDB tables. Enabling the protection for DynamoDB tables with prior existing items will cause HMAC validation errors on their retrieval.
/WEB-INF/infinispan-stateless-dynamodb.xml
- DynamoDB consistent reads for "sessionStore.sessionMap" can be enabled by setting the "dynamodb.consistentReads.sessionStore.sessionMap" Java system property to true.

Web API

/authz-sessions/rest/v3/
- The consent prompt "claims" parameter adds support for verified claims requests (OpenID Connect Identity Assurance 1.0) with multiple verifications.
  
  The "claims" -> "new" -> "essential", "voluntary" arrays will list the requested verified claims (prefixed with "verified:") across all "verified_claims" elements (if multiple are found).
  
  The "claims" -> "verification" -> "id_token", "userinfo" objects will include the first found verification element (if multiple are found), the full list of verification objects can be obtained by parsing the "claims" -> "raw_request" parameter (requires op.authz.includeRawClaimsRequestInPrompt=false).
/monitor/v1/metrics
- Adds new ".dynamoDB.invalidItemHmacCounter" metric of type counter for Connect2id server deployments with a DynamoDB database. Counts the number of retrieved DynamoDB items which failed the HMAC SHA-256 check (if enabled).

SPI

PasswordGrantHandler, JWTGrantHandler, SAML2GrantHandler
- Consented claims which name is prefixed with "id_token:" will be included in the ID token instead of via the default method, the UserInfo endpoint. This feature is adopted from the authorisation session web API.
Included OpenID Connect HTTP claims source
- Updates the included AdvancedClaimsSource SPI implementation for sourcing OpenID claims from an HTTP endpoint to version 2.1 (com.nimbusds:oidc-claims-source-http:2.1). The JSON object representing the request will now include a "claims_transport" parameter hinting how the requested claims are going to be transported to the relying party: "userinfo" for the UserInfo endpoint, "id_token" for the ID token, omitted if not applicable (for claims requested by an internal plugin, such as an access token codec).

Resolved issues

OpenID claims requests with JSON array of verified_claims must not fail (issue server/605).
Fixes NPE in OpenID Connect Federation 1.0 client registration error processing logic (issue server/585).
Front-channel logout requests must not include the issuer identifier (iss) as query parameter when a session identifier (sid) isn't included (issue server/595).
Updates the OAuth 2.0 authorisation endpoint to reject signed (JWS) request objects (JARs) where the optional JWT "sub" (subject) claim is set to the client_id value, see the latest cross-JWT confusion security recommendation in https://tools.ietf.org/html/draft-ietf-oauth-jwsreq-29#section-10.8 (issue server/588).
Fixes the reported "request" (JAR) parameter name in illegal_request error messages from the OAuth 2.0 authorisation endpoint (issue server/589).
Ignore unknown key types in a JWK set, when parsing a client JWK set and in other cases (issue nimbus-jose-jwt/377).
Logs at INFO level the enabled / disabled status of every loaded claims source at Connect2id server startup under OP7107 (issue server/600).
Logs at TRACE level the decoded self-contained access token authorisation under AS0544 (issue authz-server/178).
HTTP POST and PUT requests to the client registration endpoint where the entity body exceeds the hard-wired character limit must return a HTTP 400 Bad Request, not HTTP 500 Internal Server Error. Raises the limit from 15 thousand to 20 thousand characters (issue server/579).

Dependency changes

Upgrades to com.nimbusds:oauth2-oidc-sdk:8.23.1
Updates to com.nimbusds:nimbus-jose-jwt:8.20.1
Updates to com.nimbusds:oauth2-authz-store:16.3
Updates to com.nimbusds:oidc-claims-source-http:2.1
Updates to BouncyCastle 1.66
Updates to Infinispan 9.4.20
Upgrades to com.nimbusds:infinispan-cachestore-dynamodb:3.7.2
Updates to com.unboundid:unboundid-ldapsdk:5.1.1
Updates to com.amazonaws:aws-java-sdk-bundle:1.11.880