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
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:
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. -
[ skip_last_used_update = false ] {true|false} Optional query parameter, applies when the
SID
header parameter is present, to retrieve an individual session. Whentrue
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. Whenfalse
the last used timestamp of the session will be updated. The default value isfalse
. 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 theSID
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 theSID
header parameter.
Success:
-
Code:
200
or204
-
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 theauth_time
is omitted the authentication timestamp will be set to the current system time. The optionalacr
andamr
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:
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:
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:
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 isfalse
(synchronous purge). Deprecated in v14.7.
Form parameters:
-
[ sessions = true ] {true|false} If
true
all expired sessions will be purged. Iffalse
the expired sessions purge will be skipped. The default istrue
. 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 isfalse
. Since in v14.7. -
[ orphaned_index_keys = false ] {true|false} if
true
all orphaned subject index keys will be purged. Iffalse
the orphaned subject index keys purge will be skipped. The default isfalse
. 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 isfalse
(synchronous purge). Since in v14.7.
Success:
- Code:
204
Errors:
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
anddevice
. Defaults toweb
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