Connect2id server 12.5

This release of the Connect2id server for OAuth 2.0 and OpenID Connect brings several API and configuration updates.

Front-channel logout with custom URI schemes

OpenID Connect Front-Channel Logout 1.0 is a minimal protocol that lets an OpenID relying party register a callback to receive a notification when a user logs out.

The logout spec is geared towards web applications, however it can also potentially be used with native (mobile) applications. Starting with this release clients can also be registered with custom URI schemes (other than HTTPS), to enable an IdP / SSO server to send logout notifications into native applications that cannot handle "universal" (also called claimed) HTTPS URLs.

Note, universal links have the advantage of providing a stronger guarantee of the application's identity because they require the OS to validate the application's web domain certificate.

Example registration setting login and logout callbacks for a native client with custom URIs:

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

{
  "application_type"                     : "native",
  "redirect_uris"                        : [ "org.example.myapp:login-callback" ],
  "frontchannel_logout_uri"              : "org.example.myapp:logout-callback",
  "frontchannel_logout_session_required" : true,
  "token_endpoint_auth_method"           : "none"
}

Example notification, where the iss parameter identifies the OpenID provider, and the sid identifies the session which was established when the user was signed into the application:

org.example.myapp:logout-callback?iss=https://c2id.com&sid=Ohgah5ukieso0ohB

Localhost redirection URLs for web client testing

A new op.reg.allowLocalhostRedirectionURIsForTest configuration property is added to allow registration of HTTP and HTTPS localhost redirection URIs for the purpose of testing and developing OAuth 2.0 web application clients.

The client registration standard prohibits web clients (application_type=web) from registering localhost redirection URIs. If you are developing a web application and want to test it as an OAuth client on your localhost one way to work around that (requires administrative OS control) is to define a host alias for the loopback interface, and then provision the host with a self-signed web server certificate (check our guide for that).

With this new setting a web client can be tested in a localhost environment without resorting to an alias workaround.

op.reg.allowLocalhostRedirectionURIsForTest=true

Example registration:

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

{
  "redirect_uris" : [ "http://localhost:8008/login-callback" ]
}

Remember, this setting must not be used in production!

Opting out of access token encryption with pairwise subjects

The consent object in the authorisation session API was updated to allow deployments to opt out of the access token encryption (for self-contained tokens that are JWTs) when the OpenID relying party is registered for pairwise subject identifiers and the token subject is also set to be pairwise.

Example consent:

{
  "scope"        : [ "read", "write" ],
  "audience"     : [ "https://api.example.com" ],
  "access_token" : { "encrypt"  : false,
                     "sub_type" : "PAIRWISE" }
}

Check out the release notes below for a detailed explanation of API change and the reasoning behind the default encryption policy.

Download

Standard Connect2id server edition

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

SHA-256: 9fbb8be83389372ff22d0c303b282b84ce55261af506f0cb28eee45b521366a1

Connect2id server 12.5 WAR package: c2id.war

SHA-256: d98eb7c092df4535933188aea49681b5a93e7d95054379b4974d248d3e93509a

Multi-tenant edition

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

SHA-256: c63f009a3856c8ec8cc2703a88fb808207eeea2811006aa6469dd9956901e57e

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

SHA-256: 65f406e4cd04313da28eded526af2ffaf26c4f5c3d8a67621ca32dd05f42591c

Questions?

Contact Connect2id support.


Release notes

12.5 (2021-11-29)

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.reg.allowLocalhostRedirectionURIsForTest -- New configuration property to allow registration of HTTP and HTTPS localhost redirection URIs for the purpose of testing and developing OAuth 2.0 web application clients. The default value is false (not allowed). Must not be used in production!

