Subject session store API

1. Introduction

The Connect2id server includes a built-in session store as part of its Single Sign-On (SSO) capability. It records the end-user sessions between visits to the server to sign onto client applications or to perform other identity-management tasks.

An SSO session is implicitly created when an OpenID Connect request is handled through the authorisation session API, or when the direct authorisation API is invoked. The Connect2id server exposes the RESTful web API explained below to enable query and direct manipulation of end-user sessions.

Possible uses of the Connect2id subject (end-user) session web API:

• Facilitate end-user logout, for a single session or for all existing end-user sessions, from the SSO user interface (UI).

• Store additional data (e.g. UI preferences) in an end-user's session object, intended for use by the SSO UI (login page).

• Monitor which end-users are currently online and in what numbers. This can be utilised by tools to perform SSO statistics.

• Create end-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

Additional details are found in the session store configuration reference.

2. Web API overview

Resources
/session-store/rest/v1/ [POST] [GET] /session-store/rest/v1/{sid} [GET] [DELETE] /session-store/rest/v1/{sid}/subject-auth [PUT] /session-store/rest/v1/{sid}/data [PUT] [DELETE] /session-store/rest/v1/count [GET] /session-store/rest/v1/subjects [GET] /session-store/rest/v1/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/v1/

Use this resource to create and store new subject sessions, and to retrieve all stored sessions, optionally limited by subject.

3.1.1 POST

Creates a new subject (end-user) session. Returns 201 and a 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.

Body:

• A JSON object representation of the subject session. The only mandatory member is sub which sets the subject's 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

• Content-Type: text/plain

• Body: {string} The session identifier (SID), to refer 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 session for end-user alice, with the creation and authentication times implicitly set to now:

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

{
  "sub"  : "alice",
  "acr"  : "urn:acr:basic",
  "data" : {
    "email"    : "[email protected]",
    "login_ip" : "192.168.0.1"
  }
}

Example success response returning the session identifier (SID) for the newly created session:

HTTP/1.1 201 Created
Content-Type: text/plain

Z6WJGYlFRZQwNr6-ZZ85LYKtYHPR_6Q91fw2NRK3xYw

3.1.2 GET

Retrieves all stored subject sessions, optionally limited to a specified subject (end-user). The unbounded request can be potentially expensive and should be used sparingly.

Header parameters:

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

Query parameters:

• [ subject ] {string} Optional query parameter, to limit the returned sessions to the specified subject only.

Success:

• Code: 200

• Content-Type: application/json

• Body: {object} A JSON object with the matching session objects keyed by session identifier (SID). Empty JSON object if no sessions were found.

Errors:

• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error

Example request to retrieve all sessions for subject alice:

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

Example response detailing two session for subject alice:

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"           : "urn:acr:basic",
    "data"          : {
      "email"    : "[email protected]",
      "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"           : "urn:acr:2fa",
    "data"          : {
      "email"    : "[email protected]",
      "login_ip" : "192.168.0.2"
    }
  }
}

3.2 /session-store/rest/v1/{sid}

This resource represents an individual subject session with its attributes.

3.2.1 GET

Retrieves a stored subject session by its identifier (SID).

Path parameters:

• sid {string} The 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 representing the subject session.

Errors:

• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error

Example request to retrieve a session with SID Vcg62c...:

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

Example response detailing the available session attributes:

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"           : "urn:acr:basic",
  "data"          : {
    "email"    : "[email protected]",
    "login_ip" : "192.168.0.1"
  }
}

3.2.2 DELETE

Deletes a stored subject session. Has the effect of logging out the end-user.

Path parameters:

• sid {string} The 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 representing the removed subject session.

Errors:

• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error

Example request to delete a session with SID Vcg62c...:

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

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"           : "urn:acr:basic",
  "data"          : {
    "email"    : "[email protected]",
    "login_ip" : "192.168.0.1"
  }
}

3.3 /session-store/rest/v1/{sid}/subject-auth

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

3.3.1 PUT

Updates the subject authentication details for an existing 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).

Path parameters:

• sid {string} The 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 the updated subject authentication. The only mandatory member is sub which must be set to the subject 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
• 500 Internal Server Error

Example request to update the authentication details for a session with SID Vcg62c...:

PUT /session-store/rest/v1/Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0/subject-auth HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "sub" : "alice",
  "acr" : "urn:acr:2fa",
  "amr" : [ "ldap", "token" ]
}

Example success response, no content is returned:

HTTP/1.1 204 No content

3.4 /session-store/rest/v1/{sid}/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 an existing subject session.

Path parameters:

• sid {string} The 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 the updated subject session data.

Success:

• Code: 204

Errors:

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

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

PUT /session-store/rest/v1/Vcg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0/data HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "email"        : "[email protected]",
  "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 an existing subject session.

Path parameters:

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

Header parameters:

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

Success:

• Code: 204

Errors:

• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error

Example request to delete the data of session with SID Vcg62c...:

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

Example success response, no content is returned:

HTTP/1.1 204 No content

3.5 /session-store/rest/v1/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 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 session count:

GET /session-store/rest/v1/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/v1/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 containing the identifiers 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/v1/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/v1/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/v1/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"       : "urn:c2id:acr:mfa",
  "amr"       : [ "ldap", "token" ]
}

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.

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

• [ 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"           : "urn:c2id:acr:mfa",
  "amr"           : [ "ldap", "token" ],
  "creation_time" : 1234567,
  "max_life"      : 20160,
  "auth_life"     : 1440,
  "max_idle"      : 15,
  "data"          : { "name"     : "Alice Adams",
                      "email"    : "[email protected]",
                      "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

Indicates the session quota for the requested subject has been exhausted.

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

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

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