Session status API - SSO

The session of browser based sessions can be queried and refreshed using both front end (via the user browser) and back end APIs.

Please refer to Checking for the existence of an active session - SSO for information on various session status APIs that are front end based.

Please refer to Timeout configuration - SSO for wider information regarding session handling.

For SAML2 integrations, authentication requests using the isPassive setting enables checking of an active session in the front channel via the IDP without forcing a login if no session exists.

For backchannel requests, the server session status can be checked and refreshed by using the entityID of the application and a session_index issued with every assertion, id_token and userinfo response.

For SAML2, the assertion from the authentication response message contains the attribute SessionIndex in the Assertion/AuthnStatement element and the entityID values is found in the Assertion/Conditions/AudienceRestrictions/Audience value.

For OAuth2 integrations, the id_token and userinfo response contains an OAuth2 extension called session_index.

A server session can also be refreshed using this call - in effect extending the validity time of the server side session.

The session_index value cannot be used to retrieve user information, only for finding out if there is a valid session or not. Thus it is safer than passing an accecss token around.

Session status call format

The /uas/status endpoint takes the following query string parameters using a HTTP GET request:

entityID the entityID or client_id of the application where the user logged in interactively (mandatory)
- This value is typically the azp value in an id_token or userinfo response and matches the OAuth 2.0 ID value in the SSO Management user interface.
sessionIndex - the session_index value from an id_token or userinfo response (mandatory)
refresh - true or false, whether to refresh the master SSO session together with the query (optional, default value is false)
type - response format, valid values are "application/json" or "application/xml" (optional, default value is "application/json")

The response contains:

valid - true or false, is there an active server side session for the five entityID and sessionIndex pair
issueInstant - timestamp of when this status response was regenerated
refresh - true or false, whether the master SSO session was refreshed as a result of this query
entityID - the entityID or client_id used for making the call
sessionIndex - the sessionIndex used in the request
sessionNotOnOrAfter - timestamp of when the SSO server session expires
authnInstant - timestamp of when the user was last authenticated in this session

Date and time formats: For JSON response NumericDate format is used - the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds. For XML dateTime format is used.

JSON Example

The following example is a request for client_id bv3ow90cv5bosicv4stlv0hrxk0bdmruu3ma with session_index _64343acbfe906c61da5acae54b333a1ef014d742:

Example session status request

https://sso.example.com/uas/status?entityID=bv3ow90cv5bosicv4stlv0hrxk0bdmruu3ma&sessionIndex=_64343acbfe906c61da5acae54b333a1ef014d742

The response is by default in JSON format. Other formats are supported if sending the query parameter “type”

Example session status request

https://sso.example.com/uas/status?entityID=bv3ow90cv5bosicv4stlv0hrxk0bdmruu3ma&sessionIndex=_64343acbfe906c61da5acae54b333a1ef014d742&type=application/json

If a server session still exists, the message looks like this:

Response for an active session

{
	"valid":true,
	"issueInstant":1505991099671,
	"refresh":false,
	"entityID":"bv3ow90cv5bosicv4stlv0hrxk0bdmruu3ma",
	"sessionIndex":"_64343acbfe906c61da5acae54b333a1ef014d742",
	"sessionNotOnOrAfter":1505994469875,
	"authnInstant":1505990869766
}

The session can be refreshed with refresh parameter

Refreshing an active session

{
	"valid":true,
	"issueInstant":1505991139500,
	"refresh":true,
	"entityID":"bv3ow90cv5bosicv4stlv0hrxk0bdmruu3ma",
	"sessionIndex":"_64343acbfe906c61da5acae54b333a1ef014d742",
	"sessionNotOnOrAfter":1505994739500,
	"authnInstant":1505990869766
}

If there is no session or the entityID is invalid, the message looks like this:

Response for no active session

{
	"valid":false,
	"issueInstant":1495183121690
}

XML Example

The following example is a request for client_id bv3ow90cv5bosicv4stlv0hrxk0bdmruu3ma with session_index _64343acbfe906c61da5acae54b333a1ef014d742:

Example session status request

https://sso.example.com/uas/status?entityID=bv3ow90cv5bosicv4stlv0hrxk0bdmruu3ma&sessionIndex=_64343acbfe906c61da5acae54b333a1ef014d742&refresh=true&type=application/xml

If a server session still exists, the message looks like this:

Active session status response in XML fomat

<?xml version="1.0" encoding="utf-8"?>
<status xmlns="http://schemas.ubisecure.com/uas/status">
  <valid>true</valid>
  <issueInstant>2017-09-21T11:06:23.587Z</issueInstant>
  <refresh>true</refresh>
  <entityID>bv3ow90cv5bosicv4stlv0hrxk0bdmruu3ma</entityID>
  <sessionIndex>_64343acbfe906c61da5acae54b333a1ef014d742</sessionIndex>
  <sessionNotOnOrAfter>2017-09-21T12:06:23.587Z</sessionNotOnOrAfter>
  <authnInstant>2017-09-21T10:47:49.766Z</authnInstant>
</status>

In XML format. if there is no session or the entityID is invalid, the message looks like this:

Inactive session status response in XML fomat

<?xml version="1.0" encoding="utf-8"?>
  <status xmlns="http://schemas.ubisecure.com/uas/status">
  <valid>false</valid>
  <issueInstant>2017-09-21T11:08:15.114Z</issueInstant>
</status>