Skip to content
Connect2id

How to setup a multitenant Connect2id server

The multitenant edition of the Connect2id server can host multiple OpenID Connect providers / OAuth 2.0 authorisation servers as securely isolated tenants with their own issuer URI, configurations and data.

Tenant registration

Each tenant is identified by a unique tenant ID (tid) and is created with its configuration by means of the tenants web API.

The tid naming rules are those for internet host names, so the tid can be used as a DNS label, e.g.

https://[tid].example.com

Example tenant registration request:

POST /tenants/rest/v1/ HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "tid"   : "t123",
  "props" : { "op.issuer"         : "https://t1.example.com",
              "jose.jwkSet"       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
              "op.authz.endpoint" : "https://t1.example.com/login",
              "..."               : "..." }
}

Individual tenants can be decorated with attributes, temporarily disabled and of course deleted.

Reverse proxy configuration

Each HTTP request to the multitenant Connect2id server must include a special header that identifies the tenant. This can be either the tid or the configured issuer URI.

Identifying the tenant by its tid in a Tenant-ID header:

POST /authz-sessions/rest/v3/ HTTP/1.1
Host: c2id.com
Tenant-ID: t1
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "query" : "response_type=code&scope=openid%2020email&client_id=s6BhdR&state=af0ifjsldkj&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb"
}

Identifying the tenant by its issuer URI in a Issuer header:

POST /authz-sessions/rest/v3/ HTTP/1.1
Host: c2id.com
Issuer: https://t1.example.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "query" : "response_type=code&scope=openid%2020email&client_id=s6BhdR&state=af0ifjsldkj&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb"
}

The Tenant-ID header is the recommended method because it allows the issuer URI to be changed without a reconfiguration of the reverse proxy.

In your reverse HTTP proxy configure a pass block for each tenant and set the appropriate Tenant-ID or Issuer header there.

With nginx, assuming the Connect2id server is at http://192.168.0.1:8080/, the blocks could look like:

server {
    server_name t1.example.com;
    location / {
        proxy_pass http://192.168.0.1:8080/;
        proxy_set_header Tenant-ID "t1";
        proxy_set_header Issuer "";
    }
}

server {
    server_name t2.example.com;
    location / {
        proxy_pass http://192.168.0.1:8080/;
        proxy_set_header Tenant-ID "t2";
        proxy_set_header Issuer "";
    }
}

If there are many tenants, or tenants are going to be dynamically added or removed, the proxy can be configured to compose the Tenant-ID dynamically, by extracting the tid from the subdomain. With this configuration there is no need to define a pass block for each tenant. Note that HTTP requests for an invalid tenant will produce an HTTP 500 error with “Invalid tenant ID” message at the Connect2id server.

server {
    server_name ~^(?<subdomain>.*)\.example\.com$;
    proxy_set_header Tenant-ID $subdomain;
    proxy_set_header Issuer "";
}

Important: The tenant identification header that is not used, for example Issuer when Tenant-ID is used, must be cleared (deleted) by the reverse proxy, to prevent HTTP clients from setting it.

Note, the above configuration examples don’t include any TLS termination settings. For mTLS check the separate guide.

DNS configuration

Make sure the issuer URI for each tenant resolves in the DNS to the reverse proxy host.

A tenant can choose to create a DNS alias record using an arbitrary name that points to their subdomain managed by the Connect2id server reverse proxy.

myidp.com   ALIAS   t1.example.com

In that case the reverse proxy needs to be provisioned with a valid server TLS certificate for the DNS alias record (myidp.com).

Alternatively, the tenant can host their own reverse proxy with server TLS termination and certificate, and pass requests (always with TLS!) to the Connect2id server reverse proxy.

Easing anticipated migration to multi-tenant edition with DynamoDB

If you are deploying a new single-tenant Connect2id server with a DynamoDB backend and anticipate an eventual migration to the multi-tenant edition, configure the database connection with these additional properties:

  • dynamodb.applyRangeKey – set the optional DynamoDB range (sort) key name to tid.

  • dynamodb.rangeKeyValue – set the key value to the tenant ID that will be given to the hosted OpenID provider / OAuth 2.0 authorisation server.

Example:

dynamodb.applyRangeKey=tid
dynamodb.rangeKeyValue=t123