Connect2id Server articles

Connect2id server 6.18 allows token introspection responses to be JWTs

Posted on 2018-03-02

Updated token introspection

The Connect2id server can now return token introspection responses encapsulated in a signed JSON Web Token (JWT). The JWT can provide an additional layer of assurance where required by resource servers.

There are two ways to trigger a JWT to be returned for a token introspection response:

The JWT is signed with the same JWS algorithm and key used for the self-contained (JWT-encoded) access tokens.

Example introspection request:

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


Example introspection response encoded into a JWT:

HTTP/1.1 200 OK
Content-Type: application/jwt;charset=UTF-8


The extracted JSON object is a fully compliant token introspection response:

  "active"     : true,
  "token_type" : "Bearer",
  "iss"        : "",
  "sub"        : "n2cx7q2hqimjw",
  "scope"      : "read write",
  "iat"        : 1519995288,
  "exp"        : 1519995888,
  "client_id"  : "n2cx7q2hqimjw",
  "jti"        : "Yz5za_Yn7HI"

Note that the JWT output is a proprietary extension to RFC 7662.

JSON formatted logs and Logstash

The Connect2id server now packages a Log4j plugin to enable logs to be output in JSON format or piped to Logstash. Check the configuration howto.


To download a ZIP package of Connect2id server 6.18:

SHA-256: f985e8f199a82c656881bf54aa5096b02bb3d4aa719ecf55c44035edf5e8b0d0

As WAR package only:

SHA-256: da0868774f3c865b18aa30e21ae2d0362016c5d105c4600112864b95dfcbc486


Get in touch with Connect2id support.

Release notes

6.18 (2018-03-02)


  • /WEB-INF/oidcProviderProperties

    • op.token.introspection.alwaysRespondWithJWT — If true causes the token introspection responses to be always returned as a JWT signed with the same JWS algorithm and RSA key configured for self-contained (JWT) access tokens. The default value is false. This is a proprietary extension to RFC 7662, section 2.2.


  • /token/introspection

    • By passing an "Accept" HTTP request header set to "application/jwt" the Connect2id server will return the token introspection response as a JWT signed with the same JWS algorithm and RSA key configured for self-contained (JWT) access tokens. The default value is false. This is a proprietary extension to RFC 7662, section 2.2.

Resolved Issues

Dependency Changes

  • Adds com.github.dubasdey:log4j2-jsonevent-layout:0.0.4

Connect2id server 6.17 adds support for custom access token codecs, shaping of token introspection

Posted on 2018-02-26

The latest release of the Connect2id server for OpenID Connect identity provision opens new avenues for customisation. Three new SPIs were added, to enable plug in of alternative token codecs and for shaping of token introspection responses.

Self-contained access token claims codec

An SPI is provided for controlling what claims get included into JWT-encoded access tokens and how they get formatted. Resource servers which expect a particular structure or naming of the claims, such as for the non-standard JWT claims to represent scope or the client to which the token was issued, can benefit from this SPI.

The clear cut codec interface and the helpful base implementation make the job easy.

Identifier-based access token codec

When identifier-based access tokens are needed the Connect2id server generates secure random 128-bit numbers, with extra HMAC protection to detect and log fake tokens upon introspection.

Here also an SPI is provided for plugging in an alternative codec. For instance, to encapsulate the identifier in a signed JWT, along with the issuer URL, expiration time and client certificate confirmation, to provide resource servers in multi-tenant deployments with a hint where to introspect the token, and also allow part of the token validation to be done locally by the resource server, before the introspection call.

  "iss" : "",
  "jti" : "Hoofao7Ve1ohg4chahBee9Xee1ahvaed",
  "exp" : 1519660677,
  "cnf" : { "x5t#S256" : "Shoohie2Pee1ubi9aehai3leg0woidet" }

Token introspection

Shaping of token introspection responses is supported to control what token details a resource can see. For example, to limit the introspected scope only to those scope values which the resource server supports. This is can be important for data minimisation in authorisation server deployments with different service providers, or where access tokens can have multiple audiences.

Example introspection response for a token for two resource servers:

  "active"     : true,
  "iss"        : "",
  "scope"      : "",
  "token_type" : "Bearer",
  "sub"        : "alice"

Shaping the response for the service:

  "active"     : true,
  "iss"        : "",
  "scope"      : "",
  "token_type" : "Bearer",
  "sub"        : "alice"

Shaping the response for the service:

  "active"     : true,
  "iss"        : "",
  "scope"      : "",
  "token_type" : "Bearer",
  "sub"        : "alice"


To download a ZIP package of Connect2id server 6.17:

