Blog »

Focus on Identity Assurance in Connect2id server 9.0

2020-03-18

This new major release of the Connect2id server is designed with eKYC / Identity Assurance providers in mind. We looked at how customers have been integrating and customising provision of regular as well as verified OpenID claims and used those lessons to touch up the server web APIs and SPIs in key places. The verified claims are now clearly delineated. It is also easier to construct claims and verification metadata in the authorisation session / front-channel, which can be useful in cases such as on-demand remote in-person identity proofing.

The new release also updates eKYC / Identity Assurance support to the latest 09 draft, intended to become the basis for final publication, give or take a few cosmetic changes. The eKYC spec maturated quickly, in under three months since the official working group was founded, and so did our support for it, in the open source OpenID Connect SDK and the Connect2id server for identity provision.

Handling eKYC / Identity Assurance requests

The authorisation session web API of the Connect2id server is updated to simplify processing of requests for verified claims. An authorisation handler can now clearly find out which claims were requested by the relying party (RP) in the normal fashion and which as verified. If the RP requested a particular trust framework, such as "eidas_ial_high", or a purpose message for each claim is to be displayed to the end-user in the consent screen, these are now presented in the consent prompt.

Check out the updated eKYC / Identity Assurance guide and the release notes below for more information.

Passing additional data with the claims request

The consent object includes a new "claims_data" parameter, of type JSON object, which the claims source can use when constructing a claims set for the UserInfo endpoint or the ID token.

In eKYC / IdA the "claims_data" parameter can pass parameters needed to construct the "verification" element of a verified claims set, such as the trust and process identifiers.

{
  "scope"       : [ "openid" ],
  "claims"      : [ "email",
                    "verified:name",
                    "verified:address" ]
  "claims_data" : { "trust_framework"      : "eidas_ial_high",
                    "time"                 : "2020-03-16T18:25Z",
                    "verification_process" : "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7" }
}

The "claims_data" can also be used to feed entire OpenID claims from the authorisation session / front-channel.

If the claims are to be returned at the UserInfo endpoint the "claims_data" will be encoded into the issued access token. If the claims data must be kept confidential make sure the access token is identifier-based or an encrypted JWT.

If the authorisation is long-lived the "claims_data" will also get persisted in the Connect2id server authorisation records.

The web hook for sourcing claims was updated to include the "claims_data" parameter in the HTTP POST requests.

The new "claims_data" parameter requires an update of the database schema if the Connect2id server is deployed with an RDBMS or LDAPv3 server. Save for LDAP the schema update where needed will happen automatically when switching to Connect2id server v9.0. Check the release notes for details.

Other updates

A number of dependencies, such as Infinispan, were also updated to their latest stable versions. The new release also fixes three bugs, one of them security related (already addressed in 8.2.1), so updating is advised.

Download

To download a ZIP package of Connect2id server 9.0:

https://connect2id.com/assets/products/server/download/9.0/Connect2id-server.zip

SHA-256: d8aeb03bc84a24756d1c2323a050c538aea9be986cd6128e3f89878e5da6150d

As WAR package only:

https://connect2id.com/assets/products/server/download/9.0/c2id.war

SHA-256: e6fbe74bb6e6502ea662d8b3979fe01c06eb25232eaf62e2487b570b7dc689f8

Questions?

Contact Connect2id support.

Release notes

9.0 (2020-03-18)

