Blog »

Improved claims and access token lifecycle support in Connect2id server 6.4

2017-03-08

This release of the OpenID Connect server introduces a number of small but useful new features.

Define your own scope to claims expansions

OpenID Connect allows client apps to request claims (assertions) about the user by including special OAuth 2.0 scope values in the OpenID authentication request.

For example, apps can use the profile scope value to request access to the following user attributes at the IdP:

Scope value Claims
profile name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at

OpenID Connect defines four such scope values that expand to specific sets of claims.

This neat concept can be used with other (custom) scope values and claims that the identity provider needs to support. Up until now, identity providers with a Connect2id server had to maintain these mappings externally, and apply them during the authorisation session. With v6.4 such scope value to claim expansions can be defined internally.

Example definition of a custom org_profile scope value and the claims that it expands to:

org_profile: roles, supervisor, employee_number

Guaranteeing single use of access tokens

Applications and resource servers which require an access token to be used once only and prevent its replay have these two choices:

  1. The resource server caching the access token signature (or its JTI claim) for the duration of the token lifetime after it's validated. Subsequent requests with the same token will cause a cache hit, indicating that the
    token has already been used.

  2. With identifier (key) based tokens, which are inspected with a call to the Connect2id server. This call now has an optional query parameter revoke
    which will cause the token to be deleted when it's inspected. A subsequent inspection call will yield a 404 status code - signalling that that token is no longer valid.

    POST /authz-store/rest/v2/inspection?remove=true HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

access_token=kiuf7oPaFaePoo5tzieS8eeMEChoo7Ko

Prometheus support

The Connect2id server collects over 100 useful metrics to monitor identity provider usage and performance. These can now be exported in Prometheus format at a dedicated endpoint.

Other new features

Other new features include improved support for implicit consent of OpenID claims, additional Infinispan configurations for using Redis as a primary in-memory and cache store, and a more efficient expiration of user sessions. Check the release notes below for details.

Download

To download a ZIP package of Connect2id server 6.4:

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

(SHA-1: 6814cde422140d84e6fde0fbf816d7ec9be3cf2e)

As WAR package only:

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

(SHA-1: 761e982431ca0d597c9f7ebca85aa1ed45c2c191)

Questions?

Get in touch Connect2id support to receive assistance.

Release notes

6.4 (2017-03-08)

General

  • Adds new optional configuration file for defining custom scope value to OpenID Connect claim mappings.

  • Adds support for implicit consent of OpenID Connect claims.

  • Adds a new optional "revoke" parameter to the token introspection call to facilitate single use of identifier-based access tokens where required by the resource server / application.

  • Adds endpoint for scraping the Connect2id server metrics in Prometheus (https://prometheus.io) format.

  • Expiration of subject (end-user) sessions is now handled by Infinispan, simplifying configuration (see below) and improving the performance of session retrieval.

  • Updates the Infinispan configuration files.

Configuration

  • /WEB-INF/customClaimsMap.properties

    • New optional configuration file for defining custom scope value to OpenID Connect claim mappings. Can be used to automatically expand selected custom scope values to one or more custom claim names, e.g. "my_scope_value" to claim names "claim_a", "claim_b", etc.

  • /WEB-INF/oidcProvider.properties

    • Adds new optional "op.authz.alwaysPromptForAuth" configuration property, defaults to "false". If "true" the Connect2id server will always prompt for authentication, even if the end-user is currently authenticated (by means of a valid session cookie), or "prompt=none" was requested by the client. Intended to facilitate authentication step-up by using selected scope values.

  • /WEB-INF/sessionStore.properties

    • The sessionStore.purgeInterval configuration property is removed. Expiration of subject (end-user) sessions is now handled by Infinispan. The expiration interval can be fine tuned by changing the expiration interval attribute of "sessionStore.sessionMap" of the chosen Infinispan XML configuration (infinispan-.xml).

  • /WEB-INF/jose.properties

    • Adds support for overriding the PKCS#11 configuration via Java system properties.

  • /WEB-INF/infinispan-mysql-redis.xml

    • Adds new configuration for using Infinispan in invalidation mode, with MySQL as the persistence store and Redis as the primary in-memory / cache store.

  • /WEB-INF/infinispan-postgres95-redis.xml

    • Adds new configuration for using Infinispan in invalidation mode, with PostgreSQL 9.5+ as the persistence store and Redis as the primary in-memory / cache store.

  • /WEB-INF/infinispan-ldap-redis.xml

    • Renames the previous configuration file for using Infinispan in invalidation mode with LDAP as the persistence store and Redis as the primary in-memory / cache store.

  • /WEB-INF/infinispan-*.xml

    • Declares the required application specific AdvancedExternalizer instances in the XML configuration (see issue server/253 below).

  • /WEB-INF/web.xml

    • Configures eager servlet loading.

Web API

  • /authz-sessions/rest/v3, /authz-sessions/rest/v2

    • Adds support for implicit consent of OpenID Connect claims.

  • /authz-store/rest/v2/inspection

    • Adds an optional "revoke" query parameters (defaults to "false") to facilitate single use of identifier-based access tokens. Causes the access token to be automatically deleted from the store after successful inspection. Has no effect with self-contained (JWT-encoded) access tokens.

  • /monitor/v1/metrics/prometheus

    • Adds new resource for retrieving Connect2id server metrics in Prometheus (https://prometheus.io) format (exported from Dropwizard). Requires a
      bearer access token, which is configured in /WEB-INF/monitor.properties.

Bug fixes

  • Fixes processing of refresh token grant requests from public OAuth 2.0 clients to ensure a mismatch of the top-level client_id and the client_id encoded in the refresh token produces an invalid_grant error (issue server/254).

  • Switches to XML-based declaration of the application specific Infinispan AdvancedExternalizer classes to address startup situations when the programmatically configured externalisers don't get picked up by Infinispan (issue server/253).

  • Fixes handling of illegal URL-encoding in client secret basic authentication HTTP Authorization headers so that instead of failing with HTTP 500 status code a proper HTTP 400 status and message is returned (issue oidc-sdk/208).

  • Prevents inconsistent direct authorisation requests for a refresh token with disabled authorisation persistence (long_lived = false). Such requests will now produce a HTTP 400 status code with the error message "Invalid request: Refresh token issue requires the authorization to be persisted with long_lived=true" (issue server/262).

  • Fixes a bug that prevented the timely removal of authorisation sessions in Infinispan invalidation mode (issue server/265).

  • Removes stray System.out.println in userInfo endpoint code (issue server/261).

Dependencies

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

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

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

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

  • Upgrades to com.nimbusds:common:2.4

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