Skip to content
Connect2id

Authorisation session

1. Introduction

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 server. An HA proxy and a CDN can be utilised.

  • Plug one or more authentication methods, such as LDAP directory, OTP, X.512 certificates or biometrics. The user credentials are not shared with the Connect2id server, which is good for security.

  • If needed, plugin specific rules and policies for the token scopes and OpenID Connect claims. Consent can be explicit, implicit, or a combination of both.

  • Zero service downtime is required 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 Connect 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 OpenID response to client

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

For more information, check out the login page integration guide. If you need assistance, get in touch with Connect2id support.

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
Representations Errors

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 an OpenID authentication request from a client application.

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 OpenID authentication response. Indicated by a JSON object with "type":"response".

  • Non-redirectable error – Notifies the frontend that the submitted OpenID Connect 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.

Body:

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-redirectable 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 ID (sid).

Errors:

Example POST request to start an authorisation session with the Connect2id server, specifying the query string of the received OpenID authentication 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" : "EoOOavjQcBLx4ktIvp4Ho3p66NAd7AwB7lbBhhLLioc"
}

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 specified authorisation session identifier (sid).

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

{
  "type"           : "auth",
  "sid"            : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "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 OpenID Connect 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 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.

Body:

Success:

Errors:

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

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

{
  "sub" : "alice"
}

Example submission of the end-user’s consent to login into the client 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/g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "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"         : "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" : [ ] } }
}

Example final response, meaning the Connect2id server has collected all necessary details to complete the OpenID Connect 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 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 which the frontend should 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. If required, the optional error query parameter can be set to another recognised 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:

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. Since v6.7.

  • [ error_description ] Specifies an error description other that the standard to return for the implied error code. Since v6.7.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON object representation of a final response.

Errors:

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:

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON object representation of the authorisation session.

Errors:

Example request:

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

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

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

3.3.1 PUT

Sets the optional data of an authorisation session. Since v6.2.

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.

Body:

  • A JSON object representation of one of the data, empty object ({}) if none.

Success:

  • Code: 204

  • Content-Type: application/json

Errors:

3.3.2 GET

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

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.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON object representation of one of the data, empty object ({}) if none.

Errors:

4. Representations

4.1 Authorisation session start request

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

JSON object members:

