OpenID provider / OAuth 2.0 server issuer URL aliases
The issuer URL
The issuer URL uniquely identifies the OpenID provider / OAuth 2.0 authorisation server in the tokens that it mints. The issuer URL is also a starting point to resolve 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 by the 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:
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 issuer alias mode configures the isolation of the OAuth grants and tokens between the aliases:
-
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 tofalse
. 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 aniss
claim that doesn’t match theiss
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 JWTiss
being set to the suppliedIssuer
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. HTTP clients must prevented from setting it. Connect2id server deployments must therefore scrub all incoming client HTTP requests from any present Issuer headers.
2. Isolation
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.
3. For complete issuer isolation use separate tenants
The issuer aliases don’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.