Web API

  • /clients

    • Allows registration of a frontchannel_logout_uri with a custom URI scheme. Intended to support front-channel logout notifications to mobile applications (application_type=native) with a custom URI scheme. Previously only https URLs were allowed. The http URL scheme remains disallowed.
  • /authz-sessions/rest/v3/

    • Consent: The API is updated to support opting out of the additional encryption of self-contained (JWT-encoded) access tokens which the Connect2id server will apply when the OpenID relying party is registered for pairwise subjects (with subject_type=pairwise) and the access token subject is also set for a pairwise identifier (with access_token.sub_type=PAIRWISE). The default behaviour of the Connect2id server is to always apply encryption to the JWT-encoded access tokens when the OpenID relying party is registered for pairwise subjects, in order to prevent exposing of information about the underlying subject ID which would happen if the self-contained access token was only signed. When the token subject is made pairwise there is still a theoretical possibility for the OpenID relying party to perform some correlation between the end-users, by observing the variations of the pairwise identifier across multiple token audiences (resource servers), hence the strict default Connect2id policy to also encrypt access tokens with a pairwise subject. To opt out of the default encryption use access_token.encrypt=false in the consent object.
  • /direct-authz/rest/v2/

    • Direct authorisation request: The API is updated to support opting out of the additional encryption of self-contained (JWT-encoded) access tokens which the Connect2id server will apply when the OpenID relying party is registered for pairwise subjects (with subject_type=pairwise) and the access token subject is also set for a pairwise identifier (with access_token.sub_type=PAIRWISE). See the explanation about the related authorisation session web API change. To opt out of the default encryption use access_token.encrypt=false in the consent object.

SPI

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

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

      • Refactors the class for Optional self-contained access token preference.

Resolved issues

  • Includes the JWK kid and crv (for EC keys) in the OP0102 log error message to ease key identification when a server JWK fails the signing JWK validation on startup (issue server/696).

Dependency changes

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

  • Updates to com.nimbusds:oauth2-oidc-sdk:9.20

  • Updates to com.nimbusds:c2id-server-jwkset:1.26

Connect2id server 12.4: Support for ES256K, RSA-OAEP-384, RSA-OAEP-512 and XC20P

The October release of the Connect2id server makes new cryptographic capabilities available to our customers.

  • The ES256K JWS algorithm, based on the secp256k1 elliptic curve, which found popularity in Ethereum and Bitcoin, can now be used to sign tokens issued by the Connect2id server as well as request objects (JARs) sent by OAuth 2.0 clients. Clients can also use ES256K to authenticate with the private_key_jwt method at the token endpoint.

    Note that the JWK set generator tool for the Connect2id server was updated to be able to generate EC keys with the secp256k1 curve necessary for ES256K signatures.

  • The EdDSA JWS algorithm (with Ed25519 curve), introduced in Connect2id server 9.4 to boost the signing throughput of JWT-encoded access tokens (by a factor of 62!), can now also be applied to sign ID tokens, UserInfo JWTs and authorisation responses (JARM).

  • The RSA-OAEP-256 JWE algorithm for encrypting to a public RSA key is now complemented by the RSA-OAEP-384 and RSA-OAEP-512 algorithms which use SHA-384 resp SHA-512. They can be used in all places where a JWE algorithm for public key encryption is expected.

  • XC20P is a JWE content encryption method with extended nonce ChaCha20 / Poly1305. With 256 bit symmetric encryption strength it represents an alternative to the existing AES-based algorithms for JWE - A256CBC-HS512 and A256GCM. ChaCha20 allows for efficient implementation in software and applications on constrained devices that lack dedicated CPU instructions for AES may achieve performance and power saving advantages by switching to XC20P.

A complete list of the JWS and JWE algorithms the Connect2id server currently supports is available in the datasheet.

Here is an example OpenID relying party registration to receive ID tokens and UserInfo responses signed with EdDSA. The client registration guide has more examples.

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

{
  "redirect_uris"                : [ "https://client.example.org/callback" ],
  "id_token_signed_response_alg" : "EdDSA",
  "userinfo_signed_response_alg" : "EdDSA"
}

The new JWS and JWE algorithms are already implemented in the open source Nimbus JOSE+JWT library for Java. There are helpful examples how to deal with those algorithms on the client side:

Download

Standard Connect2id server edition

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

SHA-256: f4f7088808e660b30c74ba2050aa2965698b8d8a27e4d2bf84d44cff4b956ded

Connect2id server 12.4 WAR package: c2id.war

SHA-256: 7996fbd1b19dd15b1dfc44113676cd80915d0c77e90d0f66f06598828cb04b03

Multi-tenant edition

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

SHA-256: d3c18c0144ae60b5c9ff71014511995797cf096aeb98c0aa91328f5dfe88e541

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

SHA-256: 52c12ab1a5d9f6969d5d92e2567a2ce4e8b48201cbb7af87e174d137fa80970e

Questions?

Contact Connect2id support.


Release notes

12.4 (2021-10-27)

