Skip to content
Connect2id
Connect2id server

Connect2id server 17.0 introduces a new key store API for easy online rotation of keys

We end 2024 with a new release to automate and simplify the management of Connect2id server keys. It enables deployments to perform seamless online rotation of the server keys, at any desired frequency. This is made possible a new key store with a web API to trigger lifecycle operations such as key rotation and removal of superseded keys.

The audit function is improved too, by recording all key change events in the database and by introducing RFC 7639 style JWK thumbprints in server logs and in outputs from the new key store web API.

The private and secret material of current and historic keys in the database is encrypted with standard direct AES JWE JSON encryption. The key store web API does not support import of keys, or retrieval of non-public key parameters. This seals off the server keys from inappropriate access via the database, the key store web API and stored logs.

Three key store modes are made available.

Dynamic Static PKCS#11 + static
  • Online generation, rotation, revocation, and archival of server keys
  • The server keys are stored encrypted in the database
  • The server keys are statically configured
  • The database is not utilised
  • HSM-based server keys
  • Supplemented with statically configured keys
  • The database is not utilised

The dynamic mode becomes the new default, while the static and the PKCS#11 modes resemble the key configuration method from the previous Connect2id server versions 1.x to 16.x.

Upgrading to v17.0

Existing Connect2id server deployments can upgrade to this new release without changes to the configuration, as the old server key configuration method using the jose.jwkSet Java system property or the WEB-INF/jwkSet.json file remains supported. This is also true for the old method for configuring an HSM for the signing server keys using the pkcs11.* properties.

On startup a Connect2id server with an SQL database is going to automatically create the new requisite jwks and jwks_history tables, unless the default value of the
dataSource.createTableIfMissing property is overridden and set to false, in which case the two tables must be created manually in advance by a database administrator. This applies also to deployments with a DynamoDB database. Note that the new key store tables must be present in the database, even if the key store is configured to operate in a static, PKCS#11 or legacy mode.

To switch from a legacy server key configuration to the new dynamic key store mode check the simple migration guide.

Production environment flag

Production deployments can now be tagged with the Java system property env. When set to prod (production) this will trigger several configuration security checks on Connect2id server startup, like making sure the key store is not accidentally configured with the demo encryption key.

-Denv=prod

Upgraded offline JWK set generator tool

The library and CLI tool to generate the requisite Connect2id server keys was rewritten and features a new API and command line interface, to support the generation of an AES key to encrypt the private and secret key material in the new key store.

Removed deprecated configurations and web API versions

  • Support for weak 1024-bit RSA server keys using the jose.allowWeakKeys configuration exception is entirely removed now. The accepted RSA key sizes are 2048, 3072 and 4098 bits.

  • The legacy /authz-sessions/rest/v1 web API which was deprecated in Connect2id server 2.4 is removed. Use the current v3 of the API instead.

  • The legacy /authz-sessions/rest/v2 web API which was deprecated in Connect2id server 5.0 is removed. Use the current v3 of the API instead.

  • The legacy /direct-authz/rest/v1 web API which was deprecated in Connect2id server 2.4 is removed. Use the current v2 of the API instead.

More information about the new features, changes and resolved issues in the new release can be found in the notes below.

Download 17.0

For the signature validation: Public GPG key

Standard Connect2id server edition

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

GPG signature: Connect2id-server.zip.asc

SHA-256: 626e55d14112a29f0a45a42094202efbf70b1059e198e8333205207675265601

Connect2id server 17.0 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: 9a71e7e57e6a4478e3767d33e96e30b2c1a345a250b0750c3d18deb9c457650c

Multi-tenant edition

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

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

SHA-256: 74766b3f28114d4c307166305a9cf6ab1861bdb15d0bcac671a993a6432cc14c

Connect2id server 17.0 WAR package: c2id-mt.war

GPG signature: c2id-mt.war.asc

SHA-256: e4d2e6174180615806dfb79e496b56d9bac1be7aff06faa0bd5076726e024627

Questions?

For 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

17.0 (2024-12-17)

