Connect2id server 8.1

This release of the Connect2id server addresses issues encountered since the release of 8.0 at the start of 2020.

mTLS reverse proxy update

Connect2id server deployments where clients authenticate with a self-signed certificate (self_signed_tls_client_auth) can have the TLS connection terminated at an HTTP proxy. If the client presents an X.509 certificate the proxy passes it to the Connect2id server in a special security HTTP header configured by op.tls.clientX509CertHeader. The certificate is passed encoded as a PEM string, which is essentially the BASE64 encoding of the certificate DER binary with special start and end markers.

Sec-Client-X509-Cert-alaeLuL8geiqu3OhOg1Mafa4Ecu9ahsh: -----BEGIN CERTIFICATE-----MIICsDCCAZigAwIBAgIIdF+Wcca7gzkwDQYJKoZIhvcNAQELBQAwGDEWMBQGA1UEAwwNY2FvajdicjRpcHc2dTAeFw0xNzA4MDcxNDMyMzVaFw0xODA4MDcxNDMyMzZaMBgxFjAUBgNVBAMMDWNhb2o3YnI0aXB3NnUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCdrt40Otrveq46K3BzZuds6wDqsP0kZV+C3GdyTQWl53orBRtPIiEh6BauP17Rr19qadh7t4yFBb5thrXwBewseSNEL4j7sB0YoeNwRsmA29Fjfoe0yeNpLixFadL6dz7ej9xW2suPppIO6jA5SYgL6+S42ZlIauCnSQBKFcdP8QRvgDZBZ4A7CmuloRJst7GQzppa+YWR+Zg3V5reV8Ekrkjxhwgd+rMsGahxijY7Juf2zMgLOXwe68y41SGnn+1RwezAhnJgioGiwY2gP7z2m8yNZXhpUiX+KAP2xvYb60wNYOswuqfpya68rSmYT8mQjld1EPR21dBMjRQ8HfUBAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAAIUlqltRlbqiolGETmAUF8AiC008UCUmI+IsnORbHFSaACKW04m1iFH0OlxuAE1ECj1mlTcKb4md6i7n+Fy+fdGXFL73yhlSiBLu7XW5uN1/dAkynA+mXC5BDFijmvkEAgNLKyh40u/U1u75v2SFS+kLyMeqmVxvUHA7qA8VgyHi/FZzXCfEvxK5jye4L8tkAR34x5j5MpPDMfLkwLegUG+ygX+h/f8luKiQAk7eD4C59c/F0PpigvzcMpyg8+SE9loIEuJ9dRaRaTwIzez3QA7PJtrhu9h0TooTtkmF/Zw9HARrO0qXgT8uNtQDcRXZCItt1Qr7cOJyx2IjTFR2rE=-----END CERTIFICATE-----

The PEM encoding is considered safe in HTTP header values (with new lines removed). If the PEM string was left with new lines or other special chars this may break the header, so some proxies, like Nginx, can apply additional URL-encoding on top of the PEM string to prevent this from happening.

Starting with v8.1 the Connect2id server can also accept headers with additional URL-encoding of the PEM certificate.

Sec-Client-X509-Cert-alaeLuL8geiqu3OhOg1Mafa4Ecu9ahsh: -----BEGIN%20CERTIFICATE-----MIICsDCCAZigAwIBAgIIdF%2BWcca7gzkwDQYJKoZIhvcNAQELBQAwGDEWMBQGA1UEAwwNY2FvajdicjRpcHc2dTAeFw0xNzA4MDcxNDMyMzVaFw0xODA4MDcxNDMyMzZaMBgxFjAUBgNVBAMMDWNhb2o3YnI0aXB3NnUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCdrt40Otrveq46K3BzZuds6wDqsP0kZV%2BC3GdyTQWl53orBRtPIiEh6BauP17Rr19qadh7t4yFBb5thrXwBewseSNEL4j7sB0YoeNwRsmA29Fjfoe0yeNpLixFadL6dz7ej9xW2suPppIO6jA5SYgL6%2BS42ZlIauCnSQBKFcdP8QRvgDZBZ4A7CmuloRJst7GQzppa%2BYWR%2BZg3V5reV8Ekrkjxhwgd%2BrMsGahxijY7Juf2zMgLOXwe68y41SGnn%2B1RwezAhnJgioGiwY2gP7z2m8yNZXhpUiX%2BKAP2xvYb60wNYOswuqfpya68rSmYT8mQjld1EPR21dBMjRQ8HfUBAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAAIUlqltRlbqiolGETmAUF8AiC008UCUmI%2BIsnORbHFSaACKW04m1iFH0OlxuAE1ECj1mlTcKb4md6i7n%2BFy%2BfdGXFL73yhlSiBLu7XW5uN1%2FdAkynA%2BmXC5BDFijmvkEAgNLKyh40u%2FU1u75v2SFS%2BkLyMeqmVxvUHA7qA8VgyHi%2FFZzXCfEvxK5jye4L8tkAR34x5j5MpPDMfLkwLegUG%2BygX%2Bh%2Ff8luKiQAk7eD4C59c%2FF0PpigvzcMpyg8%2BSE9loIEuJ9dRaRaTwIzez3QA7PJtrhu9h0TooTtkmF%2FZw9HARrO0qXgT8uNtQDcRXZCItt1Qr7cOJyx2IjTFR2rE%3D-----END%20CERTIFICATE-----