Summary

  • Updates support for OpenID Connect for Identity Assurance 1.0 to draft 09 (see https://openid.net/specs/openid-connect-4-identity-assurance-1_0-09.html). Requested verified claims will now be automatically marked and processed as such in the authorisation session API. The requested "verification" and individual claim "purpose" parameters will be presented in the consent prompt.

  • Updates the authorisation session API and the OAuth 2.0 grant handler SPIs to enable passing of additional JSON data with requests to the configured claims source(s). This can be used to pass claim values from the authorisation handler or when implementing Identity Assurance the necessary verification element for verified claims in the UserInfo response or the ID token.

    The included HTTP-based claims source SPI implementation is updated to include a "claims_data" parameter (of type JSON object) in the request to represent the optional claims data.

  • Upgrades the Infinispan and backend database schemas for the identifier-based access tokens and the long-lived (persisted) authorisation records.

    On startup the Connect2id server will automatically create the new required "id_access_tokens" and "long_lived_authorizations" table columns for a relational MySQL, PostgreSQL or Microsoft SQL Server database.

    Connect2id server deployments with an LDAP v3 backend database (such as OpenLDAP or OpenDJ) need to update the LDAP schema manually to version 1.12 see https://bitbucket.org/connect2id/server-ldap-schemas/src/1.10/ , the OpenLDAP schema diff https://bitbucket.org/connect2id/server-ldap-schemas/diff/src/main/resources/ oidc-authz-schema-openldap.ldif?at=1.12 &diff1=49115daf531b48c2d9fd0f766721d84c28576eae &diff2=4c78a00734bfeb9abdd4c9dec76d9fbc51216faa and the OpenDJ schema diff https://bitbucket.org/connect2id/server-ldap-schemas/diff/src/main/resources/ oidc-authz-schema-opendj.ldif?at=1.12 &diff1=49115daf531b48c2d9fd0f766721d84c28576eae &diff2=4c78a00734bfeb9abdd4c9dec76d9fbc51216faa

    Connect2id server deployments with a DynamoDB database are essentially schema-less and no specific action is required.

Configuration

  • /WEB-INF/oidcProvider.properties

    • New "op.token.introspection.jwtType" configuration property. Sets the "typ" (type) header of JWT introspection responses. The default value is "token-introspection+jwt". This configuration allows the type header to be set to "JWT" for non-compliant clients and JWT libraries which cannot handle header values other than "JWT".

  • /WEB-INF/log4j.xml

    • Adds an optional console (SYSTEM_OUT) appender. Setting the Java system property log4j.loggers.root.appender to console switches logging from the rolling-file appender to the standard output. Can be useful in container deployments.

Web API

  • /authz-sessions/rest/v3/

    • The consent prompt identifies requested verified OpenID claims by prefixing their name with "verified:", for example "verified:given_name", "verified:family_name" or "verified:address". When submitting consent to the Connect2id server the names of the verified claims must also be prefixed with "verified:".

      To process verified OpenID claims OpenID Connect for Identity Assurance 1.0 must be enabled (op.assurance.supportsVerifiedClaims=true).

    • The consent prompt is updated to include the optional "purpose" attribute of requested verified OpenID claims (OpenID Connect for Identity Assurance 1.0) as well as regular claims. If the attribute is set for one or more claims the purpose strings will appear in a new claims.purposes JSON object containing the claim name / purpose string pairs.

      The accepted purpose string length is between 3 and 300 characters, according to the Assurance specification. The Relying Party may use the "ui_locales" OpenID authentication request parameter to set the preferred language for the purpose strings.

      In order to prevent injection attacks all special characters in a purpose string must be escaped before shown in a user interface.

    • The consent prompt is updated to include the optional "verification" JSON object for a requested verified claims set (OpenID Connect for Identity Assurance 1.0). If the verification element is set for a requested verified claims set to be returned in the UserInfo response it will appear in a new claims.verification.userinfo JSON object. Likewise, if the element is set for a requested claims set to be returned with the ID token it will appear in a claims.verifiction.id_token JSON object.

      To include the "verification" element in the consent prompt OpenID Connect for Identity Assurance 1.0 must be enabled (op.assurance.supportsVerifiedClaims=true).

    • The consent is updated to include an optional "claims_data" JSON object parameter. The data will be made available in the ClaimsSourceRequestContext.getClaimsData method when the configured claims source(s) get called at the UserInfo endpoint or when feeding the consented claims into the ID token.

      The "claims_data" can be used to provision entire claims from the authorisation session and the front-channel. It can also be used in Identity Assurance to construct the "verification" element in the authorisation session and then have it included in the UserInfo response, for example in remote in-person proofing scenarios.

      The "claims_data" will be included in the issued access token and in long-lived (persisted) authorisations in a new "cld" (claims data) JSON object field. To keep the claims data confidential from the relying party (client) either an identifier access token encoding must be chosen (access_token.encoding = IDENTIFIER in the consent) or if a self-contained (JWT) encoding is chosen the JWT must be additionally encrypted (access_token.encrypt = true).

      An AdvancedClaimsSource SPI implementation can retrieve the claims data JSON object by a call to the ClaimsSourceRequestContext.getClaimsData method.

  • /authz-store/rest/v2/authorizations

    • The OAuth 2.0 / OpenID Connect authorisations includes a new optional "cld" (claims data) JSON object field to represent claims data to be passed to the OpenID claims source(s) with access tokens consumed at the UserInfo endpoint.

  • /token/introspect

    • The access token introspection response includes a new optional "cld" (claims data) JSON object field to represent claims data to be passed to the OpenID claims source(s) with access tokens consumed at the UserInfo endpoint.

SPI

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

  • com.nimbusds.openid.connect.provider.spi.claims.ClaimsSource, AdvancedClaimsSource

    • The names of verified OpenID claims passed via the "claims" argument of the "getClaims" method will be prefixed with "verified:" by the Connect2id server (OpenID Connect for Identity Assurance 1.0).

  • com.nimbusds.openid.connect.provider.spi.claims.ClaimsSourceRequestContext

    • Adds new "getClaimsData" method to obtain optional data set by an authorisation handler to fulfill OpenID claims provision, for example to construct the "verification" element for a verified claims set (OpenID Connect for Identity Assurance 1.0).

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

    • Adds new "getClaimsData" method to the interface to represent OpenID claims fulfillment data. The default implementation returns null.

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

    • Adds new constructor and "getData" method for passing optional claims fulfillment data to the configured OpenID claims source(s).

Resolved issues

  • Fixes a security bug which caused the Connect2id server to redirect to a supplied invalid redirect_uri in a OAuth 2.0 authorisation request when the request includes a request object that doesn't parse to a valid JWT and the "redirect_uri" is present as top-level parameter. The redirection will occur with the error code and description from the failed request. The correct behaviour is to not redirect back to the client with an error unless the client_id and the redirect_uri are valid. Deployments are advised to update to prevent potential misuse of such redirections (issue server/537).

  • Fixes a bug introduced in Connect2id server 8.1 which prevented output of the "verification" element in the OpenID "claims" authentication parameter output in /authz-sessions/rest/v3/ GET responses. The bug was caused by a faulty consent-all keyword sanitization (issue server/532).

  • Removes an erroneous standard output print (issue server/535).

Dependency changes

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

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

  • Updates to com.nimbusds:nimbus-jose-jwt:8.10

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

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

  • Upgrades to com.nimbusds:oidc-claims-source-http:2.0

  • Updates to commons-codec:commons-codec:1.14

  • Updates to io.dropwizard.metrics:*:4.0.7

  • Updates to io.prometheus:*:0.8.1

  • Updates to org.apache.logging.log4j:*:2.13.1

  • Updates to org.slf4j:slf4j-api:1.7.30

  • Updates to com.amazonaws:aws-java-sdk-bundle:1.11.728

  • Updates to Infinispan 9.4.18.Final.

  • Updates to com.zaxxer:HikariCP:3.4.2

  • Updates to com.h2database:h2:1.4.200

  • Updates to org.mariadb.jdbc:mariadb-java-client:2.5.4

  • Updates to org.postgresql:postgresql:42.2.10

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

  • Updates to org.opensaml:*:3.4.3

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