Connect2id server 5.0.1 maintenance release

2016-06-23

Connect2id server users of the previous 5.0 release who still rely on the old version 2 of the authorisation session API (for binding an IdP login page and auth factors) are strongly advised to upgrade to this 5.0.1 maintenance release.

As you may recall, with Connect2id server 5.0 we updated the authorisation session API in order to support the OAuth 2.0 form_post response mode, and also to free integrators to implement custom and experimental response modes, such as Nat Sakimura's response mode based on window.postMessage.

This was a breaking change, which required a new API version - 3.

The old version 2 API is still supported, by means of a special filter that rewrites the API messages from version 3. This maintenance release fixes a rewrite bug that prevented correct reporting of HTTP 4xx status codes as well as output from a GET /authz-session/v2/{sid} request.

The new version 3 API is unaffected.

Download

To download a ZIP package of Connect2id server 5.0.1:

https://connect2id.com/assets/products/server/download/5.0.1/Connect2id-server.zip

As WAR package only:

https://connect2id.com/assets/products/server/download/5.0.1/c2id.war

Questions?

Get in touch Connect2id support, we'll be delighted to help out.

Release notes

5.0.1 (2016-05-23)

Configuration

  • No changes

Web API

  • No changes

Bug fixes

  • Fixes the servlet filter that provides a version 2 compatible view of the Authorisation Session API at /authz-session/v2. The fixed bugs prevented the correct output of 4xx HTTP responses from the API as well as GET /authz-session/v2/{authz-session-id} responses (issue #213). Users of the
    /authz-session/v2 API are strongly encouraged to upgrade. Users of the newer /authz-session/v3 API are not affected.

Dependencies

  • No changes

Greater choice of persistence backends with Connect2id server 6.0

2016-06-17

You can now download a preview of the upcoming 6th release of the Connect2id server, our enterprise solution for issuing sign-in and access tokens to apps, whether web-based or mobile.

The highlights at a glance:

Greater choice of persistence backends

The Connect2id server needs to persist two types of data - client registrations and long-lived authorisations. Back in 2012 when we began implementing the OpenID Connect server and targeted the enterprise, we chose LDAP storage for that purpose: it fit well the data model, enterprises knew it, and so did we.

Today, four years on, we're meeting a growing number of customers who have no LDAP experience (because they're start-ups, or have stayed away from traditional enterprise IT for some reason), or wish to utilise a cloud specific solution (such as Amazon's DynamoDB). To help out those customers we rewrote the Connect2id server backend, by migrating to Infinispan's generic data store API, which permits any type of database to be plugged in.

Which persistence backends are going to be supported in version 6.x?

  • File-based -- Data is persisted to a local file on each Connect2id server node. Super easy to maintain (no external database setup required), and offering raw performance that is hard to beat. Our OpenID Connect sign-in benchmark reported 43% greater throughput when we setup a Connect2id server with Infinispan's own Soft-Index File Store, compared against OpenDJ (an LDAP server). On AWS you could use EBS to store the data files. One bit that we still need to resolve with simple file-based storage: support for hot backups.

  • LDAP -- Persisting data to an LDAP directory remains supported. This still has its advantages: the database is external and can be configured for fail-over and multi-master replication; you can run external queries on your client registration and authorisation data with a standard LDAP browser.

  • DynamoDB -- For customers who run their ops in the AWS cloud and wish to have all Connect2id server data stored as JSON objects, with the ability to run external queries on it. DynamoDB support won't make it in time for 6.0, and will appear in a later 6.x release.

  • SQL RDMBS -- In order to support such a wide range of backends, database operations are limited to the most common denominator - loading and storing a value by key (where the value can be treated as an opaque string or binary blob, but may also be stored in some structured form). The database's own indexing and query capabilities are not used; instead of that the Connect2id server now employs an external engine (Apache Lucene). Using an SQL RDMBS, such as MySQL or PostgreSQL, as a simple key-value store is not particularly efficient, unless you want to run external SQL queries on the persisted data, so if we do add support for relational databases, this will happen in later 6.x release.

Pairwise identifiers

Pairwise identifiers promise enhanced privacy by making it harder for OpenID Connect clients to correlate, or "link" user identities. This is achieved by keeping the real user identifier confidential, and providing each registered client with a different
(but consistent) ID for the user.

There are several ways to implement this in a identity provider:

Hashing the user ID, together with the client's sector identifier and some salt is one way. This renders the resulting pairwise ID virtually irreversible.

Another IdP approach is to encrypt the user and sector IDs with a symmetric key. We chose this method (AES/CBC/PKCS5Padding encryption), as it enables the Connect2id server to handle the optional id_token_hint request parameter, and also to support use cases where the ID token is exchanged for an OAuth access token.

Example:

  • Alice has a user ID alice with the IdP.

  • Client A receives user ID z6rjKZ2jjGZ6JQyASLxzF5Fh1KUkv90-3aMZcXvyk4c for Alice.

  • Client B receives user ID kdbnJjGzk385mvIY_U6ml49ArpnE2yEcjFOJhDfLB7E for Alice.

  • Etc.

Here we must stress that issuing pairwise IDs is not sufficient to prevent correlation of user identities across two or more clients. In order to achieve that all details released by the IdP for a given user that may facilitate linking must be made pairwise. Email addresses of user fall into this category. But even when all assertions about a user have been considered, correlation may still happen. Cem Paya has a nice discussion on this in his blog post series on pairwise identifiers
(part 1, 2 and 3).

Download

To preview the upcoming Connect2id server 6.0 release download the following ZIP package and follow the instructions in the README.txt file:

https://connect2id.com/assets/products/server/download/6.0-pre-1/Connect2id-server.zip

This will launch a instance of the Connect2id server where data is persisted to a local file store (Infinispan's Soft-Index File Store).

An LDAP directory is still included in the package, but that's only to provide a sample user database.

Important: The Tomcat web server must be launched from the base of the extracted file tree, otherwise the Connect2id server will not be able to find the correct base directory for the file store. We intend to fix this by the time 6.0 gets released.

Questions?

If you have any questions or comments about the new persistence backends, don't hesitate to get in touch with Connect2id support.

Release notes

6.0-pre-1 (2016-06-16)

General

  • Switches to Infinispan's data store APIs for persisting client registry and long-lived authorisation records.

  • Adds support for pairwise subject (end-user) identifiers.

  • Switches to new JSON-based marshalling of Connect2id server objects stored in Infinispan.

  • Refines error messages to clients on invalid and denied client registration requests.

Configuration

  • /WEB-INF/jwkSet.json

    • Adds new symmetric JSON Web Key (JWK) with ID "subject-encrypt" to facilitate AES/CBC/PKCS5Padding encryption of pairwise subject identifiers. The acceptable AES key sizes are 128, 192 and 256 bits.

    • Adds new salt JSON Web Key (JWK) with ID "subject-salt" to facilitate AES/CBC/PKCS5Padding encryption of pairwise subject identifiers. The salt must be at least 128 bits long.

  • /WEB-INF/oidcProvider.properties

    • Removes the op.reg.preloadCache, op.reg.ldapServer.*, op.reg.ldapUser.*, op.reg.ldapDirectory.*, op.reg.customTrustStore.* and op.reg.customKeyStore.* settings for configuring an LDAP store for the OpenID Connect and OAuth client registration. Configuration of the client registration store is now assumed by the Infinispan.

  • /WEB-INF/authzStore.properties

    • Removes the authzStore.options.preloadCache, authzStore.ldapServer.*, authzStore.ldapUser.*, authzStore.ldapDirectory.*, authzStore.customTrustStore.* and authzStore.customKeyStore.* settings for configuring an LDAP store for the long-lived (persisted) OpenID Connect and OAuth authorisations. Configuration of the long-lived authorisations store is now assumed by Infinispan.

    • Adds new authzStore.options.discardedAttributes settings to list of the optional authorisation attributes that are to be automatically discarded from new authorisation objects, in order to conserve cache memory and back-end storage.

  • /WEB-INF/infinispan.xml

    • Updates all advanced externalisers.

    • Replaces "op.regCache" with "op.clientRegMap".

    • Replaces "op.regTokenCache" with "op.clientRegTokenMap".

    • Replaces "authzStore.authzCache" with "authzStore.longLivedAuthzMap".

Web API

  • /.well-known/openid-configuration

    • Advertises support for pairwise subject identifiers (subject_types_supported).

  • /clients/

    • Supports registration of OpenID Connect clients for pairwise subject identifiers. OpenID Connect clients can be registered for pairwise subject identifiers by setting the "subject_type" parameter to "pairwise"; if more than one redirection URI is specified in the "redirect_uris" parameter, a "sector_identifier_uri" parameter must also be provided.

  • /monitor/

    • Replaces "authzStore.numCachedAuthorizations" with "authzStore.numLongLivedAuthorizations".

Bug fixes

  • Adds check to prevent client registration of redirect_uris with a fragment component (issue sdk/188).

  • Fixes NPE in the LDAP connector when the asynchronous LDAP result listener receives a notification before the associated timer context is cached (issuer authz-store/117).

Dependencies

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

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

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

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

  • Upgrades to com.nimbusds:common:1.102.1

  • Upgrades to org.infinispan:infinispan-embedded:8.2.2.Final

  • Adds new dependency to org.infinispan:infinispan-query:8.2.2.Final

  • Adds new dependency to org.infinispan:infinispan-directory-provider:8.2.2.Final

  • Adds new dependency to org.infinispan:infinispan-persistence-soft-index:8.2.2.Final

  • Adds new dependency to com.nimbusds:infinispan-ldap-cache-store:1.0.2

  • Upgrades to org.apache.logging.log4j:log4j-api:2.6.1

  • Upgrades to org.apache.logging.log4j:log4j-web:2.6.1

  • Upgrades to org.apache.logging.log4j:log4j-slf4j-impl:2.6.1

Connect2id server 5.0 supports OAuth 2.0 form post and custom response modes

2016-05-18

After 4.0 which introduced support for identity impersonation and delegation use cases, 5.0 is the second major release of the Connect2id server in 2016, enabling additional OAuth response modes and upgrading to Java 8 and Infinispan 8 under the hood.

OAuth 2.0 form post response mode

OAuth defines several grants (or flows) for clients to obtain tokens, to cater for the different types of applications available today, such as traditional web based apps, browser-based apps implemented in JavaScript, mobile and native. The OAuth working group has one more flow currently in development, intended for devices (in the spirit of IoT).

Of all those OAuth flows, code and implicit, where the user is sent off to the IdP with their browser to sign in, remain the most popular. They are also catching up in the mobile world, because let's not forget, there is no other OAuth flow that permits proper 3rd party SSO, and if done well this can boost app adoption and sales. Android and iOS have also improved support for browser based flows, by polishing the UX when an app switches to the system browser and then back, and by improving support for URI callbacks into apps.

With a browser based flow the OpenID Connect / OAuth 2.0 response is returned by appending it to the callback URI (redirect_uri), which is the URI query string for returning an authorisation code, and the URI fragment for returning the tokens immediately in the implicit flow. So in OAuth jargon response mode is essentially about how the response is sent back to the client app.

Returning codes and tokens in the URI however may leak them into HTTP logs, browser histories and referral headers, which can be a problem for security. In order to address this the OpenID Connect WG devised a new response mode, called form_post, where the response parameters are safely submitted to the callback URI via a form POST.

In order for a client app to switch to form POST, just add the following parameter to the outgoing OpenID authentication request, and make sure the callback location can handle application/x-www-form-urlencoded parameters:

response_mode=form_post

Regarding server-side support, the spec has a nice example how such a hidden form can be generated and then auto-submitted with a single line of JavaScript.

Example HTTP form post with an implicit flow response (containing ID token and state):

POST /callback HTTP/1.1
Host: client.example.org
Content-Type: application/x-www-form-urlencoded

id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJqb2huIiwiYX
         VkIjoiZmZzMiIsImp0aSI6ImhwQUI3RDBNbEo0c2YzVFR2cllxUkIiLCJpc
         3MiOiJodHRwczpcL1wvbG9jYWxob3N0OjkwMzEiLCJpYXQiOjEzNjM5MDMx
         MTMsImV4cCI6MTM2MzkwMzcxMywibm9uY2UiOiIyVDFBZ2FlUlRHVE1BSnl
         lRE1OOUlKYmdpVUciLCJhY3IiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTD
         oyLjA6YWM6Y2xhc3NlczpQYXNzd29yZCIsImF1dGhfdGltZSI6MTM2MzkwM
         Dg5NH0.c9emvFayy-YJnO0kxUNQqeAoYu7sjlyulRSNrru1ySZs2qwqqwwq
         -Qk7LFd3iGYeUWrfjZkmyXeKKs_OtZ2tI2QQqJpcfrpAuiNuEHII-_fkIuf
         bGNT_rfHUcY3tGGKxcvZO9uvgKgX9Vs1v04UaCOUfxRjSVlumE6fWGcqXVE
         KhtPadj1elk3r4zkoNt9vjUQt9NGdm1OvaZ2ONprCErBbXf1eJb4NW_hnrQ
         5IKXuNsQ1g9ccT5DMtZSwgDFwsHMDWMPFGax5Lw6ogjwJ4AQDrhzNCFc0uV
         AwBBb772-86HpAkGWAKOK-wTC6ErRTcESRdNRe0iKb47XRXaoz5acA&
state=DcP7csa3hMlvybERqcieLHrRzKBra

In order to support form POST in the Connect2id server, we created a new v3 of the authorisation session API, by introducing a dedicated JSON object for representing the final response. This also establishes a future-proof framework for adding new OAuth 2.0 response modes (Nat Sakimura is drafting one), and to let Connect2id server users easily implement custom ones.

A few other bits and pieces also got revised in v3 of the authz session API, making it easier to script and integrate from the login page. Check out our updated guide on login page and auth factor integration for more details.

Please note that v2 of the authorisation session API is still available, so your existing login pages and frontends can continue working with Connect2id server 5.0+.

Custom response modes

Customers who have implemented non-standard response modes, or intend to do so (such as CORS Ajax based response modes), can switch to the new v3 of the authorisation session API.

Here a quick how-to:

  1. Put the name of your custom response mode in the op.authz.responseModes configuration setting, so the Connect2id server doesn't produce an "unsupported response mode" when an request with response_mode=my_mode is made.

  2. Add an appropriate handler to your login page for a custom response. The response parameters will be output in a JSON object as key / value pairs, and the callback URI will be indicated in the uri parameter. Just
    encode them and send them back to the client according to the contract of your custom response mode.

Java 8

Java 8 is now the required runtime for the Connect2id server.

Infinispan 8

The move to Java 8 also allowed us to upgrade from Infinispan 7 to 8. You will benefit from reduced resource consumption, smarter locking and performance improvements (which you may or may not notice).

Please note that the infinispan.xml configuration has somewhat changed with
Infinispan 8, and the async-marshalling parameter is no longer supported.

Future directions

Work on refactoring the Connect2id server to support alternative stores besides LDAP for its own data (client registrations and persisted authorisations) is continuing, and we hope to have an EAP or beta for you in June.

Download

To download a ZIP package of Connect2id server 5.0:

https://connect2id.com/assets/products/server/download/5.0/Connect2id-server.zip

As WAR package only:

https://connect2id.com/assets/products/server/download/5.0/c2id.war https://connect2id.com/assets/products/server/download/5.0/c2id-5.0.war

Questions?

As always, if you have any questions, get in touch with Connect2id support.

Release notes

5.0 (2016-05-17)

General

  • Upgrades to Java 8, which becomes the required runtime version.

  • Upgrades to Infinispan 8.2, for reduced resource consumption, reduced locking, separate thread pool for asynchronous operations, global state persistence, performance improvements, and utilisation of Java 8 APIs.

  • Adds support for the optional form_post response mode, as specified in OAuth 2.0 Form Post Response Mode, 1.0. The specification is available at
    https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html

  • Adds support for implementing custom (experimental) OAuth 2.0 response modes, such as based on CORS Ajax or window.postMessage.

Configuration

  • /WEB-INF/oidcProvider.properties

    • Adds new op.authz.responseModes configuration setting for the supported OAuth 2.0 response modes. Besides the standard query, fragment and form_post, it may also include custom (non-standard, experimental) response modes, provided the authorisation session front-end (the login page) is able to support them. Authorisation requests with a response mode that is not listed as supported will be rejected without a redirection back to the OAuth client.

    • Adds new op.reg.ldapServer.connectionPoolInitialSize configuration setting for the initial number of pooled LDAP connections to be created when the Connect2id server is started. The acceptable range is between zero and the maximum LDAP connection pool size (inclusive). Set it to zero to enable startup of the Connect2id server without the backend LDAP directory being available.

  • /WEB-INF/authzStore.properties

    • Adds new authzStore.ldapServer.connectionPoolInitialSize configuration setting for the initial number of pooled LDAP connections to be created when the Connect2id server is started. The acceptable range is between zero and the maximum LDAP connection pool size (inclusive). Set it to zero to enable startup of the Connect2id server without the backend LDAP directory being available.

  • /WEB-INF/monitor.properties

    • Allows Java system properties to override individual properties in the configuration file.

  • /WEB-INF/infinispan.xml

    • Updates the configuration to match the 8.2 Infinispan XML schema.

    • Sets the sessionStore.sessionMap, sessionStore.subjectMap, authzStore.accessTokenMap, authzStore.authzCache, op.regCache and op.regTokenCache Infinispan maps / caches to asynchronous mode.

    • Asynchronous marshalling is no longer supported in Infinispan 8, and is removed from the configuration.

  • /WEB-INF/ldapClaimsSource.properties

    • Adds new op.ldapClaimsSource.server.connectionPoolInitialSize configuration setting for the initial number of pooled LDAP connections to be created when the Connect2id server is started. The acceptable range is between zero and the maximum LDAP connection pool size (inclusive). Set it to zero to enable startup of the Connect2id server without the backend LDAP directory being available.

Web API

  • New authorization session API /authz-session/v3

    • A final response (with the encoded OAuth 2.0 response parameters, such as authorisation code, state, etc) is conveyed by means of a dedicated JSON object, instead of a HTTP 302 redirection with Location header. This enables handling of the optional OAuth 2.0 form_post response mode, as well as implementation of custom (experimental) response modes, such as based on CORS Ajax or window.postMessage. See the online documentation on v3 of the authorisation session API for more information.

    • A non-redirectable error response (e.g. due to a client request with invalid client_id or redirect_uri) is conveyed by means of a HTTP 200 with JSON object with "type":"error", following the semantics of "type":"auth", "type":"consent" and "type":"response" messages. See the online documentation on v3 of the authorisation session API for more information.

    • Custom OpenID authentication request parameters get included in the authorisation session, and can be obtained by making a HTTP GET for its JSON object representation. Any custom authentication request parameters will be included in the auth_req member of the authorisation session, alongside response_type, client_id, redirect_uri, scope, etc. This permits processing of custom and experimental OpenID authentication parameters that are not otherwise supported.

  • Authorization session API /authz-session/v2

    • V2 of the authorisation API, introduced in Connect2id server v 3.0, remains available.

Bug fixes

  • Fixes Infinispan serialisation of an explicitly set response_mode in authorisation sessions (issue server/203).

Dependencies

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

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

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

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

  • Upgrades to com.nimbusds:common:1.102

  • Upgrades to org.infinispan:infinispan-embedded:8.2.1.Final

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

How to generate human-friendly identifiers

2016-03-24

Call centre

"Can you please tell me the ID on your package?"

"Yes, of course... I-O-7-U-4-V... Hang on, it looks like 1-0-7-V-4-U"

Communicating IDs between humans is error prone and we've all experienced this at some point with things like packages, orders and bank accounts, to name a few. One source of confusion are similar looking symbols, like O and zero, or I and 1, especially when having to spell out an ID or dealing with hand-written notes.

If you're a programmer or software architect, you have the power to do something about this. Let's find out what.

Base 32 comes to the rescue

Engineers have already thought about how to make IDs more human friendly, and had come up with several solutions. They typically go along the following lines:

  1. Minimising transcription errors by avoiding similar looking symbols;
  2. Using compact encodings to reduce the overall length of the ID.

One common solution is to generate identifiers that are base 32 encoded. It is specified in RFC 4648 and uses the English alphabet (one case only), followed by the numbers from 2 to 7. The numbers 0 and 1 are deliberately skipped, due to their similarity with the letters O and I. By using letters this encoding is also 3 times more efficient compared to using only numbers (base 10), so you also get IDs that are relatively compact.

Another benefit of base 32, this time for computers, is that strings are inherently URL safe (when the = padding symbol is omitted).

This is how the base 32 character set looks like:

A   J   S   3
B   K   T   4
C   L   U   5
D   M   V   6
E   N   W   7
F   O   X   =
G   P   Y
H   Q   Z
I   R   2

The = sign is used for padding, but is redundant and therefore can be safely excluded. Can check out the spec if you need more info.

Choose base 32 for IDs if you expect them to be copied or spelled out by people at some point, while keeping their size relatively compact (in case you need a large number space). The Connect2id server for example applies base 32 to the generated client identifiers. Companies that operate IdP and OAuth servers may need to answer support calls from client developers, so that's good use case for base 32.

How to generate base 32 identifiers?

Here is one recipe:

  1. Estimate the maximum number of IDs that may be needed over the lifespan of the application. A long integer for example has 8 bytes, which means 2^64. This is will then become the spec for your database key column.

  2. Create a secure random generator, to ensure the issued IDs cannot be easily predicted (guessed). This is a must for things such as tracking and order numbers. If you need to have IDs that have the unpredictability of an AES key, their size should be at least 16 bytes (see step 1).

  3. Every time you need a new ID, generate the required random bytes for it and pass them to a base 32 encoder. All program languages have support for that, either in the standard library or through 3rd party libraries. Make sure the = sign used for padding is stripped from the output string.

Java example:

import java.security.SecureRandom;
import org.apache.commons.codec.binary.Base32;

// Create a secure random generator (it's thread-safe)
SecureRandom sr = new SecureRandom();

// Allocate an array for 8 bytes
byte[] random = new byte[8];

// Generate the random bytes
sr.nextBytes(random);

// Create the encoded ID, strip any padding
String id = new Base32().encodeToString(random).replace("=", "");

Example base 32 encoded ID with 8 bytes:

XBZO4EWP5J5B4

Base 32 encoded UUIDs

If you wander how the standard UUID encoding compares with base 32 in terms of string size:

UUID (std format)                 : 38503690-0475-4c48-95ed-a3c9eaa2ac3a
UUID (Base 32)                    : HBIDNEAEOVGERFPNUPE6VIVMHI
UUID (Base 32, with extra dashes) : HBID-NEAE-OVGE-RFPN-UPE6-VIVM-HI

Other base 32 variants

It's worth noting two alternative base 32 encodings that take care of the human factor one step further.

Z-base-32

The most notable feature of z-base-32 is the permutation of the symbol set in such a way that characters that are considered easier to read, write, speak and remember are made to occur more frequently. The number of potentially confusing characters is also further reduced.

To find out more about the design decisions behind z-base-32 take a look at its spec. It's quite an interesting and enjoyable read.

The z-base-32 alphabet:

y   e   o   a
b   j   t   3
n   k   1   4
d   m   u   5
r   c   w   h
f   p   i   7
g   q   s   6
8   x   z   9

Note that here we also have one case, but with preference for lower case, which is more pleasant to the eyes. The padding character is also entirely gone.

Base 32 by Douglas Crockford

Douglas Crockford, who made JSON popular, also had a go at base 32 encoding. The most notable feature of his version is the optional support for a check character at the end of the string, for simple error detection. This can be quite handy when dealing with important IDs, such as money accounts. International Bank Account Numbers for example use 2 check digits to eliminate routing and account number errors.

Note that even if you go along with the vanilla base 32 encoding, you can still include a check, by pre-encoding it into the base 32 input.

The base 32 alphabet of Douglas Crockford:

0   8   G   R
1   9   H   S
2   A   J   T
3   B   K   V
4   C   M   W
5   D   N   X
6   E   P   Y
7   F   Q   Z

IDs are not just numbers

Remember this next time you you design a data model. IDs often become part of the user experience, whether in tiny URLs or tracking orders. Fortunately, we have a tool to make this experience a bit more pleasant for people as well as a bit more efficient for the computer - so remember base 32 :)

Connect2id server 4.1

2016-03-08

This is a maintenance release of the OpenID Connect server which deals with data replication errors when Infinispan (the data grid layer) selects an incorrect serialiser version for a session or other object that needs to be transported across a Connect2id cluster.

If your Connect2id server cluster is affected you will be seeing serialisation errors in your logs at node startup or when performing a live roll-over from a 3.x cluster to the latest 4.x release.

The exceptions may look like this:

org.infinispan.commons.CacheException: Unable to invoke method public void org.infinispan.statetransfer.StateTransferManagerImpl.waitForInitialStateTransferToComplete() throws java.lang.Exception on object of type StateTransferManagerImpl

or

java.io.UTFDataFormatException: Invalid byte
        at org.jboss.marshalling.UTFUtils.readUTFBytes(UTFUtils.java:173) ~[infinispan-embedded-7.2.5.Final.jar:?]
        at org.jboss.marshalling.river.RiverUnmarshaller.readUTF(RiverUnmarshaller.java:1833) ~[infinispan-embedded-7.2.5.Final.jar:?]

The replication error may also manifest as some other exception.

Upgrading to 4.1

Download the 4.1 package and make sure the infinispan.xml configuration is updated to include a new externaliser declaration (see the release notes for more info).

Basically, replace the lines

<advanced-externalizer class="com.nimbusds.sessionstore.impl.ext.SubjectSessionExternalizerV1"/>
<advanced-externalizer class="com.nimbusds.sessionstore.impl.ext.SubjectSessionExternalizerV2"/>

with

<advanced-externalizer class="com.nimbusds.sessionstore.impl.ext.SubjectSessionExternalizer"/>

Unfortunately, the nature of the fix is such that a live automatic roll-over to 4.1 is not possible. To mitigate we extended the session store web API to allow creation of new sessions with a preset identifier (SID). With that an external job can be set up to copy existing user sessions from the old to the new cluster:

  1. Get the active user sessions from your current cluster with

    GET /session-store/rest/v2/sessions HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

  2. Then recreate them in the new 4.1 cluster with

    POST /session-store/rest/v2/sessions HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: session-id
Content-Type: application/json

{
  "session-data"  : "..."
}

Download

To download a ZIP package of Connect2id server 4.1:

https://connect2id.com/assets/products/server/download/4.1/Connect2id-server.zip

As WAR package only:

https://connect2id.com/assets/products/server/download/4.1/c2id.war https://connect2id.com/assets/products/server/download/4.1/c2id-4.1.war

Questions?

Get in touch Connect2id support, we'll be delighted to help out.

Release notes

4.1 (2016-03-04)

Configuration

  • /WEB-INF/infinispan.xml

    • Replaces the advanced externaliser classes com.nimbusds.sessionstore.impl.ext.SubjectSessionExternalizerV1 and com.nimbusds.sessionstore.impl.ext.SubjectSessionExternalizerV2 with com.nimbusds.sessionstore.impl.ext.SubjectSessionExternalizer (see issue session-store/27).

Web API

  • Session Store API /session-store/rest/v2:

    • The POST method adds support for an optional "SID" header to allow creation of new subject (end-user) sessions with a predefined session identifier (SID). Intended to assist migration of sessions (issue session-store/28).

  • Session Store API /session-store/rest/v2/sessions/count:

    • Modifies the behaviour of the GET method to only return the number of session present in memory, in order to avoid hitting the cache loader (in cases where the session store is configured to overflow or backup sessions to disk) (issue session-store/29).

Bug fixes

  • Fixes a serialisation bug that affected Infinispan replication of subject (end-user) sessions between Connect2id server nodes due to non-deterministic selection of versioned serialisers for session objects by Infinispan (issue session-store/27). The bug fix necessitated changes to the Infinispan configuration (see above). Live roll-over from previous Connect2id server versions to 4.1 will not migrate existing end-user sessions automatically; these may however be copied by an external job via the updated session store web API.

Dependencies

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

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

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

  • Upgrades to org.glassfish.jersey.containers:jersey-container-servlet:2.22.1