Subject session store API

1. Overview

A core feature of the Connect2id server is the provision of single sign-on (SSO) to client applications. SSO is implemented by creating a session for every successfully authenticated end-user, so that in subsequent OpenID Connect login requests or OAuth 2.0 authorisation requests the user will be spared from having to authenticate again. The user will be asked to re-authenticate when the session expires or when a step-up in the authentication level is requested.

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 typically goes into a cookie in the user's browser.

A new user session is implicitly created when an end-user gets logged in by the web API for handling front-channel OpenID authentication and OAuth 2.0 authorisation requests. The Connect2id server specific web API for direct token retrieval can also implicitly create user sessions.

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 usual 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
Representations Errors

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

  • [ 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_lifemax_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 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"    : "[email protected]",
             "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.

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

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",
  "auth_time"     : 1400491648,
  "creation_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"    : "[email protected]",
                      "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",
    "auth_time"     : 1400491648,
    "creation_time" : 1400491648,
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "acr"           : "http://loa.c2id.com/high",
    "amr"           : [ "pwd", "otp" ],
    "rps"           : [ "eedi8jah" ],
    "data"          : { "email"    : "[email protected]",
                        "login_ip" : "192.168.0.1" }
  },

  "ljSV2OKZsPKidmS6dY7Egw.XYWP6FyOYtF234cFUc6y7Q" : {
    "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" ],
    "rps"           : [ "ahp9xei5", "ioj6agah" ],
    "data"          : { "email"    : "[email protected]",
                        "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.

Note: Individual sessions should be closed via the logout session web API so that front and back-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} 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.

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:

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",
  "auth_time"     : 1400491648,
  "creation_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"    : "[email protected]",
                      "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",
    "auth_time"     : 1400491648,
    "creation_time" : 1400491648,
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "rps"           : [ "eedi8jah" ],
    "data"          : { "email"    : "[email protected]",
                        "login_ip" : "192.168.0.2" }
  },

  "ljSV2OKZsPKidmS6dY7Egw.XYWP6FyOYtF234cFUc6y7Q" : {
    "sub"           : "bob",
    "auth_time"     : 1400568801,
    "creation_time" : 1400568801,
    "max_life"      : 20160,
    "auth_life"     : 10080,
    "max_idle"      : 1440,
    "rps"           : [ "ahp9xei5", "ioj6agah" ],
    "data"          : { "email"    : "[email protected]", 
                        "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:

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:

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:

Success:

  • Code: 204

Errors:

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:

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:

Success:

  • Code: 204

Errors:

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

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

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.

  • 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} 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. Will be automatically fed into the ID tokens issued for the subject of this session, unless feeding of these claims is disabled.

  • [ 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",
  "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,
  "rps"           : [ "eedi8jah", "ahp9xei5", "ioj6agah" ],
  "claims"        : { "roles" : [ "admin", "audit" ] },
  "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

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) 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
Content-Type: application/json

{
  "error"             : "server_error",
  "error_description" : "Internal server error: Check the logs for details"
}