Authorisation session

1. Introduction

A defining feature of the Connect2id server is its authorisation session web interface. It can handle just about any authentication and authorisation requirement, and is greatly appreciated by enterprises and system integrators.

The key highlights:

Web-based integration of a login / consent UI, which is neatly decoupled from the underlying Connect2id server. The UI can be coded in any language and framework, and may also be hosted independently from the server.
Simple plugin of arbitrary authentication methods, such as LDAP, hardware tokens, X.512 certificates and biometrics. The credentials, such as passwords, need not be disclosed to the Connect2id server!
If required, also enables simple plugin of arbitrary logic and rule engines for specifying the OAuth 2.0 scope values and OpenID claims of the issued tokens, based on explicit and / or implicit consent.
Zero service downtime is required for updates and changes of the login / consent UI, authentication methods and authorisation logic.

Use of the authorisation session API involves a two-step interaction with the Connect2id server:

	Authentication (step 1)	Consent (step 2)
Purpose:	Establish the user identity	Obtain / set consent
Server → UI:	Authentication prompt	Consent prompt
UI → Server:	Subject (end-user) identity	Consented scope + claims
Step skipped if:	User has an existing session with the server (established by browser cookie)	Previous consent for the requested scope and claims (unless configured otherwise)
Success:	Go to step 2	Return redirect URI with encoded OpenID response to client

The interaction via the authorisation session API can be compared to the MVC pattern. The Connect2id server first decodes the raw OpenID Connect authentication request, then guides the login / consent UI to perform the necessary steps to complete the authorisation request:

It prompts the UI to (re)authenticate the end-user, if required. This can occur if the end-user browser / device has no established session with the Connect2id server or their session cookie has expired, or if the requesting application needs an upgraded authentication strength (ACR).
Presents a prompt with the requested OAuth 2.0 scope values and OpenID Connect claims. Those scope values and claim names for which there is previous consent on record are clearly indicated. Also included are the registered details of the client application, such as ID, name, logo, description and other information. The UI can then prompt the end-user for their consent, or call upon some business logic for that or in addition to that.

The authorisation session API also enables programmatic setting of the access token encoding, lifetime and refresh option. Check out our login page howto on integration, or get in touch with support if you need help.

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.

2. Web API overview

Resources
/authz-sessions/rest/v2/ [POST] /authz-sessions/rest/v2/{sid} [GET] [PUT] [DELETE]
Representations	Errors
Authorisation session start request Authentication prompt Subject session Consent prompt Consent Authorisation session Authorisation error without redirection	400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

3. Resources

3.1 /authz-sessions/rest/v2/

3.1.1 POST

Starts a new authorisation session with the Connect2id server.

The login / consent UI at the OAuth 2.0 authorisation endpoint should start a new authorisation session upon receiving a new OpenID Connect authentication request from the client application.

The POST request produces one of the following four types of response:

Authentication prompt – Prompts the UI to authenticate the end-user. Indicated by a 200 status code and a "type":"auth" message.
Consent prompt – Prompts the UI to obtain the end-user’s consent for the requested OAuth 2.0 scope values and OpenID Connect claims. Indicated by a 200 status code and a "type":"consent" message.
Redirection – Prompts the UI to redirect the user agent (browser) back to the client application. Indicated by a 302 status code. The redirection URI, containing the encoded OAuth 2.0 / OpenID Connect response, is found in the Location header value.
Authorisation error without redirection – Notifies the UI that the submitted OAuth 2.0 / OpenID Connect request is faulty; the user agent (browser) cannot or must not be redirected back to the client application. Indicated by a 220 status code.

Header parameters:

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

Query parameters:

[ ajax = false ] {true|false} Optional parameter, causes the HTTP redirection response to be returned with a 204 status code instead of 302. Intended for browser / Ajax - based test / development web clients of the authorisation session API.

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 or a consent prompt. The two prompts can be differentiated by their type value. The identifier of the newly created authorisation session is found in the sid member.

Redirection:

