Skip to content
Connect2id
Connect2id server

Connect2id server 16.0 rolls out device SSO for mobile and desktop applications

Connect2id server 16.0 marks the first in a series of major, closely spaced releases, each introducing a significant new feature. The highlight of this release is the OpenID Connect extension for native SSO, designed for vendors with multiple mobile or desktop applications. Upcoming releases will add support for the back-channel authentication (CIBA) flow (incorporating security revisions) and will also automate aspects of the server key management.

Native SSO for app suites

The native SSO extension to OpenID Connect can be regarded as a counterpart to the web-based single sign-on (SSO), intended for mobile or desktop app-suite providers. Users receive a streamlined sign-in and consent experience, plus the ability for single logout.

The SSO user experience makes no security compromises. The participating native apps maintain their distinct identity (client_id) in regard to the Connect2id server and protected resources. Each app has ts own, separate authorisations, tokens and token lifecycle.

The SSO is made possible by creating a device session the first time the user signs into any one of the participating apps. Subsequent ID and access token requests from other or newly installed apps from the suite can be made directly, without user interaction. If interaction is required, for example to step-up the user authentication level (ACR) of the device session for some sensitive operation, the native SSO extension has a simple protocol for this.

The Connect2id server implementation of native SSO is based on draft 06 and includes several proposed changes and enhancements made by Connect2id, which are being considered for the next draft 07.

Check out the guide if you wish to configure your Connect2id server for native SSO and register client apps.

The open source OAuth 2.0 / OpenID Connect SDK introduced native SSO support in v11.15, released in August 2024. Check out the example code that shows how a client app can first sign-in a user and then how another app can use the SSO to obtain tokens without having to redirect the user to the IdP.

New session-based claims source

Connect2id server now ships with a new claims source which is easy to setup and efficient also, as it doesn’t require any database access on its own. It relies on the common pattern that when a user gets authenticated with the Connect2id server this often involves the retrieval of selected user attributes from a back-end database, service or upstream IdP, or can be a low-cost opportunity to do that. The retrieved attributes are then saved in the claims field of the user session.

Example session with four attributes saved in the claims object:

{
  "sub"           : "alice",
  "ctx"           : "device",
  "auth_time"     : 1723187423,
  "creation_time" : 1723187423,
  "max_life"      : 302400,
  "auth_life"     : 302400,
  "max_idle"      : 10080,
  "rps"           : [ "eedi8jah" ],
  "claims"        : { "email"  : "alice@wonderland.net",
                      "name"   : "Alice Adams",
                      "roles"  : [ "admin", "audit" ],
                      "office" : "B-397" }
}

Placing attributes in the claims object of a session normally causes them to become automatically included in the issued ID tokens for the user. This behaviour has existed in the Connect2id server since 2015. To disable it, so that the claims source has control over the claims release, the
op.idToken.includeSubjectSessionClaims configuration property must be set to an empty list.

op.idToken.includeSubjectSessionClaims=

This and the general configuration of the session-based claims source is described in its configuration manual.

Consolidated plugin dependencies

To simplify maintenance and development the default Connect2id server plugins for handling the password, client credentials and other OAuth grants are now consolidated in a single dependency.

If you intend to customise a grant handler make sure you fork the new project as the old plugins will no longer be maintained.

Resolved issues

The new release resolves several issues. These are described in the notes below.

Upgrading

Upgrading to v16.0 is straightforward and doesn’t require anything special to be done. If you have a Connect2id server that uses a relational database, the server will automatically add a new required ctx column to the subject_sessions tables when it starts up. This column is required to differentiate between web and device sessions, which is required with the introduction of native SSO support.

To disable automatic table schema updates on server startup set the dataSource.createTableIfMissing configuration property to false. The column addition can then be done manually. The database SQL schemas can be found in the WAR package of the Connect2id server.

Download 16.0

For the signature validation: Public GPG key

Standard Connect2id server edition

Apache Tomcat package with Connect2id server 16.0: Connect2id-server.zip

GPG signature: Connect2id-server.zip.asc

SHA-256: bf04d16494c06bf158b31b079f5079a6f0f2066543b4217514e5f53e494b1773

Connect2id server 16.0 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: d3f3422a9f99fe7746828df1ae2e113922a4ad69bc5375d6b49df3c485a45b75

Multi-tenant edition

Apache Tomcat package with Connect2id server 16.0: Connect2id-server-mt.zip

GPG signature: Connect2id-server-mt.zip.asc

SHA-256: a5897103f40a3bfd74cfc23b3fd9d61b0333c79d61bab2d77dc094e8c1902ef8

Connect2id server 16.0 WAR package: c2id-mt.war