Summary

  • Expands the cryptographic capabilities of the Connect2id server with the ES256K algorithm for JWS, RSA-OAEP-384 and RSA-OAEP-512 for JWE and XC20P (extended nonce ChaCha20 / Poly1305) as JWE encryption method. The ES256K and EdDSA (with 25519 curve) JWS algorithms can now be used to sign ID tokens, UserInfo responses and authorisation responses (JARM). JWT-encoded access tokens can now be signed with the ES256, ES256K, ES384 and ES512 JWS algorithms.

    Specifications:

    • ES256K: https://datatracker.ietf.org/doc/html/rfc8812#section-3.1
    • RSA-OAEP-384 and RSA-OAEP-512: https://www.w3.org/TR/WebCryptoAPI/
    • XC20P: https://datatracker.ietf. org/doc/html/draft-amringer-jose-chacha-02#section-4.1

Configuration

  • /WEB-INF/jwkSet.json

    • Adds support for including an optional signing JSON Web Key (JWK) of type (kty) EC and with curve (crv) secp256k1 for performing signatures with the ES256K JWS algorithm.
  • /WEB-INF/oidcProvider.properties

    • op.token.authJWSAlgs -- Adds token endpoint private_key_jwt client authentication support for the ES256K JWS algorithm.

    • op.authz.requestJWSAlgs -- Adds request object / JAR support for the ES256K JWS algorithm.

    • op.authz.requestJWEAlgs -- Adds request object / JAR support for the RSA-OAEP-384 and RSA-OAEP-512 JWE algorithms.

    • op.authz.requestJWEEncs -- Adds request object / JAR support for the XC20P (extended nonce ChaCha20 / Poly1305) JWE encryption method .

    • op.authz.responseJWSAlgs -- Adds JARM support for the ES256K and EdDSA (with 25519 curve) JWS algorithms.

    • op.authz.responseJWEAlgs -- Adds JARM support for the RSA-OAEP-384 and RSA-OAEP-512 JWE algorithms.

    • op.authz.responseJWEEncs -- Adds JARM support for the XC20P (extended nonce ChaCha20 / Poly1305) JWE encryption method.

    • op.idToken.jwsAlgs -- Adds ID token support for the ES256K and EdDSA (with 25519 curve) JWS algorithms.

    • op.idToken.jweAlgs-- Adds ID token support for the RSA-OAEP-384 and RSA-OAEP-512 JWE algorithms.

    • op.idToken.jweEncs -- Adds ID token support for the XC20P (extended nonce ChaCha20 / Poly1305) JWE encryption method.

    • op.userinfo.jwsAlgs -- Adds UserInfo JWT response support for the ES256K and EdDSA (with 25519 curve) JWS algorithms.

    • op.userinfo.jweAlgs -- Adds UserInfo JWT response support for the RSA-OAEP-384 and RSA-OAEP-512 JWE algorithms.

    • op.userinfo.jweEncs -- Adds UserInfo JWT response support for the XC20P (extended nonce ChaCha20 / Poly1305) JWE encryption method.

  • /WEB-INF/authzStore.properties

    • authzStore.accessToken.jwsAlgorithm -- Adds support for signing self-contained (JWT) access tokens with the ES256, ES256K, ES384 and ES512 JWS algorithms.

    • authzStore.accessToken.jweMethod -- Adds support for direct encryption of self-contained (JWT-encoded) access tokens with the XC20P (extended nonce ChaCha20 / Poly1305) JWE encryption method.

Resolved issues

  • Updates the HTTP claims source connector to include an "Accept: application/json" HTTP header in the outgoing requests (issue httpcs/1).

  • Updates the AS0213 log INFO message to include the type of the introspected access token (issue server/692).

  • Updates the SE3000 log INFO message to indicate when a X.509 certificate is present for a loaded server JWK (issue server/694).

Dependency changes

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

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

  • Updates to com.nimbusds:oauth2-session-store:14.7

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

  • Updates to com.nimbusds:nimbus-jwkset-loader:5.2

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

  • Updates to com.nimbusds:oidc-claims-source-http:2.2

Issuer aliases in Connect2id server 12.3

The September release of the Connect2id server brings support for issuer aliases. An issuer alias URL can be configured to migrate a Connect2id server deployment seamlessly and over time from one issuer identifier URL to another. Issuer aliases can also be used to identify an OpenID provider / OAuth 2.0 authorisation server by multiple URLs.