Summary

  • Introduces a key store with a web API supporting online generation, rotation, revocation and historic archival of the Connect2id server keys.

    The key store supports 3 operation modes:

    • Dynamic – Enables online generation, rotation, revocation and archival of the server keys, which are stored in the database. The private key material is encrypted with an AES key before it’s committed to the database. This is the default key store mode.

    • Static – The server keys are statically configured. Online key generation, rotation, revocation and archival is not supported. The database is not utilised for key storage. This mode is equivalent to the key configuration method in previous Connect2id server releases 1.x to 16.x.

    • PKCS#11 with static – Selected signing server keys, such as RSA and EC keys, are loaded from a PKCS#11 store (HSM). Keys which types or algorithms are not provided or supported by the PKCS#11 interface are statically configured. As with the pure static mode, online key generation, rotation, revocation and archival is not supported. The database is not utilised for key storage.

    The key store web API does not allow retrieval of private and secret key material. The keys for the OpenID provider (op) context and the OpenID Federation 1.0 (federation) context are configured, managed and stored in strict separation from one another.

    Existing Connect2id server deployments that wish to switch to the new key store (in the dynamic mode) can import their keys using the keyStore.importIfEmpty.op configuration property. OpenID Federation 1.0 entity keys can be imported using the keyStore.importIfEmpty.federation configuration property.

    Existing Connect2id server deployments have the choice to continue using the old jose.jwkSet and jose.federationJWKSet configuration properties or the WEB-INF/jwkSet.json and WEB-INF/federationJWKSet.json files to set the server keys. This applies also to the pkcs11.* configuration properties and the WEB-INF/jose.properties file. Note that these methods are deprecated and may be removed in a future major release.

  • Weak 1024-bit RSA server keys using the jose.allowWeakKeys configuration exception are no longer supported. The accepted RSA key sizes are 2048, 3072 and 4098 bits.

  • Production deployments of the Connect2id server can now set the Java system property env to prod (production), e.g. with -Denv=prod, which will prevent the server from starting up if it is accidentally configured with the demo key store encryption JWK (keyStore.encJWK) or master API access token (*.apiAccessTokenSHA256).

  • Removes the /authz-sessions/rest/v1 web API which was deprecated in Connect2id server 2.4. Use the current v3 of the API instead.

  • Removes the /authz-sessions/rest/v2 web API which was deprecated in Connect2id server 5.0. Use the current v3 of the API instead.

  • Removes the /direct-authz/rest/v1 web API which was deprecated in Connect2id server 2.4. Use the current v2 of the API instead.

  • Updates the Connect2id server JWKs generator
    (com.nimbusds:c2id-server-jwkset:2.0) and command line tool (jwks-gen.jar) to support key store encryption keys and various new options. The update includes breaking changes to the Java API and the CLI arguments. The previous Connect2id server JWKs generator (version 1.x) remains compatible.

