Skip to content
Connect2id

Security Token Service (STS) API

1. Overview

This Security Token Service (STS) web API issues tokens for purposes such as federated login and cross-device channel authentication in CIBA. The tokens are minted according to strict, secure templates.

Federated login

The STS supports issue of JWTs for use in federated logins, where an IdP built with the Connect2id server acts as an OAuth 2.0 client / OpenID relying party to upstream providers. The JWT signatures are verified with the server’s public JWK set.

Available templates:

CIBA

The STS supports issue of tokens to authenticate the channel between the consumption and authentication device in a CIBA flow.

Available template:

Access

Access to the STS API is protected by means of a long-lived token specific to the issue request: JAR, private_key_jwt, or login_hint_token.

The token must be passed with each HTTP request in the Authorization header:

Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

The STS API can be configured to not require a token authorisation to issue a login_hint_token, and instead require only a valid session ID of the native IdP app to authorise the mint.

More information can be found in the STS configuration reference.

2. Web API overview

Resources
Representations Errors

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 specific to the issue request: JAR, private_key_jwt, or login_hint_token. If direct issue of login hint tokens is configured this header is not required.

  • Content-Type Must be 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:

Success:

  • Code: 200

  • Content-Type: application/jwt for a JWT, text/plain for an opaque token

  • Body: {string} The token.

Errors:

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
}

4.3 login_hint_token issue request

Request to issue a login_hint_token for a CIBA request. Since v18.0.

JSON object members:

  • template {string} Must be login_hint_token.

  • sub_sid {string} The subject session ID of the native IdP app.

  • expires_in {number} The token lifetime. Must be greater than or equal to 60 seconds.

  • [ data ] {object} Optional data, as a JSON object.

Example login_hint_token issue request:

{
  "template"   : "login_hint_token",
  "sub_sid"    : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
  "expires_in" : 600,
  "data"       : { "purpose" : "payment_confirmation" } 
}

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