GPG signature: c2id-mt.war.asc

SHA-256: fb9f518d37859cb957f56add1dde65e0d7ad2fbefad34f72fc162d48566ed9b6

Questions?

For technical questions about this new release contact Connect2id support. To purchase a production license for the Connect2id server, renew or upgrade your support and updates subscription, email our sales.

Release notes

16.0 (2024-09-30)

Summary

  • Adds support for OpenID Connect Native SSO for Mobile Apps 1.0 (based on draft 06 and the anticipated future draft 07).

    This OpenID Connect extension enables a group of native applications, such as mobile applications of the same vendor, to establish a shared device-based session with the Connect2id server (as OpenID provider) for the end-user. The session enables the participating applications to benefit from a device-based single sign-on (SSO). Issued ID tokens and refresh tokens are cryptographically bound to the device session. Closing or expiring the device session automatically disables any refresh tokens bound to it.

    The device session is represented by an opaque cryptographically secured device_secret generated by the Connect2id server and linked to a subject (end-user) session stored in the server. The device sessions can be managed via the Connect2id subject session store web API. The Connect2id server maintains strict isolation between web sessions (used for web SSO) and device sessions (used for device SSO).

    A client application can end a device session by calling the token revocation endpoint with the token parameter set to the device_secret value and the token_type_hint parameter to device_secret.

    On Android participating applications can store the device_secret and the ID token(s) required for the device SSO in the EncryptedSharedPreferences. On iOS applications can use the Keychain services API.

    A DeviceSSOHandler SPI is provided to enable deployments to make decisions about the tokens to issue in a response to a back-channel device SSO from a client. A default plugin enabling a range of configurations, such as which scope values must trigger end-user interaction at the OpenID provider, is included.

  • Includes a new plugin for sourcing OpenID Connect claims about a subject (end-user) from the subject session claims field. The plugin implements the AdvancedClaimsSource SPI from the Connect2id server SDK.

    The claims field of a subject session can be conveniently populated with attributes at the time of its creation, which occurs when the end-user is authenticated with the Connect2id server. For a closed or expired subject session the source returns no claims. This makes the claims source suitable for client applications that require UserInfo endpoint access only when the end-user is logged in with the OpenID provider. ID tokens are always issued in the presence of a subject session, thus any ID token bound sourcing of claims by this plugin is guaranteed.

    See /WEB-INF/sessionClaimsSource.properties for the plugin configuration properties.

    Note that the default op.idToken.includeSubjectSessionClaims configuration is at cross-purposes with this plugin. This configuration property must therefore be disabled, or, if automatic feeding of selected claims from the subject session into the issued ID tokens is still desired, specify the exact names of the claims to feed.

  • Consolidates the Connect2id server plugin (SPI implementations) Maven dependencies for handling the OAuth 2.0 grants client_credentials, password, urn:ietf:params:oauth:grant-type:jwt-bearer, urn:ietf:params:oauth:grant-type:saml2-bearer and urn:ietf:params:oauth:grant-type:token-exchange into a single
    com.nimbusds:oauth2-grant-handlers dependency. The consolidated dependency
    unifies the grant handler features and improves code reuse. The new dependency includes the default LocalDeviceSSOHandler implementation for handling back-channel device SSO requests.

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.sso.device.enable – New optional configuration property to enable / disable OpenID Connect Native SSO 1.0. The default value is false (disabled).

    • op.sso.device.sessionMaxLifetime – New optional configuration property that sets the maximum device session lifetime, in minutes. A negative value implies no time limit. Must not be zero. The default value is 259200 minutes (180 days).

    • op.sso.device.sessionAuthLifetime – New optional configuration property that sets the device session maximum authentication lifetime, in minutes. A negative value implies no time limit. Must not be zero. The default value is 10080 minutes (30 days).

    • op.sso.device.sessionMaxIdleTime – New optional configuration property that sets the maximum device session idle time, in minutes. A negative value implies no time limit. Must not be zero. The default value is 1440 minutes (10 days).

  • /WEB-INF/infinispan-*-{mysql|oracle|postgres95|sqlserver}.xml

    • Upgrades the SQL schema by adding a new ctx (context) column to the subject_sessions table. In existing deployments the Connect2id server will automatically add the new column on startup, unless dataSource.createTableIfMissing is disabled.

  • /WEB-INF/deviceSSOHandler.properties – New properties file specifying the default configuration of the local handler for OpenID Connect back-channel device SSO requests (implements the DeviceSSOHandler SPI). Can be overridden with Java system properties.

    • op.deviceSSOHandler.enable – Enables / disables the handler. Disabled (false) by default.

    • op.deviceSSOHandler.scopeRequiringInteraction – Scope values that require end-user interaction (re-authentication or explicit consent) at the authorisation endpoint, as space separated list. Back-channel device SSO requests that include any of these scope values will trigger an interaction_required error at the token endpoint. None by default.

    • op.deviceSSOHandler.accessToken.lifetime – The access token lifetime, in seconds. If zero, blank or omitted the default access token lifetime configured by authzStore.accessToken.defaultLifetime applies.

    • op.deviceSSOHandler.accessToken.encoding – The access token encoding. The default value is SELF_CONTAINED.

      Supported encodings:

      • IDENTIFIER – The access token is a secure identifier. The associated authorisation is looked up by a call to the Connect2id server token introspection endpoint.

      • SELF_CONTAINED – Self-contained access token. The associated authorisation is encoded in the access token itself, as a signed and optionally encrypted JSON Web Token (JWT). Can also be looked up by a call to the Connect2id server token introspection endpoint.

    • op.deviceSSOHandler.accessToken.encrypt – If true enables additional encryption of self-contained (JWT-encoded) access tokens. Disabled (false) by default.

    • op.deviceSSOHandler.accessToken.audienceList – Optional audience for the access tokens, as comma and / or space separated list of values.

    • op.deviceSSOHandler.accessToken.includeClientMetadataFields – Names of client metadata fields to include in the optional access token data field, empty set if none. To specify a member within a field that is a JSON object member use dot (.) notation.

    • op.deviceSSOHandler.refreshToken.issue – Enables / disables refresh token issue. Enabled (true) by default.

    • op.deviceSSOHandler.refreshToken.lifetime – The refresh token lifetime, in seconds. Zero for no expiration. If -1, blank or omitted the default refresh token lifetime configured by authzStore.refreshToken.defaultLifetime applies.

    • op.deviceSSOHandler.refreshToken.maxIdleTime – The refresh token maximum idle time, in seconds. Zero for no idle time expiration. The default value is 0.

    • op.deviceSSOHandler.refreshToken.rotate – If true causes the refresh token to be updated (rotated) on each refresh token use. If blank or omitted the default rotation setting configured by op.deviceSSOHandler.refreshToken.rotate applies.

    • op.deviceSSOHandler.claimsTransport – The transport to use for authorised claims. The default value is USERINFO:

      Supported values:

      • USERINFO – To release the claims at the UserInfo endpoint of the Connect2id server by presenting the issued access token.

      • ID_TOKEN – To release the claims in the ID token. If an ID token is not issued for a particular request the claims will be diverted for release at the UserInfo endpoint.

  • /WEB-INF/clientGrantHandler.properties

    • op.grantHandler.clientCredentials.simpleHandler.accessToken.lifetime – If zero or omitted the default access token lifetime configured by authzStore.accessToken.defaultLifetime applies. The previously configured property value of 600 seconds is removed.

    • op.grantHandler.clientCredentials.simpleHandler.accessToken.encoding – When omitted or blank receives a default value SELF_CONTAINED.

    • op.grantHandler.clientCredentials.simpleHandler.accessToken.encrypt – When omitted or blank receives a default value false.

  • /WEB-INF/selfIssuedJWTBearerHandler.properties

    • op.grantHandler.selfIssuedJWTBearer.accessToken.lifetime – If zero or omitted the default access token lifetime configured by authzStore.accessToken.defaultLifetime applies. The previously configured property value of 300 seconds is removed.

    • op.grantHandler.selfIssuedJWTBearer.accessToken.encoding – When omitted or blank receives a default value SELF_CONTAINED.

    • op.grantHandler.selfIssuedJWTBearer.accessToken.encrypt – When omitted or blank receives a default value false.

  • /WEB-INF/sessionClaimsSource.properties – New properties file specifying the default configuration of the subject session-based claims source (implements the AdvancedClaimsSource SPI). Can be overridden with Java system properties.

    • op.sessionClaimsSource.enable – Enables / disables the claims source. Disabled by default.

    • op.sessionClaimsSource.supportedClaims – The names of the supported (standard and custom) OpenID Connect claims, as a comma and / or space separated list. Support for a pattern of claims can be indicated with the * wildcard character, for example as https://idp.example.com/* for a set of claims having a common URI prefix in their name. A single claim set to * indicates support for all claims supported by the OpenID provider without explicitly listing them.

