Subject session store

1. Overview

The provision of web and device single sign-on (SSO) to client applications is a core function of the Connect2id server. SSO works by creating a session for a successfully authenticated end-user, so that subsequent OpenID Connect login requests or OAuth 2.0 authorisation requests can proceed without an authenticating user interaction. The user is asked to re-authenticate when the session expires or when a step-up in the authentication level is necessary.

The Connect2id server keeps the sessions of the authenticated users in a built-in store. The sessions are keyed by a secure identifier (SID), which for web sessions gets stored in a browser cookie tied to the IdP domain.

A new session is automatically created when an end-user is logged in by the web API for handling front-channel OpenID authentication and OAuth 2.0 authorisation requests. The special web API for direct token issue can also create user sessions.

Every session is bound to a context. This ensures that the SID of a web session cannot be used for device SSO and vice versa.

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

The Connect2id server exposes a RESTful web API for querying, updating and deleting sessions. This API can be used in a number of ways:

Let auxiliary services and front-ends of the IdP, for example a page for the user profile and settings, share the same session.
Logout a user, in a single session or in all existing sessions.
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 standard OpenID Connect / OAuth 2.0 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/subject-auth-life [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] /session-store/rest/v2/purge [POST]
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

Resource to create, retrieve and delete subject sessions.

3.1.1 POST