Configuration

  • env – New optional Java system property configuration. When set to prod (production) the Connect2id server will not start up if it is configured with the demo key store encryption JWK (keyStore.encJWK) or master API access token (*.apiAccessTokenSHA256). The default value is dev (development).

  • /WEB-INF/keyStore.properties – New configuration file for the key store introduced in this release. Every property in the configuration file can be overridden with a Java system property.

    • keyStore.encJWK – New optional configuration property. Specifies a 128-bit AES key for encrypting the stored private key material. Required, unless the Connect2id server is configured with static JWK sets and / or a PKCS#11 (HSM) store. The key must be a JWK of type oct (octet sequence key), with use (key use) enc (encryption) and an optional kid (key ID). The JSON string may be additionally BASE64URL encoded, to prevent character escape issues in shell environments.

      When this configuration property is specified, it overrides any encryption key in the optional WEB-INF/keyStoreEncJWK.json file.

    • keyStore.apiAccessTokenSHA256 – New optional configuration property. Specifies the access token for the key store web API, represented by its SHA-256 hash (in hexadecimal format). The hash is a measure to prevent accidental leakage of the token through configuration files, logs, etc. The token is of type Bearer, non-expiring and must contain at least 32 random alphanumeric characters to make brute force guessing impractical. If not specified the key store web API is disabled.

      Additional access tokens, for token roll-over or other needs, can be configured by appending a dot (.) with a unique label to the property name, e.g. as keyStore.apiAccessTokenSHA256.1=abc....

    • keyStore.defaultRSAKeySize – New optional configuration property. Specifies the default size of new generated RSA JWKs. The supported sizes are 2048, 3072 and 4096 bits. The default value is 2048.

    • keyStore.generateIfEmpty.op, keyStore.generateIfEmpty.federation – New optional configuration properties. When true and the specified JWK set context (op for OpenID provider, federation for OpenID Federation 1.0) is empty, the key store will automatically generate the required JWK set. The default value is true (enabled).

    • keyStore.importIfEmpty.op, keyStore.importIfEmpty.federation – New optional configuration properties. Specify a JWK set to import into the key store if the specified context (op for OpenID provider, federation for OpenID Federation 1.0) is empty. The JSON string may be additionally BASE64URL encoded, to prevent character escape issues in shell environments. The default value is none.

    • keyStore.importExp – New optional configuration property. Specifies
      the time, as seconds since the Unix epoch, after which any configured JWK sets for import will be ignored. Must be not more than 1 day ahead of the current time when the Connect2id server starts up.

    • keyStore.jwkSetCacheLifetime – New optional configuration property. Controls the local caching of JWK sets retrieved from the key store. The cache lifetime is specified in seconds. Zero or negative disables caching. Must not exceed 600 seconds (10 minutes). The default value is 60 seconds (1 minute).

    • keyStore.staticJWKSet.op, keyStore.staticJWKSet.federation – New optional configuration properties. Specify a static JWK set for the specified context (op for OpenID provider, federation for OpenID Federation 1.0). The JSON string may be additionally BASE64URL encoded, to prevent character escape issues in shell environments. The default value is none.

      When a static JWK set is specified for a given context the key store web API operations for key rotation, revocation and history retrieval are disabled.

    • keyStore.pkcs11.op.enable, keyStore.pkcs11.federation.enable – New optional configuration property. Enables / disables PKCS#11 (HSM) support for the specified context (op for OpenID provider, federation for OpenID Federation 1.0). The default value is false (disabled).

      Replaces the deprecated pkcs11.enable for the OpenID provider context.

    • keyStore.pkcs11.op.configFile, keyStore.pkcs11.federation.configFile – New optional configuration properties. Specify the location of the Sun PKCS#11 provider configuration for the specified context (op for OpenID provider, federation for OpenID Federation 1.0). The configuration can be alternatively passed inline as a string. The string may be additionally BASE64URL encoded, to prevent character escape issues in shell environments.

      Replaces the deprecated pkcs11.configFile for the OpenID provider context.

    • keyStore.pkcs11.op.password, keyStore.pkcs11.federation.password – New optional configuration properties. Specifies the password (PIN) required to unlock the HSM for the specified context (op for OpenID provider, federation for OpenID Federation 1.0).

      Replaces the deprecated pkcs11.password for the OpenID provider context.

    • keyStore.pkcs11.op.keyIDs.*, keyStore.pkcs11.federation.keyIDs.* – New optional configuration properties. Specify a list of identifiers (aliases) of PKCS#11 keys to load from the HSM for the specified context (op for OpenID provider, federation for OpenID Federation 1.0). If omitted or blank all recognised and supported keys will be loaded.

      Replaces the deprecated pkcs11.keyIDs.* for the OpenID provider context.

  • /WEB-INF/keyStoreEncJWK.json – New optional file containing the 128-bit AES key in JWK format for the key store. Overridden by the keyStore.encJWK configuration property.

  • /WEB-INF/jwkSet.json – The file for specifying a static Connect2id server JWK set for the OpenID provider context is removed but remains supported.

  • /WEB-INF/federationJWKSet.json – The file for specifying a static Connect2id server JWK set for the OpenID Federation 1.0 context is removed but remains supported.

  • /WEB-INF/jose.properties – The configuration file is removed and no longer supported.

    • jose.allowWeakKeys – The configuration property is removed and no longer supported. 1024-bit RSA keys are no longer accepted with a special exception. The accepted RSA key sizes are 2048, 3072 and 4098 bits.

    • pkcs11.enable – Deprecated, use keyStore.pkcs11.op.enable instead.

    • pkcs11.configFile – Deprecated, use keyStore.pkcs11.op.configFile instead.

    • pkcs11.password – Deprecated, use keyStore.pkcs11.op.password instead.

    • pkcs11.keyIDs.* – Deprecated, use keyStore.pkcs11.op.keyIDs.* instead.

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

    • Upgrades the SQL schema by adding new jwks and jwks_history tables. In existing deployments the Connect2id server will automatically add the new tables on startup, unless dataSource.createTableIfMissing is disabled.

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

    • Upgrades the DynamoDB schema by adding new jwks and jwks_history tables. In existing deployments the Connect2id server will automatically add the new tables on startup.