Web API

  • /.well-known/openid-configuration

    • native_sso_supported – New optional metadata field of type boolean to
      indicate support for OpenID Connect Native SSO for Mobile Apps 1.0. The
      default value is false. Omitted if not supported.

  • /token

    • Supports the device_secret token request parameter for OpenID Connect native SSO with an OAuth 2.0 authorisation code grant. For native SSO the code grant scope must include the openid and device_sso values.

    • Supports the device_secret token response parameter for OpenID Connect native SSO with an OAuth 2.0 authorisation code or token exchange grant.

  • /token/revoke

    • Supports device_secret revocation, which has the effect of closing the device session. Requires the token parameter to be set to the value of device_secret and the optional token_type_hint parameter to be set to device_secret.

  • /session-store/rest/v2/

    • Subject (end-user) sessions receive a new mandatory ctx (context) field, to identify the context of their use.

      The context web is for sessions created by the Connect2id server in the OAuth 2.0 authorisation code and implicit flows which involve a web browser. A web session links to a cookie stored by the Identity Provider login page in the user’s browser. This is the default context for sessions. Existing sessions found in the Connect2id server subject session store receive the default value web.

      The context device is for sessions created by the Connect2id server for OpenID Connect native SSO. A device session links to a device_secret stored by participating client applications on the user’s device.

      The Connect2id server isolates sessions with different contexts, so that a session with the web context cannot be used in a device context and vice versa.

      All sessions for a given subject (end-user), regardless of their context, count toward the session quota, as configured by the sessionStore.quotaPerSubject property.

      The session store web API allows the creation of sessions with other context values, for use by auxiliary services and integrations that require or will benefit from isolated sessions.

