Skip to content
Connect2id

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 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. 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.