Sessions
These topics cover concepts and implementation procedures to manage sessions in your AM environment.
This information is written for administrators configuring AM’s authentication and authorization components.
Name changes for ForgeRock products
Product names changed when ForgeRock became part of Ping Identity.
The following name changes have been in effect since early 2024:
Old name | New name |
---|---|
ForgeRock Identity Cloud |
PingOne Advanced Identity Cloud |
ForgeRock Access Management |
PingAM |
ForgeRock Directory Services |
PingDS |
ForgeRock Identity Management |
PingIDM |
ForgeRock Identity Gateway |
PingGateway |
Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.
Introduction to sessions
AM uses two types of tokens that represent an exchange of information, usually interactive, between AM and a user or identity:
-
Authentication sessions, which AM creates to track progress through an authentication tree or chain before the user has authenticated successfully.
-
Sessions, which AM creates after a user has authenticated successfully to manage the user’s or entity’s access to resources.
AM session-related services are stateless unless otherwise indicated; they do not hold any session information local to the AM instances.
Instead, they store session information either in the CTS token store (server-side sessions) or on the client (client-side sessions).
Session location
Sessions have different characteristics depending on where AM stores the sessions.
Both authentication sessions and sessions can be stored on the client or on the server.
Session location is configured at the realm level.
The following table illustrates where AM can store sessions:
In the CTS token store | On the client | In AM’s memory | |
---|---|---|---|
Authentication sessions |
✔(1) |
✔(1) (Default in new installations) |
✔(2) (Default after upgrade) |
Sessions |
✔ (Default) |
✔ |
✖ |
(1) Authentication trees only.
(2) Available for authentication trees and authentication chains.
You can configure different session locations within the same AM deployment to suit the requirements of each realm. You can also configure authentication session location independently of session location. For example, you could configure the same realm for client-side authentication sessions and server-side sessions if it suits your environment. |
Choosing where to store sessions is an important decision you must make by realm. Review the information in the following tables before configuring sessions.
Where to store authentication sessions
Consider the following factors when choosing storage location for authentication sessions.
Server-side authentication sessions | Client-side authentication sessions | In-memory authentication sessions | |
---|---|---|---|
Authentication method |
Authentication trees. |
Authentication trees. |
Authentication trees and authentication chains. |
Session location |
Authoritative source: CTS token store. Sessions might also be cached in AM’s memory for improved performance. |
On the client. No CTS storage or replication overheads. |
In AM server’s memory. |
Load balancer requirements |
None. Session stickiness recommended for performance. |
None. Session stickiness recommended for performance. |
Session stickiness. |
Core token service usage |
Authoritative source for user sessions. Session allowlisting, when enabled. |
Session allowlisting, when enabled. |
None. |
Uninterrupted session availability |
No special configuration required. |
No special configuration required. |
Not available. |
Session security |
Sessions reside in the CTS token store, and are not accessible to users. |
Sessions reside on the client and should be signed and encrypted. |
Sessions reside in AM’s memory, and are not accessible to users. |
Where to store sessions
Consider the following factors when choosing storage location for sessions.
Server-side sessions | Client-side sessions | |
---|---|---|
Hardware |
Higher I/O and memory consumption. |
Higher CPU consumption. |
Logical hosts |
Variable or large number of hosts. |
Variable or large number of hosts. |
Session monitoring |
Available. |
Not available. |
Session location |
Authoritative source: CTS token store. Sessions might also be cached in AM’s memory for improved performance. |
In a cookie in the client. |
Load balancer requirements |
None. Session stickiness recommended for performance. |
None. Session stickiness recommended for performance. |
Uninterrupted session availability |
No special configuration required. |
No special configuration required. |
Core token service usage |
Authoritative source for user sessions. |
Provides session denylisting for logged out sessions. |
Core token service demand |
Heavier. |
Lighter. |
Session security |
Sessions reside in the CTS token store, and are not accessible to users. |
Sessions should be signed and encrypted.(1) |
Cross-domain single sign-on support |
All AM capabilities supported. |
Web agents and Java agents: Supported without restricted tokens. |
(1) Web agents and Java agents support either signing or encrypting client-side sessions, but not both. For more information, refer to Client-side session security and agents.
Server-side sessions
Server-side sessions reside in the CTS token store and can be cached in memory on one or more AM servers to improve system performance.
For information about configuring AM with sticky load balancing, refer to Load balancing. |
If the session request is redirected to an AM server that does not have the session cached, that server must retrieve the session from the CTS token store.
AM stores server-side sessions in the CTS token store and caches sessions in server memory. If a server with cached sessions fails, or if the load balancer in front of AM servers directs a request to a server that does not have the user’s session cached, the AM server retrieves the session from the CTS token store, incurring performance overhead.
AM sends a reference to the session to the client, but the reference does not contain any of the session state information. AM can modify a session during its lifetime without changing the client’s reference to the session.
Advantages of server-side sessions
- Full feature support
-
Server-side sessions support all AM features, such as CDSSO and quotas. Client-side sessions do not. For information about restrictions on AM usage with client-side sessions, refer to Limitations of client-side sessions.
This advantage does not apply to authentication sessions, since they do not provide features. - Session information is not resident in browser cookies
-
With both server-side authentication sessions and sessions, all the information about the session resides in CTS and might be cached on one or more AM servers. With client-side sessions, session information is held in browser cookies. This information could be very long-lived.
Server-side authentication sessions
Server-side authentication sessions are supported for authentication trees only.
During authentication, the session reference is returned to the client after a call to the authenticate
endpoint
and stored in the authId
object of the JSON response.
AM maintains the authenticating user’s session in the CTS token store. After the authentication flow has completed, if the realm to which the user has authenticated is configured for client-side sessions, AM returns session state to the client and deletes the server-side session.
Authentication session allowlisting is an optional feature that maintains a list of in-progress authentication sessions and their progress in the authentication flow to protect against replay attacks. For more information, refer to Authentication session allowlisting.
Server-side sessions
Once the user is authenticated, the session reference is known as an SSO token.
For browser clients, AM sets a cookie in the browser that contains the session reference.
For REST clients, AM returns the session reference in response to calls to the authentication
endpoint.
For more information about session cookies, refer to Session cookies and session security.
Related information: Choose where to store sessions
Configure server-side sessions
By default, AM configures the CTS token store schema in the AM configuration store. Before configuring your AM deployment to use server-side sessions or authentication sessions, we recommend you install and configure an external CTS token store. For more information, refer to Core Token Service (CTS).
Server-side sessions and authentication sessions benefit from configuring sticky load balancing. For more information, refer to Load balancing.
Configure server-side authentication sessions
Configuring storage location for authentication sessions is only supported for authentication trees. Authentication chains always store authentication sessions in AM’s memory. For more information, refer to Introduction to sessions. |
-
In the AM admin UI, go to Realms > Realm Name > Authentication > Settings > Trees.
-
From the Authentication session state management scheme drop-down list, select
CTS
. -
In the Max duration (minutes) field, enter the maximum life of the authentication session in minutes.
-
Save your changes.
-
Go to Configure > Authentication > Core > Security.
-
In the Organization Authentication Signing Secret field, enter a base64-encoded HMAC secret that AM uses to sign the JWT that is passed back and forth between the client and AM during the authentication process. The secret must be at least 128-bits in length.
-
Save your changes.
Configure server-side sessions
-
In the AM admin UI, go to Realms > Realm Name > Authentication > Settings > General.
-
Ensure the Use Client-Side Sessions check box is not selected.
-
Save your changes.
-
Verify that AM creates a server-side session when non-administrative users authenticate to the realm. Perform the following steps:
-
Authenticate to AM as a non-administrative user in the realm you enabled for server-side sessions.
-
In a different browser, authenticate to AM as an administrative user. For example,
amAdmin
. -
Go to Realms > Realm Name > Sessions.
-
Verify that a session is present for the non-administrative user.
-
Client-side sessions
For client-side sessions, AM returns the session state to the client after each request and requires the session state to be passed in with the subsequent request.
For security reasons, you should configure AM to sign and/or encrypt client-side sessions and client-side authentication sessions. Decrypting and verifying the session can be an expensive operation to perform on each request. AM therefore caches the decrypt sequence in memory to improve performance.
For information about configuring AM with sticky load balancing, refer to Load balancing. |
For more information about configuring client-side security, refer to Client-side session security.
Advantages of client-side sessions
- Unlimited horizontal scalability for session infrastructure
-
Client-side sessions provide unlimited horizontal scalability by storing the session state on the client as a signed and encrypted JWT.
Overall performance on hosts using client-side sessions can be easily improved by adding more hosts to the AM deployment.
- Replication-free deployments
-
Global deployments may struggle to keep their CTS token stores synchronized when distances are long and updates are frequent.
Client-side sessions are not constrained by the replication speed of the CTS token store. Therefore, client-side sessions are usually more suitable for deployments where a session can be serviced at any time by any server.
Limitations of client-side sessions
The following limitations in functionality apply to client-side authentication sessions and sessions:
-
Cross-domain single sign-on with restricted tokens (web agents and Java agents)
-
Session signing and encryption (web agents and Java agents)
-
Uncompressed sessions (web agents and Java agents)
(1) Limitation only applies to authenticated sessions
(2) Reduced functionality
Client-side authentication sessions
Client-side authentication sessions are supported for authentication trees only, and are configured by default in new installations.
During authentication, the authentication session state is returned to the client
after each call to the authenticate
endpoint and stored in the authId
object of the JSON response.
After the authentication flow has completed, if the realm to which the user has authenticated is configured for server-side sessions, AM creates the user’s session in the CTS token store. Then, AM attempts to invalidate the client-side authentication session.
Storing authentication sessions on the client allows any AM server to handle the authentication flow at any point in time without load balancing requirements.
Authentication session allowlisting is an optional feature that maintains a list of in-progress authentication sessions and their progress in the authentication flow to protect against replay attacks. For more information, refer to Authentication session allowlisting.
Client-side sessions
For browser-based clients, AM sets a cookie in the browser that contains the session state. When the browser transmits the cookie back to AM, AM decodes the session state from the cookie. For REST-based clients, AM sends the cookie in a header. For more information about session cookies, refer to Session cookies and session security.
Session denylisting is an optional feature that maintains a list of logged out client-side sessions in the CTS token store. For more information about session termination and session denylisting, refer to Session termination.
A user is granted a client-side authentication session while they are completing the authentication tree.
If session denylisting is enabled, this authentication session is "logged out" when the tree is completed, to prevent
replay attacks. This "logging out" adds the authentication session to the session denylist for client-side sessions.
In the CTS store, this takes the form of a SESSION_BLACKLIST token that exists for the life of the authentication session.
|
Related information: Choose where to store sessions
Configure client-side sessions
Client-side sessions require additional setup in your environment to keep the sessions safe, and to ensure both the browser and the web server where AM runs can manage large cookies. Additionally, some AM features cannot be used with client-side sessions. Review the following list before configuring client-side sessions:
-
Ensure the trust store used by AM has the necessary certificates installed:
-
A certificate is required for encrypting JWTs containing client-side sessions.
-
If you are using RS256 signing, then a certificate is required to sign JWTs. (HMAC signing uses a shared secret.)
The same certificates must be stored on all servers participating in an AM site. For more information about managing certificates for AM, refer to Secrets, certificates, and keys.
-
-
Ensure that your users' browsers can accommodate larger session cookie sizes required by client-side sessions. For more information about session cookie sizes, refer to Session cookies and session security.
-
Ensure that the AM web container can accommodate an HTTP header that is 16K in size or greater. When using Apache Tomcat as the AM web container, configure the
server.xml
file’smaxHttpHeaderSize
property to16384
or higher. -
Ensure that your deployment does not require any of the capabilities specified in the list of limitations that apply to client-side sessions.
Configure client-side authentication sessions
Configuring storage location for authentication sessions is only supported for authentication trees. Authentication chains always store authentication sessions in AM’s memory. For more information, refer to Introduction to sessions. |
-
In the AM admin UI, go to Realms > Realm Name > Authentication > Settings > Trees.
-
From the Authentication session state management scheme drop-down list, select
JWT
. -
In the Max duration (minutes) field, enter the maximum life of the authentication session in minutes.
-
Save your changes.
-
Go to Configure > Authentication > Core > Security.
-
In the Organization Authentication Signing Secret field, enter a base64-encoded HMAC secret that AM uses to sign the JWT that is passed back and forth between the client and AM during the authentication process. The secret must be at least 128-bits in length.
-
Save your changes.
-
Protect your client-side authentication sessions.
Refer to Client-side session security.
Configure client-side sessions
-
In the AM admin UI, go to Realms > Realm Name > Authentication > Settings > General.
-
Select the Use Client-Side Sessions check box.
-
Save your changes.
-
Protect your client-side sessions. Refer to Client-side session security.
-
Verify that AM creates a client-side session when non-administrative users authenticate to the realm.
Perform the following steps:
-
Authenticate to the AM admin UI as the top-level administrator (by default, the
amAdmin
user). Note that sessions for the top-level administrator are always stored in the CTS token store. -
Go to Realms > Realm Name > Sessions.
-
Verify that a session is present for the
amAdmin
user. -
In your browser, examine the AM cookie, named
iPlanetDirectoryPro
by default. Copy and paste the cookie’s value into a text file and note its size. -
Start up a private browser session that will not have access to the
iPlanetDirectoryPro
cookie for theamAdmin
user:-
In Chrome, open an incognito window.
-
In Microsoft Edge, start InPrivate browsing.
-
In Firefox, open a new private window.
-
In Safari, open a new private window.
-
-
Authenticate to AM as a non-administrative user in the realm for which you enabled client-side sessions. Be sure not to authenticate as the
amAdmin
user this time. -
In your browser, examine the
iPlanetDirectoryPro
cookie. Copy and paste the cookie’s value into a second text file and note its size. The size of the client-side session cookie’s value should be considerably larger than the size of the cookie used by the server-side session for theamAdmin
user. If the cookie is not larger, you have not enabled client-side sessions correctly. -
Return to the original browser window in which the AM admin UI appears.
-
Refresh the window containing the Sessions page.
-
Verify that a session still appears for the
amAdmin
user, but that no session appears for the non-administrative user in the realm with client-side sessions enabled.
-
In-memory sessions
In-memory sessions reside in AM’s memory. AM sends clients a reference to the session, but the reference does not contain any of the session state information.
Advantages of in-memory sessions
- Faster performance with equivalent host
-
AM servers configured for in-memory authentication sessions can validate more sessions per second per host than those configured for client-side or server-side authentication sessions.
- Session information is not in browser cookies
-
Authentication session information resides in AM’s memory and it is not accessible to users. With client-side sessions, authentication session information is held in browser cookies.
In-memory authentication sessions
In-memory authentication sessions are the only configuration supported for authentication chains. They are also configured by default for authentication trees after an upgrade.
During authentication, the authentication session reference is returned to the client
after a call to the authenticate
endpoint and stored in the authId
object of the JSON response.
AM maintains the user’s authentication session in its memory. After the authentication flow has completed, AM performs the following tasks:
-
If the realm to which the user has authenticated is configured for server-side sessions, AM stores the user’s session in the CTS token store and deletes the authentication session from memory.
-
If the realm to which the user has authenticated is configured for client-side sessions, AM stores the user’s session in a cookie on the user’s browser and deletes the authentication session from memory.
Authentication session allowlisting is an optional feature that maintains a list of in-progress authentication sessions and their progress in the authentication flow to protect against replay attacks. For more information, refer to Authentication session allowlisting.
Deployments where AM stores authentication sessions in memory require sticky load balancing to route all requests pertaining to a particular authentication flow to the same AM server. If a request reaches a different AM server, the authentication flow will start anew. Authentication chains only support storing authentication sessions in memory. Move to authentication trees with server-side or client-side authentication sessions when possible. For information about configuring AM with sticky load balancing, refer to Load balancing. |
Configure in-memory authentication sessions
Authentication chains always store authentication sessions in AM’s memory. Perform the steps in the following procedure only for realms that configure authentication trees:
-
Ensure you have configured AM for sticky load balancing.
For more information, refer to Load balancing.
-
In the AM admin UI, go to Realms > Realm Name > Authentication > Settings > Trees.
-
From the Authentication session state management scheme drop-down list, select
In-Memory
. -
In the Max duration (minutes) field, enter the maximum life of the authentication session in minutes.
-
Save your changes.
-
Go to Configure > Authentication > Core > Security.
-
In the Organization Authentication Signing Secret field, enter a base64-encoded HMAC secret that AM uses to sign the JWT that is passed back and forth between the client and AM during the authentication process. The secret must be, at least, 128-bits in length.
-
Save your changes.
Session termination
AM manages active sessions, allowing single sign-on when authenticated users attempt to access system resources in AM’s control.
AM ensures that user sessions are terminated when a configured timeout is reached, or when AM users perform actions that cause session termination. Session termination effectively logs the user out of all systems protected by AM.
With server-side sessions, AM terminates sessions in four situations:
-
When a user explicitly logs out.
-
When an administrator monitoring sessions explicitly terminates a session.
-
When a session exceeds the maximum time-to-live.
-
When a user is idle for longer than the maximum session idle time.
Under these circumstances, AM responds by removing server-side sessions from the CTS token store and from AM server memory caches. With the user’s session no longer present in CTS, AM forces the user to reauthenticate during subsequent attempts to access resources protected by AM.
When a user explicitly logs out of AM,
AM also attempts to invalidate the iPlanetDirectoryPro
cookie in users' browsers
by sending a Set-Cookie
header with an invalid session ID and a cookie expiration time that is in the past.
In the case of administrator session termination and session timeout,
AM cannot invalidate the iPlanetDirectoryPro
cookie until the next time the user accesses AM.
Session termination differs for client-side sessions.
Since client-side sessions aren’t maintained in the CTS token store, administrators can’t monitor or terminate them.
Because AM does not modify the iPlanetDirectoryPro
cookie for client-side sessions after authentication,
the session idle time isn’t maintained in the cookie.
Therefore, AM does not automatically terminate client-side sessions that have exceeded the idle timeout.
For information about tracking idle time in PingGateway, refer to AmSessionIdleTimeoutFilter.
As with server-side sessions,
AM attempts to invalidate the iPlanetDirectoryPro
cookie from a user’s browser when the user logs out.
When the maximum session time is exceeded,
AM also attempts to invalidate the iPlanetDirectoryPro
cookie in the user’s browser
the next time the user accesses AM.
It’s important to understand that AM cannot guarantee cookie invalidation.
For example, the HTTP response containing the Set-Cookie
header might be lost.
This isn’t an issue for server-side sessions, because a logged-out session no longer exists in the CTS token store,
and a user who attempts to access AM after previously logging out will be forced to reauthenticate.
However, the lack of a guarantee of cookie invalidation is an issue for deployments with client-side sessions.
It could be possible for a logged-out user to have an iPlanetDirectoryPro
cookie.
AM could not determine that the user previously logged out.
Therefore, AM supports a feature that takes additional action when users log out of client-side sessions.
AM can maintain a list of logged out client-side sessions in a session denylist in the CTS token store.
Whenever users attempt to access AM with client-side sessions,
AM checks the session denylist to validate that the user has not, in fact, logged out.
Since AM does not modify client-side session cookies once they are stored in the end user’s browser, and client-side sessions contain, among others, the session maximum time-to-live, it is imperative to protected them against tampering. Refer to Client-side session security for more information.
Enable dynamic session attributes for the realm
To configure the session termination settings for a particular realm, enable the Session service:
-
In the AM admin UI, go to Realms > Realm Name > Services.
-
Check if the
Session
service appears in the list of services configured for the realm.If it doesn’t, click Add a Service and select
Session
from the drop-down list.The Session page appears, showing the Dynamic Attributes tab.
-
Click Save Changes.
Set maximum session time-to-live
When configuring the maximum session time-to-live (TTL), you must balance security and user experience. Depending on your application, it may be acceptable for your users to log in once a month. Financial applications, for example, tend to expire their sessions in less than an hour.
The longer a session is valid, the larger the window during which a malicious user could impersonate a user if they were able to hijack a session cookie.
-
In the AM admin UI, go to Realms > Realm Name > Services > Session > Dynamic Attributes.
Note that you can also change maximum session time settings globally for the AM site at Configure > Sessions > Dynamic Attributes.
-
In the Maximum Session Time field, set a value suitable for your environment.
-
Save your changes.
If you update the maximum session TTL, consider reviewing the expiry time for OAuth 2.0 JWTs according to your business needs. It may be convenient to set them to the same value, but there are times when these values need to be different.
-
To update the JWT lifetime for individual OIDC clients:
-
In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > OpenID Connect.
-
Set OpenID Connect JWT Token Lifetime (seconds) to the same duration as the maximum session TTL (minutes).
This value overrides the JWT lifetime set for the OAuth 2.0 provider.
-
-
To update the JWT lifetime for the OAuth2 Provider service:
-
In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > OpenID Connect.
-
Set OpenID Connect JWT Token Lifetime (seconds) to the same duration as the maximum session TTL (minutes).
-
Set maximum session idle timeout
Consider a user with a valid session navigating through pages or making changes to the configuration. If for any reason they leave their desk and their computer remains open, a malicious user could take the opportunity to impersonate them.
Session idle timeout can help mitigate those situations, by logging out users after a specified duration of inactivity.
Note that session idle timeout can only be used in realms configured for server-side sessions.
-
In the AM admin UI, go to Realms > Realm Name > Services > Session > Dynamic Attributes.
Note that you can also change idle timeout settings globally for the AM site at Configure > Sessions > Dynamic Attributes.
-
On the Maximum Time Idle property, configure a value suitable for your environment.
-
Save your changes.
Configure client-side session denylisting
Session denylisting ensures that users who have logged out of client-side sessions cannot achieve single sign-on without reauthenticating to AM. Session denylisting does not apply to authentication sessions.
-
Make sure that you deployed the Core Token Service (CTS) during AM installation.
The session denylist is stored in the CTS token store.
-
Go to Configure > Global Services, click Session, and locate the Client-Side Sessions tab.
-
Select the Enable Session Denylisting option to enable session denylisting for client-side sessions.
When you configure one or more AM realms for client-side sessions, you should enable session denylisting in order to track session logouts across multiple AM servers.
Changing the value of this property takes effect immediately.
-
Configure the Session Denylist Cache Size property.
AM maintains a cache of logged-out client-side sessions. The cache size should be around the number of logouts expected in the maximum session time. Change the default value of 10,000 when the expected number of logouts during the maximum session time is an order of magnitude greater than 10,000. A session denylist cache configured to a value that’s too low causes AM to read denylist entries from the Core Token Service store instead of obtaining them from cache, which results in a small performance degradation.
Changing the value of this property takes effect immediately.
-
Configure the Denylist Poll Interval property.
AM polls the Core Token service for changes to logged-out sessions if session denylisting is enabled. By default, the polling interval is 60 seconds. The longer the polling interval, the more time a malicious user has to connect to other AM servers in a cluster and make use of a stolen session cookie. Shortening the polling interval improves the security for logged out sessions, but might incur a minimal decrease in overall AM performance due to increased network activity.
Changing the value of this property doesn’t take effect until you restart AM.
-
Configure the Denylist Purge Delay property.
When session denylisting is enabled, AM tracks each logged-out session for the maximum session time plus the denylist purge delay. For example, if a session has a maximum time of 120 minutes and the denylist purge delay is one minute, then AM tracks the session for 121 minutes. Increase the denylist purge delay if you expect system clock skews in a cluster of AM servers to be greater than one minute. There is no need to increase the denylist purge delay for servers running a clock synchronization protocol, such as Network Time Protocol.
Changing the value of this property doesn’t take effect until you restart AM.
-
Click Save Changes.
Enabling or disabling the session denylist, or altering the cache size, takes effect immediately.
Changes to any other session denylist properties don’t take effect until you restart AM.
For detailed information about session service attributes, refer to session configuration.
Session cookies and session security
Sessions require the user or client to be able to hold on to cookies. Cookies provided by AM’s Session Service may contain a JSON Web Token (JWT) with the session or just a reference to where the session is stored.
AM issues a cookie to the user or entity
regardless of the session location for client-side and server-side sessions.
By default, the cookie’s name is iPlanetDirectoryPro
.
For sessions stored in the CTS token store,
the cookie contains a reference to the session in the CTS token store and several other pieces of information.
For sessions stored on the client,
the iPlanetDirectoryPro
cookie contains all the information that would be held in the CTS token store.
Client-side session cookies are comprised of two parts. The first part of the cookie is identical to the cookie used by server-side sessions, which ensures the compatibility of the cookies regardless of the session location. The second part is a JSON Web Token (JWT), and it contains session information, as illustrated below:
-
iPlanetDirectoryPro
cookie for server-side sessions:AQIC...sswo.*AAJ...MA..*
-
iPlanetDirectoryPro
cookie for client-side sessions:AQIC...sswo.*AAJ...MA..*ey....................................fQ.
Note that the examples are not to scale. The size of the client-side session cookie increases when you customize AM to store additional attributes in users' sessions. You are responsible for ensuring that the size of the cookie does not exceed the maximum cookie size allowed by your end users' browsers.
Since the session cookie is either a pointer to the actual user session or the session itself, you must configure AM to secure the session cookie against hijacking, session tampering, and other security concerns.
For example, terminating a session effectively logs the user or entity out of all realms, but the way AM terminates sessions has security implications depending on where AM stores the sessions. You can also configure the session time-to-live, idle timeout, the number of concurrent sessions for a user, and others.
Related information:
View and manage sessions
The AM admin UI lets the administrator view and manage active server-side user sessions by realm by going to Realms > Realm Name > Sessions.
To search for active sessions, enter a username in the search box. AM retrieves the sessions for the user and displays them within a table. If no active server-side session is found, AM displays a session not found message.
You can end any sessions—except the current amAdmin
user’s session—by selecting it
and clicking the Invalidate Selected button.
As a result, the user has to authenticate again.
Deleting a user does not automatically remove any of the user’s server-side sessions. After deleting a user, check for any sessions for the user and remove them on the Sessions page. |
Use the REST API for advanced functionality regarding sessions. |
Manage sessions using REST
To manage sessions using REST, send requests to the /json/sessions
endpoint, as shown in the following examples.
Get information about sessions
To get information about a session, send an HTTP POST request to the /json/sessions/
endpoint,
using the getSessionInfo
action.
This action returns information about the session token provided in the
iPlanetDirectoryPro
header by default. To get information about a different session token, include it in the POST body
as the value of the tokenId
parameter.
For information on retrieving custom session properties:
|
The following example shows an administrative user passing their session token in the iPlanetDirectoryPro
header,
and the session token of the demo
user as the value of the tokenId
:
$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=4.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…NX*1*" }' \
'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=getSessionInfo'
{
"username": "demo",
"universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
"realm": "/",
"latestAccessTime": "2020-02-21T14:31:18Z",
"maxIdleExpirationTime": "2020-02-21T15:01:18Z",
"maxSessionExpirationTime": "2020-02-21T16:29:56Z",
"properties": {
"AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932"
}
}
The getSessionInfo
action does not refresh the session idle timeout.
To obtain session information about a server-side session and reset the idle timeout,
use the getSessionInfoAndResetIdleTime
action, as follows:
$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…NX*1*" }' \
'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=getSessionInfoAndResetIdleTime'
{
"username": "demo",
"universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
"realm": "/",
"latestAccessTime": "2020-02-21T14:32:49Z",
"maxIdleExpirationTime": "2020-02-21T15:02:49Z",
"maxSessionExpirationTime": "2020-02-21T16:29:56Z",
"properties": {
"AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932"
}
}
|
Validate sessions
To check if a session token is valid, send an HTTP POST request to the /json/sessions/
endpoint with the validate
action. Provide the session token in the POST data as the value of the tokenId
parameter.
Provide the session token of an administrative user in the iPlanetDirectoryPro
header.
If you don’t specify a tokenId , this request validates the session in the iPlanetDirectoryPro header.
|
The following example shows an administrative user, such as amAdmin
,
validating a session token for the demo
user:
$ curl \
--request POST \
--header "Content-type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.0, protocol=1.0" \
--data '{ "tokenId": "BXCCq…NX*1*" }' \
'https://openam.example.com:8443/openam/json/realms/root/sessions?_action=validate'
If the session token is valid, the user ID and its realm is returned:
{
"valid": true,
"sessionUid": "c888fe06-dcb4-43e9-b74a-db838c163aa6-164702",
"uid": "bjensen",
"realm": "/alpha"
}
By default, validating a session resets the session’s idle time,
which triggers a write operation to the Core Token Service token store.
To avoid this, include refresh=false
, for example, validate&refresh=false
.
Refresh server-side sessions
To reset the idle time of a server-side session, send an HTTP POST request to the /json/sessions/
endpoint, with the
refresh
action. This action refreshes the session token provided in the iPlanetDirectoryPro
header by default.
To refresh a different session token, include it in the POST body as the value of the tokenId
query parameter.
The following example shows an administrative user passing their session token in the iPlanetDirectoryPro
header,
and bjensen’s session token as the tokenId
parameter:
$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq…NX*1*" }' \
'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=refresh'
{
"uid": "bjensen",
"realm": "/alpha",
"idletime": 0,
"maxidletime": 30,
"maxsessiontime": 120,
"maxtime": 6171
}
On success, AM resets the idle time for the server-side session, and returns timeout details of the session.
|
Invalidate sessions
To invalidate a session, send an HTTP POST request to the /json/sessions/
endpoint with the logout
action.
This action invalidates the session token provided in the iPlanetDirectoryPro
header by default:
$ curl \
--request POST \
--header "Content-type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/sessions/?_action=logout'
{
"result": "Successfully logged out"
}
On success, AM invalidates the session and returns a success message.
If the token is not valid and cannot be invalidated an error message is returned:
{
"result": "Token has expired"
}
An administrative user can invalidate the session of another authenticated user by providing the session token as the
value of the tokenId
query parameter.
This example shows an administrative user passing their session token in the iPlanetDirectoryPro
header and
invalidating bjensen’s session by passing her session token in the tokenId
parameter:
$ curl \
--request POST \
--header "Content-type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq…NX*1*" }' \
'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=logout'
{
"result": "Successfully logged out"
}
Invalidate specific sessions
To invalidate specific sessions for a user, first obtain a list of the user’s active sessions.
Send an HTTP GET request to the /json/sessions/
endpoint, using the SSO token of
an administrative user, such as amAdmin
as the value of the iPlanetDirectoryPro
header.
Use a queryFilter
to specify the name of the user and the realm to search.
For example, to obtain the list of active sessions for bjensen
in the alpha
realm, the query filter value would be:
username eq "bjensen" and realm eq "/alpha"
The query filter value must be URL-encoded when sent over HTTP. For more information about query filter parameters, refer to Query. |
In the following example, there are two active sessions. Note the value of the sessionHandle
properties.
$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/sessions?_queryFilter=username%20eq%20%22bjensen%22%20and%20realm%20eq%20%22%2Falpha%22'
{
"result": [
{
"username": "bjensen",
"universalId": "id=bjensen,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
"realm": "/alpha",
"sessionHandle": "shandle:ITnOR5S…AA.",
"latestAccessTime": "2022-11-11T09:32:28.265Z",
"maxIdleExpirationTime": "2022-11-11T10:02:28Z",
"maxSessionExpirationTime": "2022-11-11T11:32:28Z"
},
{
"username": "bjensen",
"universalId": "id=bjensen,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org",
"realm": "/alpha",
"sessionHandle": "shandle:JfMui6O…AA.",
"latestAccessTime": "2022-11-11T09:32:24.395Z",
"maxIdleExpirationTime": "2022-11-11T10:02:24Z",
"maxSessionExpirationTime": "2022-11-11T11:32:24Z"
}
],
"resultCount": 2,
"pagedResultsCookie": null,
"totalPagedResultsPolicy": "NONE",
"totalPagedResults": -1,
"remainingPagedResults": -1
}
To log out specific sessions, send an HTTP POST request to the /json/sessions/
endpoint, with the logoutByHandle
action.
Include an array of the session handles to invalidate as values of the sessionHandles
property in the POST body.
Use the SSO token of an administrative user, such as amAdmin
, as the value of the iPlanetDirectoryPro
header.
This example invalidates the sessions returned by the previous query:
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{
"sessionHandles": [
"shandle:ITnOR5S…AA.",
"shandle:JfMui6O…AA."
]
}' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/sessions/?_action=logoutByHandle'
{
"result": {
"shandle:ITnOR5S…AAA.": true,
"shandle:JfMui6O…AA.": true
}
}
Invalidate all sessions for a user
To invalidate (log out) all sessions for a user, send an HTTP POST request to the /json/sessions/
endpoint with the
logoutByUser
action, specifying the username in the request payload.
Provide the session token of an administrative user in the iPlanetDirectoryPro
header. Users can invalidate their
own sessions by providing their session token in the iPlanetDirectoryPro
header and their username in the body of the
request.
This example logs out all bjensen’s sessions:
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=5.1, protocol=1.0" \
--data '{"username": "bjensen"}' \
'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=logoutByUser'
{
"result": true
}
Session invalidation by user works slightly differently for server-side and client-side sessions.
- Server-side sessions
-
Logout by user simply deletes all sessions for that user. This action creates an
AM-SESSION-LOGGED-OUT
event in the activity log and anAM-LOGOUT
event in the authentication log, as with any other session termination. - Client-side sessions
-
When the user logs out, a logout token is created. If there is only one AM instance in the site, the logout token is added to a local cache of that AM instance. If there are multiple AM instances in the site, the other instances poll the CTS a specified interval to update their logout token cache. For more information, refer to the Enable Invalidation of Sessions Based on User Identifier property.
An
AM-LOGOUT-USER-TOKEN
event is created in the activity log when the user is logged out. The action isCREATE
orUPDATE
depending on whether a token for the user being logged out already exists. TheuserId
component of this audit entry is that of the caller, not of the target. For example, if an administrative user logs out another user, theuserId
is that of the administrative user, not that of the user being logged out. TheobjectId
indicates the target of the operation.A
DELETE
event is audited when the logout token expires and is deleted from the CTS.
|
Get and set session properties
Use the REST API to read and update properties on users' sessions. Define the properties you want to set in the session property allowlist service configuration. For information on allowlisting session properties, refer to Session Property Whitelist service.
You can use the REST API to:
-
Get the names of the properties that you can read or update. This is the same set of properties configured in the Session Property Whitelist service.
-
Read and update property values.
The ability to set, change and delete session properties is affected by the session state:
|
Differentiate the user who performs the operation from the session affected by the operation as follows:
-
Specify the session token of the user performing the operation on session properties in the
iPlanetDirectoryPro
header. -
Specify the session token of the user whose session is to be read or modified as the
tokenId
parameter in the body of the REST API call. -
Omit the
tokenId
parameter from the body of the REST API call if the session of the user performing the operation is the same session that you want to read or modify.
The following examples assume that you configured a property named LoginLocation
in the Session Property Whitelist service.
To retrieve the names and values of the properties you can get or set, send an HTTP POST request to the json/sessions
endpoint, with the getSessionProperties
action:
$ curl \
--request POST \
--header "Content-type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq…NX*1*" }' \
'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=getSessionProperties'
{
"LoginLocation": ""
}
To set the value of a session property, send an HTTP POST request to the /json/sessions/
endpoint, with the updateSessionProperties
action. If you do not specify a tokenId
parameter in the request body, the operation
affects the session specified in the iPlanetDirectoryPro
header:
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation":"40.748440, -73.984559"}' \
https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=updateSessionProperties
{
"LoginLocation": "40.748440, -73.984559"
}
To set multiple properties in a single REST API call, specify the list of properties and their values in the JSON payload; for example:
--data '{"property1":"value1", "property2":"value2"}'
To set the value of a session property on another user’s session, specify the session token of the user performing the action in the iPlanetDirectoryPro
header and the session token to be modified as the value of the tokenId
:
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation": "40.748440, -73.984559", "tokenId": "BXCCq…NX*1*"}' \
'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=updateSessionProperties'
{
"LoginLocation": "40.748440, -73.984559"
}
If the user attempting to modify the session does not have sufficient access privileges, the preceding examples result in a 403 Forbidden error.
You cannot set properties internal to AM sessions. If you try to modify an internal property in a REST API call, AM also returns a 403 Forbidden error; for example:
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"AuthLevel":"5", "tokenId": "BXCCq…NX*1*"}' \
'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=updateSessionProperties'
{
"code": 403,
"reason": "Forbidden",
"message": "Forbidden"
}
For a list of the default session properties, refer to Session properties.
Session upgrade
Sessions can be upgraded to provide access to sensitive resources.
Consider a website for a university. Some resources, such as courses and degree catalogs, are free for anyone to access and don’t need to be protected. The university also provides the students with a portal they can use to access their grades. This portal is protected with a policy that requires users to authenticate. To pay tuition, students are required to present additional credentials to increase their authentication level and gain access to these functions.
Allowing authenticated users to provide additional credentials to access sensitive resources is called session upgrade. Session upgrade is AM’s mechanism to perform step-up authentication.
What triggers a session upgrade?
-
An authenticated user being redirected to a URL that has the
ForceAuth
parameter set totrue
. For example,https://openam.example.com:8443/openam/XUI/?realm=/alpha&ForceAuth=true#login
In this case, the user is asked to reauthenticate to the default authentication service in the
alpha
realm.When a new session is created, the old session should no longer be valid. For client-side sessions, invalidating the old session depends on the value of the Enable Session Denylisting configuration option. If this option is
false
(default), then both the old and new sessions are considered valid after the session upgrade. If this option istrue
, the old session is no longer valid -
An authenticated user trying to access a resource protected by a web or Java agent, or a custom policy enforcement point (PEP). In this case, AM sends the agent or PEP an advice that the user must perform one of the following actions:
-
Authenticate at an authentication level greater than the current level
-
Authenticate to a specific service
-
Authenticate to a specific module
The flow of the session upgrade during policy evaluation is as follows:
-
An authenticated user tries to access a resource.
-
The PEP, for example a web or Java agent, sends the request to AM for an authorization decision.
-
AM returns an authorization decision that denies access to the resource, and returns an advice indicating that the user must present additional credentials to access the resource.
-
The policy enforcement point sends the user back to AM for session upgrade.
-
The user provides additional credentials. For example, they may provide a one-time password, swipe their phone screen, or use face recognition.
-
AM authenticates the user.
-
The user can now access the sensitive resource.
-
Session upgrade outcomes
-
Successful. AM performs one of the following actions depending on the type of session configured for the realm:
-
If the realm is configured for server-side sessions, the resulting action depends on the mechanism used to perform session upgrade:
-
When using the
ForceAuth
parameter:-
(Authentication trees only) AM issues new session tokens to users on reauthentication, even if the current session already meets the security requirements.
-
(Authentication chains only) AM doesn’t issue new session tokens on reauthentication, regardless of the security level they are authenticating to. Instead, it updates the session token with the new authentication information, if required.
-
-
When using advices, AM copies the session properties to a new session and hands the client a new session token to replace the original one. The new session reflects the successful authentication to a higher level.
-
-
If the realm is configured for client-side sessions, AM hands the client a new session token to replace the original one. The new session reflects the successful authentication to a higher level.
-
-
Unsuccessful. AM leaves the user session as it was before the attempt at stronger authentication. If session upgrade fails because the login page times out, AM redirects the user’s browser to the success URL from the last successful authentication.
Anonymous sessions can also be upgraded to non-anonymous sessions by using the Anonymous Session Upgrade node. |
Session upgrade prerequisites
-
Configure a PEP, for example, a web or Java agent, that enforces AM policies on a website or application.
AM web and Java agents handle session upgrade without additional configuration because the agents are built to handle AM’s advices. If you build your own PEPs, you must take advices and session upgrade into consideration.
Resources
-
Request policy decisions over REST (For RESTful PEPs).
-
Configure an authorization policy to protect a resource protected by the Java or web agent, or a RESTful PEP.
Example
The following policy allows GET and POST access to the
*://*:*/sample/*
resource to any authenticated user:Figure 2. Authorization Policy Example
To track the session through upgrade, enable the cross-upgrade session reference property, which retains its value throughout the session lifecycle. Enabling this property ensures the session reference is recorded in the audit logs. |
Configure the environment for session upgrade
-
Configure an authentication tree or chain to validate users' credentials during session upgrade.
Authentication trees and chains don’t require additional configuration to perform session upgrade. However, because session upgrade is a mechanism that can be used to grant users access to sensitive information, you should consider configuring a strong authentication method such as multi-factor authentication (MFA). You should also consider how long-lived sessions in your environment are. For example, if users should only have access to the protected resource to perform an operation, such as checking the balance of an account, consider implementing transactional authorization instead.
Learn more in Authentication and SSO.
-
Configure at least one of the following environment conditions in the authentication policy that you created as part of the prerequisites:
Authentication Level (greater than or equal to)
Use this condition to present a list of authentication services (trees or chains) that provide a greater or equal authentication level to the one specified in the condition. The user selects their service of choice if multiple services are able to meet the criteria of the condition. For example, the following policy requires a module that provides authentication level
3
or greater:Figure 3. Session upgrade by authentication levelYou can find more information about configuring the authentication level by authentication module in Authentication levels for chains.
Authentication by Service
Use this condition to specify the chains or authentication trees to which the user needs to use to authenticate. For example, the following policy requires the user to sign on with the
Example
tree:Figure 4. Session upgrade by serviceThe names of the authentication trees and chains are case-sensitive.
Authentication by Module Instance (authentication modules only)
Use this condition to enforce that a user has gone through a specific authentication module. For example, the following policy requires the user to sign on with the
DataStore
module:Figure 5. Session upgrade by module instanceThe examples show simple policy conditions. You can find more information about configuring policies and environment conditions in Policies.
-
Test session upgrade using a browser or REST:
Perform session upgrade with a browser
To upgrade a session using a browser, perform the following steps:
-
Ensure you have performed the tasks in Session upgrade prerequisites and Configure the environment for session upgrade.
-
In a browser, go to your protected resource.
For example,
http://www.example.com:9090/sample
.The agent redirects the browser to the AM login screen.
-
Authenticate to AM as the
demo
user.AM requires additional credentials to grant access to the resource. For example, if you set the policy environment condition to
Authentication by Service
andExample
, you will be required to sign on again as thedemo
user. -
Authenticate as the
demo
user.Providing credentials for a different user will fail.
You can now access the protected resource.
Perform session upgrade over REST
To upgrade a session using REST, perform the following steps:
-
Ensure you have performed the tasks in Session upgrade prerequisites and Configure the environment for session upgrade.
-
Sign on with an administrative user that has permission to evaluate policies, such as
amAdmin
.For example:
$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: amadmin" \ --header "X-OpenAM-Password: password" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…TU3OQ*", "successUrl":"/am/console", "realm":"/alpha" }
You can also assign privileges to a user to evaluate policies.
-
Sign on with the user that should access the resources.
For example, sign on as
bjensen
:$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: bjensen" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…TU3OQ*", "successUrl":"/am/console", "realm":"/alpha" }
-
Request a policy decision from AM for a protected resource, in this case,
http://openam.example.com:9090/sample
.The
iPlanetDirectoryPro
header sets the SSO token for the administrative user, and thesubject
element of the payload sets the SSO token forbjensen
:$ curl --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQIC5wM2…" \ --header "Accept-API-Version:protocol=1.0,resource=2.1" \ --data '{ "resources": [ "http://www.example.com:9090/sample" ], "application": "iPlanetAMWebAgentService", "subject": { "ssoToken": "AQIC5wM…TU3OQ*"} }' \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies?_action=evaluate" [ { "resource":"http://www.example.com:9090/sample", "actions":{ }, "attributes":{ }, "advices":{ "AuthLevelConditionAdvice":[ "3" ] }, "ttl":9223372036854775807 } ]
AM returns an advice, which means that the user must present additional credentials to access that resource.
You can find more information about requesting policy decisions in Request policy decisions over REST.
-
Format the advice as XML, without spaces or line breaks.
The following example is spaced and tabulated for readability purposes only:
<Advices> <AttributeValuePair> <Attribute name="AuthLevelConditionAdvice"/> <Value>3</Value> </AttributeValuePair> </Advices>
The example shows the XML render of a single advice. Depending on the conditions configured in the policy, the advice may contain several lines. Learn more in Policy decision advice.
-
URL-encode the XML advice.
For example:
%3CAdvices%3E%3CAttributeValuePair%3E%3CAttribute%20name%3D%22AuthLevelConditionAdvice%22%2F%3E%3CValue%3E3%3C%2FValue%3E%3C%2FAttributeValuePair%3E%3C%2FAdvices%3E
.Ensure there are no spaces between tags when URL-encoding the advice.
-
Call AM’s
authenticate
endpoint to request information about the advice.Use the following details:
-
Add the following URL parameters:
-
authIndexType=composite_advice
-
authIndexValue=URL-encoded-Advice
-
-
Set the
iPlanetDirectoryPro
cookie as the SSO token for thedemo
user.For example:
$ curl --request POST \ --header "Content-Type: application/json" \ --cookie "iPlanetDirectoryPro=AQIC5wM…TU3OQ*" \ --header "Accept-API-Version: protocol=1.0,resource=2.1" \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=composite_advice&authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E…' { "authId":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZ…", "template":"", "stage":"DataStore1", "header":"Sign in", "callbacks":[ { "type":"NameCallback", "output":[ { "name":"prompt", "value":"User Name:" } ], "input":[ { "name":"IDToken1", "value":"" } ] }, { "type":"PasswordCallback", "output":[ { "name":"prompt", "value":"Password:" } ], "input":[ { "name":"IDToken2", "value":"" } ] } ] }
AM returns information about how the user can authenticate in a callback; in this case, providing a username and password. You can find a list of possible callbacks, and more information about the
/json/authenticate
endpoint in Authenticate over REST.
-
-
Call AM’s
authenticate
endpoint to provide the required callback information.Use the following details:
-
Add the following URL query parameters:
-
authIndexType=composite_advice
-
authIndexValue=URL-encoded-Advice
-
-
Set the
iPlanetDirectoryPro
cookie as the SSO token for thedemo
user. -
Send as data the complete payload AM returned in the previous step, ensuring you provide the requested callback information.
In this example, provide the username and password for the
demo
user in theinput
objects, as follows:$ curl --request POST \ --header 'Content-Type: application/json' \ --header "Accept-API-Version: protocol=1.0,resource=2.1" \ --cookie "iPlanetDirectoryPro=AQIC5wM…TU3OQ*" \ --data '{ "authId":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZ…", "template":"", "stage":"DataStore1", "header":"Sign in", "callbacks":[ { "type":"NameCallback", "output":[ { "name":"prompt", "value":"User Name:" } ], "input":[ { "name":"IDToken1", "value":"demo" } ] }, { "type":"PasswordCallback", "output":[ { "name":"prompt", "value":"Password:" } ], "input":[ { "name":"IDToken2", "value":"Ch4ng31t" } ] } ] } }' \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=composite_advice&authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E…' { "tokenId":"wpU01SaTq4X2x…NDVFMAAlMxAAA.*", "successUrl":"/openam/console", "realm":"/alpha" }
AM returns a new SSO token for the
demo
user.
-
-
Request a new policy decision from AM for the protected resource.
The
iPlanetDirectoryPro
header sets the SSO token for the administrative user, and the subject element of the payload sets the new SSO token for the demo user:$ curl --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQIC5wM2…" \ --header "Accept-API-Version:protocol=1.0,resource=2.1" \ --data '{ "resources":[ "http://www.example.com:9090/sample" ], "application":"iPlanetAMWebAgentService", "subject":{ "ssoToken":"wpU01SaTq4X2x…NDVFMAAlMxAAA.*" } }' \ "https://openam.example.com:8443/openam/json/realms/root/realms/alpha/policies/policies?_action=evaluate" [ { "resource":"http://www.example.com:9090/sample", "actions":{ "POST":true, "GET":true }, "attributes":{ }, "advices":{ }, "ttl":9223372036854775807 } ]
AM returns that
demo
can performPOST
andGET
operations on the resource.