Subject session store

1. Introduction

In order to facilitate Single Sign-On (SS0) the Connect2id server maintains a session store to remember authenticated users (subjects) between login requests from client applications. The sessions are stored in memory for speedy access (with optional overflow to disk) and replicated across the entire Connect2id server cluster, where each session object is keyed by a secure unique ID (SID), to be kept as a cookie in the user’s browser.

A new session is implicitly created when a subject (user) is logged in for the first time, via the API for handling OpenID Connect authentication (or via the custom API for direct token retrieval).

Sessions expire according to their max lifetime, authentication lifetime and max idle time (whichever occurs first). These values are configured globally, but can also be overridden on a individual basis.

The Connect2id server exposes a RESTful web API, described below, for querying, updating and deleting sessions. This API has a number of good uses:

Let auxiliary services and UIs to the IdP, such as a user’s profile and settings page, to share the same session.
Logout a user (for a single session or for all sessions that a user has).
Store additional data (e.g. UI preferences) in the user’s session.
Monitor which users are currently online and in what numbers.
Create user sessions independently from the regular OpenID Connect login flows.

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

More information can be found in the session store configuration reference.

2. Web API overview

Resources
/session-store/rest/v2/sessions [POST] [GET] [DELETE] /session-store/rest/v2/sessions/subject-auth [PUT] /session-store/rest/v2/sessions/claims [PUT] [DELETE] /session-store/rest/v2/sessions/data [PUT] [DELETE] /session-store/rest/v2/sessions/count [GET] /session-store/rest/v2/subjects [GET] /session-store/rest/v2/subjects/count [GET]
Representations	Errors
Subject authentication Subject session	400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 409 Conflict 500 Internal Server Error

3. Resources

3.1 /session-store/rest/v2/sessions

Use this resource to create, retrieve or delete subject (end-user) sessions.

3.1.1 POST

Creates a new subject (end-user) session. Returns 201 and a secure unique identifier for the session (SID) on success. The session is deleted automatically from the store once its max session lifetime, max authentication lifetime or idle time expires (whichever occurs first).

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to application/json.
[ SID-Key ] Specifies a key for the new session to create (without the HMAC portion). If omitted the session will be automatically assigned a secure randomly generated key (recommended), with an HMAC appended. Used to import a session from another Connect2id server.
[ Legacy-SID ] Specifies a legacy identifier for the new session to create. Used to import a session from a Connect2id server that doesn’t support HMAC-protected SIDs (version 5x and older). Note that the Connect2id server must also be configured to accept legacy SIDs.

Body:

A JSON object representation of the subject session. The only mandatory member is sub which sets the subject’s (end-user) identifier. All other members are optional, and if omitted will be left empty (acr, amr, data), given an automatic value (auth_time, creation_time), or a default value (max_life, auth_life, max_idle).

Success:

Code: 201
SID: The session identifier (SID), to enable referral to the session in subsequent requests.

Errors:

400 Bad Request
401 Unauthorized
403 Forbidden
409 Conflict
500 Internal Server Error

Example request to create a new minimal session for end-user alice. The creation and authentication times will be implicitly set to the current system time.

POST /session-store/rest/v2/sessions HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub"  : "alice"
}

Example request to create a new session for alice detailing its authentication strength (acr), authentication factors (amr) and additional data:

POST /session-store/rest/v2/sessions HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub"  : "alice",
  "acr"  : "http://loa.c2id.com/high",
  "amr"  : [ "pwd", "otp" ],
  "data" : { "email"    : "alice@wonderland.net",
             "login_ip" : "192.168.0.1" }
}

Example success response returning the identifier for the newly created session in the SID header:

HTTP/1.1 201 Created
SID: Z6WJGYlFRZQwNr6-ZZ85LYKtYHPR_6Q91fw2NRK3xYw

3.1.2 GET

Retrieves an individual subject session, the sessions for a selected subject, or all sessions. The unbounded request can be potentially expensive and should be used sparingly.

If a single session is returned, its last access timestamp will be updated.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ SID ] The session identifier (SID) to specify an individual session for retrieval. If omitted all sessions will be retrieved, optionally limited to a single subject (see subject query parameter).

Query parameters:

