Authorisation session

1. Overview

Use the authorisation session API to attach a login UI and one or more user authentication factors to the Connect2id server.

The login / consent UI can be implemented in any language and framework, and hosted separately from the Connect2id server, utilising an HA proxy and CDN if needed.
Plug one or more authentication methods, such as password, OTP, X.512 certificates or biometrics. The user credentials are not shared with the Connect2id server, which is good for security.
Plug policies for the token scopes and OpenID claims. Consent can be explicit, implicit, or some combination of both.
Zero service downtime for updates and changes of the login / consent UI, authentication methods and authorisation logic.

The frontend’s interaction with the authorisation session API can be compared to the MVC pattern. The frontend passes each received OpenID authentication request to the Connect2id server for processing, and then, if prompted by the server, interacts with the end-user to:

(Re)authenticate the end-user, if their browser / device has no valid session with the Connect2id server, or the authentication strength (ACR) needs to be stepped up. In order to authenticate the end-user, the frontend needs to collect the user’s credentials and submit them to the appropriate service or database for verification, then, on success, pass the resolved user ID to the Connect2id server.
Get the end-user’s consent for the requested OAuth 2.0 scope values and OpenID claims, if the Connect2id server has no previous consent stored on record. The frontend can get the consent from the end-user, e.g. by presenting a form (explicit consent), or call upon some policy for that.

When the user’s identity and consent are established, the Connect2id server will generate the appropriate OpenID response, for the frontend to relay back to the requesting client.

Here is a summary of the interactions between the frontend (login page) and the Connect2id during an authorisation session, and how they are triggered:

Interaction	Authentication	Consent
Purpose:	Establish the user identity	Obtain / set consent
Server → UI:	Authentication prompt	Consent prompt
UI → Server:	Subject (end-user) identity	Consented scope + claims
Skipped if:	User has a valid existing session (cookie) with the server	Previous consent for the requested scope and claims (unless configured otherwise)
Success:	Proceed to consent	Return final response to client

The authorisation session API also enables programmatic setting of the access token encoding, lifetime and other options.

Access to the authorisation session 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

Additional details are found in the authorisation endpoint configuration reference.

For help with implementing a login page check our guide.

2. Web API overview

Resources
/authz-sessions/rest/v3/ [POST] /authz-sessions/rest/v3/{sid} [PUT] [DELETE] [GET] /authz-sessions/rest/v3/{sid}/data [PUT] [GET]
Representations	Errors
Authorisation session start request Authentication prompt Subject session Consent prompt Consent Final response Authorisation session Authorisation session data Authorisation session identifier Client (relying party) details Request parameters Non-redirecting error	400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

3. Resources

3.1 /authz-sessions/rest/v3/

3.1.1 POST

Starts a new authorisation session with the Connect2id server.

The frontend (login page) at the OAuth 2.0 authorisation endpoint starts a new authorisation session upon receiving a new request from a client application. The request can be for OpenID authentication, or for a plain OAuth 2.0 authorisation (if an ID token isn’t needed).

The POST produces one of the following JSON objects:

Authentication prompt – Prompts the frontend to authenticate the end-user. Indicated by a JSON object with "type":"auth".
Consent prompt – Prompts the frontend to obtain the end-user’s consent for the specified scope and claims. Indicated by a JSON object with "type":"consent".
Final response – Prompts the frontend to redirect the user agent (browser) back to the client application with the specified OAuth 2.0 authorisation / OpenID authentication response. Indicated by a JSON object with "type":"response".
Non-redirecting error – Notifies the frontend that the submitted OAuth 2.0 authorisation / OpenID authentication request is faulty. The user agent (browser) cannot or must not be redirected back to the client application. Indicated by a JSON object with "type":"error".

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 an authorisation start request.

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON object representation of an authentication prompt, a consent prompt, a final response or a non-redirecting error. The JSON objects can be differentiated by their type value. For a prompt, in order to complete the interaction, the frontend must use the returned authorisation session identifier (sid).

Errors:

400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error

Example POST request to start an authorisation session with the Connect2id server, specifying the query string of the received request; the subject (end-user) session identifier (SID) is omitted, indicating a browser session cookie has not been found:

POST /authz-sessions/rest/v3/ HTTP/1.1
Host: c2id.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"
}

Example start request, which also indicates that a session cookie has been found (sub_sid):

POST /authz-sessions/rest/v3/ HTTP/1.1
Host: c2id.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",
  "sub_sid" : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw"
}

Example response prompting the frontend to authenticate the present end-user. The frontend may do this by obtaining the user’s credentials and validating them with an MS-AD/LDAP directory, for instance. In the next request to the Connect2id server (submitting the resolved user ID) the frontend must use the specified authorisation session identifier (sid).

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

{
  "type"           : "auth",
  "sid"            : "cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w",
  "display"        : "popup",
  "select_account" : false
}

Example final response, showing the Connect2id server has a valid session for the end-user as well as a valid consent record to login into the requesting client application; there’s no need for the frontend to interact with the end-user, and the encoded OpenID authentication response can be returned to the client application straight away:

HTTP/1.1 OK
Content-Type: application/json

{
  "type"       : "response",
  "mode"       : "query",
  "parameters" : { "uri" : "https://example.client.com/cb?code=5rZ_KxqZ&state=Nygv4CLQ" }
}

3.2 /authz-sessions/rest/v3/{sid}

3.2.1 PUT