Creates a new subject session. Returns 201 and a secure unique identifier for the session (SID) on success. The session is deleted automatically from the store when its max session 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.
[ 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:

A JSON object representation of the subject session. The only mandatory member is sub which sets the subject (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 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 recording 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: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw

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.

When a single session is returned (by setting the SID request header), its internal last access timestamp will be updated and its max_idle timeout reset unless the skip_last_used_update query parameter is set.

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).
[ 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.

Query parameters:

[ subject ] {string} Optional query parameter, applies when the SID header parameter is omitted, to retrieve all sessions for the specified subject.
[ ctx ] {string} Optional query parameter, applies when the subject query parameter is specified, to return only sessions with the specified context, for example web or device. Since v16.1.
[ skip_last_used_update = false ] {true|false} Optional query parameter, applies when the SID header parameter is present, to retrieve an individual session. When true the internal timestamp that records the last use of the session will not be updated, leaving the maximum idle time expiration of the session unaffected. When false the last used timestamp of the session will be updated. The default value is false. Note, in a Connect2id server deployment configured for in-memory store and replication clustering of the sessions this query parameter will be ignored and have no effect. Since v15.3.

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: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw

A matching response detailing the attributes of the requested session:

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

{
  "sub"           : "alice",
  "ctx"           : "web",
  "creation_time" : 1400491648,
  "auth_time"     : 1400491648,
  "max_life"      : 20160,
  "auth_life"     : 10080,
  "max_idle"      : 1440,
  "acr"           : "http://loa.c2id.com/high",
  "amr"           : [ "pwd", "otp" ],
  "rps"           : [ "ahp9xei5", "ioj6agah" ],
  "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

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

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

3.1.3 DELETE

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

Note: Individual sessions should be ended via the logout session web API so that front-channel logout notifications get delivered to the concerned OpenID relying parties.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ SID ] The session identifier (SID) to specify an individual session.
[ 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.

Query parameters:

[ subject ] {string} Selects all sessions for a subject to be deleted. Should not be used together with the SID header parameter.
[ all = false ] {true|false} When true causes all sessions to be deleted. Should not be used together with the SID header parameter.
[ quiet = false ] {true|false} When 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.

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 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 delete a single session with the specified SID:

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

Example response:

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

{
  "sub"           : "alice",
  "ctx"           : "web",
  "creation_time" : 1400491648,
  "auth_time"     : 1400491648,
  "max_life"      : 20160,
  "auth_life"     : 10080,
  "max_idle"      : 1440,
  "acr"           : "http://loa.c2id.com/high",
  "amr"           : [ "pwd", "otp" ],
  "rps"           : [ "ahp9xei5", "ioj6agah" ],
  "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

{
  "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw" : {
    "sub"           : "bob",
    "ctx"           : "web",
    "creation_time" : 1400491648,
    "auth_time"     : 1400491648,
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "rps"           : [ "eedi8jah" ],
    "data"          : { "email"    : "bob@wonderland.net",
                        "login_ip" : "192.168.0.2" }
  },

  "ljSV2OKZsPKidmS6dY7Egw.XYWP6FyOYtF234cFUc6y7Q" : {
    "sub"           : "bob",
    "ctx"           : "web",
    "creation_time" : 1400568801,
    "auth_time"     : 1400568801,
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "rps"           : [ "ahp9xei5", "ioj6agah" ],
    "data"          : { "email"    : "bob@wonderland.net",
                        "login_ip" : "192.168.0.3" }
  }
}

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

Resource to 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 session’s internal last access timestamp will be updated and its max_idle timeout reset.

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.
[ 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:

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: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw
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/subject-auth-life

Resource to change the authentication lifetime of a subject session. Since v13.5.

3.3.1 PUT

Changes the subject authentication lifetime (auth_life) of a session.

The session’s internal last access timestamp will be updated and its max_idle timeout reset.

Since v13.5.

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 text/plain.
[ 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:

Integer number representing the new session authentication lifetime in minutes, where -1 means infinite (no timeout) and 0 implies the default lifetime.

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 change the authentication lifetime for a session to 1 week (10080 minutes):

PUT /session-store/rest/v2/sessions/subject-auth-life HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw
Content-Type: text/plain

10080

Example success response, no content is returned:

HTTP/1.1 204 No content

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

Resource to update and delete the optional claims in a subject session.

3.4.1 PUT

Updates the optional claims in a session.

The session’s internal last access timestamp will be updated and its max_idle timeout reset.

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.
[ 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:

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: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw
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.4.2 DELETE

Deletes the optional claims in a subject session.

The session’s internal last access timestamp will be updated and its max_idle timeout reset.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
SID The session identifier (SID).
[ 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.

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: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw

Example success response, no content is returned:

HTTP/1.1 204 No content

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

Resource to update and delete the optional data in a subject session.

3.5.1 PUT

Updates the optional data in a subject session.

The session’s internal last access timestamp will be updated and its max_idle timeout reset.

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.
[ 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:

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: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw
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.5.2 DELETE

Deletes the optional data in a subject session.

The session’s internal last access timestamp will be updated and its max_idle timeout reset.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
SID The session identifier (SID).
[ 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.

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: WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw

Example success response, no content is returned:

HTTP/1.1 204 No content

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

Resource to keep count of the sessions.

3.6.1 GET

Returns the current session count.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ 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.

Query parameters:

[ subject ] {string} Optional query parameter, to count the sessions for the specified subject only.

Success:

Code: 200
Content-Type: text/plain
Body: {integer} The 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.7 /session-store/rest/v2/subjects

Resource to keep track of the subjects with sessions.

3.7.1 GET

Returns a list of the subjects with sessions.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ 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.

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.8 /session-store/rest/v2/subjects/count

Resource to keep count of the subjects with sessions.

3.8.1 GET

Returns the current total subject count.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
[ 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.

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

3.9 /session-store/rest/v2/purge

Resource for forcing a purge of the session store.

3.9.1 POST

Forces a purge of expired subject sessions, and expired and orphaned subject index entries.

The purge call can be used when a Connect2id server deployment has switched to automatic DynamoDB expiration of sessions and there are pre-existing sessions without the “ttl” attribute that can be expired only by Infinispan.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to 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.

Query parameters:

[ async ] {true|false} Optional query parameter, if true the purge will be done asynchronously and an HTTP response will be returned immediately. The default is false (synchronous purge). Deprecated in v14.7.

Form parameters:

[ sessions = true ] {true|false} If true all expired sessions will be purged. If false the expired sessions purge will be skipped. The default is true. Since in v14.7.
[ index = false ] {true|false} If true all expired subject index keys will be purged. false the expired subject index keys purge will be skipped. The default is false. Since in v14.7.
[ orphaned_index_keys = false ] {true|false} if true all orphaned subject index keys will be purged. If false the orphaned subject index keys purge will be skipped. The default is false. Since in v14.7.
[ async = false ] {true|false} If true the purge will be done asynchronously and an HTTP response will be returned immediately. The default is false (synchronous purge). Since in v14.7.

Success:

Code: 204

Errors:

401 Unauthorized
403 Forbidden
500 Internal Server Error

Example request to trigger a default synchronous purge:

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

Example request to trigger an asynchronous purge of the orphaned subject index keys only:

POST /session-store/rest/v2/purge HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/x-www-form-urlencoded

sessions=false&orphaned_index_keys=true&async=true

4. Representations

4.1 Subject authentication

Subject (end-user) authentication. Contains the subject identifier, the authentication timestamp, level and methods (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. Signifies the strength of the authentication.
[ amr ] {string array} List of the Authentication Method References (AMR), omitted if not specified. Indicates the methods employed to authenticate the subject, such as password, OTP, 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. Contains 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.
ctx {string} The session context. A session created with a specific context cannot be used in other contexts. The reserved values are web and device. Defaults to web if not specified when a new subject session is created. Since v16.0.
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.
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.
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} Optional Authentication Context Class Reference (ACR), omitted if not specified. Signifies the strength of the employed authentication methods.
[ amr ] {string array} List of the Authentication Method References (AMR), omitted if not specified. Indicates the methods employed to authenticate the subject, such as password, OTP, biometrics, etc.
[ rps ] {string array} List of OpenID relying parties logged in during the subject session. OAuth 2.0 clients which are issued with an access token but no ID token during the session are not accounted. OpenID relying parties which subsequently submit a logout notification with an ID token hint that identifies them are automatically removed from the list.
[ claims ] {object} Optional OpenID claims about the subject. Made available for automatic inclusion in ID tokens issued for the subject in this session, in accordance with the op.idToken.includeSubjectSessionClaims configuration property. Can also be used as a lightweight claims source for ID tokens and userinfo responses.
[ data ] {object} Optional session data, represented as a JSON object.

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

{
  "sub" : "alice"
}

Example subject session, with all fields specified:

{
  "sub"           : "alice",
  "ctx"           : "web",
  "creation_time" : 1234567,
  "auth_time"     : 12345678,
  "max_life"      : 20160,
  "auth_life"     : 1440,
  "max_idle"      : 15,
  "acr"           : "http://loa.c2id.com/high",
  "amr"           : [ "mfa", "pwd", "otp" ],
  "rps"           : [ "eedi8jah", "ahp9xei5", "ioj6agah" ],
  "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 signalled with the 409 Conflict status code when attempting to create a new session:

The session quota for the subject (end-user) is 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