[ subject ] {string} Optional query parameter, applies only when the SID header parameter is omitted, to retrieve all sessions for the specified subject.

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON object representing the individual subject session, or, if all sessions are being retrieved (optionally limited to a particular subject) a JSON object containing the session objects keyed by their session identifier (SID) (empty JSON object if no sessions were found).

Errors:

401 Unauthorized
403 Forbidden
404 Not Found – if the SID is invalid or the session has expired
500 Internal Server Error

Example request to retrieve an individual session with the specified SID:

GET /session-store/rest/v2/sessions HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: cg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0

A matching response detailing the attributes of the requested session:

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

{
  "sub"           : "alice",
  "auth_time"     : 1400491648,
  "creation_time" : 1400491648,
  "max_life"      : 20160,
  "auth_life"     : 10080,
  "max_idle"      : 1440,
  "acr"           : "http://loa.c2id.com/high",
  "amr"           : [ "pwd", "otp" ],
  "data"          : { "email"    : "alice@wonderland.net",
                      "login_ip" : "192.168.0.1" }
}

Example request to retrieve all sessions for subject alice:

GET /session-store/rest/v2/sessions?subject=alice HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

A matching response response returning two sessions for subject alice, keyed by their SIDs:

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

{
  "Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0" : {
    "sub"           : "alice",
    "auth_time"     : 1400491648,
    "creation_time" : 1400491648,
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "acr"           : "http://loa.c2id.com/high",
    "amr"           : [ "pwd", "otp" ],
    "data"          : { "email"    : "alice@wonderland.net",
                        "login_ip" : "192.168.0.1" }
  },

  "khHklxYH_1n7fwEK52mOd8pRyP9R2Tt2vw57kGZ9Cjw" : {
    "sub"           : "alice",
    "auth_time"     : 1400568801,
    "creation_time" : 1400568801
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "acr"           : "http://loa.c2id.com/high",
    "amr"           : [ "pwd", "otp" ],
    "data"          : { "email"    : "alice@wonderland.net",
                        "login_ip" : "192.168.0.2" }
  }
}

3.1.3 DELETE

Deletes one or multiple subject sessions. Has the effect of logging out the associated end-user(s) on the browser / device where they have a session.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ SID ] The session identifier (SID) to specify an individual session.

Query parameters:

[ subject ] {string} Selects all sessions for a subject (end-user) to be deleted. Should not be used together with the SID header parameter.
[ all = false ] {true|false} If set to true causes all sessions to be deleted. Should not be used together with the SID header parameter.
[ quiet = false ] {true|false} If set to true suppresses output when deleting all sessions, the response will be HTTP 204 No Content. Should not be used together with the SID header parameter. Since v6.19.

Success:

Code: 200 or 204
Content-Type: application/json
Body: {object} A JSON object representing the removed subject session, or, if removal of multiple sessions was requested, a JSON object containing the removed sessions keyed by their session identifier (SID) (empty JSON object if noe sessions were found).

Errors:

401 Unauthorized
403 Forbidden
404 Not Found – if the SID is invalid or the session has expired
500 Internal Server Error

Example request to delete a single session with the specified SID:

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

Example response:

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

{
  "sub"           : "alice",
  "auth_time"     : 1400491648,
  "creation_time" : 1400491648,
  "max_life"      : 20160,
  "auth_life"     : 10080,
  "max_idle"      : 1440,
  "acr"           : "http://loa.c2id.com/high",
  "amr"           : [ "pwd", "otp" ],
  "data"          : { "email"    : "alice@wonderland.net",
                      "login_ip" : "192.168.0.1" }
}

Example request to delete all sessions for end-user bob:

DELETE /session-store/rest/v2/sessions?subject=bob HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

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

{
  "Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0" : {
    "sub"           : "bob",
    "auth_time"     : 1400491648,
    "creation_time" : 1400491648,
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "data"          : { "email"    : "bob@wonderland.net",
                        "login_ip" : "192.168.0.2" }
  },

  "khHklxYH_1n7fwEK52mOd8pRyP9R2Tt2vw57kGZ9Cjw" : {
    "sub"           : "bob",
    "auth_time"     : 1400568801,
    "creation_time" : 1400568801,
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "data"          : { "email"    : "bob@wonderland.net",
                        "login_ip" : "192.168.0.3" }
  }
}

3.2 /session-store/rest/v2/sessions/subject-auth

This resource enables update of the authentication details for a subject session.

3.2.1 PUT