Check the new guide for how to configure and switch between issuer aliases in a Connect2id server deployment.

Download

Standard Connect2id server edition

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

SHA-256: 6bd77fc1d3ba1a0222c222ca8b194ec2c37164b6585c96c871725bc4279c7509

Connect2id server 12.3 WAR package: c2id.war

SHA-256: 2050dea95db72dfb57ab4f99fef4356068f262d19698aa1c196ba398f01bfbd6

Multi-tenant edition

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

SHA-256: 44c87b33cef26e754d1702b99651fd594dd5b1ec3d70c94fb0f8919136aabf91

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

SHA-256: d12ba4fa77de3cf836e43a5f6e646a7dfe8b9aeed4e8271c4504a3632e612ec5

Questions?

Contact Connect2id support.


Release notes

12.3 (2021-09-17)

Summary

  • Supports issuer URL aliases. An issuer alias URL can be configured to migrate
    a Connect2id server deployment seamlessly and over time from one issuer identifier URL (op.issuer) to another. Issuer aliases can also be used when an OpenID provider / OAuth 2.0 authorisation server is known by multiple URLs.

    The allowed issuer aliases, if any, are configured in a new optional op.issuerAliases.* property.

    A Connect2id server endpoint or API will process a request under an issuer alias when the HTTP request header "Issuer" is present and set to a value matching a configured alias. If no "Issuer" header is specified the default issuer configured in op.issuer will be assumed. The default op.issuer will also be assumed when the "Issuer" header is explicitly set to it. If the "Issuer" header is set to an issuer URL that isn't configured the Connect2id server will return an HTTP 400 error with a message.

    The "Issuer" header must be set by the reverse HTTP proxy or similar trusted internal infrastructure. It must not be settable by client applications. Connect2id server deployments must scrub the incoming client application HTTP requests from any "Issuer" headers.

    Issuer aliases are supported in the regular as well as the multi-tenant Connect2id server edition.

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.issuer.aliases.* -- New optional configuration property for setting one or more issuer alias URLs of the OpenID provider / OAuth 2.0 authorisation server. Can be used to migrate from one issuer URL (op.issuer) to another, or to operate an OpenID provider / OAuth 2.0 authorisation server that is known by multiple URLs. Blank if none.

Web API

  • The standard OAuth 2.0 / OpenID Connect endpoints and Connect2id server specific web APIs will process a request under a configured issuer alias (op.issuerAliases.*) when the HTTP request includes an "Issuer" header set to the issuer alias URL. The header value must match the configured issuer alias URL exactly. If the "Issuer" header is set to an issuer URL that isn't configured the Connect2id server will return an HTTP 400 "Bad Request" error with an appropriate message.

Resolved issues

  • Updates log message OP6205 for reporting internal token handler errors to include the client ID, authentication method and grant (issue server/693).

Dependency changes

  • Updates to com.nimbusds:tenant-manager:6.0.2

  • Updates to com.nimbusds:tenant-registry:6.0

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

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

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

  • Updates to org.cryptomator:siv-mode:1.4.3

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

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

DPoP tokens with the OpenID Connect developer client

Our open source web client for testing OpenID Connect compliant providers received an update to handle DPoP tokens.

OpenID Connect client

DPoP is a new type of OAuth 2.0 token, designed primarily for Single Page Applications (SPAs) and with higher-grade security than the common Bearer tokens. The extra DPoP security makes the token "sender-constrained", by binding it to a private RSA or EC key that belongs to the client. A DPoP token that is leaked, by accident or through some malicious action, cannot be used on its own (as opposed to Bearer tokens). For a client to use a DPoP token at the intended endpoint it must also possess the private binding key and this key can be generated and stored via the SubtleCrypto API in a way that prevents its extraction from the browser.

Note, the DPoP token is not a security cure for buggy or vulnerable JavaScript code in a SPA! If the SPA is taken over in a XSS attack the malicious code may perform all the necessary operations to impersonate the legitimate user without exfiltrating the private key.

You can test DPoP in our online demo against the most recent Connect2id server release (v12.2):

Client URL https://demo.c2id.com/oidc-client/

To trigger a request for a DPoP token click on the Options "Show" button, then select a JWS algorithm for the DPoP proof, a signed JWT used to Demonstrate Proof-of-Possession (DPoP) of the key at the OAuth 2.0 server. You can select RS256 or any other JWS algorithm that is supported by the server.

