Session status API

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

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”

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

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

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

The session can be refreshed with refresh parameter

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

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

XML Example

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

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:

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

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