SPI

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

    • New DeviceSSOHandler SPI for authorising the scope values and other token properties for native SSO back-channel token requests, which requests are based on the OpenID Connect native SSO profile for the token exchange grant (RFC 8693). A default plugin is provided, see /WEB-INF/deviceSSOHandler.properties.

    • The TokenExchangeGrantHandler SPI receives a new TokenIntrospection.getOIDCClientMetadata helper method to obtain the OAuth 2.0 / OpenID relying party metadata for a subject_token that is a locally issued access token.

    • Updates all OAuth 2.0 grant handler SPIs by providing a GrantHandlerContext.resolveClaimNames(Scope) helper method that resolves the claim names for all values in the specified scope that expand to claims. Recognises all standard OpenID Connect scope values as well as any custom mappings configured in the Connect2id server. The processGrant methods with the InvocationContext are deprecated, in favour of a new processGrant method with a GrantHandlerContext argument that extends GrantHandlerContext. The updated SPIs are:

      • ClientCredentialsGrantHandler
      • PasswordGrantHandler
      • SelfIssuedJWTGrantHandler
      • ThirdPartyJWTGrantHandler
      • SelfIssuedSAML2GrantHandler
      • ThirdPartySAML2GrantHandler
      • TokenExchangeGrantHandler

Resolved issues

  • Modifies processing of the optional id_token_hint parameter at the authorisation endpoint and the end-session endpoint to treat the ID token hint as invalid for clients that are registered with an id_token_signed_response_alg metadata parameter none (unsecured ID token) or HSxxx (HMAC-SHA-2 secured ID token). These JWS algorithms cannot establish the authenticity of the ID token as being issued by the OpenID provider, only digitally signed tokens can, such as tokens signed with the default RS256 JWS algorithm. Clients that use the id_token_hint parameter to provide a hint to the Connect2id server about the end-user identity or session in OpenID authentication and OpenID RP-initiated logout requests must switch to a digital signature algorithm, such as RS256 (issue server/1013).

  • Fixes a regression introduced in v14.0 that caused the names of the authorised UserInfo endpoint claims for an access token to include the names of claims for which the Connect2id server has a previous long-lived consent on record for the subject and client_id. The bug affected long-lived access token authorisations that include no UserInfo claims. Access token authorisations that include at least one UserInfo claim were not affected (issue server/1022).

  • Increases the maximum acceptable clock skew for the iat (issued-at) DPoP proof claim checks from 30 to 120 seconds. The change was prompted by the observation that mobile devices can experience system clock drift in the range up to 120 seconds (issue server/1014).

  • Authorisation requests with an invalid code_challenge_method that include illegal characters according to RFC 6749, section 4.1.2.1, must produce an invalid_request error and not result in an HTTP 500 in the authorisation session web API (issue server/1020).

Dependency changes

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

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

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

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

  • Updates to com.nimbusds:c2id-server-jwkset:1.30.6

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

  • Updates to Infinispan 14.0.31.Final

  • Updates to org.apache.common:commons-lang3:3.15.0

  • Removes com.nimbusds:oauth-client-grant-handler

  • Removes com.nimbusds:oauth-jwt-self-issued-grant-handler

  • Removes com.nimbusds:oauth-grant-handlers-web

  • Adds com.nimbusds:oauth2-grant-handlers:1.3

  • Adds com.nimbusds:oidc-claims-source-session:1.0