Nginx has marked the plain PEM certificate variable ($ssl_client_cert) as deprecated and encourages use of $ssl_client_escaped_cert.

Check out the updated TLS configuration guide for more information.

Seamless rolling upgrades from 7.x when refresh tokens are issued

Connect2id server 8.0 introduced a new encoding of issued refreshed to enable the inclusion of encrypted metadata. Tokens with the old encoding (7.x and earlier) will still be honoured and accepted, so OAuth clients with them can still used them to obtain new access tokens.

However, in a rolling cluster upgrade from Connect2id server 7.x to 8.x if a client tries to use a new refresh token obtained from an 8.x server instance against an 7.x instance the token will not be recognised, resulting in a invalid_grant error.

To prevent such errors from occurring during rolling cluster upgrades Connect2id server 8.1 introduces a new authzStore.options.issueLegacyRefreshTokens configuration property. When enabled the server will issue refresh tokens in the old encoding, so 7.x and older instances in the cluster can recognise them.

After the rolling upgrade is completed and all server instances are 8.1 the setting should be disabled (on a subsequent upgrade) to start issuing refresh tokens with the new encoding.

Other features and resolved issues

Grant handler loading (for the password, client credentials and other grants) was broken in 8.0 which prevented loading of multiple SPI implementations. The behaviour was fixed, so deployments which load two or more grant handlers but enable only one can continue to function as before.

The new release also improves logging and exception reporting in several areas.

For more information read the release notes below.


To download a ZIP package of Connect2id server 8.1:

SHA-256: 365de12aca275789d0899ba3a04d0a38b78d479fbe8e50690f7cbb75e5f8ab7e

As WAR package only:

SHA-256: 210f4fec34db979bda24b02855c223d3f7751435f9f306678e4d680ab2bd4ace


Contact Connect2id support.

Release notes

8.1 (2020-02-03)


  • Updates mTLS client authentication by accepting client X.509 certificates with additional URL-encoding on top of the PEM encoding when the certificate is received from a TLS termination proxy via the HTTP security header configured by "op.tls.clientX509CertHeader".

  • Adds a new "authzStore.options.issueLegacyRefreshTokens" configuration property to facilitate seamless rolling cluster upgrades from Connect2id server 7.x and earlier versions to 8.x. When this setting is enabled Connect2id server 8.1 instances will issue refresh tokens in the old encoding supported and recognised in 7.x (instead of the new refresh token encoding with additional encryption of metadata, introduced in 8.0). After the rolling upgrade is completed and all instances are 8.1 the setting can be disabled (on a subsequent upgrade) to start issuing new refresh tokens with the new encoding.


  • /WEB-INF/

    • Client X.509 certificates received with the HTTP security header configured by "op.tls.clientX509CertHeader" can have an optional additional URL-encoding (also called percent encoding) of the PEM-encoded string. The presence of additional URL-encoding is automatically detected.
  • /WEB-INF/

    • New "authzStore.options.issueLegacyRefreshTokens" configuration property. If true the Connect2id server will issue refresh tokens in the legacy format supported up to v7.x. Intended to facilitate seamless rolling cluster upgrades to v8.x and later without producing invalid_grant errors when a new 8.x refresh token is used at a Connect2id server 7.x instance. The default value is false (no issue of legacy refresh tokens).

Resolved issues

  • Fixes parse exception reporting when reading DynamoDB items from "pending_codes" and "id_access_tokens", logs JSON with error message (issue authz-store/169).

  • Fixes loading of OAuth 2.0 grant handler SPIs when multiple implementations are available (broken in Connect2id server 8.0, issue server/515).

  • Logs the names of the OAuth 2.0 grant handler SPI classes when multiple are enabled for a given grant type (issue server/515).

  • Logs the names of an SPI class when a single must be loaded and multiple are available (issue common/60).

  • Disables the setting of the "jsessionid" cookie in the Connect2id server banner page (index.jsp) as no cookie or session is required by the page (issue server/516).

Dependency changes

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

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

  • Upgrades to com.nimbusds:common:2.36

  • Adds new dependency to io.github.cemiltokatli.uricomponent:uri-component:1.0