DPoP request

When done click on "Authenticate with OpenID Connect" and follow the flow through the login and consent screens on the server.

The type of the returned access token is shown in the standard token_type parameter:

DPoP response

If the server issued a refresh token, and the OAuth 2.0 client / OpenID relying party is public (as an SPA technically is, because it has no authenticating client credentials), the refresh token will also be DPoP bound, just like the access token, to prevent its use in case of a leak.

This web client is built with the open source OAuth 2.0 / OpenID Connect SDK, which implements all standards in the OAuth 2.0 and OpenID Connect space, and the majority of drafts in development. Feel free to fork it or contribute if you have ideas!

To join the DPoP discussion check out the OAuth WG mailing list.

DPoP access tokens in Connect2id server 12.2

Connect2id server 12.2 introduces support for DPoP tokens and configuring longer RSA keys. It also addresses several issues, described in the release notes.

DPoP access tokens

Single-page applications (SPA) can now request the issue of DPoP access tokens from the Connect2id server. This is a new kind of token, with stronger security properties than the default Bearer access tokens in OAuth 2.0. The DPoP token comes with a protection against unauthorised use in case it suffers an accidental or malicious leak. This is achieved by binding the token to a private key held by the client. To prevent a leak of the key itself the client should store it behind an API that renders its private parameters inaccessible to application code. The SubtleCrypto (WebCrypto) API has this option, its generateKey() method for RSA an EC keys when called with extractable=false will prevent JavaScript application code from exporting the private key parameters from the browser.

DPoP is an alternative to the conceptually similar client certificate bound tokens (RFC 8705), which ultimately are also bound to a private key. The difference is that in DPoP the binding is conveyed by means of a JWT instead of a client X.509 certificate.

Token type Binding Spec
Bearer none RFC 6750
Bearer with client certificate binding via client X.509 certificate RFC 8705
DPoP via signed JWT draft

The security properties of the client certificate binding are stronger because it involves the underlying secure transport layer (TLS), which made it the recommended method for applications, for example in the FAPI (financial-grade) OAuth 2.0 security profile. Browsers however don't provide a JavaScript API to enable application code to deal client certificates and mutual TLS, and to work around this the DPoP binding was invented.

The current DPoP spec is draft-ietf-oauth-dpop-03. It is now considered mature for production use and an official RFC should appear in the coming months.

How can an SPA request a DPoP token?

  1. At the start of a new session the SPA generates a new RSA or EC key pair, with disabled extraction (extractable=false) so the private key parameters cannot be exported from the browser.

  2. To request a DPoP access token the SPA generates a one-time-use JWT signed with the private key. The function of this JWT is to demonstrate possession of the key (hence the PoP acronym). Its header includes the public parameters of the signing key in JWK format. The claims include a unique JWT identifier (jti), the JWT issue time (iat) and the HTTP method and URI of the token endpoint (htm and htu).

    Example DPoP proof JWT header:

    {
     "typ" : "dpop+jwt",
     "alg" : "ES256",
     "jwk" : { "kty" : "EC",
               "crv" : "P-256",
               "x"   : "l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs",
               "y"   : "9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA"
     }
    }
    

    Example DPoP proof JWT claims:

    {
     "jti" : "f352c2fa-2d06-47b9-8347-8cda8a70a17d",
     "htm" : "POST",
     "htu" : "https://c2id.com/token",
     "iat" : 1562262616
    }
    
  3. The SPA makes the usual token request to the Connect2id server, but to trigger issue of a DPoP access token the proof JWT must be included in a HTTP request header called DPoP.

    POST /token HTTP/1.1
    Host: c2id.com
    Content-Type: application/x-www-form-urlencoded;charset=UTF-8
    DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7...
    
    grant_type=authorization_code
    &code=SplxlOBeZQQYbYS6WxSbIA
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
    &code_verifier=bEaL42izcC-o-xBk0K2vuJ6U-y1p9r_wW2dFWIWgjz-
    
  4. If the DPoP proof is valid and signed with a supported JWS algorithms (the Connect2id server supports all standard RSxxx, PSxxx and ESxxx algorithms) the token response will appear in the usual format, but with the token type set to DPoP.

    HTTP/1.1 200 OK
    Content-Type: application/json
    Cache-Control: no-store
    
    {
     "access_token"  : "tai1eeJ0eeNgiech.aing6aiJoopohsoh",
     "token_type"    : "DPoP",
     "expires_in"    : 600,
     "refresh_token" : "Ci8Fieshaikeiwaih8Tee5ZuaP5Iepho"
    }
    

