OpenID provider / OAuth 2.0 server issuer URL 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:
Use of 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.
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:
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
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):
The configured issuer aliases can be verified by checking the server
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:
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_livedflag 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.
The configured issuer aliase mode can be verified by checking the server
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
POST /token HTTP/1.1
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
"error" : "invalid_request",
"error_description" : "Invalid issuer or issuer alias: https://login.example.com"
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.
In Connect2id server v13.0+
In both issuer alias modes -
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 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.
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.