Code: 302 (204 if the ajax query parameter was true).
Location: The URI to which the user agent (browser) should be redirected, containing the encoded OpenID Connect authentication success / error response in the query / fragment string.

Authorisation error without redirection:

Code: 220
Content-Type: application/json
Body: {object} A JSON object detailing the authorisation request error. The user agent (browser) cannot or must not be redirected back to the client application.

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 OpenID Connect authentication request; the subject (end-user) session identifier (SID) is omitted, indicating a browser session cookie has not been found:

POST /authz-sessions/rest/v2/ 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 response, citing the identifier of the newly created authorisation session (sid) and prompting the UI to authenticate the present end-user (e.g. by verifying their username / password credentials):

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

{
  "type"           : "auth",
  "sid"            : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "display"        : "popup",
  "select_account" : false
}

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

3.1.1 GET

Returns the original request parameters of 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.

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/v2/g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response, citing the key parameters of the OpenID Connect 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"  : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE"
}

3.1.2 PUT

Updates an authorisation session with the required details, which can be the subject identity details, or the consent details. Once these are submitted the OpenID Connect authentication / OAuth 2.0 authorisation is completed.

The PUT request can produce two possible response types:

Consent prompt – Prompts the UI to obtain the end-user’s consent for the requested OAuth 2.0 scope values and OpenID Connect claims. Indicated by a 200 status code and a "type":"consent" message.
Redirection – Prompts the UI to redirect the user agent (browser) back to the client application. Indicated by a 302 status code. The redirection URI, containing the encoded OAuth 2.0 / OpenID Connect response, is found in the Location header value.

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.

Query parameters:

[ ajax = false ] {true|false} Optional parameter, causes the HTTP redirection response to be returned with a 204 status code instead of 302. Intended for browser / Ajax - based test / development web clients of the authorisation session API.

Body:

A JSON object representation of one of the following:
- The details for the subject identity and session, in response to a previous POST or PUT request returning an authentication prompt;
- The details of the OAuth 2.0 / OpenID Connect 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.

Redirection:

Code: 302 (204 if the ajax query parameter was true).
Location: The URI to which the user agent (browser) should be redirected, containing the encoded OpenID Connect authentication success / error response in the query / fragment string.
Subject-Session-ID: This header is included if a new subject (end-user) session was created by the server. Whenever this header is present in the 302 redirection response the session cookie must be updated accordingly with the provided new session ID (this situation occurs when a new end-user session is created and the consent step is skipped).

Errors:

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

Example request to submit the details for the new subject session to be created, such as the end-user ID and the authentication properties, so the UI can proceed to the consent step.

PUT /session-store/rest/v2/g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "sub"       : "alice",
  "auth_time" : 12345678,
  "acr"       : "http://loa.c2id.com/high",
  "amr"       : [ "mfa", "pwd", "otp" ]
}

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

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

{
  "type"        : "consent",
  "sid"         : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "display"     : "popup",
  "sub_session" : { "sid"           : "9yLXidrzk91r3BCpJeF1Vrf_aza4oNe-EdNkaXBa1iw",
                    "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" : [ ] } }
}

3.1.3 DELETE

Denies the authorisation request. This request can made in response to the end-user pressing a button to deny login or authorisation to the client application.

Produces a redirection URI with an encoded access_denied OAuth 2.0 error which the UI can use to send the user agent (browser) back to the client application.

Path parameters:

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

Header parameters:

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

Query parameters:

[ ajax = false ] {true|false} Optional parameter, causes the HTTP redirection response to be returned with a 204 status code instead of 302. Intended for browser / Ajax - based test / development web clients of the authorisation session API.

Redirection:

Code: 302 (204 if the ajax query parameter was true).
Location: The URI to which the user agent (browser) should be redirected, containing the encoded access_denied OAuth 2.0 error response in the query / fragment string.

Errors:

401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Example request to deny login or authorisation:

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

Example response, the Location header specifies the redirection URI with the encoded Auth 2.0 access_denied error:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied&state=xyz

4. Representations

4.1 Authorisation session start request

