OAuth 2.0 articles

Connect2id server 7.2

Posted on 2018-06-11

What’s in this week’s release of the Connect2id server for OpenID Connect and OAuth 2.0 security?

More server endpoints accept client authentication with a self-signed X.509 certificate

When we originally implemented the OAuth 2.0 mutual TLS profile in Connect2id server 6.13 only the token endpoint was made to handle client authentication with a self-signed X.509 certificate. Support for this new authentication method is now extended to the following endpoints:

The calling clients must be registered with a token_endpoint_auth_method set to self_signed_tls_client_auth and also provide to the Connect2id server a suitable JWK set, either by URI (with jwks_uri) or inline (with jwks).

In a future release we’ll add support for registering dedicated client introspection_endpoint_auth_method and revocation_endpoint_auth_method parameters.

Client certificate bound tokens also get handled at the introspection endpoint

In addition to the above, the introspection endpoint will also accept token authorisations that are bound to a client certificate. The client must then include a X.509 certificate that matches the cnf.x5t#S256 claim associated with the submitted authorising token.

Custom UserInfo response status codes

When processing a claims request at the UserInfo endpoint a thrown Java exception will cause a 500 Internal Server Error HTTP response to be returned.

To cause the Connect2id server to return a different HTTP status code throw a com.nimbusds.oauth2.sdk.GeneralException from the OAuth 2.0 SDK, with an ErrorObject having the desired status code.

Example:

throw new GeneralException(new ErrorObject(
    "my_error_code",
    "My error message",
    444));

This will result in a HTTP response like this:

HTTP/1.1 444
Content-Type: application/json;charset=UTF-8

{
  "error" : "my_error_code",
  "error_description" : "My error message"
}

Download

To download a ZIP package of Connect2id server 7.2:

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

SHA-256: f426b28b5623cce0c787ab3edeeea78c6099baec64b8661a346247d041493166

As WAR package only:

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

SHA-256: 4768a2cc9d32f35784de61e46e1e002951d6606bf3c7bd97022c234849e950f4

Questions?

Get in touch with Connect2id support.


Release notes

7.2 (2018-06-11)

Summary

  • Adds support for self-signed certificate TLS client authentication (draft-ietf-oauth-mtls-09) at the token introspection and revocation endpoints. The calling clients must be registered for self_signed_tls_client_auth.

  • Adds support for mutual TLS client certificate bound access token authorisation (draft-ietf-oauth-mtls-09) at the token introspection endpoint. The client must include a X.509 certificate that matches the cnf.x5t#S256 claim associated with the submitted access token.

Web API

  • /token/introspect — Adds support for client authentication with a self-signed X.509 certificate (self_signed_tls_client_auth).

  • /token/introspect — Adds support for mutual TLS client certificate bound access token authorisation (self_signed_tls_client_auth).

  • /token/revoke — Adds support for client authentication with a self-signed X.509 certificate (self_signed_tls_client_auth).

SPI

  • The ClaimsSource and AdvancedClaimsSource SPIs can throw a com.nimbusds.oauth2.sdk.GeneralException with an ErrorObject to set a specific HTTP status code and error message when processing UserInfo requests.

    Example:

    throw new GeneralException(new ErrorObject(
      "my_error_code",
      "My error message",
      444));

Resolved issues

  • Logs TokenIntrospectionResponseComposer SPI loading under OP6530 (issue server/369).

Dependency changes

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

Connect2id server 7.1

Posted on 2018-06-01

With June arrives a new release of the OpenID Connect / OAuth 2.0 server, featuring updates to the claims (attribute) sources, the OAuth 2.0 mutual TLS profile and support for custom error codes at the authorisation endpoint.

Source OpenID Connect claims from an HTTP endpoint

The connector for sourcing OpenID claims (attributes) from an HTTP endpoint is now part of the official Connect2id server package. You can use it to integrate any database or system as claims source, by setting up a simple web service to act as broker.

Example request for an array of claims associated with user alice:

