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 point for resolving important metadata about the server, such as its endpoints and capabilities.

Example configured issuer URL:


Use of issuer aliases

Starting with Connect2id server 12.3 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 multiple issuer URLs.


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

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


How to switch between 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 particular request under an issuer alias the Connect2id server must receive the HTTP request with an "Issuer" header set to the issuer URL.

Example HTTP request:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded


The URL in the "Issuer" header value must match the configured alias exactly. The "Issuer" header can also be explicitly set to the main issuer configured in op.issuer.

If the "Issuer" header doesn't match the 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:"

Issuer header security

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

Support for issuer aliases in the multi-tenant server

Issuer aliases are supported in the regular as well as the multi-tenant Connect2id server editions.

Use separate tenants for proper issuer isolation

Note, the use of issuer aliases doesn't isolate the OAuth 2.0 requests, such as those for client registration or authorisation, or the underlying server data. For proper issuer isolation use separate tenants.