Connect2id server 15.4 introduces an STS web API to aid federated login

2024-03-11

This release of the Connect2id server ships the much anticipated Security Token Service (STS) web API to ease implementation of federated logins for identity providers. The concept of federated login enables an identity provider to call on 3rd party providers to authenticate end-users and obtain attributes about them, in a manner that is completely transparent to the client applications.

An identity provider that is built with the Connect2id server can now utilise the server's existing cryptographic facilities - JWT signing and key store - to mint JWTs to secure OAuth 2.0 flows with upstream OpenID providers. An upstream provider can verify the signature of a JWT using the public JWK set URL of the Connect2id server.

The first version of the STS API supports minting of tokens for the following purposes:

JAR -- For signed authorisation requests (JAR), as specified in RFC 9101, also called request objects in OpenID Connect.
private_key_jwt -- For JWT based client authentication at the token and other endpoints, using private key authentication.

To prevent mistakes in client logic, the STS API uses carefully designed templates to mint the requested JWTs. The templates take care to populate the JWT headers and claims sets with the correct data for the type of JWT and perform validation on the POSTed parameters. This means the STS cannot be used (or abused) to mint arbitrary JWTs.

Example request to the STS API to mint a token for a JAR:

POST /sts/rest/v1/issuer HTTP/1.1
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "template"   : "JAR",
  "alg"        : "RS256",
  "aud"        : "https://op.example.com",
  "parameters" : {
      "response_type"         : "code",
      "client_id"             : "client-123",
      "redirect_uri"          : "https://rp.example.com/cb",
      "scope"                 : "openid",
      "state"                 : "Mu0niexo",
      "nonce"                 : "Baemie2F",
      "code_challenge"        : "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
      "code_challenge_method" : "S256"
  }
}

The STS will return a JWT, which when inspected will show a header and a claims set similar to these:

JWT header, note the typ (type) header to explicitly type the JWT, a security measure against cross-jwt confusion:

{
  "alg" : "RS256",
  "typ" : "oauth-authz-req+jwt",
  "kid" : "q9SZ"
}

JWT claims set, containing the requisite iss and aud claims, the rest are parameters of the signed OpenID authentication request:

{
  "iss"                   : "client-123",
  "aud"                   : "https://op.example.com",
  "response_type"         : "code",
  "client_id"             : "client-123",
  "redirect_uri"          : "https://rp.example.com/cb",
  "scope"                 : "openid",
  "state"                 : "Mu0niexo",
  "nonce"                 : "Baemie2F",
  "code_challenge"        : "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method" : "S256"
}

What else has changed in this release can be found in the release notes below.

Download 15.4

For the signature validation: Public GPG key

Standard Connect2id server edition

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

GPG signature: Connect2id-server.zip.asc

SHA-256: 8b6f08c4ac9de28092e3139a511e684709ba97d071895bc795d9f7bb693bad5f

Connect2id server 15.4 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: d87932c45b635ac5c55380f8325c98ea841372c1be3b27d82094b16721c57242

Multi-tenant edition

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

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

SHA-256: 4034b1b9fa41e17feb45484648aac58bf893528172a14564570140682e9db0be

Connect2id server 15.4 WAR package: c2id-mt.war

GPG signature: c2id-mt.war.asc

SHA-256: 880bb43a909834c9ea6ce465281b2a0b9b60541c0bea085baf8565f3b9a31475

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

15.4 (2024-03-11)

Summary

Adds a new Security Token Service (STS) web API to issue signed JWTs for JWT-secured Authorisation Requests (JAR, see RFC 9101) and private_key_jwt authentication. Intended when an Identity Provider based on the Connect2id server acts an OAuth 2.0 client / OpenID relying party in federated login scenarios. The signature of an issued JWT can be validated using the server JWK set published at the /jwks.json endpoint.

Configuration

/WEB-INF/oidcProvider.properties
- op.sts.apiAccessTokenSHA256.* -- New optional configuration property. Specifies a master access token for the STS web API, represented by its SHA-256 hash (in hexadecimal format). The hashed storage is intended to prevent accidental leakage of the token through configuration files, logs, etc. The token is of type Bearer, non-expiring and must contain at least 32 random alphanumeric characters to make brute force guessing impractical. If not specified the web API is disabled.
  
  Additional access tokens, to facilitate token roll-over or for other needs, can be configured by appending a dot (.) with a unique label to the property name, e.g. as op.reg.apiAccessTokenSHA256.1=abc....
/WEB-INF/log4j.xml
- Updates the PatternLayouts of the RollingFile and Console appenders to comply with a recent Log4j library change.

Web API

/sts/rest/v1/
- New Security Token Service (STS) web API. Enabled if it has a master API access token (op.sts.apiAccessTokenSHA256) configured.
/sts/rest/v1/issuer
- New resource to issue signed JWTs for JWT-secured Authorisation Requests (JAR) and private_key_jwt authentication. Supports the RSxxx, PSxxx and ESxxx JWS algorithm families. The JWTs are generated according to a built-in template that defines the acceptable JWT header parameters and claims set. The template ensures the JWT is compliant with the respective specification and potential errors, such as including a sub claim in signed request object (JAR), are prevented.
  
  Supported templates:
  - JAR -- For issue of signed JWT-secured Authorisation Requests (JAR), also called request objects in OpenID Connect.
  - private_key_jwt -- For issue of private key client authentication JWTs for use at the token and other endpoints of an OAuth 2.0 authorisation server / OpenID provider.

Resolved issues

Corrects the OP5109 log INFO message that records whether a master API token for the client registration endpoint is configured (issue server/978).
Fixes the shipped /WEB-INF/log4j.xml configuration to comply with a recent Log4j library change. In Connect2id server 15.3 this caused the log lines to contain only the log message (%m), with timestamp, etc. missing (issue server/980).
Logs token success response (OP6225) and error response (OP6226) at INFO level, with client ID, grant type and other details (issue server/982).

Dependency changes

Updates to org.slf4j:slf4j-api:2.0.9
Updates to com.github.dubasdey:log4j2-jsonevent-layout:0.0.8