Specifies the OpenID Connect authentication request received at the OAuth 2.0 authorisation endpoint (the login UI) and the identifier of the subject (end-user) session with the Connect2id server, if such exists.

JSON object members:

query {string} The raw (undecoded) URI query string of the OpenID Connect authentication request request received at OAuth 2.0 authorisation endpoint.
[ sub_sid ] {string} The subject (end-user) session identifier (SID), typically saved in a browser cookie, omitted or null if none. The SID is used to resolve the session of the present end-user and whether (re)authentication is required.

Example JSON object for an authorisation session start request, detailing the OpenID Connect query string and the subject session identifier (SID) obtained from a 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" : "9yLXidrzk91r3BCpJeF1Vrf_aza4oNe-EdNkaXBa1iw"
}

If no session cookie is found the subject SID 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 login page 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 prompt from a consent prompt.
sid {string} The authorisation session identifier, used 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 time.
[ 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 an ID token hint submitted by 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 to the UI about the login identifier the end-user might use to log in (if necessary). This hint can be used by a client application if it first asks the end-user for their e-mail address (or other identifier) and then wants to pass that value as a hint to the discovered Identity Provider. The use of this parameter is left to the Identity Provider’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 prompted to select a user account. This enables an end-user who has multiple accounts with the Identity Provider to select amongst the multiple accounts that they might have current sessions for.
[ sub_session ] {object} A JSON object representation of the current subject (end-user) session, omitted if none.
[ client ] {object} A JSON object representation of the registered details for the requesting client. Typically this information is not required at this stage and will be omitted unless the server is configured otherwise.
- client_id {string} The identifier of the client application.
- 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.
- [ 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 service specific and can also be ignored.
- [ data ] {object} Optional client data.

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

{
  "type"           : "auth",
  "sid"            : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "display"        : "popup",
  "select_account" : false
}

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

{
  "type"           : "auth",
  "sid"            : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "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"            : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "display"        : "popup",
  "acr"            : { "essential" : [ "http://loa.c2id.com/high" ] },
  "select_account" : false,
  "sub_session     : { "sid"           : "9yLXidrzk91r3BCpJeF1Vrf_aza4oNe-EdNkaXBa1iw",
                       "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" } }
}

Prompts the login page to obtain the end-user’s consent for the specified OAuth 2.0 scope values and OpenID Connect claims.

JSON object members:

type {string} Set to consent. Used to differentiate this prompt from an authentication prompt.
sid {string} The authorisation session identifier, used 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} A JSON object representation of the current subject (end-user) session.
client {object} A JSON object representation of the registered details for the requesting client:
- client_id {string} The identifier of the client application.
- 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.
- [ 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 service specific and can also be ignored.
- [ data ] {object} Optional client data.
scope {object} A JSON object representing the requested OAuth 2.0 scope values, grouped into two sets:
- new {string array} A string array of scope values requested for the first time, empty array if none.
- consented {string array} A string array of requested scope values for which the Connect2id server has previously recorded the end-user’s consent, empty array if none.
claims {object} A JSON object representing the requested OpenID Connect claims:
- new {object} A JSON object representing the claims requested for the first time, grouped 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} A JSON object representing the requested claims for which the Connect2id server has previously recorded the end-user’s consent, grouped 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.
- [ locales ] {string array} The requested claims locales, omitted if not specified.

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

