Blog »

Connect2id server 13.0

2022-12-01

This release of the Connect2id server for OpenID provision and OAuth 2.0 authorisation focuses on PKCE and issuer (domain) aliasing. It is given a new major number for two reasons: the database schema receives an update; deployments that have an embedded H2 database for persisting server data are switched to a new backwards incompatible version of H2.

Per-client PKCE policy support

The Proof Key for Code Exchange by OAuth Public Clients (PKCE) is a security extension originally devised to prevent code injection attacks on clients that cannot authenticate at the token endpoint. It was later found to be useful against other attack vectors and thus became mandatory in OAuth 2.1.

This release of the Connect2id server introduces the new code_challenge_method metadata field to require a client to use PKCE. If the client makes an authorisation request without a code_challenge or with a method other than the registered the Connect2id server will return an invalid_request error with an explanation what PKCE method is expected.

Note, the global op.authz.requiredPKCE configuration property, which applies to all clients, will always override the individual PKCE setting.

Example registration request where the client is required to use the recommended S256 code challenge method:

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

{
  "redirect_uris"         : [ "https://client.example.org/callback" ],
  "code_challenge_method" : "S256"
}

The client registration howto is updated with this and other useful examples.

OpenID provider issuer (domain) aliases

Connect2id server 12.3 introduced the concept of issuer aliases, for scenarios where an OpenID provider / OAuth 2.0 server can be known by multiple issuer URLs. This can also be useful to migrate an identity provider seamlessly and over time from one issuer URL to another.

This release upgrades the issuer alias model, by adding a new mode suitable for light multitenancy, by isolating the OAuth flows, grants and tokens between issuer aliases while keeping the client registrations and end-user sessions shared.

The issuer aliases guide has a thorough explanation how to configure and operate such a deployment. The guide also lists the limitations of issuer aliases and when the multitenant edition of the Connect2id server is appropriate.

Client registration entity size limit

The Connect2id server limits the size of client metadata in registration requests to 250K chars, to prevent DoS attacks.

This limit can now be adjusted if needed via a op.reg.httpMaxRequestSize Java system property.

Example:

op.reg.httpMaxRequestSize=100000

Database schema

The introduction of the new code_challenge_method client metadata parameter will necessitate a change to the database schema of Connect2id server deployments that use an SQL store (MySQL, PostgreSQL, SQL Server or H2) or an LDAP store (such as OpenLDAP).

If you have an SQL database on startup the Connect2id server will automatically add the new code_challenge_method column to the clients table.

If you have LDAP store this will require a manual schema upgrade, explained in the release notes below.

If you have a DynamoDB store which is schema-less there is nothing to do.

SQL connector and driver updates

The connector for SQL stores, including jOOQ, the connection pool library and some of the JDBC drivers were also upgraded.

H2 database

Support for the H2 SQL database was upgraded from v1.x to 2.x. The new version of the database received changes to the SQL data types and the underlying file format. This means that data stored in H2 v1.x is not compatible and cannot be read by the new v2.x. If you have a Connect2id server deployment with the embedded H2 database and need to migrate the server data check out the data migration guide.

Redis

Connect2id server deployments with Redis for storing short lived and cached data can now easily configure a password to access the Redis server with the new redisMapPassword and redisCachePassword system properties.

For more information what's new or changed check the release notes below.

Download 13.0

For the signature validation: Public GPG key

Standard Connect2id server edition

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

GPG signature: Connect2id-server.zip.asc

SHA-256: 02c72ef9d3ef9c35db9189b8984fb67abfe7f844ceccf854a7f71e383c3906f0

Connect2id server 13.0 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: 95280957fed80e6bf827668bffc5afafeb63cc49904d6a2d6ea14ec7ab432017

Multi-tenant edition

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

GPG signature: Connect2id-server-mt.zip.asc

SHA-256: 3c61225f1f3dccdc7e69c932d53adc46b60ec4abd971f8234069f4980aa60dc3

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

GPG signature: c2id-multi-tenant.war.asc

SHA-256: 2c75c97dcdd6e6098a7a2b7ee7f3e35b91c0e39f9b5260b30ecebf197a08f92b

Questions?

If you have technical questions about this new release contact Connect2id support. To purchase a production license for the Connect2id server, renew or upgrade your support and updates subscription, email our sales.

Release notes

13.0 (2022-11-30)

