Blog »

Connect2id server 7.15 has new FAPI features

2019-08-26

FAPI is a collection of OAuth 2.0 security profiles which were originally intended for fintech applications but can also be employed in other areas where you need strongly secured identity and access tokens. This 7.15 release of the Connect2id server brings several updates for providers that need to be FAPI compliant or want to maintain the highest possible security standard for OAuth and OpenID Connect.

X.509 certificates in server JWKs

An X.509 certificate chain included in a server RSA or EC key (as x5c JWK parameter) will now be exposed in the published public key at the jwks.json endpoint and in the x5c header parameter of JWTs signed with it (ID tokens, self-contained access tokens, etc).

The X.509 certificate chain allows OAuth 2.0 clients to perform PKIX validation of the published key and hence tokens signed with it. Note that the Connect2id server will not perform PKIX validation on a configured JWK if the key includes a certificate chain. Including an "x5c" header in a JWT can also easily multiply its size.

New configuration to make PKCE required for all OAuth 2.0 clients

PKCE is an OAuth 2.0 security enhancement that binds an issued authorisation code to the original authorisation request. It was initially meant to protect public clients that lack a credential to authenticate at the token endpoint from code interception attacks, but can benefit confidential clients as well.

FAPI has therefore made the use of PKCE a requirement. Unfortunately PKCE didn't specify a standard client registration parameter to allow this to be configured individually per OAuth 2.0 client. So we created a new global server configuration op.authz.requiredPKCE which, if set, lists the required code challenge methods (S256, plain) that all clients must use.

Check our PKCE guide for clients if you have a Java application.

The UserInfo endpoint no longer accepts access tokens in the URI query

Passing an access token in the URI query is a horrible practice as it may result in the token leaking through web server logs. To discourage clients from this the UserInfo endpoint of the Connect2id server will no longer accept tokens in the access_token query parameter.

Insecure submission of a bearer token in the URI query:

GET /userinfo?access_token=Toasu1haw8ithop7 HTTP/1.1
Host: c2id.com

The HTTP response will return a helpful error message explaining why the request was rejected:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Invalid request: Access token disallowed in URI query"
}

Clients should instead pass the token in a Authorization header or in a access_token form-encoded body parameter.

If for some reason clients cannot transport the access token in the "Authorization" request header field or the HTTP request entity-body, the URI query method can be allowed with a new op.userinfo.allowAccessTokenInURIQuery configuration:

op.userinfo.allowAccessTokenInURIQuery = true

The Userinfo endpoint is now FAPI compliant

The UserInfo endpoint is now FAPI compliant, by normally disallowing tokens in the URI query and by also supporting the X-FAPI-Interaction-ID header. The header is intended to aid logging, auditing and support calls, by giving the resource request and the resulting response (success or error) a common unique identifier. If the client sets the header in the outgoing HTTP request the Connect2id server will echo it in the resulting HTTP response. The value should be an UUID.

GET /userinfo HTTP/1.1
Host: c2id.com
Authorization: Bearer Toasu1haw8ithop7
X-FAPI-Interaction-ID: 1ebc5b42-81cd-4a43-a668-c7383bfd61df

If the request header isn't set the Connect2id server will generate an UUID for the response.

New metrics gauge shows Connect2id server version

The Connect2id server version can now be found out from the metrics endpoint, by looking up the server.version gauge.

HTTP/1.1 200 Success
Cache-Control: must-revalidate,no-cache,no-store
Content-Type: application/json

{
  "version" : "3.0.0",
  "gauges"  : { "server.version" : { "value": "7.15" },
  ...
  }
  ...
}

Bug fixes

The new release also fixes several issues, details in the notes below.

Download

To download a ZIP package of Connect2id server 7.15:

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

SHA-256: 381366fdedc5524d20ba1b5d4f243a1e09e72c1558af8f5cfe07e441d7327853

As WAR package only:

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

SHA-256: 617a31748d6a66b822d05ebaed49f6e23597082019fc2b48f44596eb33c9787e

Questions?

Contact Connect2id support.

Release notes

7.15 (2019-08-26)

Configuration

  • /WEB-INF/jwkSet.json

    • Public RSA and EC JSON Web Keys (JWK) that specify an X.509 certificate chain ("x5c" parameter, see RFC 7517, section 4.7) will be published at the /jwks.json endpoint with the certificate chain included. Issued ID tokens and self-contained (JWT-encoded) access tokens that are signed with such a key will also include the certificate chain as the "x5c" JWT header parameter (see RFC 7515, section 4.1.6).

      The X.509 certificate chain allows OAuth 2.0 clients to perform PKIX validation of the published keys and the issued tokens. Note that the Connect2id server will not validate the certificate chains of configured server JWKs.

  • /WEB-INF/oidcProvider.properties

    • Adds new "op.authz.requiredPKCE" configuration property listing the required PKCE (RFC 7636) code challenge methods which OAuth 2.0 clients must use at the authorisation endpoint. The values are specified as a comma and / or space separated code challenge method names. If empty or not specified PKCE is not required. The default value is not required.

    • Adds new "op.userinfo.allowAccessTokenInURIQuery" configuration property for the UserInfo endpoint to allow access tokens submitted via the access_token URI query parameter. The default policy (false) now is to reject access tokens received via the URI query parameter in order to prevent potential token leakage via web server access logs. The URI query method should not be allowed unless it is impossible to transport the access token in the "Authorization" request header field or the HTTP request entity-body. See RFC 6750, section 2.3.

Web API

  • /userinfo

    • Makes the UserInfo endpoint FAPI profile compliant by logging and echoing the x-fapi-interaction-id HTTP request header. If the header is not set by the client the Connect2id server will generate an UUID value for it and return it in the UserInfo HTTP response.

  • /monitor/v1/metrics

    • Adds new "server.version" gauge of type string to indicate the Connect2id server version, e.g. "7.15".

Resolved issues

  • Skips validation of OpenID authentication request specific parameters, such as "claims", when processing a plain OAuth 2.0 request. Fixes an authorisation session serialisation bug that affected processing of plain OAuth 2.0 requests with custom parameters (issue server/479).

  • Fixes a concurrency issue in the session store introduced in v7.12.1 which may result in a deleted subject session after the session is read. Applies to stateless cluster deployments only (DynamoDB, Redis + MySQL / PostgreSQL) (issue session store/81).

  • Logs the exception message and PEM string when parsing an invalid client X.509 certificate. Fixes logging of a missing client certificate when the Connect2id server is behind an Apache HTTPd reverse proxy (issue server/475).

  • Logs subject session removal events under SS0213 (issue session store/81).

Dependency changes

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

  • Updates to com.nimbusds:oauth2-authz-store:12.1

  • Updates to com.nimbusds:oidc-session-store:12.0.3

  • Updates to com.thetransactioncompany:cors-filter:2.8