Tenants registry

1. Overview

This web API is available on the multitenant edition of the Connect2id server. It enables registration of OpenID Connect providers / OAuth 2.0 authorisation servers as isolated tenants with their own issuer URL and configuration.

2. Web API overview

Resources
/tenants/rest/v1 [POST] [GET] /tenants/rest/v1/{tid} [GET] [DELETE] /tenants/rest/v1/{tid}/props [GET] [PUT] /tenants/rest/v1/{tid}/enabled [GET] [PUT] /tenants/rest/v1/{tid}/metadata [GET] [PUT] /tenants/rest/v1/count [GET]
Representations	Errors
Tenant Configuration properties	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

3. Resources

3.1 /tenants/rest/v1

Use this resource to create or retrieve tenants.

3.1.1 POST

Creates a new tenant.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to application/json.

Body:

A JSON object representation of the tenant.

Success:

Code: 201

Errors:

400 Bad Request
401 Unauthorized
500 Internal Server Error

Example request to register a new tenant with ID t123:

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

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

Example response indicating successful creation:

HTTP/1.1 201 Created

3.1.2 GET

Retrieves all tenants in a JSON array.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON array representing the individual tenants, empty array if none were found.

Errors:

401 Unauthorized
500 Internal Server Error

3.2 /tenants/rest/v1/{tid}

Use this resource to retrieve or delete an individual tenant.

3.2.1 GET

Retrieves a tenant.

Path parameters:

tid {string} The tenant identifier.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Success:

Code: 200
Content-Type: application/json
Body: {object} The tenant.

Errors:

404 Not Found
500 Internal Server Error

Example request to retrieve the tenant with ID t123:

GET /tenants/rest/v1/t123 HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

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

3.2.2 DELETE

Deletes a tenant.

Path parameters:

tid {string} The tenant identifier.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Success:

Code: 204

Errors:

401 Unauthorized
500 Internal Server Error

Example request to delete the tenant with ID t123:

DELETE /tenants/rest/v1/t123 HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response indicating successful deletion:

HTTP/1.1 204 No Content

3.3 /tenants/rest/v1/{tid}/props

Use this resource to retrieve or update a tenant’s configuration properties.

3.3.1 GET

Retrieves a tenant’s configuration properties.

Path parameters:

tid {string} The tenant identifier.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Success:

Code: 200
Content-Type: application/json
Body: {object} The tenant configuration properties.

Errors:

401 Unauthorized
404 Not Found
500 Internal Server Error

Example request to retrieve the configuration properties of tenant with ID t123:

GET /tenants/rest/v1/t123/props HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "op.issuer"         : "https://t123.c2id.com",
  "jose.jwkSet"       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
  "op.authz.endpoint" : "https://t123.c2id.com/login",
  "..."               : "..."
}

3.3.2 PUT

Updates a tenant’s configuration properties.

Path parameters:

tid {string} The tenant identifier.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Body:

A JSON object representation of the tenant configuration properties.

Success:

Code: 204

Errors:

400 Bad Request
401 Unauthorized
404 Not Found
500 Internal Server Error

Example request to update the configuration properties of tenant with ID t123:

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

{
  "op.issuer"         : "https://t123.c2id.com",
  "jose.jwkSet"       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
  "op.authz.endpoint" : "https://t123.c2id.com/login",
  "..."               : "..."
}

3.4 /tenants/rest/v1/{tid}/enabled

Use this resource to retrieve or set a tenant’s enabled status.

3.4.1 GET

Retrieves a tenant’s enabled status.

Path parameters:

tid {string} The tenant identifier.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Success:

Code: 200
Content-Type: text/plain
Body: {true|false} The tenant’s enabled status.

Errors:

401 Unauthorized
404 Not Found
500 Internal Server Error

Example request to retrieve the configuration properties of tenant with ID t123:

GET /tenants/rest/v1/t123/enabled HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: plain/text
Cache-Control: no-store
Pragma: no-cache

true

3.4.2 PUT

Sets a tenant’s enabled status.

Path parameters:

tid {string} The tenant identifier.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Body:

true to enable the tenant, false to disable it.

Success:

Code: 204

Errors:

400 Bad Request
401 Unauthorized
404 Not Found
500 Internal Server Error

Example request to disable the tenant with ID t123:

PUT /tenants/rest/v1/t123/enabled HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: plain/text