How can an SPA access a protected resource with a DPoP token?

To access a protected resource with a DPoP token the client needs to generate a new DPoP proof, with one additional string claim - ath, set to the BASE64URL-encoded SHA-256 hash of the access token value. The htm (HTTP method) and htu (HTTP URI) claims must match those of the resource.

The UserInfo endpoint of the Connect2id server was updated to accept DPoP access tokens. The next section has pointers how to support DPoP tokens at a resource server.

Example DPoP proof JWT claims, for an HTTP GET to some protected resource at https://api.example.com/accounts/123 and with the access token hash in ath:

{
 "jti" : "a6716edf-eb6a-4649-8f6d-ac0325d26738",
 "htm" : "GET",
 "htu" : "https://api.example.com/accounts/123",
 "iat" : 1562262716,
 "ath" : "fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo"
}

The token is passed in a standard Authorization header, but instead of Bearer we have the token scheme set to DPoP:

GET /accounts/123 HTTP/1.1
Host: api.example.com
Authorization: DPoP tai1eeJ0eeNgiech.aing6aiJoopohsoh
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7...

If the resource server finds the DPoP proof or the token to be invalid or expired it will respond with a standard 401 Unauthorized and describe the error in the WWW-Authenticate header.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: DPoP error="invalid_token", error_description="Invalid / expired DPoP token", algs="RS256 PS256 ES256"

The algs parameter is optional, but very useful as it allows the client to find out which JWS algorithms for signing the DPoP proofs the resource server is able to handle.

How to support DPoP access tokens in a resource server?

The validation of DPoP tokens is described in the spec and has five steps:

  1. Verify the received access token in the usual way. For self-contained (JWT-encoded) tokens this means a local inspection by checking the JWT signature and claims; for an identifier-based token a call to the introspection endpoint of the Connect2id server.

  2. Check if the token authorisation has a cnf.jkt (confirmation of JWK thumbprint) parameter. If it does, then this is a DPoP token, so proceed further.

  3. Make sure the HTTP request includes a DPoP header and validate the proof JWT in it according to the described procedure.

  4. Compute the SHA-256 thumbprint of the public JWK found in the DPoP proof JWT and make sure it matches the JWK thumbprint (cnf.jkt) which the Connect2id server computed at the token endpoint when it minted the DPoP token. If the two thumbprints match this means we

  5. Finally, compute the SHA-256 hash of the access token and make sure it matches the ath claim of the DPoP proof JWT.

Resource servers may implement an additional check against DPoP proof replay, by recording the proof jti (JWT ID) and making sure it doesn't appear again within the time window determined by the acceptable iat age of the proofs.

The Java open source OAuth 2.0 SDK includes a DPoP proof verifier to help resource servers with this task.

How to refresh a DPoP token?

If the Connect2id server issued a refresh token the client must generate a DPoP proof whenever the refresh token is used.

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7...

grant_type=refresh_token
&refresh_token=Ci8Fieshaikeiwaih8Tee5ZuaP5Iepho

3072 and 4096 bit RSA keys

The Connect2id server can now be configured with longer RSA keys for signing the issued tokens and receiving encrypted request objects. 2048 bits remains the default length of the generated RSA keys when using the provided jwkset-gen tool.

Download

Standard Connect2id server edition

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

SHA-256: 33b49db86b129a6d92f9ae9fe5cb9562e257e9f7b87f4c3bffa5e4b8c439ccdd

Connect2id server 12.2 WAR package: c2id.war

SHA-256: a85433faf9802b954b24c0251b899af6f8a9ca9a0ec4f8b94f2e091f9185b7cf

Multi-tenant edition

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

SHA-256: a2cf8a27a6d3fbbc802203301273438104bf3c23404ae7efa3ebec41cc98974d

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

SHA-256: 688417f2dde16deb5f7e1f388d2d02060e6f4e8294b8d3633e731deca58864ac

Questions?

Contact Connect2id support.


Release notes

12.2 (2021-08-26)