Updates the subject authentication details of a session. Use this method to record the event of a subject being re-authenticated while preserving their session, possibly with different factors (as indicated by the acr and amr parameters).

The last access timestamp the session will be automatically updated.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
SID The session identifier (SID).
Content-Type Must be set to application/json.

Body:

A JSON object representation of the updated subject authentication. The only mandatory member is sub which must be set to the subject (user) identifier of the session. If the auth_time is omitted the authentication timestamp will be set to the current system time. The optional acr and amr members are used to identify the applicable authentication strength and methods.

Success:

Code: 204

Errors:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found – if the SID is invalid or the session has expired
500 Internal Server Error

Example request to step up the authentication details for a session with the specified SID:

PUT /session-store/rest/v2/sessions/subject-auth
/subject-auth HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0
Content-Type: application/json

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

Example success response, no content is returned:

HTTP/1.1 204 No content

3.3 /session-store/rest/v2/sessions/claims

This resource enables update and deletion of the optional claims associated with a subject’s (end-user’s) session.

3.3.1 PUT

Updates the optional claims of a subject session.

The last access timestamp the session will be automatically updated.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
SID The session identifier (SID).
Content-Type Must be set to application/json.

Body:

A JSON object representation of the updated subject session claims.

Success:

Code: 204

Errors:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found – if the SID is invalid or the session has expired
500 Internal Server Error

Example request to update the claims of a session with the specified SID:

PUT /session-store/rest/v2/sessions/claims HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0
Content-Type: application/json

{
  "roles"    : [ "admin", "audit" ],
  "login_ip" : "192.168.0.1"
}

Example success response, no content is returned:

HTTP/1.1 204 No content

3.3.2 DELETE

Deletes the optional claims of a subject session.

The last access timestamp the session will be automatically updated.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
SID The session identifier (SID).

Success:

Code: 204

Errors:

401 Unauthorized
403 Forbidden
404 Not Found – if the SID is invalid or the session has expired
500 Internal Server Error

Example request to delete the claims of a session with the specified SID:

DELETE /session-store/rest/v2/sessions/claims HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0

Example success response, no content is returned:

HTTP/1.1 204 No content

3.4 /session-store/rest/v2/sessions/data

This resource enables update and deletion of the optional data associated with a subject’s (end-user’s) session.

3.4.1 PUT

Updates the optional data of a subject session.

The last access timestamp the session will be automatically updated.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
SID The session identifier (SID).
Content-Type Must be set to application/json.

Body:

A JSON object representation of the updated subject session data.

Success:

Code: 204

Errors:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found – if the SID is invalid or the session has expired
500 Internal Server Error

Example request to update the data of a session with the specified SID:

PUT /session-store/rest/v2/sessions/data HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0
Content-Type: application/json

{
  "email"        : "alice@wonderland.net",
  "name"         : "Alice Adams"
  "geo_location" : [ 123.123, 456.456 ],
  "timezone"     : "CET"
}

Example success response, no content is returned:

HTTP/1.1 204 No content

3.4.2 DELETE

Deletes the optional data of a subject session.

The last access timestamp the session will be automatically updated.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
SID The session identifier (SID).

Success:

Code: 204

Errors:

401 Unauthorized
403 Forbidden
404 Not Found – if the SID is invalid or the session has expired
500 Internal Server Error

Example request to delete the data of a session with the specified SID:

DELETE /session-store/rest/v2/sessions/data HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0

Example success response, no content is returned:

HTTP/1.1 204 No content

3.5 /session-store/rest/v2/sessions/count

This resource keeps count of the subject (end-user) sessions.

3.5.1 GET

Returns the current total subject session count.

Header parameters:

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

Success:

Code: 200
Content-Type: text/plain
Body: {integer} The total session count, zero if none.

Errors:

401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Example request to retrieve the total session count:

GET /session-store/rest/v2/sessions/count HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response indicating 15200 current sessions:

HTTP/1.1 200 OK
Content-Type: text/plain

15200

3.6 /session-store/rest/v2/subjects

This resource keeps track of the subjects (end-users) with sessions.

3.6.1 GET

Returns a list of the subjects with sessions.

Header parameters:

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

Success:

Code: 200
Content-Type: application/json
Body: {array} An unordered JSON array of the subjects that currently have sessions. Empty array if none.

Errors:

401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Example request to retrieve the identifiers of subjects that have sessions:

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