false

3.5 /tenants/rest/v1/{tid}/metadata

Use this resource to retrieve or update a tenant’s optional metadata.

3.5.1 GET

Retrieves a tenant’s optional metadata.

Path parameters:

tid {string} The tenant identifier.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Success:

Code: 200
Content-Type: application/json
Body: {object} The tenant metadata, empty object if none.

Errors:

401 Unauthorized
404 Not Found
500 Internal Server Error

Example request to retrieve the metadata of tenant with ID t123:

GET /tenants/rest/v1/t123/metadata HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "customer_id" : "13",
  "contact"     : "admin@example.org",
  "created"     : "2018-06-24"
}

3.5.2 PUT

Updates a tenant’s optional metadata.

Path parameters:

tid {string} The tenant identifier.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Body:

A JSON object representation of the tenant metadata, empty object if none.

Success:

Code: 204

Errors:

400 Bad Request
401 Unauthorized
404 Not Found
500 Internal Server Error

Example request to update the metadata of tenant with ID t123:

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

{
  "customer_id" : "13",
  "contact"     : "admin@example.org",
  "created"     : "2018-06-24"
}

3.6 /tenants/rest/v1/count

This resource keeps count of the tenants.

3.6.1 GET

Returns the current total tenant count.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.

Success:

Code: 200
Content-Type: text/plain
Body: {integer} The total tenant count, zero if none.

Errors:

401 Unauthorized
500 Internal Server Error

Example request to retrieve the total tenant count:

GET /tenants/rest/v1/count HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response indicating 10 registered tenants:

HTTP/1.1 200 OK
Content-Type: text/plain

10

4. Representations

4.1 Tenant

OpenID Connect provider / OAuth 2.0 Authorisation Server tenant.

JSON object members:

tid {string} The tenant identifier. Legal characters are ASCII letters (case insensitive), digits 0 through 9, and the hyphen-minus character (-). Underscore (_) is also allowed but not recommended. This syntax for tenant identifiers allows their use as internet host names and DNS labels according to RFC 1123.
props {object} The tenant specific configuration properties.
enabled {true|false} If true the tenant is enabled and its OpenID Connect provider / OAuth 2.0 Authorisation server will accept requests. Defaults to true when creating a new tenant.
metadata {object} Optional arbitrary metadata for the tenant, omitted if none.

4.2 Configuration properties

Tenant configuration, as Java property name / value pairs contained in a JSON object.

All property values must be put in strings, including values that are integers, booleans and JSON objects. Properties that are not recognised will be stored but ignored.

The following tenant specific configuration properties are supported in Connect2id server 7.9+ (all that are required must be set):

All core configuration settings (op.*), save for those for back-channel logout and mutual TLS. The issuer URL (op.issuer) must be unique across all registered tenants.
The Connect2id server JWK set (jose.jwkSet). HSM (PKCS#11) based private keys are not supported in multitenant mode.
All session store settings (sessionStore.*), save for those in the internal section.
All authorisation store settings (authzStore.*).
The optional scope values to OpenID claims map (op.claims.map.*).
The optional claim names compression dictionary (op.claims.compressionDictionary.*).

Example configuration properties:

{
  "op.issuer"                         : "https://t123.c2id.com",
  "jose.jwkSet"                       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
  "op.authz.endpoint"                 : "https://t123.c2id.com/login",
  "op.policy"                         : "https://t123.c2id.com/policy",
  "op.tos"                            : "https://t123.c2id.com/terms-of-service",
  "op.serviceDocs"                    : "https://t123.c2id.com/service-docs",
  "sessionStore.apiAccessTokenSHA256" : "cca68b8b82bcf0b96cb826199429e50cd9...",
  "sessionStore.maxLifetime"          : "20160",
  "sessionStore.authLifetime"         : "10080",
  "sessionStore.maxIdleTime"          : "1440",
  "sessionStore.quotaPerSubject"      : "5",
  "..."                               : "..."
}

5. Errors

400 Bad Request

Invalid or malformed request.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Bad request: Invalid JSON: Unexpected token foo at position 3."
}

401 Unauthorized

The request was denied due to an invalid or missing bearer access token.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "error"             : "missing_token",
  "error_description" : "Unauthorized: Missing Bearer access token"
}

404 Not Found

The requested resource doesn’t exist.

Example:

HTTP/1.1 404 Not Found

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error