{
  "type"        : "consent",
  "sid"         : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "display"     : "popup",
  "sub_session" : { "sid"           : "9yLXidrzk91r3BCpJeF1Vrf_aza4oNe-EdNkaXBa1iw",
                    "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 all fields defined:

{
  "type"        : "consent",
  "sid"         : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "display"     : "popup",
  "ui_locales"  : [ "es", "en" ],
  "sub_session" : { "sid"           : "9yLXidrzk91r3BCpJeF1Vrf_aza4oNe-EdNkaXBa1iw",
                    "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 it to construct an authorisation record with the required ID, access and refresh token parameters for the given subject 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. If consent is given should at least contain the openid scope value.
[ audience ] {string array} Optional parameter specifying an explicit audience for the issued access token. The audience should be represented as one or more client identifiers.
[ claims ] {string array} The names of the consented OpenID Connect claims, with optional language tags (BCP47). These may be a subset of the originally requested claims, or include additional ones.
[ preset_claims ] {object} Optional JSON object specifying additional preset OpenID Connect claims to include in the ID token and / or the UserInfo response:
- [ id_token ] Preset claims to include in the ID token, omitted or empty JSON object if none.
- [ userinfo ] 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 identifies a long-lived authorisation that is persisted and may optionally allow issue of a refresh token. If false the authorisation is transient and will be deleted as soon as the access token associated with it expires. Defaults to true if not specified.
[ 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 defaults to the configured access token lifetime.
- [ encoding = “SELF_CONTAINED” ] {“SELF_CONTAINED”|“IDENTIFIER”} The access token encoding. If omitted defaults to self-contained (JWT-encoded).
[ id_token ] {object} Optional ID token settings, overriding the default configuration:
- [ lifetime = 0 ] {integer} The ID token lifetime in seconds. If zero or omitted defaults to the configured ID token lifetime.
- [ ~~impersonated_sub~~ ] {string} Deprecated, use the top-level impersonated_sub parameter instead.
[ refresh_token ] {object} Optional refresh token settings:
- [ issue = true ] {true|false} Enables / disable refresh token issue. Applies only to long-lived (persisted) authorisations. If true a refresh token will be issued along with the access token. If false no access token will be issued. Defaults to true if omitted.
- [ lifetime = 0 ] {integer} The refresh token lifetime in seconds. If zero or omitted defaults to permanent (no expiration). If a client tries to refresh an access token and the refresh token has expired, the token endpoint of the Connect2id server will return an invalid_grant error. This can serve as a signal to the client to repeat the authentication request.
[ data ] {object} Optional additional information to be stored in the dat field of the authorisation record and self-contained (JWT-encoded) access tokens.

Example minimal consent:

{
  "scope" : [ "openid" ]
}

Example consent for the standard openid and email scope values and the OpenID 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.5 Authorisation session

Specifies the request parameters for the authorisation session.

JSON object members:

auth_req {object} A JSON object representing the original OpenID Connect authentication request parameters:
- response_type {string} The OAuth 2.0 response type.
- client_id {string} The client identifier.
- redirect_uri {string} The redirection URI.
- scope {string array} The requested scope values.
- [ state ] {string} The state parameter, omitted if not specified.
- [ nonce ] {string} The nonce, 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.
- [ claims ] {object} The OpenID Connect claims parameter, omitted if not specified.
- [ claims_locales ] {string array} The end-user’s preferred claims locales, by order of preference, omitted if not specified.
- [ code_challenge ] {string} Optional code challenge for PKCE.
- [ code_challenge_method ] {string} Optional code challenge method for PKCE.
[ sub_sid ] {string} The subject (end-user) session identifier, omitted if none is currently associated with the authorisation session.

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",
                 "ui_locales"    : [ "es", "en" ] },
  "sub_sid"  : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE"
}

4.6 Authorisation error without redirection

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

JSON object members:

error {string} The error code.
[ error_description ] {string} Optional human readable error description.

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

{
  "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:

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

{
  "error"             : "authz_not_found",
  "error_description" : "Not found: Authorization 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
Content-Type: application/json

{
  "error"             : "server_error",
  "error_description" : "Internal server error: Something bad happened",
  "stack"             : "Exception in thread...",
  "note"              : "See the server logs for additional details"
}

Authorisation session

1. Introduction

2. Web API overview

3. Resources

3.1 /authz-sessions/rest/v2/

3.1.1 POST

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

3.1.1 GET

3.1.2 PUT

3.1.3 DELETE

4. Representations

4.1 Authorisation session start request

4.2 Authentication prompt

4.3 Consent prompt

4.4 Consent

4.5 Authorisation session

4.6 Authorisation error without redirection

5. Errors

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error