PingOne Platform APIs

Sessions

The Sessions service enables you to create and manage sessions for either specified or unspecified (anonymous) users. Anonymous sessions are short-lived sessions that are created while the user authentication process occurs.

Session token cookies can be handled through a browser or, for non-browser authentication flows, in the same manner as a browser, by saving the cookies when returned in an HTTP response from PingOne, and including the cookies on subsequent requests. Whenever possible, use the cookie handling features of the development platform, HTTP client library, or both.

Refer to User Sessions for interfaces on the Users endpoint, and Best Practices: Session Management for best practices.

PingOne sessions have the following characteristics:

  • Sessions are created (always) when a user signs on through PingOne and an existing session does not exist for the client.

  • A session is tied to all applications that the user signed into on that client (browser).

  • Sessions are identified through a session cookie when a user signs on (calls the authorize endpoint).

  • Sessions are associated with an entire SSO session, which includes all applications using the session.

  • A sign-off action terminates the entire SSO session and logs the user out of all applications using the session.

Sign-off and sessions

When the GET /{{envID}}/as/signoff endpoint is invoked, the sign-off operation ends the user’s SSO session, which signs them out of all applications using that session. This endpoint can take an id_token_hint parameter to provide information about the user’s current authenticated session. The session token must be an id_token type to complete the sign-off action successfully.

For more information about setting an application’s responseTypes property to include an id_token, refer to Application Operations in the PingOne Platform API Reference.

For more information, refer to Signoff in the PingOne Platform Auth Reference.

Token revocation and sessions

When the POST /{{envID}}/as/revoke endpoint is invoked, the token revocation operation revokes the specified token, but leaves the SSO session intact. This endpoint revokes tokens of type access_token and refresh_token. It does not support revocation of tokens of type id_token.

The tokens to be revoked must be an access_token or refresh_token for a custom resource. Tokens issued for the PingOne API resource may not be revoked.

For more information, refer to Token Revocation in the PingOne Platform Auth API Reference.

Session tokens and PingOne flows

For PingOne flows, the session token cookies establish the user’s authentication session, and maintain the flow session, allowing the flow to redirect back to the authorization server to get the token.

For flows started through the Read Flow endpoint, a session token cookie is set only after the identity of the user has been partially established. For example, if the sign-on policy specifies identifier first and MFA actions, the cookie is set after the user is identified through a user lookup action, and the user supplies the correct password. For a flow initiated in a browser that already has a valid session token cookie, calling the flow requires the session token cookie, which can be passed in as a request header.

Typical authentication flow for the Sessions service

Typical sessions authentication flow

Session data model

Property Type Required? Mutable? Description

activeAt

Date

Required

Mutable

The time of last user activity for this session (such as, completing a flow, or an application activity like validating a token).

browser.name

String

N/A

Read-only

The name of the browser.

browser.version

String

N/A

Read-only

The version of the browser.

createdAt

Date

N/A

Read-only

The time the resource was created.

device.type

String

N/A

Read-only

The type of remote device.

environment.id

String

N/A

Read-only

The UUID for the environment.

expiresAt

Date

N/A

Read-only

The date and time the session will expire, based on the values for 'idleTimeoutInMinutes' and activeAt.

id

String

N/A

Read-only

The unique identifier for the session.

idleTimeoutInMinutes

Integer

Optional (for POST)

Mutable

This is required for a PUT operation. The maximum idle time in minutes after which the session will become invald. This is used to evaluate expiresAt, based on the activeAt value. For POST operations to create a session, the idle timeout for an anonymous session defaults to 30 minutes (the maximum for anonymous sessions). The idle timeout for user-specified sessions defaults to 30 days, with a maximum of 365 days. The minimum idle timeout value for any session is 1 minute. Sessions are automatically removed after the idle timeout.

lastSignOn

Object

Required

Mutable

Contains information about the most recent sign-on events. Null if the user isn’t identified.

lastSignOn.at

String

N/A

Read-only

The last time the user signed on using one or more authenticators.

lastSignOn.remoteIp

String

Required

Mutable

The IP address of the remote device used during the last sign-on.

lastSignOn.policy

Object

N/A

Read-only

The Flow Policy UUID.

lastSignOn.policy.id

String

N/A

Read-only

The Policy associated with the last completed sign-on by the lastSignOn.authenticator.

lastSignOn.policy.type

String

N/A

Read-only

This is either DAVINCI or PINGONE.

lastSignOn.authenticators

String[]

Required

Mutable

The authenticators used during the last sign-on.

lastSignOn.withAuthenticator

Map

Required

Mutable

Details for all authenticators used in a session, and each authenticator’s most recent sign-on activity.

lastSignOn.withAuthenticator.
authenticator

String

Required

Mutable

The name of the authenticator. The names are generally Authentication Method Reference (AMR) values (such as, pwd, mfa). Values other than AMR values are also supported. The values must be lowercase alpha characters with a maximum length of 10.

lastSignOn.withAuthenticator.
authenticator.at

Date

Required

Mutable

The last time the authenticator was used for sign-on.

lastSignOn.withAuthenticator.
authenticator.policy

Object

Required

Mutable

The Flow Policy UUID.

lastSignOn.withAuthenticator.
authenticator.policy.id

String

Required

Mutable

The Policy associated with the last completed sign-on by the lastSignOn.authenticator. If lastSignOn.withAuthenticator.authenticator.policy.type is PINGONE, this value is a UUID. If lastSignOn.withAuthenticator.authenticator.policy.type is DAVINCI, this value must be 32 lowercase HEX characters.

lastSignOn.withAuthenticator.
authenticator.policy.type

String

Required

Mutable

This is either DAVINCI or PINGONE.

locations

Object[]

N/A

Read-only

Contains the attributes identifying the user location. Only the last 5 locations are maintained.

location.at

Date

N/A

Read-only

The last time the user signed on.

location.remoteIp

String

N/A

Read-only

The IP address of the remote device used during the last sign-on.

location.city

String

N/A

Read-only

The city resolved from the IP address.

location.state

String

N/A

Read-only

The state resolved from the IP address.

location.region

String

N/A

Read-only

The region resolved from the IP address.

location.country

String

N/A

Read-only

The country resolved from the IP address.

operatingSystem.name

String

N/A

Read-only

The name of the operating system.

operatingSystem.version

String

N/A

Read-only

The operating system version.

remoteIp

String

Optional

Mutable

IP address used to perform any activity that extends the session (for activities other than sign-on). If specified, this value is appended to the location history as location.remoteIp, with the activeAt value as the value of location.at. This setting cannot be retrieved in a JSON response directly, as it’s incorporated into location history.

token

String

Optional

Mutable

Required for Update Session By Session Token. The token associated with the session for use with the session token cookie. For a POST operation, you need to specify this if you intend to use any of the /me (Session Token) endpoints. This is a UUID value, and must be unique to the environment. For Update Session By ID, if the session token is specified in the request, it is discarded. The session token can be changed only using Update Session By Session Token.

user.id

String

Optional

Immutable

The UUID for the user associated with the session. This can be null until authentication is completed. Once set, this value can’t be changed. If user.Id is specified for a session, you need to supply authenticator information in the lastSignOn object. If user.id isn’t specified, the lastSignOn object is null, and any values assigned to the lastSignOn object are ignored.

userAgent

String

Required

Mutable

The raw user agent string from the user agent header of the request that initiated the flow.