POST /claims-source HTTP/1.1
Host: www.example.com
Content-Type: application/json; charset=UTF-8
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "iss"    : "https://c2id.com",
  "sub"    : "alice",
  "claims" : [ "email", "email_verified", "name", "given_name", "family_name" ]
}

The response has the JSON format of a UserInfo response:

HTTP/1.1 200 OK
Date: Mon, 23 May 2016 22:38:34 GMT
Content-Type: application/json; charset=UTF-8

{
  "sub"            : "alice",
  "email"          : "[email protected]",
  "email_verified" : true,
  "name"           : "Alice Adams",
  "given_name"     : "Alice",
  "family_name"    : "Adams"
}

Update to the LDAP claims source connector

The configuration which sets the mapping of LDAP attributes to JSON entities can now be passed as an op.ldapClaimsSource.attributeMap property. With that the LDAP connector can now be configured entirely via Java system properties.

op.ldapClaimsSource.attributeMap = {"sub":{"ldapAttr":"uid"},"name":{"ldapAttr":"cn","langTag":true},...

The hosted and multi-tenant Connect2id servers will accept configuration only via Java properties, passed via the configuration API.

Claims sources can use wildcards when advertising support of claims

Every claims source that gets set up with the Connect2id server needs to provide the names of the claims it can handle. The server finds out the names by calling the supportedClaims() of the claims source implementation.

@Override
public Set<String> supportedClaims() {

    return new HashSet<>(Arrays.asList("email", "email_verified"));
}

If the names of the handled claims are not known in advance or can change dynamically, the source can now specify a name with a wildcard character (*), provided the names follow a pattern. To prevent clashes it’s good practise to prefix custom names with a prefix, so that can be one suitable naming pattern, e.g. id4me.* for claims having the id4me prefix.

@Override
public Set<String> supportedClaims() {

    return new Collections.singleton("id4me.*");
}

At most one wildcard character may be used per advertised claim name. If the Connect2id server has more than one installed claims source matching a requested claim name, the source precedence is not deterministic.

Support for custom error codes in authorisation responses

If you have the need to return an authorisation error with a custom code, you can now do so, provided the possible custom codes are listed in the new op.authz.customErrorCodes configuration setting.

When cancelling an authorisation session the Connect2id server checks the error code against the list of standard OAuth 2.0 codes (and now custom codes as well) to make sure the client doesn’t get sent an invalid error code by accident.

Mutual TLS client authentication and client certificate bound access tokens

Support for the OAuth 2.0 mutual TLS profile was updated to the latest draft-ietf-oauth-mtls-08. There were two naming changes - the client and authorisation server metadata field mutual_tls_sender_constrained_access_tokens was renamed to tls_client_certificate_bound_access_tokens.

The OAuth 2.0 / OpenID Connect SDK was also updated accordingly (v5.62).

Download

To download a ZIP package of Connect2id server 7.1:

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

SHA-256: 5f65db6b816b9bbd005673e68f3c23097f370ac0838d7e9a98300ab1159b0bb9

As WAR package only:

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

SHA-256: 856580b85f636e653c03e484458a67aa36b9c3fcb4284e4715b7cd6652651b14

Questions?

Get in touch with Connect2id support.


Release notes

7.1 (2018-06-01)

Summary

  • Adds new connector for sourcing OpenID Connect claims for a subject (end-user) from an HTTP endpoint. Implements the AdvancedClaimsSource SPI from the Connect2id server SDK.

    • Supports retrieval of arbitrary OpenID Connect claims.

    • Supports multiple scripts and languages via language tags.

    • Access to the HTTP endpoint requires a non-expiring bearer token.

    • Utilises an HTTP POST request to obtain the claims in order to prevent leaking of the request parameters (subject identifier and claim names) into HTTP server logs.
  • Updates support for OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens to draft-ietf-oauth-mtls-08.

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.authz.customErrorCodes — New configuration property, for specifying additional custom OAuth 2.0 error codes that may be returned at the authorisation endpoint. The standard error codes allowed by default are access_denied, invalid_request, unauthorized_client, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, login_required, consent_required, interaction_required, account_selection_required, request_uri_not_supported, request_not_supported, invalid_request_uri and invalid_request_object. The custom error codes can be specified as a space and / or comma separated list.
  • /WEB-INF/httpClaimsSource.properties — New configuration file for the HTTP-based OpenID Connect claims sources. Every setting can be overridden with a Java system property.

    • op.httpClaimsSource.enable — Enables / disables the HTTP claims source. Disabled by default (if omitted).

    • op.httpClaimsSource.supportedClaims — The names of the supported (standard and custom) OpenID Connect claims, as a comma and / or space separated list.

    • op.httpClaimsSource.url — The URL of the HTTP endpoint for sourcing the OpenID Connect claims. Should be HTTPS.

    • op.httpClaimsSource.connectTimeout — The timeout in milliseconds for establishing HTTP connections. If zero the underlying HTTP client library will determine the timeout.

    • op.httpClaimsSource.readTimeout — The timeout in milliseconds for obtaining HTTP responses after connection. If zero the underlying HTTP client library will determine the timeout.

    • op.httpClaimsSource.trustSelfSignedCerts — Determines whether to accept self-signed X.509 / TLS certificates presented by the HTTP server. Self-signed certificates are not trusted by default.

    • op.httpClaimsSource.apiAccessToken — Access token of type bearer (non-expiring) for accessing the HTTP endpoint. Should contain at least 32 random alphanumeric characters to make brute force guessing impractical.
  • /WEB-INF/ldapClaimsSource.properties

    • op.ldapClaimsSource.attributeMap — New optional configuration setting for passing the LDAP attribute map definition as a property, optionally BASE-64 encoded to ease passing the JSON string as a Java system property via the command line. Can also be set to point to a file resource within the web application. Defaults to "/WEB-INF/ldapClaimsMap.json" if not specified.

SPI

  • ClaimsSource, AdvancedClaimsSource — The supportedClaims() method may return claim names with a wildcard ‘’ character to indicate support for a pattern of names, e.g. "id4me.". The string "*" can be used to indicate that the source can potentially serve any claim. At most one wildcard character may be used per advertised claim name. If the Connect2id server has more than one installed claims source matching a requested claim name, the source precedence is not deterministic.

Web API

  • /.well-known/openid-configuration

    • Updates the OpenID provider metadata for draft-ietf-oauth-mtls-08 where the mutual_tls_sender_constrained_access_tokens metadata field is renamed to tls_client_certificate_bound_access_tokens.
  • /.well-known/oauth-authorization-server

    • Updates the OAuth 2.0 authorisation server metadata for draft-ietf-oauth-mtls-08 where the mutual_tls_sender_constrained_access_tokens metadata field is renamed to tls_client_certificate_bound_access_tokens.
  • /clients

    • Updates the OAuth 2.0 client metadata for draft-ietf-oauth-mtls-08 where the mutual_tls_sender_constrained_access_tokens metadata field is renamed to tls_client_certificate_bound_access_tokens.

Dependency Changes

  • Adds new dependency to com.nimbusds:oidc-claims-source-http:1.0.1

  • Upgrades to com.nimbusds:oidc-claims-source-ldap:1.6

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

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

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

  • Upgrades Infinispan to 9.2.4.Final.

Connect2id server 7.0 extends plain OAuth 2.0 support, hardens security, upgrades Infinispan

Posted on 2018-05-03

After a series of 19 feature updates to Connect2id server 6 it was time to stage a new major release. What’s in it? Coverage for more OAuth 2.0 use cases and a major upgrade to the underlying in-memory, caching and persistence layer. Configuration of the server was also made more secure.

Plain OAuth 2.0

Client applications which only need an access token and are not interested in the end-user’s identity (OpenID Connect) can now make plain OAuth 2.0 authorisation requests to the Connect2id server. The requests can be made via the code flow as well as the implicit flow.

Example minimal OAuth 2.0 authorisation request in the code flow:

https://c2id.com/login?response_type=code&client_id=123

The redirect_uri and scope parameters are not mandatory in plain OAuth 2.0 authorisation requests, as opposed to OpenID Connect. If the redirect_uri parameter is omitted, the Connect2id server will take the first registered one for the client. Similarly, if the scope parameter is omitted, the authorisation session handler may assume the client requested the scope values included in its registration.

Everything else regarding the authentication and consent steps remains the same when serving plain OAuth 2.0 authorisation requests.

Securing sensitive configuration details

Access to the integration web APIs of the Connect2id server requires special opaque tokens. Because the tokens are set in the server configuration, this can be a potential security risk. Depending on how the Connect2id server gets deployed and how its configuration gets applied, the token strings may leak through environment variables, Java system properties, logs and package files, to name a few scenarios.

To prevent damage from accidental leaks the Connect2id server will no longer allow the tokens to be configured in plain text. Instead, their SHA-256 hash (in hex) must now be provided. If the server detects the old configuration format it will abort startup with an error.

Script to generate a 32 character token and compute its SHA-256 hash in hex:

#! /bin/sh
TOKEN=`pwgen 32 1`
echo "Access token: $TOKEN"
TOKEN_SHA256=`echo -n $TOKEN | sha256sum`
echo "Access token SHA-256: $TOKEN_SHA256"

With that the only remaining sensitive material in the Connect2id server configuration are the private and secret keys in the server’s JWK set. This risk can also be mitigated, by locking the keys away in a Hardware Security Module (HSM). Unfortunately, HSMs are still quite expensive and may not be readily available in some cloud environments. Inexpensive solutions based on open source hardware may however eventually change this.

Infinispan upgrade

The embedded Infinispan module for providing caching, in-memory storage, persistence and replication clustering to the Connect2id server was upgraded to the latest stable version 9.2 of Infinispan. Overall server performance will benefit from that.

Due to breaking changes in Infinispan’s object serialisation, direct rolling upgrades from Connect2id server 5.x and 6.x clusters will fail with a warning if attempted. To perform a rolling upgrade to a Connect2id server 7.0 cluster with no downtime a special migration procedure will be required. We intend to devise several options for that. Please, contact Connect2id support if you need assistance.

Tentative 7.x roadmap

Important portions of the Connect2id server were rewritten to prepare the groundwork for front and back-channel logout notifications as well as encrypted request JWTs.

Connect2id server 6.x documentation

The documentation for 6.x was moved to the archive.

Download

To download a ZIP package of Connect2id server 7.0:

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

SHA-256: 83f27c68db6f56dad706b919d2fffb41a7a0bccdf1c75d2568373262cb8a8e9c

As WAR package only:

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

SHA-256: 6bb51245124bd2b915f01ea29ca7a746db40ef4489bf3b41b177a35c7540c43e

Questions?

Get in touch with Connect2id support.


Release notes

7.0 (2018-05-02)

Summary

  • Adds support for processing plain OAuth 2.0 authorisation requests for clients that only require an access token, i.e. end-user authentication with OpenID Connect and ID token is not needed. Plain OAuth 2.0 authorisation requests can be made via the code (response_type=code) and implicit (response_type=token) flows. See RFC 6749 sections 4.1.1 and 4.2.1.

  • The master / API access tokens for the Connect2id server must now be configured by setting their SHA-256 hash, in hexadecimal format. Plain text configuration is no longer accepted. The hashing is intended to prevent accidental token leaks via web server logs, configuration files and Java system properties / environment variables.

  • Upgrades Infinispan from version 8.2 to 9.2. Due to object serialisation changes introduced in Infinispan 9, direct rolling upgrades from Connect2id server 6.x clusters will silently fail if attempted. To perform a rolling upgrade to a Connect2id server 7.0 cluster with no downtime a special migration procedure is required.

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.authz.responseTypes — The OAuth 2.0 "token" response type becomes supported.

    • op.reg.apiAccessTokenSHA256 — Replaces the op.reg.apiAccessToken configuration property, which is no longer supported. The master access token for the client registration endpoint is configured by setting its SHA-256 hash (in hexadecimal format).

    • op.reg.secondaryAPIAccessTokenSHA256 — New optional secondary master access token for the client registration endpoint. Has the same format as op.reg.apiAccessTokenSHA256. Must not be set if not used.

    • op.authz.apiAccessTokenSHA256 — Replaces the op.authz.apiAccessToken configuration property, which is no longer supported. The access token for the authorisation session endpoint and for the direct authorisation endpoint is configured by setting its SHA-256 hash (in hexadecimal format).

    • op.logout.apiAccessTokenSHA256 — Replaces the op.logout.apiAccessToken configuration property, which is no longer supported. The access token for the logout session endpoint is configured by setting its SHA-256 hash (in hexadecimal format).
  • /WEB-INF/authzStore.properties

    • authzStore.apiAccessTokenSHA256 — Replaces the authzStore.apiAccessToken configuration property, which is no longer supported. The access token for the authorisation store web API is configured by setting its SHA-256 hash (in hexadecimal format).

    • authzStore.secondaryAPIAccessTokenSHA256 — New optional secondary access token for the authorisation store web API. Has the same format as authzStore.apiAccessTokenSHA256. Must not be set if not used.
  • /WEB-INF/sessionStore.properties

    • sessionStore.apiAccessTokenSHA256 — Replaces the sessionStore.apiAccessToken configuration property, which is no longer supported. The access token for the session store web API is configured by setting its SHA-256 hash (in hexadecimal format).

    • sessionStore.secondaryAPIAccessTokenSHA256 — New optional secondary access token for the session store web API. Has the same format as sessionStore.apiAccessTokenSHA256. Must not be set if not used.
  • /WEB-INF/monitor.properties

    • monitor.apiAccessTokenSHA256 — Replaces the monitor.apiAccessToken configuration property, which is no longer supported. The access token for the logout session endpoint is configured by setting its SHA-256 hash (in hexadecimal format).
  • /WEB-INF/infinispan-*.xml

    • Updates the Infinispan configurations to match the schema of Infinispan 9.2.
  • CLASSPATH/default-jgroups-*.xml

    • Updates the JGroups configurations to match the schema of JGroups 4.

Web API

  • /.well-known/oauth-authorization-server

    • New endpoint for publishing the OAuth 2.0 Authorisation Server metadata of the Connect2id server at a well-known URL. The published metadata implements OAuth 2.0 Authorization Server Metadata (draft-ietf-oauth-discovery-10) and is identical to the OpenID Provider metadata provided at /.well-known/openid-configuration.

Dependency Changes

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

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

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

  • Upgrades to com.nimbusds:common:2.27

  • Upgrades to org.infinispan:infinispan-core:9.2.1.Final

  • Upgrades to org.infinispan:infinispan-query:9.2.1.Final

  • Upgrades to org.infinispan:directory-provider:9.2.1.Final

  • Upgrades to org.infinispan:directory-provider:9.2.1.Final

  • Upgrades to com.nimbusds:infinispan-cachestore-ldap:2.3.2

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

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

  • Upgrades to com.nimbusds:infinispan-cachestore-redis:9.2.1

Connect2id server 6.19.1 maintenance release

Posted on 2018-04-26

This maintenance release of the Connect2id server fixes a bug in the old version 2 of the authorisation session API for identity providers who use the form_post response mode, or a custom response mode. See the change log below for details.

Version 2 of the authZ session API was introduced in Connect2id server 3.0 (2015-03-26) and was superseded by the current version 3, in Connect2id server 5.0 (2016-05-17).

Download

To download a ZIP package of Connect2id server 6.19.1:

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

SHA-256: 09d885d7856794cf86ea711841223ab5d5d39217013aadc17ac99aa66e13e439

As WAR package only:

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

SHA-256: a36c2571733061f8574f46de9eebb8b406f905b3bf07a1ced70169474fa347b8

Questions?

Get in touch with Connect2id support.


Release notes

6.19.1 (2018-04-20)

Resolved Issues

  • Fixes a bug in the old v2 of the authorisation session API (/authz-sessions/rest/v2) which prevented ID token output in the final OpenID authentication response for response types "id_token" and "token id_token" in combination with a "form_post" or a custom response mode (issue server/361).