Connect2id server 9.1 updates JWT-secured token introspection responses

This release of the Connect2id server updates support for JWT Response for OAuth Token Introspection to the upcoming version 09. This OAuth 2.0 extension is intended for securing token introspection results with a digital signature, which is intended for business cases where the identity provider assumes liability for the content of the token. One such case is services using verified person data to create digital certificates, which in turn are used to create qualified electronic signatures (QES).

What changes were made in version 09?

  • The content of the token introspection response was moved to a separate JWT claim called token_introspection. This is done to prevent potential confusion and clashes of token introspection response parameters with top-level JWT claims that bear the same name.

  • The following top-level JWT claims are now made mandatory:

    • iss -- Set to the Connect2id server issuer URL.
    • aud -- Set to the client_id of the introspection endpoint caller (typically a resource server inspecting a token).
    • iat -- Set to the issue timestamp.
    • token_introspection -- JSON object containing the token introspection response mentioned above.
  • The JWT-secured response is triggered by an Accept HTTP request header set to application/token-introspection+jwt, unless op.token.introspection.alwaysRespondWithJWT is enabled, when the Accept header will be ignored and the response will always be JWT-secured.

Example request, the client (the resource server) authenticates at the introspection endpoint with basic authentication, using its registered client_id and client_secret. Notice the Accept header:

POST /token/introspect HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Accept: application/token-introspection+jwt


Example response with a signed JWT in the body:

HTTP/1.1 200 OK
Content-Type: application/token-introspection+jwt


Example decoded JWT header, using the same JWS algorithm and key as for self-contained (JWT) access tokens:

  "alg" : "RS256",
  "typ" : "5iKs",
  "kid" : "token-introspection+jwt"

Example decoded JWT claims, notice how the introspection members are now encapsulated in a container claim:

  "iss"                 : "",
  "aud"                 : "kengo6Bo",
  "token_introspection" : { "active"    : true,
                            "iss"       : "",
                            "aud"       : "kengo6Bo",
                            "iat"       : 1514797822,
                            "exp"       : 1514797942,
                            "client_id" : "paiB2goo0a",
                            "scope"     : "openid email profile",
                            "sub"       : "c5787848-d360-42fa-b01f-558b8f33506c",
                            "jti"       : "doRu8eeNg0geew7u" }

The legacy JWT-secured introspection response from draft-ietf-oauth-jwt-introspection-response-08 can still be triggered, by setting the Accept header to application/jwt:

POST /token/introspect HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Accept: application/jwt



To download a ZIP package of Connect2id server 9.1:

SHA-256: 80d252bc3a1a966bee9abdaeb079b5b1a0f1e11c8c2d1bf5a6ae97c038421995

As WAR package only:

SHA-256: eb547fd5a7eecc804980c367b556808639c2665e294fd4c1eb03c08ad4e128b0


Contact Connect2id support.

Release notes

9.1 (2020-03-24)


  • /token/introspect

    • Updates "JWT Response for OAuth Token Introspection" support to the upcoming draft-ietf-oauth-jwt-introspection-response-09 version.

      For a client (resource server) to obtain a JWT-secured introspection response it must submit an introspection request with the Accept HTTP request header set to "application/token-introspection+jwt". The request must be authorised with the registered client authentication method or with an access token.

      The JWT response will be JWS signed and include the following JWT claims:

      • "iss" -- Set to the OpenID Provider / Authorisation server issuer URL.
      • "aud" -- Set to the client_id of the caller (resource server).

      • "iat" -- The issue timestamp.

      • "token_introspection" -- A JSON object containing the token introspection response members, such as "active", etc.

      The optional op.token.introspection.jwtType configuration property that overrides the JWT "typ" (type) header applies.

      Legacy JWT-secured introspection responses (according to draft-ietf-oauth-jwt-introspection-response-08) will continue to be supported, for a client (resource server) to request one the Accept HTTP request header must be set to "application/jwt".


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

  • com.nimbusds.openid.connect.provider.spi.par.ValidatorContext

    • Adds a getIssuer() method to the PAR ValidatorContext.

Dependency changes

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

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