Key store

1. Overview

This web API allows inspection of the current Connect2id server keys, without revealing private and secret key material. In dynamic key store mode, it also supports online rotation and revocation of the server keys.

Access to the web API is protected by means of a long-lived token. The token must be passed with each HTTP request in the Authorization header:

Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

The standard public JWK set endpoint provides access to a subset of the current server keys that is intended for OpenID Connect and OAuth 2.0 client applications.

2. Web API overview

Resources
/key-store/rest/v1/{ctx} [GET] /key-store/rest/v1/{ctx}/generate [POST] /key-store/rest/v1/{ctx}/rotate [POST] /key-store/rest/v1/{ctx}/{kid} [DELETE] /key-store/rest/v1/{ctx}/history [GET]
Representations	Errors
JWK set Historic JWK set JWK	400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

3. Resources

3.1 /key-store/rest/v1/{ctx}

Resource to inspect the server keys for a context.

3.1.1 GET

Inspects the current JSON Web Key (JWK) set for the specified context.

Path parameters:

ctx {“op”|“federation”} The key context: op for the OpenID provider / OAuth 2.0 authorisation server context, federation for OpenID Federation 1.0.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Query parameters:

[ skip_cache = false ] {true|false} When true the JWK set is retrieved directly from the key store, skipping the configured local in-memory cache.
[ pkcs11_only = false] {true|false} When true only PKCS#11 keys will be included in the JWK set.

Success:

Code: 200
Content-Type: application/json
Body: {object} The current JWK set.

Errors:

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

Example request to get the current JWK set for the OpenID provider / OAuth 2.0 authorisation server context:

GET /key-store/rest/v1/op HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example success response with the current JWK set:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "keys" : [ { "kty" : "RSA", ... } ]
}

3.2 /key-store/rest/v1/{ctx}/generate

Resource to generate a new JWK set for a context, with the option to precede the generation with a revocation and removal of all active keys as compromised.

3.2.1 POST

Generates a new JWK set for the specified context.

The key context must be empty, which is the case for Connect2id deployments configured to skip the automatic generation of the server keys on startup.

This request can be used with the optional revoke_all_active_as_compromised parameter to revoke and remove all active keys in the current JWK set. After that a new JWK set will be generated in its place.

If the request is successful the change is recorded in the history.

Path parameters:

ctx {“op”|“federation”} The key context: op for the OpenID provider / OAuth 2.0 authorisation server context, federation for OpenID Federation 1.0.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to application/x-www-form-urlencoded.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Form parameters:

[ rsa ] {2048|3072|4096} The bit size of the new RSA key(s) to generate. If omitted the default size applies.
[ no_eddsa=false ] {true|false} When true skips the generation of signing EdDSA keys.
[ revoke_all_active_as_compromised=false ] {true|false} When true all active keys in the current JWK will be marked as revoked with reason compromised, then current JWK will be emptied from all keys.

Success:

Code: 200
Content-Type: application/json
Body: {object} The new generated rotating keys, as a JWK set.

Errors:

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

Example request to immediately revoke and remove the current JWK set for the OpenID provider / OAuth 2.0 authorisation server context and then generate a new JWK set in its place:

POST /key-store/rest/v1/op/generate HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/x-www-form-urlencoded

revoke_all_active_as_compromised=true

Example success response with the new generated keys:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "keys" : [ { "kty" : "RSA", ... } ]
}

3.3 /key-store/rest/v1/{ctx}/rotate

Resource to rotate the applicable server keys for a context.

3.3.1 POST

Rotates the applicable keys in the current JWK set for the specified context. The old keys will remain in the current JWK set, marked as revoked with reason superseded and will no longer be used by the server.

If the request is successful the change is recorded in the history.

Note that the uptake of the new server keys across a Connect2id server cluster may be delayed, depending on the configured local caching.

Path parameters:

ctx {“op”|“federation”} The key context: op for the OpenID provider / OAuth 2.0 authorisation server context, federation for OpenID Federation 1.0.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to application/x-www-form-urlencoded.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Form parameters:

[ rsa ] {2048|3072|4096} The bit size of the new RSA key(s) to generate. If omitted the default size applies.
[ no_eddsa=false ] {true|false} When true skips the generation of signing EdDSA keys.

Success:

Code: 200
Content-Type: application/json
Body: {object} The new generated rotating keys, as a JWK set.

Errors:

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

Example request to rotate the applicable keys in the current JWK set for the OpenID provider / OAuth 2.0 authorisation server context:

POST /key-store/rest/v1/op/rotate HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/x-www-form-urlencoded

Example success response containing the new generated rotating keys:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "keys" : [ { "kty" : "RSA", ... } ]
}

3.4 /key-store/rest/v1/{ctx}/{kid}

Resource to remove a revoked server key for a context.

3.4.1 DELETE

Removes the key with the specified identifier (kid) from the current JWK set for the specified context.

The key must be in a revoked (superseded) state, which occurs after a key is
rotated. Make sure superseded keys are not removed until all JWTs signed with it have expired, otherwise clients may be unable to validate the tokens.

If the request is successful the change is recorded in the history.

Path parameters:

