Issuer aliases

The issuer URL

The issuer URL uniquely identifies a Connect2id server instance in the various tokens that it mints as OpenID provider / OAuth 2.0 authorisation server. The issuer URL is also a starting point for resolving metadata about the server, such as its endpoints and cryptographic capabilities.

Example issuer URL configuration:

op.issuer=https://openid.wonderland.net

Use of issuer aliases

Starting with Connect2id server 12.3 (the regular as well as the multitenant edition), a deployment can be optionally configured with one or more issuer aliases:

To migrate seamlessly and over time from one issuer URL to another.
To identify an OpenID provider / OAuth 2.0 authorisation server by more than one issuer URLs. This can be useful as a light form of multitenancy, in deployments where the complete data isolation of individual issuers provided by the special multitenant Connect2id server edition is not required or feasible.

Configuration

1. Issuer aliases whitelist

The issuer URL aliases must be configured as properties with the op.issuerAliases.* prefix.

Example server configuration with a main issuer URL and two whitelisted aliases:

op.issuer=https://openid.wonderland.net
op.issuerAliases.1=https://login.wonderland.net
op.issuerAliases.2=https://wonderland.net/sso

The purpose of the op.issuerAliases.* configuration is to declare a whitelist of acceptable issuers and prevent accidental mistakes when setting the Issuer header from the HTTP reverse proxy of the Connect2id server.

In cases when the issuers may change dynamically and frequent reconfiguration of the Connect2id server is not desirable, set the aliases value to an asterisk (since v13.0):

op.issuerAliases=*

The configured issuer aliases can be verified by checking the server log for OP0006:

INFO main MAIN - [OP0006] OP / AS issuer aliases: [https://login.wonderland.net, https://wonderland.net/sso]

2. Issuer alias mode

The second configuration is the issuer alias mode (since v13.0):

MIGRATION – Enables seamless migration over time to a new issuer URL. This is the default mode.

Supported OAuth 2.0 grants: all
PERSISTED_GRANT_ISOLATION – Enforces separation of the OAuth grants and tokens between the issuer aliases, while keeping the client registrations and user sessions shared. This mode is intended for Connect2id server deployments that seek a light form of multitenancy, without going for the full blown multitenant edition of the server.

Supported OAuth 2.0 grants:
- authorization_code
- implicit
- client_credentials
- urn:ietf:params:oauth:grant-type:jwt-bearer
- urn:ietf:params:oauth:grant-type:saml2-bearer
When selected this mode the Connect2id server will alter its behaviour in several ways to guarantee the complete isolation of the OAuth grants between the aliases:
- Long-lived (persisted) consent in the authorisation session API is disabled. This means that when submitting the end-user consent the long_lived flag will always be set to false. Disabling persisted consent means that the next time the client asks the end-user for the same scope values and other authorisation, like OpenID claims, their previous choice will not be automatically remembered.
- If the consent allows a refresh token to be issued, it will always be a self-contained (stateless) refresh token (encoded as encrypted JWT). Note, this applies only to the authorisation code and implicit grants.
- Any previously issued refresh tokens that are identifier-based and thus linked to long-lived (persisted) consent will become unusable, i.e. the Connect2id server will reject their use at the token endpoint.
This mode also alters the behaviour of back-channel logout notifications, which are encoded as signed JWTs and include the OpenID provider issuer (iss) URL. In Connect2id server versions up to and including 15.5 such events will be blocked, since a subject session may potentially be shared by more than one issuer. If such sharing occurs an OpenID RP registered for back-channel logout notifications may receive a logout JWT with an iss claim that doesn’t match the iss for the ID token it has previously received for the logged-in user. In Connect2id server v15.6 this policy was weakened and the server will deliver back-channel logout notifications in response to logout requests, with the logout JWT iss being set to the supplied Issuer header in the logout session API. If this weakened policy doesn’t suit your security and privacy requirements, disable back-channel logout for all clients. Note that back-channel logout notifications on session expiration are always unconditionally blocked.

The configured issuer alias mode can be verified by checking the server log for OP0009:

INFO main MAIN - [OP0009] Issuer alias mode: PERSISTED_GRANT_ISOLATION

How to switch issuers

The default behaviour of the Connect2id server is to respond to requests and issue tokens under the main issuer URL configured in op.issuer.

To process a request under an issuer alias the Connect2id server must receive the HTTP request with an Issuer header set to the desired issuer URL. The header will be typically set by a domain-aware reverse HTTP proxy.

Example HTTP request with an Issuer header set to https://login.wonderland.net:

POST /token HTTP/1.1
Host: openid.wonderland.net
Issuer: https://login.wonderland.net
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

The Issuer header value must match a configured alias or main (default) op.issuer exactly!

If the Issuer header doesn’t match a configured main issuer or an alias the Connect2id server will return a 400 “Bad Request” error.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "error"             : "invalid_request",
  "error_description" : "Invalid issuer or issuer alias: https://login.example.com"
}

Security

1. Scrub incoming Issuer headers

The Issuer header must be set by a suitably configured reverse HTTP proxy or similar trusted internal infrastructure. This header must not be settable by client applications. Connect2id server deployments must therefore scrub the incoming client application HTTP requests from any present Issuer headers.

2. Isolation

In Connect2id server v13.0+

In both issuer alias modes - MIGRATION or PERSISTED_GRANT_ISOLATION, the Connect2id server has the following isolation guarantees in place:

Prohibits switching of the issuer URL during an OAuth authorisation code, implicit or hybrid flow (which may involve the PAR endpoint).
Prohibits switching of the issuer URL in the authorisation session API at the user authentication or consent step.
The token introspection endpoint will mark any token issued under a different alias as invalid and the scope to access the endpoint must also be set to the current issuer URL.
The UserInfo endpoint will reject access tokens issued under a different alias.

Note, in the MIGRATION issuer alias mode refresh tokens which are tied to long-lived (persisted) consent can be shared across all issuer aliases. The resulting access tokens however will be issued and remain valid for the current issuer alias only.

In Connect2id server v12.x

The Connect2id server assumes that issuer aliases are equivalent and interchangeable, which resembles the MIGRATION in v13.0+.

This means the server will not return an error if the Issuer header for an alias is changed to a different value during an OAuth 2.0 flow or within a related set of API calls.

To illustrate:

During an OAuth 2.0 flow that involves the PAR, authorisation and token endpoints. For example, starting a code flow with one Issuer alias header and then changing the header in a subsequent request.
During invocations of the authorisation session API when processing a particular login request.
Introspecting a token issued under an alias.
Consuming an access token at the UserInfo endpoint issued under an alias.

3. For complete issuer isolation use separate tenants

Note, the use of issuer aliases doesn’t isolate the client registrations (with their credentials) and the user-sessions. These are shared between all tenants. For complete issuer isolation use separate tenants.