Example JSON object for an authorisation session start request, detailing the OpenID Connect 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" : "9yLXidrzk91r3BCpJeF1Vrf_aza4oNe-EdNkaXBa1iw"
}

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 non-redirectable error.

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

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

  • [ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state and other variables. Since v6.10.

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 frontend 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 object from an authentication prompt, a final response and non-redirectable error.

  • 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} 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 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} The requested OpenID Connect claims:

    • new {object} The claims requested for the first time, 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} The requested claims for which the Connect2id server has the end-user’s consent on record (from a previous login), 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.

    • [ locales ] {string array} The requested claims locales, omitted if not specified.

  • [ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state and other variables. Since v6.10.

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 the JSON object to construct an authorisation record with the required ID, access and refresh token parameters for the given 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. If consent is given it should at least contain the openid scope value. An “*” (asterisk) in the string array indicates consent for all requested scope values.

  • [ audience ] {string array} Optional parameter specifying an explicit audience for the issued access token. The audience should be represented as one or more resource server identifiers or URIs.

  • [ 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. An “*” (asterisk) in the string array indicates consent for all requested claims.

  • [ 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 ] {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 identifies a long-lived authorisation that is persisted and may optionally allow issue of a refresh token. If false the authorisation is transient (not remembered). 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).

    • [ encrypt = false ] {true|false} Applies additional encryption to the issued access token (if self-contained / JWT) using JWE direct encryption (“dir”) with an AES key. In order to decrypt the access token the AES key must be shared with the intended resource server(s). If the client is registered for pairwise subject identifiers the JWT will always be encrypted.

  • [ id_token ] {object} Optional ID token settings, overriding the default configuration:

  • [ refresh_token ] {object} Optional refresh token settings:

    • [ issue = true ] {true|false} Enables / disables 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 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.5 Final response

The final OpenID authentication response to be relayed back to the client. Encodes the requested authorisation code, and / or token(s) on success, or an error code on failure (e.g. due to invalid or denied request).

All three standard OAuth 2.0 response modes are supported:

  • query – the response is returned as URI query parameters to the redirect_uri (mandatory to implement)
  • fragment – the response is returned as an URI fragment to the redirect_uri (mandatory to implement)
  • form_post – the response is returned by submitting a form POST to the redirect_uri (optional to implement)

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-redirectable error.

  • mode {“query”|“fragment”|“form_post”|“…“} The response mode (implied or requested explicitly by the client application).

  • parameters {object} The response mode parameters. See query encoded, fragment encoded, form POST and custom mode parameters.

  • [ 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. Since v6.14.

  • [ 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. Since v6.14.

  • [ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state and other variables. Since v6.12.

Example final response:

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"    : "9yLXidrzk91r3BCpJeF1Vrf_aza4oNe-EdNkaXBa1iw"
}

4.5.1 Query response mode parameters

The OpenID authentication response is returned as a query string to the redirect_uri. This response mode is mandatory to implement.

JSON object members:

  • uri {string} The redirect_uri with the response encoded in the query string. 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.5.2 Fragment response mode parameters

The OpenID authentication response is returned as a fragment to the redirect_uri. This response mode is mandatory to implement.

JSON object members:

  • uri {string} The redirect_uri with the response encoded in the 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#id_token=eyJraWQiOiJzMSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJhbGljZSIsImF1ZCI6IjAwMDEyMyIsImFjciI6Imh0dHA6XC9cL2xvYS5jMmlkLmNvbVwvYmFzaWMiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiYW1yIjpbInB3ZCJdLCJicm93c2VyIjoiTmV0c2NhcGUiLCJpc3MiOiJodHRwOlwvXC8xMjcuMC4wLjE6ODA4MFwvYzJpZCIsImV4cCI6MTQ2MzM5MzM5MCwiaWF0IjoxNDYzMzkyNzkwLCJub25jZSI6IjFHUlhIMUNpZXNrTEFqYzI5WS1HRHI5Z19MZFJocFMxRXpnbjUxU3Y3c2siLCJsb2dpbl9pcCI6IjEwLjIwLjMwLjQwIiwiZW1haWwiOiJhbGljZUB3b25kZXJsYW5kLm5ldCJ9.IPS68XhQHlQXxnCvVJBOk7myP7qa1LGdGVnPmPcrjwSKxxir-d2rTWvartpWgaRisYfef-5Ztrb0Eb8UTiDI3fCK_UFc46xPh6fvWVe5XpQQPBgOjjDCvtfibO4MYMRBlhqQgG9KmeE1n1Hvdi1RG4SQiJ5Kfp0jM25VgBIc4QU&state=br3NzNDkz7M60FDoXVjRBAJsWTnY_fLIGrIEn8hleFw"
}

Example 303 redirection:

HTTP/1.1 303 See Other
Location: https://client.example.com/cb#id_token=eyJraWQiOiJzMSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJhbGljZSIsImF1ZCI6IjAwMDEyMyIsImFjciI6Imh0dHA6XC9cL2xvYS5jMmlkLmNvbVwvYmFzaWMiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiYW1yIjpbInB3ZCJdLCJicm93c2VyIjoiTmV0c2NhcGUiLCJpc3MiOiJodHRwOlwvXC8xMjcuMC4wLjE6ODA4MFwvYzJpZCIsImV4cCI6MTQ2MzM5MzM5MCwiaWF0IjoxNDYzMzkyNzkwLCJub25jZSI6IjFHUlhIMUNpZXNrTEFqYzI5WS1HRHI5Z19MZFJocFMxRXpnbjUxU3Y3c2siLCJsb2dpbl9pcCI6IjEwLjIwLjMwLjQwIiwiZW1haWwiOiJhbGljZUB3b25kZXJsYW5kLm5ldCJ9.IPS68XhQHlQXxnCvVJBOk7myP7qa1LGdGVnPmPcrjwSKxxir-d2rTWvartpWgaRisYfef-5Ztrb0Eb8UTiDI3fCK_UFc46xPh6fvWVe5XpQQPBgOjjDCvtfibO4MYMRBlhqQgG9KmeE1n1Hvdi1RG4SQiJ5Kfp0jM25VgBIc4QU&state=br3NzNDkz7M60FDoXVjRBAJsWTnY_fLIGrIEn8hleFw

4.5.3 Form POST response mode parameters

The OpenID authentication response is returned via a form POST to the redirect_uri. This response mode is optional to implement. See the specification for more information.

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 OpenID authentication response to be auto-submitted to the client 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.5.4 Custom response mode parameters

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

JSON object members:

  • uri {string} The redirect_uri.

  • [ code ] {string} The OAuth 2.0 authorisation code, included in the authorisation code or hybrid flow.

  • [ id_token ] {string} The ID token, included in the implicit or hybrid flow.

  • [ access_token ] {string} The OAuth 2.0 access token, included in the implicit or hybrid flow.

  • [ token_type ] {string} The OAuth 2.0 access token type, set to Bearer, included in the implicit or hybrid flow.

  • [ scope ] {string} The OAuth 2.0 access token scope (if specified), included in the implicit or hybrid flow.

  • [ expires_in ] {integer} The OAuth 2.0 access token expiration, included in the implicit or hybrid flow.

  • [ state ] {string} The state parameter, omitted if not specified.

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.6 Authorisation session

The OpenID Connect authentication request parameters and subject session ID for an 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.

    • [ prompt ] {string array} The requested prompt, 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.

    • [ custom_parameter_name ] {string} Any additional custom parameters, as name / string value members. May be used by the login page / frontend to customise processing of the request.

  • [ sub_sid ] {string} The subject (end-user) session identifier, omitted if none is currently associated with the authorisation session.

  • [ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state. Since v6.2.

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

4.7 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.

Since v6.2.

Example:

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

4.8 Client (relying party) details

Selected client (relying party) 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.

  • [ 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.9 Non-redirectable 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. Since v6.14.

  • [ data ] {object} Optional data stored in the authorisation session. May be used to store front-end state and other variables. Since v6.12.

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:

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