ctx {“op”|“federation”} The key context: op for the OpenID provider / OAuth 2.0 authorisation server context, federation for OpenID Federation 1.0.
kid {string} The kid (key identifier) of the JWK to remove.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Success:

Code: 204

Errors:

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

Example request to remove a superseded key from the current JWK set for the OpenID provider / OAuth 2.0 authorisation server context:

DELETE /key-store/rest/v1/op/ogJz HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/x-www-form-urlencoded

Example response for a successful JWK removal:

HTTP/1.1 204 No Content

Example error response:

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

{
  "error"             : "invalid_request",
  "error_description" : "Bad request: JWK must be in revoked state"
}

3.5 /key-store/rest/v1/{ctx}/history

Resource to retrieve the server key history for a context.

3.5.1 GET

Retrieves the JWK set history for the specified context.

Path parameters:

ctx {“op”|“federation”} The key context: op for the OpenID provider / OAuth 2.0 authorisation server context, federation for OpenID Federation 1.0.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Success:

Code: 200
Content-Type: application/json
Body: {array} A JSON array containing the historic JWK sets for the context, empty array if none.

Errors:

400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error

Example request to get the JWK set history for the OpenID provider / OAuth 2.0 authorisation server context:

GET /key-store/rest/v1/op HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response with a history of two JWK set changes, the ts (timestamp) indicates the time when the recorded JWK set became active (current).

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "keys" : [ { "kty" : "RSA", ... } ], 
    "ts"   : 1735503420
  },
  {
    "keys" : [ { "kty" : "RSA", ... } ], 
    "ts"   : 1735217195
  }
]

4. Representations

4.1 JWK set

JSON Web Key (JWK) set, as specified in RFC 7517, section 5.

4.2 Historic JWK set

JWK set, as specified above, with the following custom top-level JSON object member:

ts {number} The time when JWK set became active (current), after a rotation or another modification event, as number of seconds since the Unix epoch (1970-01-01T0:0:0Z) as measured in UTC until the date/time.

4.3 JWK

JSON Web Key (JWK), as specified in RFC 7517. The key-type specific parameters, such as the parameters for RSA keys, are specified in RFC 7518, section 6 and in RFC 8037, section 2.

The JWKs returned from the key store web API include the following additional JSON object members:

tpr {string} The BASE64URL encoded SHA-256 thumbprint of the JWK, as specified in RFC 7638.
iat {number} The JWK generation time, as number of seconds since the Unix epoch (1970-01-01T0:0:0Z) as measured in UTC until the date/time.
[ revoked ] {object} For a JWK that was revoked:
- revoked_at {number} The JWK revocation time, as number of seconds since the Unix epoch (1970-01-01T0:0:0Z) as measured in UTC until the date/time.
- reason {“superseded”|“compromised”} The revocation reason.

Asymmetric JWKs (key types RSA, EC and OKP are represented in their public form, with all private parameters excluded.

Secret JWKs (key type oct) have their secret parameters masked with zeros.

Example public JWK:

{
  "kty" : "EC",
  "crv" : "P-256",
  "use" : "sig",
  "kid" : "6Jse",
  "x"   : "4Jj78MyLH72EkkZV2Ni3S86Cc4M7xXzz4ZEMq0nP9BU",
  "y"   : "RJWY1J8mgOnhd9TBGXyd5fo2dC5h4lbVwblIHF4tLlM",
  "tpr" : "0t65BojG6Di4IvnZvZTPPIuk_Gywc2aJ0TqzsxXxFW4",
  "iat" : 1735217194
}

Example public JWK that was replaced with another key after a rotation:

{
  "kty"     : "EC",
  "crv"     : "P-256",
  "use"     : "sig",
  "kid"     : "6Jse",
  "x"       : "4Jj78MyLH72EkkZV2Ni3S86Cc4M7xXzz4ZEMq0nP9BU",
  "y"       : "RJWY1J8mgOnhd9TBGXyd5fo2dC5h4lbVwblIHF4tLlM",
  "tpr"     : "0t65BojG6Di4IvnZvZTPPIuk_Gywc2aJ0TqzsxXxFW4",
  "iat"     : 1735217194,
  "revoked" : {
    "reason"     : "superseded",
    "revoked_at" : 1735506574 
  }
}

Example masked secret JWK:

{
  "kty" : "oct",
  "use" : "enc",
  "kid" : "subject-encrypt",
  "k"   : "000000000000000000,
  "tpr" : "8dUcgwrF_yProeyyBTOVXSRnxCkcvLuQYk7eyELn1wY",
  "iat" : 1735217194
}

5. Errors

400 Bad Request

Invalid or malformed request.

Example response indicating key modifications, such as rotation, are disabled due to key store being configured with a static JWK set:

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

{
  "error"             : "invalid_request",
  "error_description" : "Bad request: The OP context is configured with a static and / or PKCS#11 JWK set, modifications are disabled"
}

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"
}

403 Forbidden

Indicates the web API is disabled.

Example:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error"             : "web_api_disabled",
  "error_description" : "Forbidden: Web API disabled"
}

404 Not Found

The requested resource doesn’t exist.

Example response indicating no JWK set was found for given context:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error"             : "not_found",
  "error_description" : "Context has no JWK set"
}

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