Updates an authorisation session with the required details, which can be the subject identity details, or the consent details. The Connect2id server will utilise these details to continue / finish processing of the OAuth 2.0 authorisation / OpenID authentication request.

The PUT produces one of the following JSON objects:

Consent prompt – Prompts the frontend to obtain the end-user’s consent for the specified scope and claims. Indicated by a JSON object with "type":"consent".
Final response – Prompts the frontend to redirect the user agent (browser) back to the client application with the specified OAuth 2.0 authorisation / OpenID authentication response. Indicated by a JSON object with "type":"response".

Path parameters:

sid {string} The authorisation session identifier (SID).

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 one of the following:
- The details for the subject identity and session, in response to a previous POST request returning an authentication prompt;
- The details of the consent, in response to a previous POST or PUT request returning a consent prompt.

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON object representation of a consent prompt, a final response or a non-redirecting error. The JSON objects can be differentiated by their type value.

Errors:

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

Example submission of the end-user’s identity (user ID), after the frontend has (re)authenticated her:

PUT /authz-sessions/rest/v3/cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub" : "alice"
}

Example submission of the end-user’s consent to login into the client application with an ID token (indicated by openid scope) and permit access to her email data (indicated by email scope, which expands to the email and email_verified claims):

PUT /authz-sessions/rest/v3/cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "scope"  : [ "openid", "email" ],
  "claims" : [ "email", "email_verified" ]
}

Example response prompting the frontend to obtain the end-user’s consent to log into “Example App” and authorise access to her email data.

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

{
  "type"        : "consent",
  "sid"         : "cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w",
  "display"     : "popup",
  "sub_session" : { "sid"           : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
                    "sub"           : "alice",
                    "auth_time"     : 12345678,
                    "creation_time" : 12345678,
                    "acr"           : "http://loa.c2id.com/high",
                    "amr"           : [ "mfa", "pwd", "otp" ],
                    "max_life"      : 20160,
                    "auth_life"     : 1440,
                    "max_idle"      : 15 },
  "client"      : { "client_id"        : "8cc2043",
                    "client_type"      : "confidential",
                    "application_type" : "web",
                    "name"             : "Example App",
                    "uri"              : "http://app.example.com" },
  "scope"       : { "new"       : [ "openid", "email" ],
                    "consented" : [ ] },
  "claims"      : { "new"       : { "essential" : [ "email", "email_verified" ],
                                    "voluntary" : [ ] },
                    "consented" : { "essential" : [ ],
                                    "voluntary" : [ ] } }
}

Example final response, meaning the Connect2id server has collected all necessary details to complete the request:

HTTP/1.1 OK
Content-Type: application/json

{
  "type"       : "response",
  "mode"       : "query",
  "parameters" : { "uri" : "https://example.client.com/cb?code=5rZ_KxqZ&state=Nygv4CLQ" }
}

3.2.2 DELETE

Cancels an OAuth 2.0 authorisation / OpenID authentication request with an appropriate error code and message. This can be done during the authentication or consent step.

Deletes the underlying authorisation session.

Produces a response with an appropriate encoded OpenID Connect or OAuth 2.0 error error for the frontend to relay back to the client application. The default error is access_denied, to signal that the end-user has chosen to deny login to the client application. The optional error query parameter can be set to another standard OpenID Connect / OAuth 2.0 error code, for example, to signal an invalid_scope, or that the server is temporarily_unavailable.

Path parameters:

sid {string} The authorisation session identifier (SID).

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:

[ error = access_denied ] {access_denied | invalid_request | unauthorized_client | unsupported_response_type | invalid_scope | server_error | temporarily_unavailable | login_required | consent_required | interaction_required | account_selection_required | request_uri_not_supported | request_not_supported | invalid_request_uri | invalid_request_object} To signal the client that the authorisation has been canceled for other reason than the default access_denied OAuth 2.0 error.
[ error_description ] Specifies an error description other that the standard to return for the implied error code. Must not include characters outside the set %x20-21 / %x23-5B / %x5D-7E (see RFC 6749, section 5.2).
[ error_uri ] Specifies an optional URI for a human readable web page with additional information about the error. Must not include characters outside the set %x21 / %x23-5B / %x5D-7E (see RFC 6749, section 5.2).

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON object representation of a final response.

Errors:

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

Example request to deny login or authorisation:

DELETE /authz-sessions/rest/v3/Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0 HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response, with an encoded access_denied error appended to the redirection URI:

HTTP/1.1 OK
Content-Type: application/json

{
  "type"       : "response",
  "mode"       : "query",
  "parameters" : { "uri" : "https://example.client.com/cb?error=access_denied&state=Nygv4CLQ" }
}

3.2.3 GET

Returns the original request parameters used to start the specified authorisation session.

Path parameters:

sid {string} The authorisation session identifier (SID).

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: {object} A JSON object representation of the authorisation session.

Errors:

401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Example request:

GET /authz-sessions/rest/v3/cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response, listing key parameters of an OpenID authentication request that was used to create the authorisation session; the sub_sid member refers to the subject session of the end-user:

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

{
  "auth_req" : { "response_type" : "code id_token",
                 "client_id"     : "8cc2043",
                 "redirect_uri"  : "https://client.example.org/cb",
                 "scope"         : [ "openid", "email" ],
                 "state"         : "af0ifjsldkj",
                 "nonce"         : "8dfqxd90pa_",
                 "display"       : "popup",
                 "ui_locales"    : [ "es", "en" ] },
  "sub_sid"  : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw"
}

