Security Token Service (STS) API

1. Overview

This Security Token Service (STS) web API enables client applications to obtain JWTs that are signed by the Connect2id server and whose signatures can be verified using the server's public JWK set.

Currently the STS supports issue of JWTs to facilitate federated login scenarios, where an identity provider built with the Connect2id server also acts as an OAuth 2.0 client / OpenID relying party to upstream providers.

The JWTs are minted according to strict templates, to prevent mistakes in client application logic as well as the issue of tokens with arbitrary headers and payload.

Available JWT templates:

• JAR -- For signed authorisation requests (JAR), as specified in RFC 9101, also called request objects in OpenID Connect.

• private_key_jwt -- For JWT based client authentication at the token and other endpoints, using private key authentication.

Access to the STS 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

More information can be found in the STS configuration reference.

2. Web API overview

Resources
/sts/rest/v1/issuer [POST]
Representations	Errors
JAR issue request private_key_jwt issue request	400 Bad Request 401 Unauthorized 403 Forbidden 500 Internal Server Error

3. Resources

3.1 /sts/rest/v1/issuer

Resource to issue tokens. Since v15.4.

3.1.1 POST

Issues a new JWT according to the specified template and other parameters.

Header parameters:

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

• Content-Type Must be set to application/json.

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

Body:

• A JSON object representation of a JAR or private_key_jwt issue request.

Success:

• Code: 200

• Content-Type: application/jwt

• Body: {string} The JWT.

Errors:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 500 Internal Server Error

Example request to issue a JAR:

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

{
  "template"   : "JAR",
  "alg"        : "RS256",
  "aud"        : "https://op.example.com",
  "parameters" : {
      "response_type"         : "code",
      "client_id"             : "client-123",
      "redirect_uri"          : "https://rp.example.com/cb",
      "scope"                 : "openid",
      "state"                 : "Mu0niexo",
      "nonce"                 : "Baemie2F",
      "code_challenge"        : "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
      "code_challenge_method" : "S256"
  }
}

Example success response returning a signed JAR:

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

eyJraWQiOiJzMSIsInR5cCI6Im9hdXRoLWF1dGh6LXJlcStqd3QiLCJhbGciOiJSUzI1NiJ9.eyJhdW
QiOiJodHRwczovL29wLmV4YW1wbGUuY29tIiwic2NvcGUiOiJvcGVuaWQiLCJpc3MiOiJjbGllbnQtM
\TIzIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3JwLmV4YW1
wbGUuY29tL2NiIiwic3RhdGUiOiJNdTBuaWV4byIsImNvZGVfY2hhbGxlbmdlX21ldGhvZCI6IlMyNT
YiLCJub25jZSI6IkJhZW1pZTJGIiwiY2xpZW50X2lkIjoiY2xpZW50LTEyMyIsImNvZGVfY2hhbGxlb
mdlIjoiRTlNZWxob2EyT3d2RnJFTVRKZ3VDSGFvZUsxdDhVUldidUdKU3N0dy1jTSJ9.cOFChe20O4x
4oAvsBdNjWa1323Ouowo2y7wuAxMmRpwp-SSt09pNaQQz_Kt-Fzaacxn1PP85GhIi0Io-R781AutpKw
RbFboumWetw91UkVspN674plawt-dNTFcvRgJ_YLG5MPTIQ8DXjigoEbDy6tBP4XhIqeQPR6VQBlFuX
kBUVH0P4-AKa0dvEGKdu2XsfaGC-dUeLolqZrvOS4EuNNUfqNpsV5ylzoIYI3EVStFa7MyMlGav8fpn
eUd-NFMVZ7T7OEHmqRRZDqImyhoMHiISTu3_SVQoPUqQuI49Hjbb1mHqpRBMhTVsONG4jfpWIie5OIv
uiUk-vhJFT-gtYQ

4. Representations

4.1 JAR issue request

Request to issue a signed OAuth 2.0 JWT-secured Authorisation Request (JAR), as specified in RFC 9101, also called request object in OpenID Connect.

The parameters of the authorisation request to sign can be passed as a JSON object or serialised as a URI.

JSON object members:

• template {string} Must be JAR.

• alg {string} The JWS algorithm. Must be supported and the Connect2id server must have a key for it.

• aud {string} The JWT audience. Must be the OAuth 2.0 authorisation server / OpenID provider issuer URL.

• [ parameters ] {object} The authorisation request parameters, omitted when the request member is used. When specified must at minimum include the response_type and client_id parameters.

• [ request ] {string} A regular authorisation request to use, omitted when the parameters member is used. When specified the authorisation request must be represented serialised to a URI.

Example request passing the authorisation request parameters as a JSON object:

{
  "template"   : "JAR",
  "alg"        : "RS256",
  "aud"        : "https://op.example.com",
  "parameters" : {
      "response_type" : "code",
      "client_id"     : "client-123",
      "redirect_uri"  : "https://rp.example.com/cb",
      "scope"         : "openid",
      "state"         : "Mu0niexo"
  }
}

Example request passing the authorisation request parameters serialised to a plain URI request. This method is suitable when a library is used to construct the OAuth 2.0 authorisation / OpenID authentication request:

{
  "template" : "JAR",
  "alg"      : "RS256",
  "aud"      : "https://op.example.com",
  "request"  : "https://op.example.com/login?response_type%3Dcode%26client_id%3Dclient-123%26redirect_uri%3Dhttps%3A%2F%2Frp.example.com%2Fcb%26scope%3Dopenid%26state%3DMu0niexo"
  }
}

4.2 private_key_jwt issue request

Request to issue a private_key_jwt client authentication, as specified in section 9 of OpenID Connect.

JSON object members:

• template {string} Must be private_key_jwt.

• alg {string} The JWS algorithm. Must be supported and the Connect2id server must have a key for it.

• iss {string} The JWT issuer. Must be the client_id.

• aud {string} The JWT audience. Must be the OAuth 2.0 authorisation server / OpenID provider issuer URL.

• expires_in {number} Determines the JWT expiration time. Must be greater than or equal to 5 seconds.

Example private_key_jwt issue request:

{
  "template"   : "private_key_jwt",
  "alg"        : "RS256",
  "iss"        : "client-123",
  "aud"        : "https://op.example.com/token",
  "expires_in" : 60
}

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: The expires_in must be greater than or equal to 5 seconds"
}

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

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
Content-Type: application/json

{
  "error"             : "server_error",
  "error_description" : "Internal server error: Check the logs for details"
}