Example response:

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

[ "alice", "bob", "claire", "dan" ]

3.7 /session-store/rest/v2/subjects/count

This resource keeps count of the subjects (end-users) with sessions.

3.7.1 GET

Returns the current total subject count.

Header parameters:

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

Success:

Code: 200
Content-Type: text/plain
Body: {integer} The total count of subjects with sessions, zero if none.

Errors:

401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Example request to retrieve the total subject count:

GET /session-store/rest/v2/subjects/count HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response indicating 12768 subjects with sessions:

HTTP/1.1 200 OK
Content-Type: text/plain

12768

4. Representations

4.1 Subject authentication

Subject (end-user) authentication. Details the subject identifier, the authentication timestamp, and the applicable methods and strength (if specified).

JSON object members:

sub {string} The subject (end-user) identifier.
auth_time {integer} The time of the subject authentication, as number of seconds since the Unix epoch. Defaults to the current system time if not specified when a new subject authentication is created.
[ acr ] {string} Optional Authentication Context Class Reference (ACR), omitted if not specified. Used to signify the strength of the employed authentication methods.
[ amr ] {string array} Optional list of the Authentication Method References (AMR), omitted if not specified. Used to signify the employed methods for subject authentication, such as password, hardware token, biometrics, etc.

Example minimal representation of a subject authentication:

{
  "sub"       : "alice",
  "auth_time" : 12345678
}

Example representation of a subject authentication with all fields defined:

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

4.2 Subject session

Subject (end-user) session. Details the subject identifier, various session timestamps and limits, and other data.

JSON object members:

sub {string} The subject (end-user) identifier.
[ sid ] {string} The session identifier, set when the subject session is included in a authentication prompt or consent prompt JSON object, else omitted.
auth_time {integer} The time of the subject authentication, as number of seconds since the Unix epoch. Defaults to the current system time if not specified when a new subject session is created.
creation_time {integer} The session creation time, as number of seconds since the Unix epoch. Defaults to the current system time if not specified when a new subject session is created.
max_life {integer} The maximum session lifetime in minutes, unlimited if negative. Defaults to the preferred maximum session lifetime if not specified when a new subject session is created.
auth_life {integer} The authentication lifetime in minutes, unlimited if negative. Defaults to the preferred authentication lifetime if not specified when a new subject session is created.
max_idle {integer} The maximum session idle time in minutes, unlimited if negative. Defaults to the preferred idle time if not specified when a new subject session is created.
[ acr ] {string} The Authentication Context Class Reference (ACR) for the session, omitted if not specified. Used to signify the strength of the employed authentication methods.
[ amr ] {string array} List of the Authentication Method References (AMR), omitted if not specified. Used to signify the employed methods for subject authentication, such as password, hardware token, biometrics, etc.
[ claims ] {object} Optional OpenID claims about the subject. May be used as a source to feed additional claims about the logged in subject into the issued ID tokens.
[ data ] {object} Optional session data, represented as a JSON object.

Example minimal JSON object to create a new subject session, with just the subject identifier specified:

{
  "sub" : "alice"
}

Example subject session, with all fields specified:

{
  "sub"           : "alice",
  "auth_time"     : 12345678,
  "acr"           : "http://loa.c2id.com/high",
  "amr"           : [ "mfa", "pwd", "otp" ],
  "creation_time" : 1234567,
  "max_life"      : 20160,
  "auth_life"     : 1440,
  "max_idle"      : 15,
  "claims"        : { "roles" : [ "admin", "audit" ] },
  "data"          : { "name"     : "Alice Adams",
                      "email"    : "alice@wonderland.net",
                      "login_ip" : "192.168.0.1" }
}

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

403 Forbidden

Indicates the web API is disabled.

Example:

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

{
  "error"             : "web_api_disabled",
  "error_description" : "Forbidden: Web API disabled"
}

404 Not Found

The requested resource doesn’t exist.

Example:

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

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

409 Conflict

Two types of error conditions are signaled with the 409 Conflict status code when attempting to create a new session:

The session quota for the subject (end-user) has been exhausted:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error"             : "exhausted_session_quota",
  "error_description" : "Over session quota"
}

The specified new session identifier (SID) matches an existing one:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error"             : "session_id_collision",
  "error_description" : "Couldn't add session: SID collision, try another one"
}

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: Check the logs for details"
}