3.3 /authz-sessions/rest/v3/{sid}/data

3.3.1 PUT

Sets the optional data of an authorisation session.

Path parameters:

sid {string} The authorisation session identifier (SID).

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 one of the data, empty object ({}) if none.

Success:

Code: 204
Content-Type: application/json

Errors:

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

3.3.2 GET

Gets (directly) the optional data of an authorisation session.

Path parameters:

sid {string} The authorisation session identifier (SID).

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.

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON object representation of one of the data, empty object ({}) if none.

Errors:

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

4. Representations

4.1 Authorisation session start request

Specifies the OAuth 2.0 authorisation / OpenID authentication request received at the OAuth 2.0 authorisation endpoint (the login page) as well as the identifier of the subject (end-user) session (if any) with the Connect2id server.

JSON object members:

query {string} The raw (not decoded) URI query string received at the OAuth 2.0 authorisation endpoint.
[ sub_sid ] {string} The subject (end-user) session identifier (SID), saved in a browser cookie, omitted or null if none. The SID is used to retrieve the session of the present end-user and find out whether (re)authentication is required.
[ redirect_uri_template_param ] {string} Optional parameter to set the [param] in the redirect_uri of the processed authorisation request where the URI is a template. Applies to all authorisation requests, including JAR and PAR. Since v13.4.
[ data ] {object} Optional data to store in the authorisation session. May be used to store front-end state and other variables.

Example JSON object for an authorisation session start request, detailing the query string and the subject session identifier (SID) obtained from the browser cookie:

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

If no session cookie is found the subject session ID is omitted:

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

4.2 Authentication prompt

Prompts the frontend to (re)authenticate the present end-user. May specify required authentication methods (amr), strength (acr) and other parameters.

JSON object members:

