Web session bootstrap endpoint

1. Overview

This endpoint allows authorised native clients to bootstrap a web session at the Connect2id server for a subject (end-user) who was authenticated with an ID token. The endpoint returns a session cookie, which a native client can inject into the cookie jar of a WebView. Web applications loaded in the WebView that rely on the Connect2id server for sign-in and / or tokens can then skip the user authentication step, providing a seamless login experience.

The endpoint must be enabled in order to accept requests. A native client bootstraps a web session by presenting a short-lived, single-use token with the appropriate scope. This token is obtained in exchange for an ID token for the authenticated subject, as explained in this guide.

Bootstrapped web sessions have these properties:

sub – The subject (end-user) identifier.
ctx – Set to web.
creation_time, auth_time – Set to the current time.
max_life, auth_life, max_idle – Set according to the configured sessionStore.maxLifetime, sessionStore.authLifetime and sessionStore.maxIdleTime properties.
[ acr ] – Set according to the configured op.webSessionBootstrap.assumeIDTokenACR and op.webSessionBootstrap.defaultACR properties.
[ amr ] – Set according to the op.webSessionBootstrap.assumeIDTokenAMR and op.webSessionBootstrap.defaultAMR properties.
data – Includes:
- bootstrap – JSON object with members:
  - client_id – The ID of the client that bootstrapped the session.
  - id_token – Selected claims from the ID token was used to bootstrap the session:
    - iat – The iat (issued-at) claim of the ID token.
    - [ auth_time ] – The auth_time claim of the ID token (if present).
    - [ acr ] – The acr (authentication context class reference) claim of the ID token (if present).
    - [ amr ] – The amr (authentication methods references) claim of the ID token (if present).

4. Web API overview

Resources
/web-session-bootstrap/rest/v1 [POST]
Representations	Errors
Error	400 Bad Request 401 Unauthorized 401 Forbidden 500 Internal Server Error

4. Resources

4.1 /web-session-bootstrap/rest/v1

4.1.1 POST

Submits a web session bootstrap request.

Clients registered for mutual TLS sender-constrained resource access must submit their client X.509 certificate with the HTTP request.

Header parameters:

Authorization The access token of type Bearer or DPoP.
[ DPop ] The DPoP proof JWT, for an access token of type DPoP. The JWT must include an ath claim representing the BASE64URL encoded SHA-256 hash of the DPoP access token value.
Content-Type Must be application/x-www-form-urlencoded.
[ 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:

None.

Success:

Code: 204
Set-Cookie: A Set-Cookie header for the bootstrapped web session.

Errors:

400 Bad Request with an error code.
401 Unauthorised with an error code.
403 Forbidden with an error code.
500 Internal Server Error

Example web session bootstrap request with a Bearer token:

POST /web-session-bootstrap/rest/v1 HTTP/1.1
Host: c2id.com
Authorization: Bearer 1zudgjwV3Oj3uEnjGDqD0Q.xkc9mOXIwHz8pOYiVvZBRw
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Example web session bootstrap request with a DPoP proof and DPoP token:

POST /web-session-bootstrap/rest/v1 HTTP/1.1
Host: c2id.com
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwieC...
Authorization: DPoP 1zudgjwV3Oj3uEnjGDqD0Q.xkc9mOXIwHz8pOYiVvZBRw
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Example success response, the Set-Cookie header contains the subject session cookie and its attributes:

HTTP/1.1 204 No Content
Set-Cookie=sid=lxCY2Y954NRpN9NFjTf5QA.fMUJ5mx4YGM127L1fa-s6Q;Version=1;Domain=c2id.com;Path=/;Secure;HttpOnly;SameSite=Lax
Cache-Control=no-store, no-transform

Example error response for an invalid Bearer token:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token" error_description="Invalid access token"
Content-Type: application/json

{
  "error"             : "invalid_token",
  "error_description" : "Invalid access token"
}

5. Representations

5.1 Error

JSON object with members:

error An error code which can take one of the following values:
- invalid_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
- forbidden The endpoint is disabled, the access token has insufficient scope, or the subject session quota is exhausted.
- missing_token The access token is missing.
- invalid_token The access token is invalid.
- invalid_dpop_proof The DPoP proof is missing or invalid.
[ error_description ] Optional text providing additional information about the error that occurred.
[ error_uri ] Optional URI for a web page with information about the error that occurred.

Example rror:

{
  "error"             : "invalid_token",
  "error_description" : "Invalid access token"
}

6. Errors

400 Bad Request

Invalid request. See error codes for more information.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Expired login_hint_token"
}

401 Unauthorized

The request was denied due to an invalid or missing access token, an invalid or missing DPoP proof. See error codes for more information.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
WWW-Authenticate: DPoP algs="PS256 RS384 RS512 PS256 PS384 PS512 ES256 ES384 ES512 ES256K"
Content-Type: application/json

{
  "error"             : "missing_token",
  "error_description" : "Unauthorized: Missing access token"
}

403 Forbidden

The request was denied due to the endpoint being disabled, the access token having insufficient scope, or the subject session quota being exhausted. See error codes for more information.

Example:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error"             : "forbidden",
  "error_description" : "The web session bootstrap endpoint is disabled"
}

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error