Blog »

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