type {string} Set to auth. Used to differentiate this object from a consent prompt, a final response and a non-redirecting error.
sid {string} The authorisation session identifier, to refer to the authorisation session in subsequent requests. Not to be confused with the subject (end-user) session identifier.
display {“page”|“popup”|“touch”|“wap”} The end-user display type.
[ ui_locales ] {string array} The end-user’s preferred UI locales, by order of preference, omitted if not specified.
[ required_sub ] {string} If set specifies the required subject (end-user) to authenticate, implied by a valid ID token hint (the expiration timestamp is disregarded) received from the client .
[ impersonated_sub] {string} If set indicates that this is an authentication prompt for an impersonated subject (end-user), as implied by an ID token hint submitted by the client.
[ login_hint ] {string} Optional hint about the identifier the end-user might use to log in, such as an email address. May also be used in cases when the IdP for the end-user was discovered based on their email address as login identifier. Acceptance and interpretation of this parameter is at the IdP’s discretion.
[ acr ] {object} The requested Authentication Context Class Reference (ACR), omitted if not specified: * [ essential ] {string array} The essential ACRs, ordered by preference, omitted if not specified. * [ voluntary ] {string array} The voluntary ACRs, ordered by preference, omitted if not specified.
select_account {true|false} If true the end-user should be presented with an account selection screen. This enables an end-user who has multiple accounts or sessions to select one.
create_account {true|false} If true the end-user should be presented with a sign-up screen. After successful registration the flow should continue as usual. Will never be set together with select_account. Since v12.10.
[ sub_session ] {object} The current subject (end-user) session, omitted if none is present. The sid parameter represents the session identifier (used for the session cookie).
[ client ] {object} Information about the requesting client. Typically this information is not required at this step and will be omitted unless the server is configured otherwise.
[ request ] {object} Selected parameters of the received OAuth 2.0 authorisation / OpenID authentication request.
[ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state and other variables.

Example prompt to authenticate an end-user for the first time:

{
  "type"           : "auth",
  "sid"            : "cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w",
  "display"        : "popup",
  "select_account" : false
}

Example authentication prompt where the client provided the alice@wonderland.net login hint:

{
  "type"           : "auth",
  "sid"            : "cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w",
  "display"        : "popup",
  "login_hint"     : "alice@wonderland.net",
  "select_account" : false
}

Example prompt to step up the authentication strength (ACR) for the current end-user session from http://loa.c2id.com/basic to http://loa.c2id.com/high:

{
  "type"           : "auth",
  "sid"            : "cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w",
  "display"        : "popup",
  "acr"            : { "essential" : [ "http://loa.c2id.com/high" ] },
  "select_account" : false,
  "sub_session"    : { "sid"           : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
                       "sub"           : "alice",
                       "auth_time"     : 12345678,
                       "acr"           : "http://loa.c2id.com/basic",
                       "amr"           : [ "pwd" ],
                       "creation_time" : 1234567,
                       "max_life"      : 20160,
                       "auth_life"     : 1440,
                       "max_idle"      : 15,
                       "data"          : { "name"  : "Alice Adams",
                                           "email" : "alice@wonderland.net" } }
}

4.3 Subject session

The subject (end-user) identity and session is specified in the session store API reference.

Example minimal JSON object where only the subject (user ID) is specified:

{
  "sub" : "alice"
}

Prompts the frontend to obtain the end-user’s consent for the requested OAuth 2.0 scope values and OpenID claims.

JSON object members:

type {string} Set to consent. Used to differentiate this object from an authentication prompt, a final response and a non-redirecting error.
sid {string} The authorisation session identifier, to refer to the authorisation session in subsequent requests. Not to be confused with the subject (end-user) session identifier.
display {“page”|“popup”|“touch”|“wap”} The end-user display type.
[ ui_locales ] {string array} The end-user’s preferred UI locales, by order of preference, omitted if not specified.
[ impersonated_sub] {string} If set indicates that this is a consent prompt for an impersonated subject (end-user), as implied by an ID token hint submitted by the client.
sub_session {object} The current subject (end-user) session. The sid parameter represents the session identifier, which must be used to set the session cookie for the present end-user.
client {object} Information about the requesting client.
scope {object} The requested OAuth 2.0 scope values, split into the following sets:
- new {string array} Requested scope values for which the Connect2id server has no previous end-user consent on record, empty array if none.
- consented {string array} Requested scope values for which the Connect2id server has previous end-user consent on record, empty array if none.
- other_consented {string array} Scope values that are not requested and for which the Connect2id server has previous end-user consent on record, empty array if none. Not included unless enabled
claims {object} The requested OpenID Connect claims. If Identity Assurance is enabled requested verified claims will be included and prefixed with verified:.
- new {object} Requested claims for which the Connect2id server has no previous end-user consent on record, split into two sets:
  - essential {string array} Those marked as essential, empty array if none.
  - voluntary {string array} Those marked as voluntary, empty array if none.
- consented {object} Requested claims for which the Connect2id server has prevous end-user consent on record, split into two sets:
  - essential {string array} Those marked as essential, empty array if none.
  - voluntary {string array} Those marked as voluntary, empty array if none.
- other_consented {string array} Claims that are not requested and for which the Connect2id server has previous end-user consent on record, empty array if none. Not included unless enabled.
- [ locales ] {string array} The requested claims locales as language tags, omitted if not specified.
- [ verification ] {object} If Identity Assurance is enabled the optional requested verification. If multiple verifications are requested they can be obtained by parsing the raw “claims” parameter.
  - [ id_token ] {object} The optional requested verification for claims returned in the ID token.
  - [ userinfo ] {object} The optional requested verification for claims returned at the UserInfo endpoint.
- [ purposes ] {object} Individual purposes for each requested claim, as claim name / purpose string pairs, omitted if not specified. To prevent injection attacks all special characters in a purpose string must be escaped before being shown in a user interface.
- [ raw_request ] {object} The raw “claims” parameter of the OpenID authentication request, omitted if not specified or inclusion of this field is disabled.
[ purpose ] {string} The transaction specific purpose request parameter, if Identity Assurance is enabled. To prevent injection attacks all special characters in a purpose string must be escaped before shown in a user interface.
[ request ] {object} Selected parameters of the received OAuth 2.0 authorisation / OpenID authentication request.
[ data ] {object} Optional data stored in the authorisation session. Can be used to store front-end state and other variables.

Example JSON object, with the minimum amount of fields defined:

{
  "type"        : "consent",
  "sid"         : "cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w",
  "display"     : "popup",
  "sub_session" : { "sid"           : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
                    "sub"           : "alice",
                    "auth_time"     : 12345678,
                    "creation_time" : 1234567,
                    "max_life"      : 20160,
                    "auth_life"     : 1440,
                    "max_idle"      : 15 },
  "client"      : { "client_id"        : "8cc2043",
                    "client_type"      : "confidential",
                    "application_type" : "web" },
  "scope"       : { "new"       : [ "openid" ],
                    "consented" : [ ] },
  "claims"      : { "new"       : { "essential" : [ ],
                                    "voluntary" : [ ] },
                    "consented" : { "essential" : [ ],
                                    "voluntary" : [ ] } }
}

Example consent prompt, with various fields defined:

{
  "type"        : "consent",
  "sid"         : "cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w",
  "display"     : "popup",
  "ui_locales"  : [ "es", "en" ],
  "sub_session" : { "sid"           : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
                    "sub"           : "alice",
                    "auth_time"     : 12345678,
                    "acr"           : "http://loa.c2id.com/high",
                    "amr"           : [ "mfa", "otp", "pwd" ],
                    "creation_time" : 1234567,
                    "max_life"      : 20160,
                    "auth_life"     : 1440,
                    "max_idle"      : 15,
                    "data"          : { "name"  : "Alice Adams",
                                        "email" : "alice@wonderland.net" } },
  "client"     : { "client_id"        : "8cc2043",
                   "client_type"      : "confidential",
                   "application_type" : "web",
                   "name"             : "My Web Store",
                   "name#es"          : "Mi tienda virtual",
                   "uri"              : "http://my-web-store.com",
                   "uri#es"           : "http://my-web-store.com/es",
                   "logo_uri"         : "http://my-web-store.com/logo.jpg",
                   "logo_uri#es"      : "http://my-web-store.com/es/logo.jpg",
                   "policy_uri"       : "http://my-web-store.com/privacy-policy.html",
                   "policy_uri#es"    : "http://my-web-store.com/es/privacy-policy.html",
                   "tos_uri"          : "http://my-web-store.com/tos.html",
                   "tos_uri#es"       : "http://my-web-store.com/es/tos.html",
                   "scope"            : [ "openid", "email" ] },
  "scope"      : { "new"       : [ "app:write" ],
                   "consented" : [ "openid", "profile", "email" ] },
  "claims"     : { "new"       : { "essential" : [ ],
                                   "voluntary" : [ ] },
                   "consented" : { "essential" : [ "name", "email" ],
                                   "voluntary" : [ "website", "birthdate", "phone_number" ] },
                   "locales"   : [ "es", "en" ] }
}

Specifies the consented OAuth 2.0 scope values and OpenID Connect claims. The Connect2id server will use the JSON object to construct an authorisation record with the required ID, access and refresh token parameters for the subject (end-user) and client.

JSON object members:

[ scope ] {string array} The consented OAuth 2.0 scope values. These may be a subset of the originally requested values, or include additional ones. The openid scope value must be included for a consented OpenID authentication request. An “*” (asterisk) in the string array indicates consent for all requested scope values. May be omitted or empty, for example for a Rich Authorisation Request (RAR).
[ audience ] {string array} Optional parameter specifying the resource server audience for the issued access token. Should typically include the client_id(s) of the resource(s), but any other type of identifier, such as URI, is also accepted. Identifier-based tokens with a specified audience can be introspected only by resource servers whose client_id is in the audience.
[ claims ] {string array} Optional array of names of consented OpenID claims. These can be a subset of the originally requested claims, or include additional ones.

Special keywords and prefixes:

* - An asterisk (“*“) in the string array indicates consent for all requested claims.

id_token: - For a non-requested claim, the “id_token:” prefix to its name will cause the claim to be delivered in the issued ID token instead of at the UserInfo endpoint (default location for all non-requested claims).

access_token: - For a non-requested claim, this prefix will cause the claim to be delivered in the issued access token. If the access token is self-contained (JWT) the claim will be added at the top-level. If the access token is identifier-based the claim will appear at the top-level in the token introspection response.

access_token:uip: - For a non-requested claim, this prefix will cause the claim to be merged into the top-level “uip” (optional preset UserInfo claims) JSON object claim of the access token.

access_token:dat: - For a non-requested claim, this prefix will cause the claim to be merged into the top-level “dat” (optional data) JSON object claim of the access token.

verified: - If Identity Assurance is enabled indicates a verified claim. Must be after any other prefixes.
[ claims_data ] {object} Optional data to be passed in the request to retrieve the consented OpenID claims from the configured source(s). The claims data will be included in a “cld” (claims data) field in the issued access token(s) and in the long-lived authorisations if the consent is persisted. If the claims data must be kept confidential from the client either an identifier access token encoding must be chosen or if a self-contained (JWT) access token is chosen it must be additionally encrypted. An AdvancedClaimsSource SPI implementation can retrieve the claims data JSON object by a call to the ClaimsSourceRequestContext.getClaimsData method.
[ preset_claims ] {object} Optional JSON object specifying additional preset OpenID claims to include in the ID token and / or the UserInfo response:
- [ id_token ] {object} Preset claims to include in the ID token, omitted or empty JSON object if none.
- [ userinfo ] {object} Preset claims to include in the UserInfo response, omitted or empty JSON object if none.
[ long_lived = true ] {true|false} Long-lived authorisation flag. If true indicates a long-lived (persisted) authorisation. If false the authorisation is transient (not remembered). Defaults to true.
[ impersonated_sub ] {string} Specifies a subject (end-user) to impersonate by means of the issued ID, access token and refresh token. May be used to enable privileged users to login into a client or access protected resources under a different identity. The actual authorised subject (the impersonator) will be indicated in the custom act.sub ID and JWT access token claim.
[ access_token ] {object} Optional access token settings, overriding the default configuration:
- [ lifetime = 0 ] {integer} The access token lifetime in seconds. If zero or omitted the default setting will apply.
- [ encoding = “SELF_CONTAINED” ] {“SELF_CONTAINED”|“IDENTIFIER”} The access token encoding. If SELF-CONTAINED the token authorisation is encoded in the access token, as a signed and optionally encrypted JSON Web Token (JWT). If IDENTIFIER the issued access token is a secure random identifier; the underlying token authorisation can be retrieved at the introspection endpoint. Defaults to SELF_CONTAINED.
- [ encrypt = false ] {true|false} Encryption of the self-contained (JWT) access token after signing, to make its payload confidential from the client. The token is encrypted with the current active AES key using the configured JWE algorithm and method. The resource server(s) must be provisioned with a copy of the AES key to decrypt the token. Defaults to false, unless the client is an OpenID relying party registered for pairwise subjects in which case the token will be encrypted. The encryption can be opted out from if the access token subject is set to pairwise.
- [ sub_type = “PUBLIC” ] {“PUBLIC”|“PAIRWISE”} The access token subject type. If PAIRWISE the access token with be issued with a pairwise subject identifier. This requires the audience to be set (if multiple audience values are set the first in the list will used to compute the pairwise identifier). Defaults to PUBLIC.
[ id_token ] {object} Optional ID token settings, overriding the default configuration:
- [ lifetime = 0 ] {integer} The ID token lifetime in seconds. When zero or omitted the default setting will apply.
- [ allow_refresh = false ] {true|false} Allows ID token refresh at the token endpoint provided the subject (end-user) session is still present (not closed or expired). Since v14.0.
[ refresh_token ] {object} Optional refresh token settings:
- [ issue = true ] {true|false} Enables / disables refresh token issue. If true a refresh token will be issued (the client must also be registered for the refresh token grant. If false no refresh token will be issued. Defaults to true if omitted. Note, the long_lived consent parameter controls the encoding of the refresh token.
- [ lifetime ] {integer} The refresh token lifetime in seconds. Zero means no lifetime limit. When omitted the default setting will apply. If a client tries to use a refresh past its lifetime the token endpoint of the Connect2id server will return an invalid_grant error. This is a signal to the client to repeat the authorisation request.
- [ max_idle = 0 ] {integer} The refresh token maximum idle time in seconds. Zero means no idle time. If a client tries to use a refresh token invalidated due to inactivity the token endpoint of the Connect2id server will return an invalid_grant error. This is a signal to the client to repeat the authorisation request. Since v15.0.
- [ rotate ] {true|false} If true the refresh token will be rotated at each use. Rotation does not reset the expiration of a refresh token with a lifetime. When omitted the default setting will apply. Since v14.0.
[ data ] {object} Optional additional information to be stored in the dat field of the authorisation record and included as dat claim in access tokens.

Example minimal consent for an OpenID authentication request, to issue an ID token:

{
  "scope" : [ "openid" ]
}

Example consent for the standard openid and email scope values and the OpenID Connect claims that they expand to:

{
  "scope"  : [ "openid", "email" ],
  "claims" : [ "email", "email_verified" ]
}

Example consent overriding some of the default access, ID and refresh token settings:

{
  "scope"         : [ "openid", "profile", "email" ],
  "claims"        : [ "email", "email_verified" ],
  "access_token"  : { "lifetime" : 600,
                      "encrypt"  : true },
  "id_token"      : { "lifetime" : 3600 },
  "refresh_token" : { "issue" : true }
}

Example consent supplying some of the ID token and UserInfo claims directly via the preset_claims parameter:

{
  "scope"         : [ "openid", "profile", "email", "app:admin" ],
  "claims"        : [ "name", "email", "email_verified" ],
  "preset_claims" : { "id_token" : { "login_ip"  : "185.7.248.1",
                                     "login_geo" : { "long" : "37.3956",
                                                     "lat"  : "-122.076" } },
                      "userinfo" : { "groups" : [ "admin", "audit" ] } }
}

4.6 Final response

The final OAuth 2.0 authorisation / OpenID authentication response to be relayed back to the client. Encodes the requested authorisation code, and / or token(s) on success, or error on failure.

All standard OAuth 2.0 response modes are supported:

Redirection to the redirect_uri:
- query – the response parameters are encoded as URI query parameters
- query.jwt – the response parameters are packaged into a JWT (JARM) that is then encoded as URI query parameter
- fragment – the response parameters are encoded into an URI fragment
- fragment.jwt – the response parameters are packaged into a JWT (JARM) that is then encoded as URI fragment
Form POST to the redirect_uri:
- form_post – the response parameters are POSTed in a form
- form_post.jwt – the response parameters are packaged into a JWT (JARM) that is then POSTed in a form

Custom response modes are supported by declaring them in the server configuration. After processing a request with a custom response mode, the Connect2id server will output a generic JSON object with the response parameters, which the frontend can then encode and relay according to the mode’s contract.

JSON object members:

type {string} Set to response. Used to differentiate this object from an authentication prompt, a consent prompt and a non-redirecting error.
mode {“query”|“query.jwt”|“fragment”|“fragment.jwt”|“form_post”|“form_post.jwt”|“…“} The response mode (implied or requested explicitly by the client).
parameters {object} The parameters to compose the response to the client, which vary for the redirection based, the form-POST based and custom response modes.
[ sub_sid ] {string} If set, indicates that a new subject (end-user) session was created by the Connect2id server. Use the provided session ID to set a session cookie for the present end-user.
[ sub_session ] {object} The current subject (end-user) session, omitted if none is present. The sid parameter represents the session identifier (used for the session cookie). Typically this information is not required at this step and will be omitted unless the server is configured otherwise.
[ client ] {object} Information about the requesting client. Typically this information is not required at this step and will be omitted unless the server is configured otherwise.
[ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state and other variables.

Example final response for the query response mode:

HTTP/1.1 OK
Content-Type: application/json

{
  "type"       : "response",
  "mode"       : "query",
  "parameters" : { "uri" : "https://example.client.com/cb?code=5rZ_KxqZ&state=Nygv4CLQ" }
}

Like the above response, but indicating that a new session was created for the end-user; use the session ID (sub_sid) to set a new session cookie:

HTTP/1.1 OK
Content-Type: application/json

{
  "type"       : "response",
  "mode"       : "query",
  "parameters" : { "uri" : "https://example.client.com/cb?code=5rZ_KxqZ&state=Nygv4CLQ" },
  "sub_sid"    : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw"
}

4.6.1 Response via URL-redirection

The response is returned encoded into the URI query or fragment to the client’s redirect_uri. Applies to the response modes query, query.jwt, fragment and fragment.jwt.

JSON object members:

uri {string} The redirect_uri with the response encoded in the URI query or fragment. The frontend must redirect the user agent (browser) to this URI via an HTTP 303 with the redirection URI set in the Location header.

Security advice: Use a 303 redirection (instead of 302), as it is defined unambiguously to drop the body of an HTTP POST request.

Example:

{
  "uri" : "https://client.example.com/cb?code=637FKlXTl&state=NV2kkDp"
}

Example 303 redirection:

HTTP/1.1 303 See Other
Location: https://client.example.com/cb?code=637FKlXTl&state=NV2kkDp

4.6.2 Response via form POST

The response is returned via a form POST to the client’s redirect_uri. Applies to the response modes form_post and form_post.jwt. See the specification for more information.

Note, all form parameters must be escaped when rendered in HTML as name / value pairs!

JSON object members:

uri {string} The redirect_uri where the form must be posted, e.g. by auto-submitting the form values with JavaScript.
form {object} A JSON object containing the form key / value pairs to be submitted to the URI above.

Example:

{
  "uri"  : "https://client.example.com/cb",
  "form" : { "code"  : "a8xxGwELo1tG5DdMXbE48Q",
             "state" : "Nygv4CLQcexJFmuMCP2ld0Htd2zHIvchRiFCPtvj-mM" }
}

Example rendered HTML form with the encoded response to be auto-submitted to the client’s redirect_uri:

HTTP/1.1 200 OK
Content-Type: text/html;charset=UTF-8
Cache-Control: no-cache, no-store
Pragma: no-cache

<html>
 <head><title>Submit This Form</title></head>
 <body onload="javascript:document.forms[0].submit()">
  <form method="post" action="https://client.example.com/cb">
    <input type="hidden" name="code" value="a8xxGwELo1tG5DdMXbE48Q"/>
    <input type="hidden" name="state" value="Nygv4CLQcexJFmuMCP2ld0Htd2zHIvchRiFCPtvj-mM"/>
  </form>
 </body>
</html>

which results in the following HTTP post to the client application:

POST /callback HTTP/1.1
Host: client.example.org
Content-Type: application/x-www-form-urlencoded

code=a8xxGwELo1tG5DdMXbE48Q&state=Nygv4CLQcexJFmuMCP2ld0Htd2zHIvchRiFCPtvj-mM

4.6.3 Custom response mode parameters

The response parameters for a custom response mode (which is configured as supported by the Connect2id server).

JSON object members:

uri {string} The redirect_uri.
[ … ] {string} One or more response parameters depending on the OAuth 2.0 response type, such as code and state. May include custom parameters.

The frontend must encode and relay the parameters according to the contract of the response mode.

Example custom response mode with an ID token and state parameters:

{
  "uri"      : "https://client.example.com/cb",
  "id_token" : "eyJraWQiOiJzMSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJib2IiLCJhdWQiOiIwMDAxMjMiLCJhY3IiOiJodHRwOlwvXC9sb2EuYzJpZC5jb21cL2Jhc2ljIiwiYW1yIjpbInB3ZCJdLCJicm93c2VyIjoiTmV0c2NhcGUiLCJpc3MiOiJodHRwOlwvXC8xMjcuMC4wLjE6ODA4MFwvYzJpZCIsImV4cCI6MTQ2MzQzMTk3MiwiaWF0IjoxNDYzNDMxMzcyLCJub25jZSI6IkxxQ1Jvclg1YXMycjdqX0R5VTBIWjNFNUFWeV90Z1NUa1VBdWJJMGE5ZDgiLCJsb2dpbl9pcCI6IjEwLjIwLjMwLjQwIn0.iK20La9muiYeVnjPlpjEwVmQ-eaj8B8qjs_dInxeIIC-22xR3pl9sr_QfGyEifIX9-nMnnRF7SChUXtppfbXx6DLntZqoFbXcuysdx2IB6Vt8cikIqBF-aT6xzVux8IkFGmjoekz72p430Qa8rc2Px5hMAPiv-E6-v0smWTW1Ho",
  "state"    : "OGw5AWZY_tGUsdOgcRDASOK4jDDryHR08WBb86NUhhs"
}

4.7 Authorisation session

An instance of an authorisation session with the Connect2id server.

JSON object members:

auth_req {object} The parameters of the received OAuth 2.0 authorisation / OpenID authentication request.
[ sub_sid ] {string} The subject (end-user) session identifier, omitted if none is currently associated with the authorisation session.
[ required_sub ] {string} The required subject, omitted if not specified. This parameter can be present only during a pending authentication prompt.
[ claims ] {object} The names of the requested OpenID claims. This parameter can be present only during a pending consent prompt.
- id_token {string array} The names of the additional requested claims to be returned with the ID token, with optional appended language tags, empty array if none.
- userinfo {string array} The names of the requested claims to be returned at the UserInfo endpoint, with optional appended language tags, empty array if none.
[ consent_record ] {object} Existing end-user consent on record, omitted if none. This parameter can be present only during a pending consent prompt.
- scope {string array} The scope values with consent on record, empty array if none.
- claims {string array} The names of the OpenID claims with consent on record, empty array if none.
[ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state.

Example authorisation session, as JSON object:

{
  "auth_req" : { "response_type" : "code id_token",
                 "client_id"     : "8cc2043",
                 "redirect_uri"  : "https://client.example.org/cb",
                 "scope"         : [ "openid", "email" ],
                 "state"         : "af0ifjsldkj",
                 "nonce"         : "8dfqxd90pa_",
                 "display"       : "popup" },
  "sub_sid"  : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw"
}

4.8 Authorisation session data

Optional data stored in the authorisation session. Represented by a JSON object. May be used to store front-end state, callback state if redirecting to an external identity provider during the authentication step, and other variables.

Example:

{
  "external_idp" : "https://accounts.google.com",
  "state"        : "a775227d-ed3d-4269-a07f-bdab3fbe03c1"
}

4.9 Authorisation session idenifier

Identifier for an authorisation session. The Connect2id server invalidates it when the authorisation session completes with a final response, is canceled, or expires.

The identifier is a 128 bit secure random number with a SHA-256 based HMAC.

Example:

cAjH3ZAonDVFs9u8XZtvuA.L-WFBXv5ompD96ztw0Rr4w

The security properties of the identifier allow for it to be passed to the user browser, and thus enable login / consent UIs with a completely stateless backend. If you choose this approach a cookie with a maximum restricted policy (Secure, HttpOnly, SameSite=Strict) is recommended. Do not encode the identifier into a URL component as this creates a risk for leaks via logs, referrer headers and browser history.

4.10 OAuth client details

Selected OAuth client registration details which may have use during an authorisation session, for example, to display information about the requesting client to the end-user in the consent screen.

JSON object members:

client_id {string} The client identifier.
client_type {“confidential”|“public”} Indicates the OAuth client type. Public clients may be granted limited scopes and should be denied incremental authorisation.
application_type {“web”|“native”} The client application type.
[ contacts ] {string array} Array of e-mail addresses of people responsible for the client. This might be used by some providers to enable a web user interface to modify the client information.
[ name ] {string} Optional name of the client application to be presented to the end-user. May use language tags (BCP47).
[ uri ] {string} Optional URI of the home page of the client application to be presented to the end-user in a followable fashion. May use language tags (BCP47).
[ logo_uri ] {string} Optional logo of the client application to be presented to the end-user. May use language tags (BCP47).
[ policy_uri ] {string} Optional URI of a page describing how the end-user profile data will be used by the client application, to be presented to the end-user in a followable fashion. May use language tags (BCP47).
[ tos_uri ] {string} Optional URI of a page describing the client application’s terms of service, to be presented to the end-user in a followable fashion. May use language tags (BCP47).
[ scope ] {string array} Optional OAuth 2.0 scope values that the client application may request. These values are set at client registration; their semantics and treatment is policy matter and may be ignored.
[ data ] {object} Optional client data.

4.11 Request parameters

The parameters of the received OAuth 2.0 authorisation / OpenID authentication request.

JSON object members:

response_type {string} The OAuth 2.0 response type.
client_id {string} The client identifier.
[ redirect_uri ] {string} The redirection URI, omitted if not specified.
[ scope ] {string array} The requested scope values, omitted if not specified.
[ authorization_details ] {object array} The requested authorisation details for RAR, omitted if not specified. Since v14.4.
[ state ] {string} The state parameter, omitted if not specified.
[ code_challenge ] {string} Optional code challenge for PKCE.
[ code_challenge_method ] {string} Optional code challenge method for PKCE.
[ resource ] {string array} The resource indicator URI(s), omitted if not specified.
[ response_mode ] {string} The explicitly requested response mode, omitted if not specified.
[ prompt ] {string array} The requested prompt request, omitted if not specified.
[ custom_parameter_name ] {string} Any additional custom (non-standard) parameters, as name / string value members. May be used by the login page to customise processing of the request. Note, custom parameters with multiple values are automatically trimmed to a single value.

Parameters present for an OpenID authentication request:

[ nonce ] {string} The nonce for the ID token, omitted if not specified.
[ display ] {string} The end-user display type, omitted if not specified.
[ ui_locales ] {string array} The end-user’s preferred UI locales, by order of preference, omitted if not specified.
[ max_age ] {number} The maximum allowable age in seconds of the end-user authentication in the current session, omitted if not specified. Since v14.5.
[ acr_values ] {string array} The requested Authentication Context Class Reference (ACR) values, omitted if not specified. Since v14.5.
[ claims ] {object} The OpenID claims parameter, omitted if not specified.
[ claims_locales ] {string array} The end-user’s preferred OpenID claims locales, by order of preference, omitted if not specified.
[ id_token_hint ] {string} The ID token hint, omitted if not specified.
[ login_hint ] {string} The login hint, omitted if not specified. Since v14.5.
[ purpose ] {string} The transaction purpose in OpenID Connect for Identity Assurance, omitted if not specified.

4.12 Non-redirecting authorisation error

Indicates an OAuth 2.0 / OpenID Connect authorisation error. The user agent (browser) cannot or should not be redirected back to the client application.

The error code and description should be displayed to the end-user, so they may be reported to the developers of the client application.

JSON object members:

type {string} Set to error. Used to differentiate this object from an authentication prompt, a consent prompt and a final response.
error {string} The error code.
[ error_description ] {string} Optional human readable error description.
[ sub_session ] {object} The current subject (end-user) session, omitted if none is present. The sid parameter represents the session identifier (used for the session cookie). Typically this information is not required at this step and will be omitted unless the server is configured otherwise.
[ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state and other variables.

Example error for an OpenID Connect request that is missing the redirect_uri parameter:

{
  "type"              : "error",
  "error"             : "invalid_request",
  "error_description" : "Missing \"redirect_uri\" parameter"
}

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 for an invalid or expired authorisation session:

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

{
  "error"             : "invalid_session_id",
  "error_description" : "Not found: Invalid SID or expired session"
}

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

Authorisation session

1. Overview

2. Web API overview

3. Resources

3.1 /authz-sessions/rest/v3/

3.1.1 POST

3.2 /authz-sessions/rest/v3/{sid}

3.2.1 PUT

3.2.2 DELETE

3.2.3 GET

3.3 /authz-sessions/rest/v3/{sid}/data

3.3.1 PUT

3.3.2 GET

4. Representations

4.1 Authorisation session start request

4.2 Authentication prompt

4.3 Subject session

4.4 Consent prompt

4.5 Consent

4.6 Final response

4.6.1 Response via URL-redirection

4.6.2 Response via form POST

4.6.3 Custom response mode parameters

4.7 Authorisation session

4.8 Authorisation session data

4.9 Authorisation session idenifier

4.10 OAuth client details

4.11 Request parameters

4.12 Non-redirecting authorisation error

5. Errors

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error