SHA-256: af37f5b29191178bbda93290b806f95ee495a4cc8a9dad4ce097d87d0918664d

As WAR package only:

SHA-256: fd9d057b99580d158c7ef247acda7452f0da319a25871d0ca29ef131305748d1


Get in touch with Connect2id support.

Release notes

6.17 (2018-02-26)


  • /WEB-INF/

    • accessToken.allowDirectInspection — The default setting becomes false (always require the master API token for inspecting access tokens at the /authz-store/rest/v2/inspection endpoint). The change is made to encourage resource servers to use the standard /token/introspect endpoint which requires the introspection request to be authenticated or authorised with an access token.

    • accessToken.selfContainedClaims — The setting for specifying the JWT claims to include in self-contained access tokens is no longer supported. If such customisation is required this can now be implemented via the SelfContainedAccessTokenClaimsCodec SPI (see below).


  • No changes


  • IdentifierAccessTokenCodec — Adds new optional SPI for customis generation and decoding of identifier-based access tokens. The SPI invocation context provides access to a secure random generator, an HMAC computer, a JWT signer and the OpenID claims source of the Connect2id server.

  • SelfContainedAccessTokenClaimsCodec — Adds new optional SPI for custom encoding and decoding of JWT claims in self-contained access tokens. The SPI invocation context provides access to a secure random generator, an HMAC computer, a JWT signer and the OpenID claims source of the Connect2id server.

  • TokenIntrospectionResponseComposer — Adds new optional SPI for custom composition of token introspection (RFC 7662) responses. The SPI invocation context provides access to the OpenID claims source of the Connect2id server and the registered information of the requesting client (for introspection requests with client authentication).

  • IDTokenIssueEventListener — Updates the SPI method to include EventContext (breaking change from v6.16).

  • AccessTokenIssueEventListener — Updates the SPI method to include EventContext (breaking change from v6.16).

Resolved Issues

  • Always encrypts issued self-contained (JWT) access tokens when the OpenID relying party is registered for pairwise subject identifiers. This is done to prevent leakage of the underlying subject identifier. Previously the consent logic driving the authorisation session had to explicitly take care of that by setting access_token.encrypt in the consent object to true (issue server/349).

  • Updates logging of client IP in HTTP requests to take into account Forwarded (RFC 7239) and X-Forwarded-For headers set by reverse proxies (issue common/57).

  • Fixes NoSuchMethodError on Dropwizard HealthCheckRegistry shutdown (issue server/341).

  • Logs cause of self-contained (JWT) access token failing inspection.

Dependency Changes

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

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

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

  • Upgrades to com.nimbusds:common:2.22

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

  • Upgrades to com.thetransactioncompany:java-property-utils:1.13

  • Upgrades to com.nimbusds:infinispan-cachestore-sql:2.7

  • Upgrades to BouncyCastle 1.59

  • Upgrades to Dropwizard Metrics 3.2.6.

  • Upgrades to com.unboundid:unboundid-ldapsdk:4.0.4

  • Upgrades to Apache Commons Lang 3.7

  • Upgrades to Log4j 2.10.0

Connect2id server 6.16

Posted on 2017-12-08

Improved DevOps support

DevOps engineers will love the new Connect2id server release:

  • The server JWK set for signing the issued tokens and performing other cryptographic operations can now be passed via a Java system property, just like the rest of the configuration. This means that the server WAR package can be distributed and deployed onto Apache Tomcat without any secrets (keys, master API tokens, database credentials) included in it. These can be applied at startup time, from a script or a secure configuration vault.

  • The server can optionally load configuration properties from a local file, an Amazon S3 object or an Amazon DynamoDB table. The external properties location is specified by a URL like

  • A new /config/check endpoint was added. It can be used as part of a DevOps pipeline, to perform quick online validation of a set of server configuration properties.

Token events and SETs

The new Connect2id server release also exposes two Java SPIs for installing listeners for ID and access token issue events.

The events can be passed to a message queue, time-series database or some other service to monitor sign-in activity and OAuth 2.0 authorisations in real time, for purposes such as security audit logging and usage metering.

The events can optionally be turned into Security Event Tokens (SET), to protect their integrity and cryptographically assert their origin.

Sample SET claims for an ID token issue event:

  "iss"    : "",
  "sub"    : "[email protected]",
  "iat"    : 1458496404,
  "jti"    : "cuiqu8isaixo6Ien",
  "aud"    : [ "" ],
  "events" : { "urn:com:c2id:op:id_token_issue": { "client_id" : "doh9Kool",
                                                   "acr"       : "0",
                                                   "amr"       : [ "pwd" ] } }