Summary

  • Supports issue of access tokens of type DPoP, where the token is bound to a private RSA or EC key generated and held by the OAuth 2.0 client, potentially in secure storage preventing the key's extraction. Use of the DPoP token at a resource server requires proof of possession of the private key, preventing the use of an accidentally or maliciously leaked token by an unauthorised party. The original Bearer tokens in OAuth 2.0 offer no such protection to constrain their use.

    DPoP is intended primarily for browser based applications (also commonly called single page applications, or SPAs) where the alternative standard method to constrain a token, by binding it to a client X.509 certificate (RFC 8705), is not suitable, due to the browsers' poor support for dealing with client certificates and mutual TLS in JS application code.

    SPAs should use the WebCrypto browser API to generate the necessary private keys (with disabled extraction) for signing the DPoP proofs and actual signing.

    The Connect2id server accepts the following JWS algorithms for the signed DPoP proof JWTs: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES256K, ES384 and ES512.

    The Connect2id server will reject DPoP proof JWTs with an "iat" (issued-at time) that is more than 30 seconds behind or ahead of the current system time. Proof JWTs with a repeated "jti" (JWT ID) will also be rejected to prevent replay.

    See OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (draft-ietf-oauth-dpop-03).

  • The Connect2id server can now be configured with longer RSA signing and encryption keys, with lengths of 3072 and 4096 bits. The 2048 RSA key length remains the recommended for now and also the default for in provided jwkset-gen.jar tool for generating server JWK sets (the latest tool version is 1.22).

Configuration

  • /WEB-INF/jwkSet.json

    • Supports RSA signing and encryption keys of lengths 3072 and 4096 bits, in addition to 2048-bit RSA keys.

Web API

  • /.well-known/openid-configuration, /.well-known/oauth-authorization-server

    • dpop_signing_alg_values_supported -- New metadata field, lists the accepted JWS algorithms for the DPoP proof JWTs: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES256K, ES384 and ES512.
  • /token

    • Supports issue of access tokens of type DPoP for the following OAuth 2.0 grants:

      • authorisation code
      • refresh token
      • client credentials
      • resource owner password credentials
    • Supports issue of DPoP bound refresh tokens for public OAuth 2.0 clients.

  • /token/introspect

    • Supports introspection of access tokens of type DPoP. Introspection success responses for a DPoP token will have the "token_type" member set to "DPoP" and will include a "cnf.jkt" member set to the BASE64URL encoded SHA-256 thumbprint of the JWK used to sign the DPoP proof JWT.
  • /userinfo

    • Supports access tokens of type DPoP. Those must be included in the "Authorization" HTTP request header using the "DPoP" scheme.
  • /monitor/v1/metrics

    • Adds new "dPoP.numCachedJTIs" metric of type gauge showing the number of locally cached DPoP proof JWT ID (jti) entries intended to ensure the single use of received DPoP proofs at the token and UserInfo endpoints.

SPI

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

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

      • Adds default getJWKThumbprintConfirmation method to represent a DPoP JWK SHA-256 thumbprint confirmation.
    • com.nimbusds.openid.connect.provider.spi.tokens.MutableAccessTokenAuthorization

      • Implements AccessTokenAuthorization.getJWKThumbprintConfirmation

      • Adds withJWKThumbprintConfirmation setter method.

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

      • Updates the base abstract codec for JWT-encoded access tokens to support the "cnf.jkt" claim for DPoP.
    • com.nimbusds.openid.connect.provider.spi.tokens.introspection.BaseTokenIntrospectionResponseComposer

      • Updates the base abstract composer for customer token introspection responses support the "cnf.jkt" member for DPoP.

Resolved issues

  • Logs invalid refresh token (AS0270), refresh token request client_id - encoded client mismatch (AS0274) and refresh token not permitted (AS0275) events (issue authz-store/188).

  • Improves the efficiency when loading issuer lookup cache entries in the tenant registry (issue/tenant-registry/5).

  • Fixes a bug in AuthorizationRequest.Builder(AuthorizationRequest) that prevented copy of OpenID authentication request parameters, which can affect modification of requests in AuthorizationRequestValidator and PARValidator SPI implementations (issue oidc-sdk/367).

  • Refactors and extends handling of corrupted JSON in long_lived_authorizations items in a AWS DynamoDB table for get, put-if-absent, replace and remove operations to prevent an internal server error (HTTP 500) and clean up the detected corrupted items where feasible (issues authz-store/186, 187).

Dependency changes

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

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

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

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

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

  • Updates to com.nimbusds:tenant-registry:5.3.4