Web API

  • /key-store/rest/v1/ – New web API for the Connect2id server key store. The web API is disabled unless an access token is configured (keyStore.apiAccessTokenSHA256).

    • /key-store/rest/v1/{ctx} – The current JWK set for the specified key context (op for OpenID provider, federation for OpenID Federation 1.0). The GET method retrieves the current JWK set. The private material of JWKs of type RSA, EC and OKP and the secret material of JWKs of type oct is masked. The custom tpr (thumbprint) JWK parameter indicates the SHA-256 thumbprint (RFC 7638) of each JWK. Supported query parameters: skip_cache={false|true}, pkcs11_only={false|true}.

    • /key-store/rest/v1/{ctx}/generate – The POST method generates a new JWK set for the specified key context (op for OpenID provider, federation for OpenID Federation 1.0). Supported form parameters: rsa={2048|3072|4096}, no_eddsa={false|true}, revoke_all_active_as_compromised={false|true}.

    • /key-store/rest/v1/{ctx}/rotate – The POST method rotates the public signing JWKs, public encryption JWKs and symmetric JWK for the optional encryption of JWT-encoded access tokens for the specified key context (op for OpenID provider, federation for OpenID Federation 1.0). The superseded keys are marked as such. Supported form parameters: rsa={2048|3072|4096}, no_eddsa={false|true}.

    • /key-store/rest/v1/{ctx}/{kid} – The DELETE method removes a superseded JWK with the specified kid (key ID) for the specified key context (op for OpenID provider, federation for OpenID Federation 1.0).

    • /key-store/rest/v1/{ctx}/history – The GET method retrieves a timestamped JWK set history for the specified key context (op for OpenID provider, federation for OpenID Federation 1.0).

  • /authz-sessions/rest/v1 – Deprecated web API removed. Use the current /authz-sessions/rest/v3 instead.

  • /authz-sessions/rest/v2 – Deprecated web API removed. Use the current /authz-sessions/rest/v3 instead.

  • /direct-authz/rest/v1 – Deprecated web API removed. Use the current /direct-authz/rest/v2 instead.

Resolved issues

  • The WEB-INF/*.properties configuration files are made optional and may be removed from Connect2id server deployments in which the configuration is supplied entirely via Java system properties (issue server/1037).

  • Removes the deprecated /authz-sessions/rest/v1, /authz-sessions/rest/v2 and /direct-authz/rest/v1 web APIs (issue server/1038).

  • Changes the Oracle database schema for the data column of the clients table from NVARCHAR2(2000) to NCLOB to allow storage of JSON objects with a size greater than 2 thousand characters. The column type change applies only to new Connect2id server deployments. Existing deployments can continue using their existing schema (with NVARCHAR2(2000)) (issue server/1036).

  • Fixes the fatal [OP0140] Configuration property conflict log message, must name the op.authz.feedSubjectSessionClaimsIntoIDToken configuration property as deprecated (issue server/1034).

Dependency changes

  • Adds com.nimbusds:c2id-server-key-store:1.7

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

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

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

  • Upgrades to com.nimbusds:nimbus-jwkset-loader:7.3

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

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

  • Upgrades to com.nimbusds:common:3.6

  • Updates to Infinispan 14.0.33.Final

  • Updates to Bouncy Castle 1.79

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

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

  • Updates to Log4j 2.24.2