Updated login UI

The sample login page that comes with the Connect2id server is now more capable, thanks to a contribution from Para:

  • The UI can also handle logout requests initiated by client applications.
  • The session cookie is now set as HTTP-only to guard against XSS attacks.


To download a ZIP package of Connect2id server 6.16:

SHA-256: d2e38dee9acc71e83fc23c16ab047c25b00a4dd31686d565261bb7d3c77251df

As WAR package only:

SHA-256: 762c96b84d3423f4e93060ad6220912e263ccb3163a1bc46143bacf43d1375c5


Get in touch with Connect2id support.

Release notes

6.16 (2017-12-08)


  • The Connect2id server JWK set can be alternatively passed via a jose.jwkSet Java system property, overriding the content of /WEB-INF/jwkSet.json. The JWK set can be passed in its standard JSON string format, or with additional BASE64URL encoding (to work around the need to escape special characters in the shell).

  • Adds support for loading Java system properties at Connect2id server startup from a local file, an AWS S3 object or an AWS DynamoDB item. The properties location is specified by a URL passed via a systemPropertiesURL Java system property, for example file:////etc/c2id/ to retrieve them from a local file or to retrieve them from an S3 object.

    The AWS credentials for accessing the S3 bucket or DynamoDB table must be configured in way that the default AWS credentials provider chain can look them up, ideally via IAM instance profile roles. See

    The loaded Java system properties can be used to override Connect2id server configuration properties found in the /WEB-INF/*.properties and /WEB-INF/*.xml configuration files.


  • /config/check — New endpoint for online validation of a Connect2id server configuration property set, consisting of the combined properties specified in /WEB-INF/, /WEB-INF/, /WEB-INF/ and /WEB-INF/ The properties are validated by a HTTP POST request to the endpoint. The endpoint is not protected by an access token. Upon successful validation a 204 No Content status code is returned, else a 400 Bad Request with a JSON object body with the name of the invalid property and additional information to aid debugging.


  • com.nimbusds.openid.connect.provider.spi.config.SystemPropertiesSource — Adds new optional SPI for loading system properties from alternative sources such as databases and cloud stores.

  • — Adds new SPI for listening to ID token issue events.

  • — Adds new SPI for listening to access token issue events.

  • — Adds the OpenID Provider Issuer URI to the ClaimsRequestContext.

  • com.nimbusds.openid.connect.provider.spi.ServiceContext — Adds a new getJWTIssuer method to the service context interface. Intended for issuing JWTs created by SPI implementations, for example security events (SET).

Resolved Issues

  • Switches to shadowed AWS SDK dependency to prevent transient dependency conflicts with other packages. The issue was observed in AWS Elastic Beanstalk deployments (issue hosted-server/20).

  • Logs loading of monitor API servlets at Connect2id server startup (issue server/316).

  • Adds trace logging of first 16 characters of submitted bearer access token at the client registration endpoint for debugging purposes (issue server/337).

Dependency Changes

  • Adds com.nimbusds:c2id-server-property-source:1.0.1 dependency

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

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

  • Upgrades to org.bouncycastle:bcprov-jdk15on:1.58

  • Upgrades to org.bouncycastle:bcpkix-jdk15on:1.58

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

  • Upgrades to com.nimbusds:oidc-session-store:5.2.14

  • Upgrades to com.nimbusds:common:com.nimbusds:2.18

  • Upgrades to com.nimbusds:infinispan-cachestore-dynamodb:1.5.3

  • Upgrades to com.nimbusds:jgroups-dynamodb-ping:1.2.2

  • Upgrades to com.amazonaws:aws-java-sdk-bundle:1.11.235

Global identity provision with the Connect2id server just got easier

Posted on 2017-11-30

Serving identities, SSO and access tokens in multiple regions just got easier. Last night at Re:Invent AWS announced global DynamoDB tables which enable transparent replication of table data as well as multi-master writes across regions.

If you’re running a Connect2id server in the AWS cloud this means you can now take advantage of the new feature to create a cluster that spans two or more regions, issuing tokens closer to your applications and users while also ensuring greater overall availability.

Your Connect2id server must be running in stateless mode with a DynamoDB as a backend database and with the new global tables option turned on.

Previously DynamoDB replication across regions was only possible with by deploying continuous streams, but these lacked the multi-master write capability.

At the time of the announcement global DynamoDB tables are supported in these regions:

  • US East 1 (N. Virginia)
  • US East 2 (Ohio)
  • US West 2 (Oregon)
  • EU West 1 (Ireland)
  • EU Central 1 (Frankfurt)

You can find more information in the WAN replication FAQ.