Blog »

Connect2id server 12.9 enables explicitly typed ID tokens and UserInfo JWTs

2022-03-23

This release of the Connect2id server arrives with support for explicitly typed OpenID Connect tokens and a new client metadata parameter to simplify refreshing of client secrets.

Explicitly typed ID tokens and UserInfo JWTs

Applications that deal with JSON Web Tokens (JWT) meant for different purposes can potentially become vulnerable to accidental mix ups of JWTs and even to attacks that try to pass one type of JWT for another. The claims structure of JWTs minted for different purposes would normally differ, however not all JWT consuming logic may be robust enough to do this correctly and this may become a security issue.

To prevent such mix ups the JSON Web Token standard (RFC 7519) defines an optional "typ" (type) header parameter to give the JWT an explicit type. Consuming logic needs only to probe this header to find out the JWT purpose, without resorting to further analysis of the claims in the JWT payload.

OpenID Connect does not specify an explicit type for ID tokens and for signed UserInfo responses, relying on the fact that their claims sets differ substantially. Clients also obtain them at different endpoints - ID tokens at the token endpoint and signed UserInfo responses at the UserInfo endpoint.

Example ID token claims set:

{
  "iss"   : "https://c2id.com",
  "aud"   : "123",
  "sub"   : "alice",
  "iat"   : 1648547159,
  "exp"   : 1648547759
}

Example UserInfo JWT claims set:

{
  "iss"   : "https://c2id.com",
  "aud"   : "123",
  "sub"   : "alice",
  "iat"   : 1648547159,
  "email" : "[email protected]"
}

Notice how the ID token differs only by the presence of the "exp" (expiration) claim (the email UserInfo claim is optional).

In scenarios like token exchange the lack of explicit typing can however turn into an issue. That's why more recent specifications coming out of the the OAuth working group and the OpenID Foundation started making use of the explicit JWT typing. For example, at+jwt for access tokens compliant with RFC 9068.

In this new release Connect2id server deployments will be able to set explicit type headers for the ID tokens and UserInfo JWTs. This is made possible by two new configuration properties:

  • op.idToken.jwtType -- Sets the type header of issued ID tokens, if set the recommended value is id_token+jwt. Disabled by default.
  • op.userinfo.jwtType -- Set the type header of issued UserInfo JWTs, if set the recommended value is userinfo+jwt. Disabled by default.

A future release of the Connect2id server will also add support for typed back-channel logout tokens.

Sample ID token without explicit typing:

  • JWS Header:

    {
   "kid" : "CXup",
   "alg" : "RS256"
}

  • Claims:

    {
   "iss"   : "https://c2id.com",
   "aud"   : "123",
   "sub"   : "alice",
   "iat"   : 1648547159,
   "exp"   : 1648547759
}

Sample ID token with explicit typing (note the id_token+jwt header):

  • JWS Header:

    {
   "kid" : "CXup",
   "alg" : "RS256",
   "typ" : "id_token+jwt"
}

  • Claims:

    {
   "iss"   : "https://c2id.com",
   "aud"   : "123",
   "sub"   : "alice",
   "iat"   : 1648547159,
   "exp"   : 1648547759
}

The IDTokenValidator was updated in v9.32 of the OAuth 2.0 / OpenID Connect SDK to support explicitly typed ID tokens. Note, since this is a non-standard feature, other libraries may not be able to observe the "typ" header or may simply reject explicitly typed ID tokens.

New client metadata parameter to simplify secret refresh

The standard method to refresh a client's secret is to make a PUT request to the client's registration resource. If the client secret has expired or the server is configured to always refresh the secret on client update the response will include a newly generated secret. In case those conditions aren't met the client can now use a refresh_client_secret metadata field to explicitly signal its intent and receive a new secret.

Example client update request, showing use of the new refresh_client_secret metadata field:

PUT /clients/s6BhdRkqt3 HTTP/1.1
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0
Content-Type: application/json

{
  "client_id"             : "s6BhdRkqt3",
  "redirect_uris"         : [ "https://client.example.org/cb" ],
  "client_name"           : "My App",
  "refresh_client_secret" : true
}

For simplicity our recommendation is to always use the refresh_client_secret whenever a client secret refresh is desired.

The old secret will remain usable for a period of 30 minutes, to enable a seamless rollover to the new one, avoiding client interruption or temporary client authentication failures.

The OAuth 2.0 client authentication guide was updated to describe this new feature.

Operation of client secret codec plugins is not affected by the new refresh_client_secret metadata field and they will continue to work as before.

Download 12.9

For the signature validation: Public GPG key

Standard Connect2id server edition

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

GPG signature: Connect2id-server.zip.asc

SHA-256: d79e79a829817a52202efc27399f0c50c7ceda5322ec00863be98248017ea97e

Connect2id server 12.9 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: 5f87b6cf5a140891ade20e57acf8b2140b06c7a65b4063f4a7a24fe2572eecfe

Multi-tenant edition

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

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

SHA-256: 435b90170d61896598a61baa43fddb970aa0a3c390b98702018c17b201de757d

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

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

SHA-256: 0022ce97081e2054aa2e389358f043a82f1d4db2e39f6e2621590e4b4abe7059

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

12.9 (2022-03-23)

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.token.idToken.jwtType -- New configuration property to set the type ("typ") header of issued ID tokens. Explicit JWT typing is a simple measure to prevent mix-up of ID tokens JWTs with other types of JWT without having to examine the JWT claims structure. Note this is a non-standard feature and may result in rejection of ID tokens by client libraries not able or not configured to handle typing. Typing is disabled by default.

    • op.token.userinfo.jwtType -- New configuration property to set the type ("typ") header of issued UserInfo JWTs. Explicit JWT typing is a simple measure to prevent mix-up of UserInfo JWTs with other types of JWT without having to examine the JWT claims structure. Note this is a non-standard feature and may result in rejection of UserInfo JWTs by client libraries not able or not configured to handle typing. Typing is disabled by default.

Web API

  • /clients/

    • Adds support for a new optional "refresh_client_secret" client metadata field of type boolean for use in client update requests. When the "refresh_client_secret" is set to true in a client update request the Connect2id server will refresh the client secret, overriding a disabled op.reg.alwaysRefreshClientSecretOnUpdate configuration setting. When "refresh_client_secret" is set to false or omitted the refresh of the client secret will be determined by the configured op.reg. alwaysRefreshClientSecretOnUpdate setting.

      The intent of "refresh_client_secret" is to give registered clients a direct control over how soon or often to refresh their secret. This is a non-standard metadata field.

Dependency changes

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

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

  • Updates to com.nimbusds:lang-tag:1.6

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

  • Updates to org.postgresql:postgresql:42.3.3