Summary

  • Individual clients can be registered to require use of Proof Key for Code Exchange by OAuth Public Clients (RFC 7636) by means of the code_challenge_method client metadata.

  • Upgrades the OpenID provider / OAuth 2.0 authorisation server issuer alias model.

    Issuer aliasing was introduced in v12.3 (2021-09-17) to enable a Connect2id server deployment to migrate seamlessly and over time from one issuer identifier URL to another. Issuer aliases can also be used when an OpenID provider / OAuth 2.0 authorisation server is known by multiple URLs.

    This release introduces two differentiated issuer alias modes (configurable by op.issuerAliasMode):

    • MIGRATION -- Intended to facilitate issuer URL migration or deployments where the OpenID provider is known by multiple URLs. This is the default mode and how the Connect2id server previously behaved with enabled issuer aliases.

    • PERSISTED_GRANT_ISOLATION -- Enforces complete OAuth 2.0 grant isolation between issuer aliases. Has the effect of disabling long-lived (persisted) consent, forcing issue of self-contained (stateless) refresh tokens only, and blocking the use of any previously issued identifier-based refresh tokens. This mode is intended for deployments that for some reason choose not to operate a multi-tenant Connect2id server where the OpenID providers / OAuth 2.0 authorisation servers completely isolated.

    For security reasons both issuer alias modes will now behave as follows:

    • Prevent switching of the issuer URL during an OAuth authorisation code, implicit or hybrid flow (which may involve the PAR endpoint).

    • Prevent switching of the issuer URL in the authorisation session API at the user authentication or consent step.

    • The token introspection endpoint will mark any token issued under a different alias as invalid and the scope to access the endpoint must also be set to the current issuer URL.

    • The UserInfo endpoint will reject access tokens issued under a different alias.

    Note, in the MIGRATION issuer alias mode refresh tokens which are tied to long-lived (persisted) consent can be shared across all issuer aliases. The resulting access tokens however will be issued and remain valid for the current issuer alias only.

    Finally, the issuer aliasing was updated to enable dynamic addition and removal of issuer alias URLs, with no changes to the Connect2id server configuration.

  • Upgrades H2 SQL database support from v1.x to v2.x. This is a breaking change that affects the persisted H2 data format. Data stored by H2 v1.x is not compatible and cannot be read by H2 v2.x. Connect2id server deployments that use H2 to persist server data will need to perform a migration. See the Data Migration guide for more information.

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.issuerAliases -- New optional configuration property for Connect2id server deployments that need to support issuer alias URLs of the OpenID provider / OAuth 2.0 authorisation server. By setting the configuration property to "*" (asterisk) the HTTP reverse proxy in front of the Connect2id server is enabled to determine the whitelisted issuer alias URLs when setting the "Issuer" security header. This can be useful in deployments where issuer aliases must be added or removed dynamically, without restarting the server (in the regular edition) or updating the OpenID provider / OAuth 2.0 authorisation server configuration via the tenants web API (in the multi-tenant edition). Previously the Connect2id server supported only a static whitelist of allowed issuer aliases.

    • op.issuerAliasMode -- New optional configuration property introducing two differentiated modes of issuer aliasing:

      • MIGRATION -- Enables seamless migration over time to a new issuer URL. This is the default mode and how the Connect2id server previously behaved with enabled issuer aliases.

      • PERSISTED_GRANT_ISOLATION -- Enforces persisted grant isolation between issuer aliases: disables long-lived (persisted) consent; forces issue of self-contained (stateless) refresh tokens; blocks the use of any previously issued identifier-based refresh tokens.

    • op.reg.httpMaxRequestSize -- New optional configuration property enabling override of the size limit of the entity body of HTTP POST and PUT requests to the client registration web API. Configurable via Java system property only! The default value is 250 thousand (250000) characters.

  • /WEB-INF/infinispan--redis-.xml

    • New redisMapPassword and redisCachePassword configuration properties of type string to set a password for accessing Redis. The default value is no password.

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

    • Adds new "code_challenge_method" column to the "clients" table. In existing Connect2id server deployments with an SQL RDBMS the server will automatically add the new column (with an appropriate default value) on startup.

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

    • Adds new "oauthCodeChallengeMethod" attribute to the "oauthClientMetadata" object classes. Connect2id server deployments with an LDAP v3 backend database (such as OpenLDAP or OpenDJ) must update the LDAP schema manually to version 1.19 see https://bitbucket.org/connect2id/server-ldap-schemas/src/1.19/ , the OpenLDAP schema diff https://bitbucket.org/connect2id/server-ldap-schemas /diff/src/main/resources/oidc-client-schema-openldap.ldif?at=1.19 &diff2=97f372ce82ddd94e08a3937c4169f3a190aed2b2 and the OpenDJ schema diff https://bitbucket.org/connect2id/server-ldap-schemas /diff/src/main/resources/oidc-client-schema-opendj.ldif?at=1.19 &diff2=97f372ce82ddd94e08a3937c4169f3a190aed2b2

Web API

  • /clients

    • Supports registration of clients with the optional custom code_challenge_method metadata field of type string and values S256 and plain to force the client to use a code challenge method (see Proof Key for Code Exchange by OAuth Public Clients, RFC 7636) at the authorisation and the pushed authorisation request (PAR) endpoints. The default value is no code challenge method.

      Note that the Connect2id server op.authz.allowedPKCE and op.authz. requiredPKCE configuration properties will always override this client metadata.

Resolved issues

  • Upgrades the security of the authorisation code grant at the token endpoint by adding an immediate code invalidation to complement the usual invalid_grant OAuth 2.0 error in the following cases: 1) mismatch between token request client_id (for a public or successfully authenticated confidential client) and the client_id associated with the issued code at the authorisation endpoint; 2) invalid or missing redirect_uri; 3) missing, invalid or unexpected code_verifier (PKCE); 4) mismatch between the code issuer and the tenant issuer at the token endpoint (issue authz-store/195).

  • Improves the data layer performance of code for token exchange at the token endpoint (issue authz-store/195).

  • Updates the token endpoint unauthorized_client error description in the case when the request is rejected because the client is not registered for the grant type (issue server/798).

Dependency changes

  • Updates to com.nimbusds:oauth2-authz-store:19.3

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

  • Upgrades to com.nimbusds:tenant-manager:7.3.1

  • Upgrades to com.nimbusds:tenant-registry:7.1

  • Updates to com.google.code.gson:gson:2.10

  • Updates to com.nimbusds:infinispan-cachestore-sql:5.0

  • Updates to com.nimbusds:infinispan-cachestore-redis:9.2.9

  • Upgrades to org.jooq.pro-java-11:jooq:3.17.4

  • Updates to com.zaxxer:HikariCP:5.0.1

  • Updates to org.postgresql:postgresql:42.5.1

  • Upgrades to com.h2database:h2:2.1.214