Core Token Service (CTS) and sessions in AM/OpenAM

This book provides information on the CTS and sessions in AM/OpenAM, including best practice advice for configuring CTS.


CTS Configuration


Best practice for using Core Token Service (CTS) Affinity based load balancing in AM (All versions) and OpenAM 13.5.1, 13.5.2

The purpose of this article is to provide best practice advice on using CTS Affinity based load balancing in AM/OpenAM. Affinity deployments allow AM/OpenAM to connect to multiple master directory server instances, with each instance acting as the master for a subset of CTS tokens. In this architecture, CTS tokens are described as having an affinity for a given directory server instance.

Overview

The ForgeRock Core Token Service (CTS) is a specific DS/OpenDJ repository used to store and persist AM/OpenAM SSO, OAuth2/OIDC and SAML tokens. In terms of architecture, typical primary/secondary aka active/standby or all active 1:1 AM/OpenAM topologies are adopted for AM/OpenAM to CTS connections (described in the Traditional AM/OpenAM - CTS topology section). Both of these approach have inherent limitations, namely:

  • Active/standby topologies do not maximize available hardware (only the primary node services requests) and horizontal scaling of the CTS pool of servers is not possible.
  • Active/standby topologies require expensive vertically scaled instances under high load.
  • 1:1 all active CTS topologies require stickiness for all session requests to the server which created the token or replication delay becomes a functional issue.

Affinity based load balancing for CTS elegantly resolves these problems.

Topics

This article covers the following topics:

Traditional AM/OpenAM - CTS topology

Assuming CTS connections strings are used; the recommended approach to avoid the need for a load balancer and allow AM/OpenAM to manage its own connections is to typically use one of two AM/OpenAM - CTS topologies - Primary/Secondary (aka Active/Standby) or 1:1 all active. These are described below.

Mode 1 - Primary/Secondary 

All AM/OpenAMs in the pool communicate with a single CTS server. If this server fails, all connections failover to the secondary CTS server and so on. The following topology depicts this architecture:

In this mode, replication delay is not an issue as all traffic hits the primary and as long as replication happens successfully over time; functionality is unaffected.

A connection string for this mode would look like this:

cts1.example.com:1636,cts2.example.com:1636

Issues:

  • In an high load environment, CTS needs to be vertically scaled to ensure a single server can handle all requests. This is extremely costly for both on-prem and cloud based deployments.
  • It does not make efficient use of the available hardware; only one server is handling traffic, while the others are sat idle awaiting primary failure.

Mode 2 - All Active CTS with 1:1 Mapping between AM/OpenAM and CTS nodes

Each AM/OpenAM communicates with its own CTS server, if this node fails it connects to its failover CTS. For example, AM1 connects to CTS1 as its primary with CTS2 as it secondary, AM2 connects to CTS2 as its primary and CTS1 as its secondary. The following topology depicts this architecture:

This mode allows an all active CTS farm to maximize hardware usage. This approach must ensure end-to-end stickiness to the AM/OpenAM node that created the session/token for all interactions to prevent functional issues. If this cannot be ensured, this is not a viable option.

The connection string would look like the following, where the serverID for AM1=01 and AM2=02.

cts1.example.com:1636|01,cts2.example.com:1636|01,cts2.example.com:1636|02, 
cts1.example.com:1636|02 

Issues:

  • An all active architecture like this is highly susceptible to replication delay if stickiness to the AM/OpenAM node that created a given session cannot be guaranteed. DS/OpenDJ replication is based on a “loose” algorithm where all CTS nodes will fully converge over time, but not instantly. This means under high load a token create may hit AM1 and CTS1, however AM2 (which is connected to CTS2) may be hit for the token validate request. If replication has not happened fast enough, the request would error.

What is CTS Affinity based load balancing?

Affinity based load balancing for CTS addresses the key issues highlighted with the more traditional approaches; namely, unlimited horizontal scaling of the CTS pool using smaller, cheaper instances and eliminating functional issues as a result of replication delay.

It does this by making use of the new affinity based load balancing algorithm built into the DS/OpenDJ SDK deployed with AM/OpenAM. For each and every inbound token DN, the SDK creates a hash and allocates the result to a specific CTS DS/OpenDJ instance in the CTS connection string. All AM/OpenAM servers in the pool compute the same hash and thus send the request to the same CTS instance. The next request for another token DN is hashed and may be sent to another CTS instance in the pool and so on. The end result of this is, for each and every token a create occurs on a specific CTS instance (the token origin server) and from that point on all read, update and delete operations will be sent to this same origin server from any AM/OpenAM node. The following topology depicts this architecture:

The DS/OpenDJ SDK also makes sure token creates are spread close to evenly across all CTS nodes in the pool to ensure one CTS server is not overloaded with requests, while the others remain idle. Finally, the DS/OpenDJ SDK is instance aware; if the origin server goes down, the request goes to another in the pool and remains sticky to that CTS instance from then on. Assuming replication has happened there will be no functional impact. When the original CTS server comes back online, requests fail back to that server for any requests where it is the origin servers.

The connection string for affinity simply lists all CTS instances as a comma separate list:

cts1.example.com:1636,cts2.example.com:1636
Caution

It is imperative that all AM/OpenAM servers share the same connection string; affinity will fail if each AM/OpenAM server changes the ordering of the connection string.

What are the advantages of CTS Affinity based load balancing?

The primary advantages of CTS Affinity based load balancing over the traditional topologies are:

  • Allows horizontal scaling of the CTS server farm, this is not possible with the traditional topologies.
  • Maximizes available resources by introducing an all active CTS pool of servers.
  • Allows smaller, cheaper nodes for handling CTS traffic with the all active CTS architecture, rather than expensive vertically scaled nodes.
  • Combats replication delay between CTS nodes.
  • Removes the need for end-to-end stickiness to AM/OpenAM for session activities (stickiness is still required for authentication as the AuthID is held in the memory of the AM/OpenAM server that was first hit for the ../json/authenticate call; see OPENAM-8336 (XUI+REST authentication with chains must have sticky load balancing) for further information).

How do you configure CTS Affinity based load balancing?

CTS Affinity based load balancing can be configured using Amster, ssoadm and the console. The console approach is described below:

  1. Build an external CTS repository per the following guides: Installation Guide › CTS Deployment Steps and Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions) .
  2. As the connection string for CTS Affinity needs to be exactly the same across all AM/OpenAM nodes, it is recommended to make the necessary CTS changes at the Server Default level rather than at an instance level to ensure all AM/OpenAM nodes inherit the settings from these defaults. Navigate to: Configure > Server Defaults > CTS.
  3. Configure the following settings:
    • Change the Store Mode to External Token Store.
    • Set the Root Suffix to that configured in step 1.
    • Set Max Connections as appropriate depending on your version: 
      • AM 5 and later: Each AM will create a small number of connections on startup to each CTS node in the pool. As load increases, the number of connections from each AM to each CTS node will increase up to this Max Connection setting. In addition, the first CTS node in the connection string will receive additional connections for the AM Reaper and Blacklisting threads. For example, if Max Connections is set to 20 and there are 2 AM nodes and 2 CTS nodes:
        • AM1 will create a maximum of 20 connections to CTS1* and a maximum of 20 connections to CTS2.
        • AM2 will create a maximum of 20 connections to CTS1* and a maximum of 20 connections to CTS2.
        * CTS1 will however receive additional connections from each AM for the AM Reaper and AM Blacklisting threads, so total connections from AM1 and AM2 to CTS1 will be greater than 20. The Reaper and Blacklisting threads execute on the first CTS node in the connection list only, unless it is down in which case it will create a new set of connections to the next CTS in the CTS connection string list.
      • Pre-AM 5: The Max connections is shared as follows; 1 connection for CTS cleanup Reaper and the rest shared equally between the nodes specified in the connection string. For example, if there are 2 CTS nodes and the connection string is set to 21; 10 connections will be allocated to CTS1; 10 to CTS2 and 1 reserved for the reaper. Load testing will determine optimal value - increase as appropriate. 

 

  1. Click Save Changes
  2. Select the External Store Configuration tab and configure the following settings: 
    • Enable SSL/TLS Enabled if CTS is LDAPS enabled.
    • Define the Connection String with a comma separated list in the format <server FQDN>:<port>. An example connection string is:
      cts1.example.com:1636,cts2.example.com:1636
    • Set the Login Id and Password as appropriate.
    • Enable Affinity Enabled.

  1. Click Save Changes.
  2. Restart the AM/OpenAM node(s). Configuration complete.
Note

If there are problems be sure to check out AM/OpenAM’s debug logs - usually it is something like the bind credentials to connect to CTS are wrong. See How do I enable Message level debugging in AM/OpenAM (All versions) debug files?

What about multi-data center deployments?

As always the optimal AM/OpenAM to CTS topology for a multi-data center (DC) deployment is it depends. For example, is failover across DCs really required? The worst case is a user needs to re-authenticate, there is cost and complexity for DC SSO and OAuth2 session failover. Another consideration may be latency; for example, some customers have dedicated communication lines which guarantee low latency between their DCs; others are subject to public internet conditions. These considerations and more should be factored in when deciding on which CTS architecture to go with.

However, if for example, inter-DC failover for SSO and OAuth2 sessions is required and latency levels are guaranteed, the standard affinity approach could be used, whereby all CTS nodes from both sites are set in the connection string and AM/OpenAM sees the CTS pool as one collection of servers and is unaware that some CTS nodes are local and some remote. Example connection string: 

cts1-dc1.example.com:1636,cts2-dc1.example.com:1636,cts1-dc2.example.com:1636,cts2-dc2.example.com:1636

If however latency levels cannot be guaranteed, then perhaps affinity within a site would be more appropriate, whereby the connection string is set at an instance level for all CTS nodes within a particular DC. However, this approach would be subject to replication delay for token replication between DCs; if the data does not make the remote DC quick enough and stickiness to a particular DC cannot be guaranteed, there is a chance for failure at the token validation phase. Example connection string:

AM1 and AM2 in DC1: cts1-dc1.example.com:1636,cts2-dc1.example.com:1636
AM1 and AM2 in DC2: cts1-dc2.example.com:1636,cts2-dc2.example.com:1636

Multi-DC deployments are complex; ForgeRock Deployment Support Services are available to help customers to architect, design and build in the best way. For more information, please contact ps@forgerock.com   

See Also

Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)

How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm?

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

Installation Guide › Implementing the Core Token Service

Installation Guide › General Recommendations for CTS Configuration

Related Training

N/A

Related Issue Tracker IDs

N/A


Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)

The purpose of this article is to provide best practice advice on configuring an external DS/OpenDJ instance for CTS in AM/OpenAM as a non-admin user. CTS is used to provide session failover in AM/OpenAM.

Introduction

AM/OpenAM uses the CTS as the enabling technology for Session Failover (SFO). CTS leverages DS/OpenDJ to provide persistent and highly available storage for sessions, OAuth2 tokens and SAML2 tokens.

DS/OpenDJ is the only supported directory for CTS. By default CTS uses the same instances of DS/OpenDJ that holds the AM/OpenAM configuration. However, due to the very different profile of token data, an external DS/OpenDJ instance dedicated to CTS traffic is highly recommended as CTS traffic is ~90%+ writes and ~10% reads (unlike most LDAP traffic). Furthermore, the data is highly volatile and hence requires different sizing and tuning parameters to typical LDAP servers, which tend to host fairly static data optimized for reads.

This article guides you on how to configure such an external repository for CTS and integrate with AM/OpenAM using a non-admin user (that is, not the Directory Manager).

Note

Tuning, replication design and sizing is considered out of scope of this article, but must be considered in your environments.

AM 5.x

Key changes to be aware of:

You should refer to Installation Guide › General Recommendations for CTS Configuration for general recommendations about CTS configuration.

OpenAM 13.5.x and earlier

The Affinity type deployment architecture noted above is also available in OpenAM 13.5.1.

You should refer to OpenAM Installation Guide › General Recommendations for CTS Configuration for general recommendations about CTS configuration.

Overview of deployment steps

Note

The following steps were tested against OpenAM 13 with OpenDJ 3 and OpenAM 12 with OpenDJ 2.6.3.

The deployment is broken down into the following steps:

  1. DS/OpenDJ base build and CTS data (container and schema) import
  2. Non-admin user creation and ACI import
  3. CTS index import and rebuild
  4. Console configuration
  5. Testing session failover

In a replicated setup, you need to complete steps 2 and 3 on all servers as the ACI is a global-aci and the index is local to each server. Step 1 is only needed on one server as the schema is replicated by default.

Note

If you are using Amazon Web Services (AWS) to host AM/OpenAM and DS/OpenDJ, you should ensure your DS/OpenDJ servers are replicating prior to installing and configuring AM/OpenAM. If you configure replication after installing AM/OpenAM, you will need to restart AM/OpenAM before your setup functions as expected.

DS/OpenDJ base build and CTS data import

  1. Download the latest DS/OpenDJ zip file from BackStage.
  2. Unzip the DS/OpenDJ zip file and run the setup program. The following parameters have been used for the purpose of this article:
    Initial Root User DN for the Directory Server: cn=Directory Manager
    Password for the Initial Root User: [password]
    Fully Qualified Hostname: cts.example.com
    LDAP Listening Port: 3389
    Administration Connector Port: 5444
    Create Base DNs: Yes
    Provide the backend type: JE
    Base DN for Directory Data: dc=cts,dc=example,dc=com    
    Option for Populating Database: Only create base entry
    Do You Want to Enable SSL: no
    Do You Want to Enable Start TLS: no
    Do You Want To Start The Server: yes
    What Would You Like To Do: Set up server with parameters above
    Providing the backend type is necessary in OpenDJ 3.x; you can use either JE or PDB backend type. The PDB backend type is deprecated in DS 5 and removed in DS 6.
Note

Depending on your requirements, you may need to enable SSL and/or Start TLS.

  1. Check that the DS/OpenDJ instance is operational once the installation has finished.
  2. Navigate to: /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha, open the cts-container.ldif file and do a find and replace; find: @SM_CONFIG_ROOT_SUFFIX@ and replace with the Base DN defined during the DS/OpenDJ installation procedure (for example, dc=cts,dc=example,dc=com).
  3. For DS 5 and later: Update each entry in the cts-container.ldif file to include the following:
    changetype: add
    For example, an updated entry would look similar to this:
    dn: ou=tokens,dc=cts,dc=example,dc=com
    changetype: add
    objectClass: organizationalUnit
    objectClass: top
    ou: tokens
  4. Import the CTS container configuration using the following command depending on your version:
    • DS 5 and later:
      $ ./ldapmodify --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-container.ldif
    • Pre-DS 5:
      $ ./ldapmodify --defaultAdd --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL --filename /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-container.ldif
    You should see the following output:
    Processing ADD request for ou=tokens,dc=cts,dc=example,dc=com
    ADD operation successful for DN ou=tokens,dc=cts,dc=example,dc=com
    Processing ADD request for ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com
    ADD operation successful for DN ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com
    Processing ADD request for ou=famrecords,ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com
    ADD operation successful for DN ou=famrecords,ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com
    
  5. Add the CTS schema into the repository using the following command depending on your version:
    • DS 5 and later:
      $ ./ldapmodify --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-schema.ldif
    • Pre-DS 5:
      $ ./ldapmodify --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL --filename /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-schema.ldif
    You should see the following output:
    Processing MODIFY request for cn=schema
    MODIFY operation successful for DN cn=schema
    
Note

If AM/OpenAM is binding to CTS as the admin user (Directory Manager), you can skip the next section and proceed straight to the section: CTS index import and rebuild.

Non-admin user creation and ACI import

For best practice the use of the admin user is not recommended. Instead, a new and less privileged user than Directory Manager should be created and ACIs applied to allow the user read, search, modify and delete entries. You can also create a different user per AM/OpenAM instance if required.

The following section documents these step.

  1. Create an LDIF file called cts_user.ldif with the CTS user defined. The following sample LDIF creates a user called openam_cts:
    dn: ou=admins,dc=cts,dc=example,dc=com
    changetype: add
    objectClass: top
    objectClass: organizationalunit
    ou: OpenAM Administrator
    
    dn: uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com
    changetype: add
    objectClass: top
    objectClass: person
    objectClass: organizationalPerson
    objectClass: inetOrgPerson
    cn: OpenAM Administrator
    sn: OpenAM
    userPassword: [password]
    ds-privilege-name: update-schema
    ds-privilege-name: subentry-write
    ds-privilege-name: password-reset
    Ensure you replace the [password] tag with the actual password value if you use this sample as the basis of your LDIF file.
  2. Add the new user to the CTS repository using the following command depending on your version:
    • DS 5 and later:
      $ ./ldapmodify --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL .../cts_user.ldif
    • Pre-DS 5:
      $ ./ldapmodify --defaultAdd --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL --filename .../cts_user.ldif
    You should see the following output:
    Processing ADD request for ou=admins,dc=cts,dc=example,dc=com
    ADD operation successful for DN ou=admins,dc=cts,dc=example,dc=com
    Processing ADD request for uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com
    ADD operation successful for DN uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com
    
  3. Add a global ACI to allow the openam_cts user to modify schema using the following command:
    $ ./dsconfig set-access-control-handler-prop --hostname cts.example.com --port 5444 --bindDN "cn=Directory Manager" --bindPassword password --no-prompt --trustAll --add 'global-aci:(target = "ldap:///cn=schema")(targetattr = "attributeTypes || objectClasses")(version 3.0; acl "Modify schema"; allow (write) userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com";)'
  4. Check the Global ACI has been applied using the following command:
    $ ./dsconfig get-access-control-handler-prop  --hostname cts.example.com --port 5444 --bindDN "cn=Directory Manager" --bindPassword password --no-prompt --trustAll --property global-aci
    The following entry should be present:
    "(target = "ldap:///cn=schema")(targetattr = "attributeTypes || objectClasses")(version 3.0; acl "Modify schema"; allow (write) userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com";)",
  5. Create an LDIF file called cts_acis.ldif to add the ACIs to allow the CTS user to create, search, modify, delete and allow persistent search to the CTS repository. A sample LDIF file for this is:
    dn: dc=cts,dc=example,dc=com
    changetype: modify
    add: aci
    aci: (targetattr="*")(version 3.0;acl "Allow entry search"; allow (search, read)(userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)
    aci: (targetattr="*")(version 3.0;acl "Modify entries";  allow (write)(userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)
    aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0;acl "Allow  persistent search"; allow (search, read)(userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)
    aci: (version 3.0;acl "Add config entry"; allow (add)(userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)
    aci: (version 3.0;acl "Delete entries"; allow (delete)(userdn = "ldap:///uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com");)
  6. Import the ACIs into the CTS repository using the following command depending on your version:
    • DS 5 and later:
      $ ./ldapmodify --hostname cts.example.com --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL .../cts_acis.ldif
      
    • Pre-DS 5:
      $ ./ldapmodify --hostname cts.example.com --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL --filename .../cts_acis.ldif
      
    You should see the following output:
    Processing MODIFY request for dc=cts,dc=example,dc=com
    MODIFY operation successful for DN dc=cts,dc=example,dc=com
    

CTS index import and rebuild

  1. Navigate to: /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha, open the cts-indices.ldif file and do a find and replace; find: @DB_NAME@ and replace with the actual DB name (for example, userRoot).
  2. For DS 5 and later: Update each entry in the cts-indices.ldif file to include the following:
    changetype: add
    For example, an updated entry would look similar to this:
    dn: ds-cfg-attribute=coreTokenExpirationDate,cn=Index,ds-cfg-backend-id=userRoot,cn=Backends,cn=config
    changetype: add
    objectClass: top
    objectClass: ds-cfg-backend-index
    ds-cfg-attribute: coreTokenExpirationDate
    ds-cfg-index-type: ordering
  3. Apply the new indexes to the CTS repository depending on your version:
    • DS 5 and later:
      $ ./ldapmodify --port 5444 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-indices.ldif
    • Pre-DS 5:
      $ ./ldapmodify --defaultAdd --port 5444 --bindDN "cn=Directory Manager" --bindPassword password --UseSSL --trustALL --filename /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-indices.ldif
    You should see the following output:
    Processing ADD request for ds-cfg-attribute=coreTokenExpirationDate,cn=Index,ds-cfg-backend-id=userRoot,cn=Backends,cn=config
    ADD operation successful for DN ds-cfg-attribute=coreTokenExpirationDate,cn=Index,ds-cfg-backend-id=userRoot,cn=Backends,cn=config
    Processing ADD request for ds-cfg-attribute=coreTokenUserId,cn=Index,ds-cfg-backend-id=userRoot,cn=Backends,cn=config
    ADD operation successful for DN ds-cfg-attribute=coreTokenUserId,cn=Index,ds-cfg-backend-id=userRoot,cn=Backends,cn=config
    ……………
    ……………
    ……………
    ……………
    ds-cfg-attribute=coreTokenDate04,cn=Index,ds-cfg-backend-id=userRoot,cn=Backends,cn=config
    Processing ADD request for ds-cfg-attribute=coreTokenDate05,cn=Index,ds-cfg-backend-id=userRoot,cn=Backends,cn=config
    ADD operation successful for DN ds-cfg-attribute=coreTokenDate05,cn=Index,ds-cfg-backend-id=userRoot,cn=Backends,cn=config
    
Note

 These indexes may require further tuning subject to environmental load testing when used in production.

  1. Stop the DS/OpenDJ server so that you can perform the next step offline.
  2. Rebuild all indexes and verify using the following commands depending on your version:
    • DS 5 and later:
      $ ./rebuild-index --baseDN "dc=cts,dc=example,dc=com" --rebuildAll --offline
      
      $ ./verify-index --baseDN "dc=cts,dc=example,dc=com"
    • Pre-DS 5:
      $ ./rebuild-index --baseDN "dc=cts,dc=example,dc=com" --rebuildAll
      
      $ ./verify-index --baseDN "dc=cts,dc=example,dc=com"
  3. Restart the DS/OpenDJ server and continue on to the AM/OpenAM console configuration.

AM/OpenAM console configuration

Complete the following configuration steps in the console to integrate the new CTS repository with AM/OpenAM. Alternatively, you can perform these configuration steps using ssoadm as described in How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm?

Assumptions

Configuration

  1. Configure the CTS repository in AM/OpenAM:
    • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > CTS and complete the required details on both tabs.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > CTS, select the External Token Store option and complete the required details.
    The following settings have been used for the purpose of this article; see Reference › Configuration Reference > CTS Token Store (AM 5 and later) or OpenAM Reference › Configuration Reference > CTS (OpenAM 13.5.x and earlier) for further information on these settings:
    Root Suffix: dc=cts,dc=example,dc=com 
    SSL/TLS Enabled: leave this option switched off
    Connection String(s): cts.example.com:3389
    Login Id: uid=openam_cts,ou=admins,dc=cts,dc=example,dc=com
    Password: password
    Max Connections: 10 (this is the default value and should be tuned for Production depending on the authentication profile)
    Heartbeat: 10 (this is the default value and should be tuned for Production depending on the network and physical architecture)
    Affinity Enabled: leave this option switched off (only available in OpenAM 13.5.1 / AM 5 and later)
    
    Click Save to save these changes.
Note

By default, the AM/OpenAM to DS/OpenDJ CTS connection string is inherited by all AM/OpenAM instances. It can also be configured on an instance by instance basis as discussed below, although in an Affinity deployment, all instances must share the same connection string.

  1. In OpenAM 13.5.x and earlier: Configure the secondary configuration instance in OpenAM: 
    • OpenAM 13.5: navigate to: Configure > Global Services > Session > Secondary Configuration Instance. Click New and select the Site from the drop-down list.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > Session > Secondary Configuration Instance. Click New and select the Site from the drop-down list.
    Complete the following settings:
    Session persistence and High Availability Failover: select the Enabled option
    Reduced Crosstalk: select the Enabled option
    Session Logout/Destroy Broadcast: Disabled
    Reduced Crosstalk Purge Delay: 1
    
    Click Add to save these changes.
  2. Restart all AM/OpenAM servers in the site and test your configuration.

Instance specific Connection String (active/passive deployments only)

You can configure the connection string on an instance by instance basis as follows: you must repeat this on all instances:

  • AM / OpenAM 13.5 console: navigate to: Deployment > Servers > [Server Name] > CTS > External Store Configuration, click the padlock against Connection String(s) to remove inheritance and set the connection string for this server. The connection string can also be multi-valued and ordered (using commas) to split CTS traffic by instances, limit traffic by geography and/or specify failover servers.
  • Pre-OpenAM 13.5 console:
    1. Navigate to: Configuration > Servers and Sites > [Server Name] > Inheritance Settings and deselect the Connection String property. Click Save to save these changes. The connection string is now specific to this server.
    2. Navigate to: Configuration > Servers and Sites > [Server Name] > CTS and amend the connection string for this server as required. The connection string can also be multi-valued and ordered (using commas) to split CTS traffic by instances, limit traffic by geography and/or specify failover servers.

For example:

  • Single CTS DS/OpenDJ instance or LB:
    cts.example.com:3389
    In this scenario, all instances of AM/OpenAM will use this address - this address could be a server or a load balancer intelligently managing traffic to multiple DS/OpenDJ CTS instances.
  • Single CTS DS/OpenDJ Instance no LB:
    cts-1.example.com:3389, 
    cts-2.example.com:3389
    
    In this scenario, all instances of AM/OpenAM will go to cts-1 unless that DS/OpenDJ server goes down; in which case, all AM/OpenAM instances will go to cts-2.
  • Multi-DS/OpenDJ Instance per AM/OpenAM Limited to Site:
    cts-1.example.com:3389|server1|site1,
    cts-2.example.com:3389|server1|site1,
    cts-2.example.com:3389|server2|site1,
    cts-1.example.com:3389|server2|site1,
    cts-3.example.com:3389|server1|site2,
    ...
    In this scenario, server 1 of site 1 will go to cts-1 as it's the primary DS/OpenDJ CTS server with cts-2 as its failover. Server 2 in site 1 will go to cts-2 as it's the primary server with cts-1 as its failover. Server 1 in site 2 will go to cts-3 as it's the primary server and so on.
Note

It is clear from these examples that the connection string value is highly configurable and flexible depending on the target environment.

Testing session failover

This article uses two browsers to test failover: Chrome™ and Firefox®. You can use any two browsers or browsers running in incognito mode. Other approaches, such as viewing tokens using an LDAP browser, could also be used.

  1. In Chrome, log into the second AM/OpenAM instance with the amadmin user and click on Sessions.
  2. In Firefox, log into the first AM/OpenAM instance with a test user.
  3. In Chrome, verify the test user exists in the first AM/OpenAM instance’s session list and not in the second instance.
  4. Shutdown the first AM/OpenAM instance.
  5. In Firefox, rewrite the URL to point to the second AM/OpenAM instance. If successful, the browser should not prompt for login.
  6. Confirm the session has failed over - in Chrome, list the sessions on the second instance and verify that the test user’s session is present.
  7. Restart the first AM/OpenAM instance to complete the testing.

See Also

Best practice for using Core Token Service (CTS) Affinity based load balancing in AM (All versions) and OpenAM 13.5.1, 13.5.2

How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm?

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

Core Token Service (CTS) and sessions in AM/OpenAM

Installation Guide › Implementing the Core Token Service

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-10383 (Validation of External CTS store using OpenAM GUI)

OPENAM-10382 (If we set up External CTS wrongly then OpenAM fails catastrophically on start up.)

OPENAM-9762 (Introduce Explicit Health Monitoring for the CTS Reaper)

OPENAM-9738 (Enable CTS segregation to allow each token type to write to a different CTS instance)

OPENAM-8210 (Enhance CTS to persist tokens across multiple OpenDJ instances rather than a single primary OpenDJ instance by some form of sharding)

OPENAM-8202 (If the "Login Id" in the External Store Configuration(CTS) is set to incorrect value,CoreSystem debug log is full of duplicate error)

OPENAM-7466 (Get CTS total tokens using SNMP monitoring fails )

OPENAM-5478 (CTS Reaper auto negotiation)

OPENAM-3510 (all tokens (session,saml,oauth) are stored below the same entry when external CTS is used)

OPENAM-3341 (CTS Root Suffix Issue)


How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm?

The purpose of this article is to provide information on configuring an external Core Token Service (CTS) token store in AM/OpenAM using Amster or ssoadm.

Prerequisites

The external CTS token store must already exist (and you just want to modify its configuration) or you must take steps to prepare the external DS/OpenDJ instance for CTS first if you want to automate the entire process.

The Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)  article guides you through all the steps needed to configure an external DS/OpenDJ instance for CTS. In summary, these steps are:

  1. DS/OpenDJ base build and CTS data (container and schema) import.
  2. Non-admin user creation and ACI import.
  3. CTS index import and rebuild.
  4. AM/OpenAM console configuration.
  5. Testing session failover.

You must complete steps 1 to 3 prior to configuring an external CTS token store in AM/OpenAM. You can then use these instructions to complete step 4 using Amster or ssoadm instead of using the console if you wish.

See Installation Guide › Implementing the Core Token Service for further information.

Note

The CTS token store is the authoritative source for sessions (as of AM 5). This means you will lose access to the console if you misconfigure the CTS store. As such, it is highly recommended that you have up to date backups prior to configuring the external CTS store in case of misconfiguration. See How do I make a backup of configuration data in AM/OpenAM (All versions)? for further information.

Configuring an external CTS token store (Amster)

You can configure an external CTS token store using Amster as follows:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  2. Connect to AM using Amster, for example:
    $ ./amster
    
    am> connect --interactive http://host1.example.com:8080/openam
    Sign in to top level realm
    User Name: amadmin
    Password: **********
  3. Run the read command against the DefaultCtsDataStoreProperties entity to get the current configuration, for example (exclude the --prettyPrint option in Amster 5.x):
    am> read DefaultCtsDataStoreProperties --global --prettyPrint false
    Example response:
    ===> {"amconfig.org.forgerock.services.cts.store.common.section":{"org.forgerock.services.cts.store.location":"default","org.forgerock.services.cts.store.root.suffix":"","org.forgerock.services.cts.store.max.connections":"10","org.forgerock.services.cts.store.page.size":"0","org.forgerock.services.cts.store.vlv.page.size":"1000"},"amconfig.org.forgerock.services.cts.store.external.section":{"org.forgerock.services.cts.store.password":null,"org.forgerock.services.cts.store.loginid":"","org.forgerock.services.cts.store.heartbeat":"10","org.forgerock.services.cts.store.ssl.enabled":"","org.forgerock.services.cts.store.directory.name":""},"_rev":"758717280","_id":"null/properties/cts"}
    
  4. Copy the outputted JSON response and make the following changes:
    • Update the necessary property values to point to the external CTS store: you must set org.forgerock.services.cts.store.location to external, org.forgerock.services.cts.store.root.suffix to a relevant suffix and specify values for the properties in the amconfig.org.forgerock.services.cts.store.external.section. See Entity Reference › CtsDataStoreProperties: update for further information.
    • Remove the end of the response starting with ,"_rev" (leaving the closing curly bracket). The string to remove includes the _id field and possibly others such as _type. You would remove the following from the end of the response in this example:
      ,"_rev":"758717280","_id":"null/properties/cts"
      
    • Amster 5.5 only: Remove the line breaks (for example, using sed or an online tool). 
  5. Run the update command against the DefaultCtsDataStoreProperties entity, passing the edited JSON response in the body. You must enclose the JSON response in single quotes. For example:
    am> update DefaultCtsDataStoreProperties --global --body '{"amconfig.org.forgerock.services.cts.store.common.section":{"org.forgerock.services.cts.store.location":"external","org.forgerock.services.cts.store.root.suffix":"ou=tokens","org.forgerock.services.cts.store.max.connections":"10","org.forgerock.services.cts.store.page.size":"0","org.forgerock.services.cts.store.vlv.page.size":"1000"},"amconfig.org.forgerock.services.cts.store.external.section":{"org.forgerock.services.cts.store.password":"password1","org.forgerock.services.cts.store.loginid":"uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens","org.forgerock.services.cts.store.heartbeat":"10","org.forgerock.services.cts.store.ssl.enabled":"","org.forgerock.services.cts.store.directory.name":"ds1.example.com:389"}}'
  6. Restart the web application container in which AM runs.

Configuring an external CTS token store (ssoadm)

You can configure an external CTS token store using ssoadm as follows:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  2. Create a data file (called DATA_FILE to match the next command) and include the following properties with appropriate values (example values are shown): 
    ​org.forgerock.services.cts.store.directory.name=host.domain:60589
    org.forgerock.services.cts.store.heartbeat=10
    org.forgerock.services.cts.store.location=external
    org.forgerock.services.cts.store.loginid=uid=user
    org.forgerock.services.cts.store.max.connections=10
    org.forgerock.services.cts.store.password=password
    org.forgerock.services.cts.store.root.suffix=dc=example,dc=com
    org.forgerock.services.cts.store.ssl.enabled=false
  3. Enter the following command:
    $ ./ssoadm update-server-cfg -s [serverName] -u [adminID] -f [passwordfile] -D DATA_FILE
    
    replacing [serverName], [adminID] and [passwordfile] with appropriate values. You can use default for [serverName] if you want to change the Default Server Settings.
  4. Restart the web application container in which AM/OpenAM runs.

If you only want to update some of the configuration settings, you can specify just the attributes you want to change. For example, to change the maximum number of connections, you could use the following ssoadm command:

$ ./ssoadm update-server-cfg -s default -u amadmin -f pwd.txt -a org.forgerock.services.cts.store.max.connections=17

See Also

Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

Login to AM/OpenAM console (All versions) fails for amadmin user

FAQ: Installing and using ssoadm in AM/OpenAM

Installation Guide › CTS Configuration

Installation Guide › Implementing the Core Token Service

Setup and Maintenance Guide › Tuning LDAP CTS and Configuration Store Settings

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4673 (External CTS Root DN is hardcoded)


CTS Token Types


How do I know what LDAP attributes are used by CTS tokens in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on the LDAP attributes used by OAuth2 and session tokens in the CTS in AM/OpenAM. With this information, you can perform LDAP searches to retrieve token details from the CTS.

Overview

This is the first article in a two part series, which is designed to help you understand CTS token types (OAuth2 and session) in AM/OpenAM.

See How do I know what token types are stored in the CTS in AM (All versions) and OpenAM 13.x? for the second part.

LDAP searches

You can use the information in these articles to query the CTS using ldapsearch, where this article provides the LDAP attributes and the other article provides the data format. For example, if you want to list user OAuth2 refresh tokens, you would filter on coreTokenString03=<user> and coreTokenString10=refresh_token. For example:

$ ./ldapsearch --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org" "(&(coreTokenString03=demo)(coreTokenString10=refresh_token))"

LDAP attributes used by tokens

The CTS uses a generic LDAP schema for all token types. At present, the schema has undergone three revisions:

  • AM 5 - Additional multi-value attributes and indices.
  • OpenAM 13 - Update coreTokenDate01 index to 'ordering' to improve client-based session blacklist performance.
  • OpenAM 11 - major change from the OpenAM 10.1.0-Xpress schema.

The following sections describe which tokens use which LDAP attributes and for what purpose:

OAuth2 Grant-Set Tokens (AM 6.5 and later)

The following table details which LDAP attributes are used by OAuth2 Grant-Set tokens in AM 6.5 and later, where:

  • Items shown in bold are static values that all tokens of that type have in common (these are used to identify the token type).
  • Items shown in italic describe the type of data that is contained in the given LDAP attribute.
  OAuth2 Grant-Set token
coreTokenUserId  
coreTokenType OAUTH2_GRANT_SET
coreTokenString01  
coreTokenString02  
coreTokenString03 user
coreTokenString04  
coreTokenString05  
coreTokenString06  
coreTokenString07  
coreTokenString08 realm
coreTokenString09 client ID
coreTokenString10  
coreTokenString11  
coreTokenString12  
coreTokenString13  
coreTokenString14  
coreTokenString15  
coreTokenString16  
coreTokenMultiString03 JSON representation of the OAuth2 Grant (access codes, refresh tokens and access tokens)

Stateless OAuth2 Tokens (AM 5.5 and later)

The following table details which LDAP attributes are used by stateless OAuth2 tokens in AM 5.5 and later, where:

  • Items shown in bold are static values that all tokens of that type have in common (these are used to identify the token type).
  • Items shown in italic describe the type of data that is contained in the given LDAP attribute.
  Stateless Access Code token Stateless OAuth2 Grant token
coreTokenUserId   user
coreTokenType OAUTH OAUTH2_STATELESS_GRANT 
coreTokenString01 scopes  
coreTokenString02    
coreTokenString03 user  
coreTokenString04 redirect_uri client ID
coreTokenString05    
coreTokenString06 equal to true when code used scope
coreTokenString07 Bearer  
coreTokenString08 realm  
coreTokenString09 client ID  
coreTokenString10 access_code  
coreTokenString11 nonce realm
coreTokenString12    
coreTokenString13    
coreTokenString14    
coreTokenString15 grant ID  
coreTokenString16    

OAuth2 Tokens (AM 5, 5.1.x and OpenAM 13.x)

The following table details which LDAP attributes are used by OAuth2 tokens in pre-AM 5.5, where:

  • Items shown in bold are static values that all tokens of that type have in common (these are used to identify the token type).
  • Items shown in italic describe the type of data that is contained in the given LDAP attribute.
LDAP Attribute Access Code token Stateless OAuth2 Access token Stateless OAuth2 Refresh token
coreTokenUserId   user user
coreTokenType OAUTH OAUTH_STATELESS OAUTH_STATELESS
coreTokenString01 scopes scopes scopes
coreTokenString02      
coreTokenString03 user user user
coreTokenString04 redirect_uri redirect_uri redirect_uri
coreTokenString05      
coreTokenString06      
coreTokenString07 Bearer    
coreTokenString08 realm realm realm
coreTokenString09 client ID client ID client ID
coreTokenString10 access_code access_token refresh_token
coreTokenString11 nonce Bearer Bearer
coreTokenString12      
coreTokenString13 session token    
coreTokenString14 access code    
coreTokenString15 grant type    
coreTokenString16      

Other OAuth2 Tokens

The following table details which LDAP attributes are used by other OAuth2 tokens in AM/OpenAM, where:

  • Items shown in bold are static values that all tokens of that type have in common (these are used to identify the token type).
  • Items shown in italic describe the type of data that is contained in the given LDAP attribute.
LDAP Attribute Stateful OAuth2 Access token Stateful OAuth2 Refresh token OpenID Connect OPS token OAuth2 Device Code token
coreTokenUserId        
coreTokenType OAUTH OAUTH OAUTH OAUTH
coreTokenString01 scopes scopes    
coreTokenString02        
coreTokenString03 user user    
coreTokenString04 redirect_uri redirect_uri   redirect_uri
coreTokenString05        
coreTokenString06        
coreTokenString07 Bearer Bearer    
coreTokenString08 realm realm   realm
coreTokenString09 client ID client ID   client ID
coreTokenString10 access_token refresh_token   device_code
coreTokenString11        
coreTokenString12        
coreTokenString13        
coreTokenString14       device_code
coreTokenString15 grant type grant type    
coreTokenString16        

Session Tokens

The following table details which LDAP attributes are used by session tokens, where:

  • Items shown in bold are static values that all tokens of that type have in common (these are used to identify the token type).
  • Items shown in italic describe the type of data that is contained in the given LDAP attribute.
LDAP Attribute CTS-based Session token (AM 5 and later) CTS-based Session token (OpenAM 13.x) Client-based Session Blacklist token
coreTokenUserId AM internal user DN OpenAM internal user DN user
coreTokenType SESSION SESSION SESSION_BLACKLIST
coreTokenString01   latest access time server id
coreTokenString02   session token  
coreTokenString03   session handle  
coreTokenString04      
coreTokenString05 session token    
coreTokenString06 session handle    
coreTokenString07      
coreTokenString08      
coreTokenString09      
coreTokenString10      
coreTokenString11 realm    
coreTokenString12      
coreTokenString13      
coreTokenString14      
coreTokenString15      
coreTokenString16      
coreTokenMultiString01 listeners    

See Also

Core Token Service (CTS) and sessions in AM/OpenAM

Installation Guide › Implementing the Core Token Service

Installation Guide › Core Token Service (CTS) Object Identifiers

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I know what token types are stored in the CTS in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on the OAuth2 and session token types stored in the CTS in AM/OpenAM with example token formats included. With this information, you can perform LDAP searches to retrieve token details from the CTS.

Overview

This is the second article in a two part series, which is designed to help you understand CTS token types (OAuth2 and session) in AM/OpenAM.

See How do I know what LDAP attributes are used by CTS tokens in AM (All versions) and OpenAM 13.x? for the first part.

LDAP searches

You can use the information in these articles to query the CTS using ldapsearch, where the other article provides the LDAP attributes and this article provides the data format. For example, if you want to list user OAuth2 refresh tokens, you would filter on coreTokenString03=<user> and coreTokenString10=refresh_token. For example:

$ ./ldapsearch --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org" "(&(coreTokenString03=demo)(coreTokenString10=refresh_token))"

CTS token types

AM 5.5 introduced a number of improvements to the OAuth2 tokens stored in the CTS. The changes made were specifically designed to reduce the number of writes to the CTS, therefore improving the performance of the entire system. 

This article looks at the following CTS token types in detail (the token details apply to all AM and OpenAM 13.x releases unless otherwise stated):

OAuth2 Grant-Set token (AM 6.5 and later)

The OAuth2 Grant-Set token in AM 6.5 and later:

  • Stores the state of multiple authorizations for a given OAuth2 client and resource owner pair. Previously, this state was stored across multiple OAUTH and OAUTH2_STATELESS_GRANT entries.
  • Grant-Set acts as a container for all authorizations:
    • Stateless access code tokens and grant tokens.
    • Stateful access code tokens, access tokens and refresh tokens.
  • Reduces the amount of data stored in the CTS by removing duplication and reduces the number of operations to the CTS.

Stateless Grant-Set token example

dn: coreTokenId=kOrkxaDZ6fYcUrcE0c3PEMFIGNk,ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org
objectClass: frCoreToken
objectClass: top
coreTokenExpirationDate: 20190522143603.155Z
coreTokenId: kOrkxaDZ6fYcUrcE0c3PEMFIGNk
coreTokenMultiString03: {"g":"kOrkxaDZ6fYcUrcE0c3PEMFIGNk.xuPxwKKadXjWvMfKg9WFzvqIOC4","gx":1529062484276,"_s":["openid","profile"],"a":"kOrkxaDZ6fYcUrcE0c3PEMFIGNk.vm6gyeD5t8mF8nTYQ1XQBYTskMo","ax":1528454203638,"aati":"809b87b3-4fad-4ca1-9312-a7f0c669fd6c-34347","ai":true,"au":"https://www.example.com","asi":"UmR8fqI7iG1lmmbQdMBUVXvr2u8.*AAJTSQACMDIAAlNLABxFNXVzNDJlcnZyY1VnV0JQU2ZWbitkbEtiUms9AAR0eXBlAANDVFMAAlMxAAIwMQ..*","ast":"1234","_am":"DataStore","_acr":"0","gt":[]}
coreTokenString03: demo
coreTokenString08: /myRealm
coreTokenString09: OIDCclient1
coreTokenType: OAUTH2_GRANT_SET

Stateful Grant-Set token example

dn: coreTokenId=fx-GTfShtRhmJ89qMNVkxLx339U,ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org
objectClass: frCoreToken
objectClass: top
coreTokenExpirationDate: 20181211094355.401Z
coreTokenId: fx-GTfShtRhmJ89qMNVkxLx339U
coreTokenMultiString03: {"g":"fx-GTfShtRhmJ89qMNVkxLx339U.BwOWUGadbho7rKgCYj5Uq1XuRPc","gx":0,"_s":["openid","profile"],"a":"fx-GTfShtRhmJ89qMNVkxLx339U.0g7urZwlwyK_5gUOlC49t4PVUPo","ax":1540546982500,"aati":"fb479915-c2aa-42b3-ad76-b7eb3de950c5-338537161","ai":true,"au":"http://example.com","asi":"xE5imkWhvI66-6gg1lkGjQgmGdU.*AAJTSQACMDIAAlNLABxJNmxnTElxTXFQdEU0b040RUtzN2JUakV6dEk9AAR0eXBlAANDVFMAAlMxAAIwMQ..*","ast":"1234","_am":"DataStore","_acr":"0","r":"fx-GTfShtRhmJ89qMNVkxLx339U.vXS04FRzuWulPMomSoVDnZvj-6s","rx":1541151662549,"rgt":"authorization_code","rtt":"Bearer","rtn":"refresh_token","rati":"fb479915-c2aa-42b3-ad76-b7eb3de950c5-338537554","ro":"jS474J1xvNZwD-uLeJJeTDWjAzI","_at":1540546862,"_al":0,"gt":[{"t":"fx-GTfShtRhmJ89qMNVkxLx339U.SGEDFJ5BkuuKXKHVeV24_IzoHRg","tx":1540550462814,"tgt":"authorization_code","ts":["openid","profile"],"ttn":"access_token","tati":"fb479915-c2aa-42b3-ad76-b7eb3de950c5-338537841","tck":null}]}
coreTokenString03: demo
coreTokenString08: /myRealm
coreTokenString09: OIDCclient1
coreTokenType: OAUTH2_GRANT_SET

Stateless Access Code token (AM 5.5 and later)

The Stateless Access Code token in AM 5.5 and later:

  • Is used in the OAuth2/OIDC Authorization Code flow and the OIDC Hybrid flow.
  • Provides state for the code that is used by the client to retrieve an access token.
  • Does not contain the session token of the session that generated the request in an indexable attribute, which is different to the equivalent token in previous versions of AM/OpenAM.
  • Uses the value of the access code to form the unique identity of the subsequent grant token.
  • Sets the CoreTokenString06 to true when the code is used and consent is granted, which is different to the equivalent token in previous versions of AM/OpenAM.

Stateless access code example

dn: coreTokenId=4e915f7a-08ec-4c65-915f-2256d6c3a503,ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org
objectClass: top
objectClass: frCoreToken
coreTokenObject: {"redirectURI":["http://example.com"],"clientID":["OIDCclient1"],"ssoTokenId":["mJLebOGs9Y4rAE_JY0uSaS_SVwM.*AAJTSQACMDEAAlNLABwvbWJRSVJ4aGdVcUhHTmNUTkRZVjAxcVl4eFE9AAJTMQAA*"],"auditTrackingId":["a7180708-c39b-4f92-90ea-b2b8bb79ec75-83912"],"tokenName":["access_code"],"authModules":["DataStore"],"code_challenge_method":[],"userName":["demo"],"nonce":["abcdef"],"authGrantId":["f58f19f9-7f3f-43db-be90-466643414143"],"acr":[],"expireTime":["1523281431770"],"scope":["openid","profile"],"claims":[null],"realm":["/myRealm"],"id":["4e915f7a-08ec-4c65-915f-2256d6c3a503"],"state":[],"tokenType":["Bearer"],"code_challenge":[],"issued":["true"]}
coreTokenString11: abcdef
coreTokenString01: openid,profile
coreTokenString10: access_code
coreTokenString04: http://example.com
coreTokenString15: f58f19f9-7f3f-43db-be90-466643414143
coreTokenString03: demo
coreTokenExpirationDate: 20180409134351.770Z
coreTokenString08: /myRealm
coreTokenString09: OIDCclient1
coreTokenId: 4e915f7a-08ec-4c65-915f-2256d6c3a503
coreTokenString06: true
coreTokenString07: Bearer
coreTokenType: OAUTH

Stateless OAuth2 Grant token (AM 5.5 and later)

The Stateless OAuth2 Grant token in AM 5.5 and later:

  • Replaces stateless Access and Refresh tokens in previous versions of AM/OpenAM with a single token indicating that a grant took place.
  • Prevents additional data being written to the CTS if a new access token is issued based on an existing refresh token with an existing grant ID.
  • Uses the grant ID value from the preceding Access code if this token is generated in the OAuth2 Code flow.
  • The grant ID in the stateless OAuth2 JWT matches the DN of the token in the CTS.

Stateless grant token example 

dn: coreTokenId=f58f19f9-7f3f-43db-be90-466643414143,ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org
objectClass: top
objectClass: frCoreToken
coreTokenObject: {}
coreTokenString11: /myRealm
coreTokenString04: OIDCclient1
coreTokenExpirationDate: 20180416144152.757Z
coreTokenUserId: demo
coreTokenId: f58f19f9-7f3f-43db-be90-466643414143
coreTokenString06: openid,profile
coreTokenType: OAUTH2_STATELESS_GRANT

An access token issued from this CTS grant token may look like this:

{
  "sub": "demo",
  "auth_level": 0,
  "auditTrackingId": "610b705d-51a9-43e1-b59a-47b372b9d3ae",
  "iss": "http://am3.example.com:38080/am0551/oauth2/myRealm",
  "tokenName": "access_token",
  "token_type": "Bearer",
  "authGrantId": "f58f19f9-7f3f-43db-be90-466643414143",
  "nonce": "abcdef",
  "aud": "OIDCclient1",
  "nbf": 1523281312,
  "grant_type": "authorization_code",
  "scope": [
    "openid",
    "profile"
  ],
  "auth_time": 1523281311000,
  "realm": "/myRealm",
  "exp": 1523284912,
  "iat": 1523281312,
  "expires_in": 3600,
  "jti": "c35e5c2a-081b-417f-82c5-2708781816d6"
}

Access Code token (AM 5, 5.1.x and OpenAM 13.x)

The Access Code token in pre-AM 5.5:

  • Is used in the OAuth2/OIDC Authorization Code flow and the OIDC Hybrid flow.
  • Provides state for the code that is used by the client to retrieve an access token.
  • Is short lived - the lifetime is defined by Authorization Code Lifetime in the OAuth2 provider.
  • Has the same format in both stateless and stateful OAuth2 modes.
  • Contains a copy of the user SSO token - it is large when used in combination with a realm in client-based sessions mode.

CTS-based session realm token example

dn: coreTokenId=cafdd8cc-b155-464a-a020-15013532578c,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenString11: abcdef
coreTokenObject: {"redirectURI":["http://example.com"],"clientID":["OIDCclient1"],"ssoTokenId":["AQIC5wM2LY4S...kyNgACUzEAAjAx*"],"auditTrackingId":["ff85ab51-f0b6-48e2-85af-bc26feca5a98-280"],"tokenName":["access_code"],"authModules":["DataStore"],"code_challenge_method":[],"userName":["demo"],"nonce":["abcdef"],"authGrantId":["6f10ad62-1be7-4ebe-aeea-81b7c9eb3735"],"acr":[],"expireTime":["1502142089100"],"scope":["openid","profile"],"claims":[null],"realm":["/statefulRealm"],"id":["cafdd8cc-b155-464a-a02015013532578c"],"tokenType":["Bearer"],"code_challenge":[],"issued":["true"]}
coreTokenString01: openid,profile
coreTokenString10: access_code
coreTokenString15: 6f10ad62-1be7-4ebe-aeea-81b7c9eb3735
coreTokenString04: http://example.com
coreTokenString13: AQIC5wM2LY4S...kyNgACUzEAAjAx*
coreTokenString03: demo
coreTokenString08: /statefulRealm
coreTokenExpirationDate: 20170807214129.100Z
coreTokenString09: OIDCclient1
coreTokenId: cafdd8cc-b155-464a-a020-15013532578c
coreTokenString06: true
coreTokenString07: Bearer
coreTokenType: OAUTH

Client-based session realm token example

dn: coreTokenId=60742780-8ad6-4091-a277-8d24bd69938d,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenString11: abcdef
coreTokenObject: {"redirectURI":["http://example.com"],"clientID":["OIDCclient2"],"ssoTokenId":["AQIC5wM2LY4SfcyvKEBc-PhbFqsHH5ULidH1FMscUOKScfg.*AAJTSQACMDIAAlNLABQtMTkyNTUxMDA4NzgzNDA2ODIzNwACUzEAAjAx*eyAidHlwIjogIkpXVCIsICJhbGciOiAiSFMyNTYiIH0.eyAic2VyaWFsaXplZF9zZXNzaW9uIjogIntcInNlY3JldFwiOlwiZDk3Y2FhYTktZmU3ZS00MTBlLWEzNzgtM2Q3ZDAyZWMwNzlmXCIsXCJleHBpcnlUaW1lXCI6MTUwMjE0OTE2OTQwNyxcImxhc3RBY3Rpdml0eVRpbWVcIjoxNTAyMTQxOTY5NDA3LFwic3RhdGVcIjpcInZhbGlkXCIsXCJwcm9wZXJ0aWVzXCI6e1wiQ2hhclNldFwiOlwiVVRGLThcIixcIlVzZXJJZFwiOlwiZGVtb1wiLFwiRnVsbExvZ2luVVJMXCI6XCIvYW0xMzUwL1VJL0xvZ2luP3JlYWxtPSUyRnN0YXRlbGVzc1JlYWxtXCIsXCJzdWNjZXNzVVJMXCI6XCIvYW0xMzUwL2NvbnNvbGVcIixcImNvb2tpZVN1cHBvcnRcIjpcInRydWVcIixcIkF1dGhMZXZlbFwiOlwiMFwiLFwiU2Vzc2lvbkhhbmRsZVwiOlwic2hhbmRsZTpBUUlDNXdNMkxZNFNmY3ctY0hYaWZDR1VIdU1Gb3VxMDlkTnIxQVZMc3hGVUVQay4qQUFKVFNRQUNNRElBQWxOTEFCUXROekUwTnpjNE56VXlOalkyTkRjeU1EZ3lOQUFDVXpFQUFqQXgqXCIsXCJVc2VyVG9rZW5cIjpcImRlbW9cIixcImxvZ2luVVJMXCI6XCIvYW0xMzUwL1VJL0xvZ2luXCIsXCJQcmluY2lwYWxzXCI6XCJkZW1vXCIsXCJTZXJ2aWNlXCI6XCJsZGFwU2VydmljZVwiLFwic3VuLmFtLlVuaXZlcnNhbElkZW50aWZpZXJcIjpcImlkPWRlbW8sb3U9dXNlcixvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCIsXCJhbWxiY29va2llXCI6XCIwMVwiLFwiT3JnYW5pemF0aW9uXCI6XCJvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCIsXCJMb2NhbGVcIjpcImVuX1VTXCIsXCJIb3N0TmFtZVwiOlwiMTI3LjAuMC4xXCIsXCJBdXRoVHlwZVwiOlwiRGF0YVN0b3JlXCIsXCJIb3N0XCI6XCIxMjcuMC4wLjFcIixcIlVzZXJQcm9maWxlXCI6XCJSZXF1aXJlZFwiLFwiQU1DdHhJZFwiOlwiZTNlZWRmMGRmMTY1Y2M5ZjAxXCIsXCJjbGllbnRUeXBlXCI6XCJnZW5lcmljSFRNTFwiLFwiYXV0aEluc3RhbnRcIjpcIjIwMTctMDgtMDdUMjE6Mzk6MjlaXCIsXCJQcmluY2lwYWxcIjpcImlkPWRlbW8sb3U9dXNlcixvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCJ9LFwibWF4VGltZVwiOjEyMCxcInNlc3Npb25UeXBlXCI6XCJ1c2VyXCIsXCJtYXhJZGxlXCI6MzAsXCJtYXhDYWNoaW5nXCI6MyxcIm5ldmVyRXhwaXJpbmdcIjpmYWxzZSxcInNlc3Npb25JRFwiOm51bGwsXCJjbGllbnRJRFwiOlwiaWQ9ZGVtbyxvdT11c2VyLG89c3RhdGVsZXNzcmVhbG0sb3U9c2VydmljZXMsbz1vcGVuYW1cIixcImNsaWVudERvbWFpblwiOlwibz1zdGF0ZWxlc3NyZWFsbSxvdT1zZXJ2aWNlcyxvPW9wZW5hbVwifSIgfQ.2O4EYXM7sPN0YwW78aF2TzjLSEm-NQizNkzOpVCP2mw"],"auditTrackingId":["ff85ab51-f0b6-48e2-85af-bc26feca5a98-330"],"tokenName":["access_code"],"authModules":["DataStore"],"code_challenge_method":[],"userName":["demo"],"nonce":["abcdef"],"authGrantId":["1e70b499-2860-4b06-9bd8-3b202197a3a7"],"acr":[],"expireTime":["1502142089432"],"scope":["openid","profile"],"claims":[null],"realm":["/statelessRealm"],"id":["60742780-8ad6-4091-a277-8d24bd69938d"],"tokenType":["Bearer"],"code_challenge":[],"issued":["true"]}
coreTokenString01: openid,profile
coreTokenString10: access_code
coreTokenString15: 1e70b499-2860-4b06-9bd8-3b202197a3a7
coreTokenString04: http://example.com
coreTokenString13: AQIC5wM2LY4SfcyvKEBc-PhbFqsHH5ULidH1FMscUOKScfg.*AAJTSQACMDIAAlNLABQtMTkyNTUxMDA4NzgzNDA2ODIzNwACUzEAAjAx*eyAidHlwIjogIkpXVCIsICJhbGciOiAiSFMyNTYiIH0.eyAic2VyaWFsaXplZF9zZXNzaW9uIjogIntcInNlY3JldFwiOlwiZDk3Y2FhYTktZmU3ZS00MTBlLWEzNzgtM2Q3ZDAyZWMwNzlmXCIsXCJleHBpcnlUaW1lXCI6MTUwMjE0OTE2OTQwNyxcImxhc3RBY3Rpdml0eVRpbWVcIjoxNTAyMTQxOTY5NDA3LFwic3RhdGVcIjpcInZhbGlkXCIsXCJwcm9wZXJ0aWVzXCI6e1wiQ2hhclNldFwiOlwiVVRGLThcIixcIlVzZXJJZFwiOlwiZGVtb1wiLFwiRnVsbExvZ2luVVJMXCI6XCIvYW0xMzUwL1VJL0xvZ2luP3JlYWxtPSUyRnN0YXRlbGVzc1JlYWxtXCIsXCJzdWNjZXNzVVJMXCI6XCIvYW0xMzUwL2NvbnNvbGVcIixcImNvb2tpZVN1cHBvcnRcIjpcInRydWVcIixcIkF1dGhMZXZlbFwiOlwiMFwiLFwiU2Vzc2lvbkhhbmRsZVwiOlwic2hhbmRsZTpBUUlDNXdNMkxZNFNmY3ctY0hYaWZDR1VIdU1Gb3VxMDlkTnIxQVZMc3hGVUVQay4qQUFKVFNRQUNNRElBQWxOTEFCUXROekUwTnpjNE56VXlOalkyTkRjeU1EZ3lOQUFDVXpFQUFqQXgqXCIsXCJVc2VyVG9rZW5cIjpcImRlbW9cIixcImxvZ2luVVJMXCI6XCIvYW0xMzUwL1VJL0xvZ2luXCIsXCJQcmluY2lwYWxzXCI6XCJkZW1vXCIsXCJTZXJ2aWNlXCI6XCJsZGFwU2VydmljZVwiLFwic3VuLmFtLlVuaXZlcnNhbElkZW50aWZpZXJcIjpcImlkPWRlbW8sb3U9dXNlcixvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCIsXCJhbWxiY29va2llXCI6XCIwMVwiLFwiT3JnYW5pemF0aW9uXCI6XCJvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCIsXCJMb2NhbGVcIjpcImVuX1VTXCIsXCJIb3N0TmFtZVwiOlwiMTI3LjAuMC4xXCIsXCJBdXRoVHlwZVwiOlwiRGF0YVN0b3JlXCIsXCJIb3N0XCI6XCIxMjcuMC4wLjFcIixcIlVzZXJQcm9maWxlXCI6XCJSZXF1aXJlZFwiLFwiQU1DdHhJZFwiOlwiZTNlZWRmMGRmMTY1Y2M5ZjAxXCIsXCJjbGllbnRUeXBlXCI6XCJnZW5lcmljSFRNTFwiLFwiYXV0aEluc3RhbnRcIjpcIjIwMTctMDgtMDdUMjE6Mzk6MjlaXCIsXCJQcmluY2lwYWxcIjpcImlkPWRlbW8sb3U9dXNlcixvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCJ9LFwibWF4VGltZVwiOjEyMCxcInNlc3Npb25UeXBlXCI6XCJ1c2VyXCIsXCJtYXhJZGxlXCI6MzAsXCJtYXhDYWNoaW5nXCI6MyxcIm5ldmVyRXhwaXJpbmdcIjpmYWxzZSxcInNlc3Npb25JRFwiOm51bGwsXCJjbGllbnRJRFwiOlwiaWQ9ZGVtbyxvdT11c2VyLG89c3RhdGVsZXNzcmVhbG0sb3U9c2VydmljZXMsbz1vcGVuYW1cIixcImNsaWVudERvbWFpblwiOlwibz1zdGF0ZWxlc3NyZWFsbSxvdT1zZXJ2aWNlcyxvPW9wZW5hbVwifSIgfQ.2O4EYXM7sPN0YwW78aF2TzjLSEm-NQizNkzOpVCP2mw
coreTokenString03: demo
coreTokenString08: /statelessRealm
coreTokenExpirationDate: 20170807214129.432Z
coreTokenString09: OIDCclient2
coreTokenId: 60742780-8ad6-4091-a277-8d24bd69938d
coreTokenString06: true
coreTokenString07: Bearer
coreTokenType: OAUTH 

Stateless OAuth2 Access token (AM 5, 5.1.x and OpenAM 13.x)

The Stateless OAuth2 Access token in pre-AM 5.5 is:

  • Issued when the OAuth2 provider is in stateless mode (no relationship to client-based sessions).
  • Used in all OAuth2 and OIDC flows.
  • Usually short lived.
  • A JWT containing the information provided by the relevant scopes. Clients can introspect the token without having to visit an additional endpoint; the stored token contains a reference found in the issued JWT.

Stateless access token example

dn: coreTokenId=7fdce636-eede-4f0a-90d3-34e0ea24374c,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenString12: Bearer
coreTokenString01: openid,profile
coreTokenString10: refresh_token
coreTokenString15: 1e70b499-2860-4b06-9bd8-3b202197a3a7
coreTokenString03: demo
coreTokenString08: /statelessRealm
coreTokenExpirationDate: 20170814213929.460Z
coreTokenUserId: demo
coreTokenString09: OIDCclient2
coreTokenId: 7fdce636-eede-4f0a-90d3-34e0ea24374c
coreTokenType: OAUTH_STATELESS

Stateless OAuth2 Refresh token (AM 5, 5.1.x and OpenAM 13.x)

The Stateless OAuth2 Refresh token in pre-AM 5.5 is:

  • Issued when the OAuth2 provider is in stateless mode (no relationship to client-based sessions).
  • Used in the OAuth2 Code flow and the OIDC Code / Hybrid flow.
  • Usually long lived.
  • Exchanged for access tokens by clients.
  • A JWT containing the information provided by the relevant scopes. Clients can introspect the token without having to visit an additional endpoint; the stored token contains a reference found in the issued JWT.

Stateless refresh token example 

dn: coreTokenId=7fdce636-eede-4f0a-90d3-34e0ea24374c,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenString12: Bearer
coreTokenString01: openid,profile
coreTokenString10: refresh_token
coreTokenString15: 1e70b499-2860-4b06-9bd8-3b202197a3a7
coreTokenString03: demo
coreTokenString08: /statelessRealm
coreTokenExpirationDate: 20170814213929.460Z
coreTokenUserId: demo
coreTokenString09: OIDCclient2
coreTokenId: 7fdce636-eede-4f0a-90d3-34e0ea24374c
coreTokenType: OAUTH_STATELESS 

Stateful OAuth2 Access token

The Stateful OAuth2 Access token in AM/OpenAM is:

  • Issued when the OAuth2 provider is not in stateless mode (no relationship to client-based sessions).
  • Used in all OAuth2 and OIDC flows.
  • Typically short lived.

Stateful access token example

dn: coreTokenId=daaa2a39-ffe9-40a0-b0df-71dc6e278628,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenString11: abcdef
coreTokenObject: {"redirectURI":["http://example.com"],"parent":["cafdd8cc-b155-464a-a020-15013532578c"],"clientID":["OIDCclient1"],"auditTrackingId":["ff85ab51-f0b6-48e2-85af-bc26feca5a98-290"],"tokenName":["access_token"],"userName":["demo"],"authGrantId":["6f10ad62-1be7-4ebe-aeea-81b7c9eb3735"],"nonce":["abcdef"],"expireTime":["1502145569132"],"grant_type":["authorization_code"],"scope":["openid","profile"],"realm":["/statefulRealm"],"id":["daaa2a39-ffe9-40a0-b0df-71dc6e278628"],"tokenType":["Bearer"],"refreshToken":["21f89047-4bcf-4d62-853b-d4fa22d632e5"]}
coreTokenString12: authorization_code
coreTokenString01: openid,profile
coreTokenString10: access_token
coreTokenString15: 6f10ad62-1be7-4ebe-aeea-81b7c9eb3735
coreTokenString04: http://example.com
coreTokenString05: 21f89047-4bcf-4d62-853b-d4fa22d632e5
coreTokenString02: cafdd8cc-b155-464a-a020-15013532578c
coreTokenString03: demo
coreTokenString08: /statefulRealm
coreTokenExpirationDate: 20170807223929.132Z
coreTokenString09: OIDCclient1
coreTokenId: daaa2a39-ffe9-40a0-b0df-71dc6e278628
coreTokenString07: Bearer
coreTokenType: OAUTH

Stateful OAuth2 Refresh token

The Stateful OAuth2 Refresh token in AM/OpenAM is:

  • Issued when the OAuth2 provider is not in stateless mode (no relationship to client-based sessions).
  • Used in the OAuth2 Code Grant flow, the Resource Owner Password flow and the OIDC Code / Hybrid flow.
  • Usually long lived.
  • Exchanged for access tokens by clients.

Stateful refresh token example

dn: coreTokenId=21f89047-4bcf-4d62-853b-d4fa22d632e5,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenObject: {"redirectURI":["http://example.com"],"clientID":["OIDCclient1"],"auditTrackingId":["ff85ab51-f0b6-48e2-85af-bc26feca5a98-289"],"tokenName":["refresh_token"],"authModules":["DataStore"],"userName":["demo"],"authGrantId":["6f10ad62-1be7-4ebe-aeea-81b7c9eb3735"],"acr":[],"expireTime":["1502746769129"],"grant_type":["authorization_code"],"scope":["openid","profile"],"realm":["/statefulRealm"],"id":["21f89047-4bcf-4d62-853b-d4fa22d632e5"],"tokenType":["Bearer"]}
coreTokenString12: authorization_code
coreTokenString01: openid,profile
coreTokenString10: refresh_token
coreTokenString15: 6f10ad62-1be7-4ebe-aeea-81b7c9eb3735
coreTokenString04: http://example.com
coreTokenString03: demo
coreTokenString08: /statefulRealm
coreTokenExpirationDate: 20170814213929.129Z
coreTokenString09: OIDCclient1
coreTokenId: 21f89047-4bcf-4d62-853b-d4fa22d632e5
coreTokenString07: Bearer
coreTokenType: OAUTH

OpenID Connect OPS token

The OpenID Connect OPS token in AM/OpenAM:

  • Provides a link between the OIDC ID token and the user session that generated it.
  • Is required for the endSession and checkSession endpoints to function.
  • Can be disabled in the OAuth2 provider. It is good practice to disable this token if you are not using the endSession and checkSession endpoints; doing so can dramatically reduce the load on the CTS.
  • Is issued in the Code or Implicit flow if the openid scope is requested and it is enabled in the OAuth2 provider.
  • Contains a copy of the user SSO token (same as the access code token) - again, it is large when used in combination with a realm in client-based sessions mode.

CTS-based session realm OPS token example

dn: coreTokenId=c23b5787-ace5-43c4-aeb3-369bbf4e07be,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenObject: {"id":["c23b5787-ace5-43c4-aeb3-369bbf4e07be"],"ops":["AQIC5wM2LY4S...kyNgACUzEAAjAx*"],"expireTime":["1502145569141"]}
coreTokenExpirationDate: 20170807223929.141Z
coreTokenId: c23b5787-ace5-43c4-aeb3-369bbf4e07be
coreTokenType: OAUTH

Client-based session realm OPS token example

dn: coreTokenId=938fbe6a-cab6-48fc-ba42-3dbe82af61f3,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenObject: {"id":["938fbe6a-cab6-48fc-ba42-3dbe82af61f3"],"ops":["AQIC5wM2LY4SfcyvKEBc-PhbFqsHH5ULidH1FMscUOKScfg.*AAJTSQACMDIAAlNLABQtMTkyNTUxMDA4NzgzNDA2ODIzNwACUzEAAjAx*eyAidHlwIjogIkpXVCIsICJhbGciOiAiSFMyNTYiIH0.eyAic2VyaWFsaXplZF9zZXNzaW9uIjogIntcInNlY3JldFwiOlwiZDk3Y2FhYTktZmU3ZS00MTBlLWEzNzgtM2Q3ZDAyZWMwNzlmXCIsXCJleHBpcnlUaW1lXCI6MTUwMjE0OTE2OTQwNyxcImxhc3RBY3Rpdml0eVRpbWVcIjoxNTAyMTQxOTY5NDA3LFwic3RhdGVcIjpcInZhbGlkXCIsXCJwcm9wZXJ0aWVzXCI6e1wiQ2hhclNldFwiOlwiVVRGLThcIixcIlVzZXJJZFwiOlwiZGVtb1wiLFwiRnVsbExvZ2luVVJMXCI6XCIvYW0xMzUwL1VJL0xvZ2luP3JlYWxtPSUyRnN0YXRlbGVzc1JlYWxtXCIsXCJzdWNjZXNzVVJMXCI6XCIvYW0xMzUwL2NvbnNvbGVcIixcImNvb2tpZVN1cHBvcnRcIjpcInRydWVcIixcIkF1dGhMZXZlbFwiOlwiMFwiLFwiU2Vzc2lvbkhhbmRsZVwiOlwic2hhbmRsZTpBUUlDNXdNMkxZNFNmY3ctY0hYaWZDR1VIdU1Gb3VxMDlkTnIxQVZMc3hGVUVQay4qQUFKVFNRQUNNRElBQWxOTEFCUXROekUwTnpjNE56VXlOalkyTkRjeU1EZ3lOQUFDVXpFQUFqQXgqXCIsXCJVc2VyVG9rZW5cIjpcImRlbW9cIixcImxvZ2luVVJMXCI6XCIvYW0xMzUwL1VJL0xvZ2luXCIsXCJQcmluY2lwYWxzXCI6XCJkZW1vXCIsXCJTZXJ2aWNlXCI6XCJsZGFwU2VydmljZVwiLFwic3VuLmFtLlVuaXZlcnNhbElkZW50aWZpZXJcIjpcImlkPWRlbW8sb3U9dXNlcixvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCIsXCJhbWxiY29va2llXCI6XCIwMVwiLFwiT3JnYW5pemF0aW9uXCI6XCJvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCIsXCJMb2NhbGVcIjpcImVuX1VTXCIsXCJIb3N0TmFtZVwiOlwiMTI3LjAuMC4xXCIsXCJBdXRoVHlwZVwiOlwiRGF0YVN0b3JlXCIsXCJIb3N0XCI6XCIxMjcuMC4wLjFcIixcIlVzZXJQcm9maWxlXCI6XCJSZXF1aXJlZFwiLFwiQU1DdHhJZFwiOlwiZTNlZWRmMGRmMTY1Y2M5ZjAxXCIsXCJjbGllbnRUeXBlXCI6XCJnZW5lcmljSFRNTFwiLFwiYXV0aEluc3RhbnRcIjpcIjIwMTctMDgtMDdUMjE6Mzk6MjlaXCIsXCJQcmluY2lwYWxcIjpcImlkPWRlbW8sb3U9dXNlcixvPXN0YXRlbGVzc3JlYWxtLG91PXNlcnZpY2VzLG89b3BlbmFtXCJ9LFwibWF4VGltZVwiOjEyMCxcInNlc3Npb25UeXBlXCI6XCJ1c2VyXCIsXCJtYXhJZGxlXCI6MzAsXCJtYXhDYWNoaW5nXCI6MyxcIm5ldmVyRXhwaXJpbmdcIjpmYWxzZSxcInNlc3Npb25JRFwiOm51bGwsXCJjbGllbnRJRFwiOlwiaWQ9ZGVtbyxvdT11c2VyLG89c3RhdGVsZXNzcmVhbG0sb3U9c2VydmljZXMsbz1vcGVuYW1cIixcImNsaWVudERvbWFpblwiOlwibz1zdGF0ZWxlc3NyZWFsbSxvdT1zZXJ2aWNlcyxvPW9wZW5hbVwifSIgfQ.2O4EYXM7sPN0YwW78aF2TzjLSEm-NQizNkzOpVCP2mw"],"expireTime":["1502145569471"]}
coreTokenExpirationDate: 20170807223929.471Z
coreTokenId: 938fbe6a-cab6-48fc-ba42-3dbe82af61f3
coreTokenType: OAUTH 

OAuth2 Device Code token

The OAuth2 Device Code token in AM/OpenAM is:

  • Used to persist the code in the Device Code flow.
  • Typically short lived.
  • In the same format in OAuth2 stateless and stateful modes.

Device code token example

dn: coreTokenId=501905e0-b350-47d5-92cc-161a4291116f,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenObject: {"clientID":["OIDCclient1"],"expireTime":["1502142269359"],"user_code":["PDRxhXht"],"auditTrackingId":["ff85ab51-f0b6-48e2-85af-bc26feca5a98-311"],"scope":["profile"],"tokenName":["device_code"],"response_type":["token"],"realm":["/statefulRealm"],"id":["501905e0-b350-47d5-92cc-161a4291116f"],"userName":["demo"],"AUTHORIZED":["true"]}
coreTokenString01: profile
coreTokenString10: device_code
coreTokenString14: PDRxhXht
coreTokenString03: demo
coreTokenString08: /statefulRealm
coreTokenExpirationDate: 20170807214429.359Z
coreTokenString09: OIDCclient1
coreTokenId: 501905e0-b350-47d5-92cc-161a4291116f
coreTokenType: OAUTH 

CTS-based Session token (AM 5 and later)

The CTS-based Session token in AM 5 and later:

  • Is created in the CTS when a user authenticates to a realm that is in CTS-based session mode.
  • Allows a user to remain authenticated even when the AM instance they authenticated with has been shutdown.
  • Is not compatible with the equivalent token in OpenAM 13.5.x and earlier.

CTS-based Session token example

dn: coreTokenId=-8288022266790569769,ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org
objectClass: top
objectClass: frCoreToken
coreTokenString11: /
coreTokenObject: {"clientDomain":"dc=openam,dc=forgerock,dc=org","clientID":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org","cookieMode":true,"cookieStr":null,"creationTimeInMillis":1502229535517,"isSessionUpgrade":false,"listeners":{"9d16b2e1-50c2-43f8-86ce-97a67be1661a":true,"4bd2e5b4-22c8-4172-a2a6-b9f028e86dc8":true},"maxCachingTimeInMinutes":3,"maxIdleTimeInMinutes":30,"maxSessionTimeInMinutes":120,"restrictedTokensBySessionID":{},"sessionEventURLs":{},"sessionID":{"comingFromAuth":false,"cookieMode":null,"encryptedString":"AQIC5wM2LY4S...kyNgACUzEAAjAx*","sessionDomain":"dc=openam,dc=forgerock,dc=org","sessionServer":"am3.example.com","sessionServerID":"01","sessionServerPort":"38080","sessionServerProtocol":"http","sessionServerURI":"/am5"},"sessionProperties":{"Locale":"en","authInstant":"2017-08-08T21:58:55Z","Organization":"dc=openam,dc=forgerock,dc=org","UserProfile":"Required","Principals":"amadmin","successURL":"/am5/console","CharSet":"UTF8","Service":"ldapService","Host":"127.0.0.1","cookieSupport":"true","FullLoginURL":"/am5/UI/Login?realm=%2F","AuthLevel":"0","clientType":"genericHTML","AMCtxId":"77a740625b90bc6301","loginURL":"/am5/UI/Login","UserId":"amadmin","AuthType":"DataStore","sun.am.UniversalIdentifier":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org","amlbcookie":"01","HostName":"127.0.0.1","Principal":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org","UserToken":"amadmin"},"sessionState":"VALID","sessionType":"USER","timedOutTimeInSeconds":0}
coreTokenInteger07: 30
coreTokenString12: 1502229535517
coreTokenInteger06: 120
coreTokenString04: 1502229797863
coreTokenString05: AQIC5wM2LY4S...kyNgACUzEAAjAx*
coreTokenMultiString01: 9d16b2e1-50c2-43f8-86ce-97a67be1661a
coreTokenMultiString01: 4bd2e5b4-22c8-4172-a2a6-b9f028e86dc8
coreTokenExpirationDate: 20170809003317.863+0200
coreTokenUserId: id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org
coreTokenId: -8288022266790569769
coreTokenString06: shandle:AQIC5wM2LY4S...kyNgACUzEAAjAx*
coreTokenType: SESSION

CTS-based Session token (OpenAM 13.x )

The CTS-based Session token in OpenAM 13.x:

  • Is created in the CTS when a user authenticates to a realm that is in CTS-based session mode and the OpenAM deployment has session failover enabled.
  • Allows a user to remain authenticated even when the OpenAM instance they authenticated with has been shutdown.
  • Is not compatible with the equivalent token in AM 5 and later.

CTS-based Session token example

dn: coreTokenId=-6412296181144271926,ou=famrecords,ou=openam-session,ou=tokens,o=openam
objectClass: top
objectClass: frCoreToken
coreTokenObject: {"clientDomain":"o=statefulrealm,ou=services,o=openam","clientID":"id=demo,ou=user,o=statefulrealm,ou=services,o=openam","cookieMode":null,"cookieStr":null,"creationTime":1502141969,"isISStored":true,"maxCachingTime":3,"maxIdleTime":30,"maxSessionTime":120,"reschedulePossible":false,"restrictedTokensBySid":{},"sessionEventURLs":{"http://am1.example.com:18080/am1350/notificationservice":[{"comingFromAuth":false,"cookieMode":null,"encryptedString":"AQIC5wM2LY4S...kyNgACUzEAAjAx*","sessionDomain":"","sessionServer":"am.example.com","sessionServerID":"02","sessionServerPort":"8000","sessionServerProtocol":"http","sessionServerURI":"/am1350"}]},"sessionID":{"comingFromAuth":false,"cookieMode":null,"encryptedString":"AQIC5wM2LY4S...kyNgACUzEAAjAx*","sessionDomain":"o=statefulrealm,ou=services,o=openam","sessionServer":"am.example.com","sessionServerID":"02","sessionServerPort":"8000","sessionServerProtocol":"http","sessionServerURI":"/am1350"},"sessionProperties":{"CharSet":"UTF-8","UserId":"demo","FullLoginURL":"/am1350/UI/Login?realm=%2FstatefulRealm","successURL":"/am1350/console","cookieSupport":"true","AuthLevel":"0","UserToken":"demo","loginURL":"/am1350/UI/Login","Principals":"demo","Service":"ldapService","sun.am.UniversalIdentifier":"id=demo,ou=user,o=statefulrealm,ou=services,o=openam","amlbcookie":"01","Organization":"o=statefulrealm,ou=services,o=openam","Locale":"en_US","HostName":"127.0.0.1","AuthType":"DataStore","Host":"127.0.0.1","UserProfile":"Required","AMCtxId":"f0444f0bf43ab5d701","clientType":"genericHTML","authInstant":"2017-08-07T21:39:29Z","Principal":"id=demo,ou=user,o=statefulrealm,ou=services,o=openam"},"sessionState":1,"sessionType":0,"timedOutAt":0,"willExpireFlag":true}
coreTokenString01: 1502141969
coreTokenString02: AQIC5wM2LY4S...kyNgACUzEAAjAx*
coreTokenString03: shandle:AQIC5wM2LY4S...kyNgACUzEAAjAx*
coreTokenExpirationDate: 20170808001429.080+0200
coreTokenUserId: id=demo,ou=user,o=statefulrealm,ou=services,o=openam
coreTokenId: -6412296181144271926
coreTokenType: SESSION 

Client-based Session Blacklist token

The Client-based Session Blacklist token in AM/OpenAM is:

  • Used to keep a record of client-based sessions that have been ended by logging out.
  • Created only when client-based sessions blacklist is enabled in global session properties.

Client-based session blacklist token example

dn: coreTokenId=7fac1a04-f358-4ed5-958b-48aac6dd5a34,ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org
objectClass: top
objectClass: frCoreToken
coreTokenString01: 01
coreTokenDate01: 20170824151809.429Z
coreTokenExpirationDate: 20170824171908Z
coreTokenId: 7fac1a04-f358-4ed5-958b-48aac6dd5a34
coreTokenType: SESSION_BLACKLIST

See Also

Core Token Service (CTS) and sessions in AM/OpenAM

Installation Guide › Implementing the Core Token Service

Installation Guide › Core Token Service (CTS) Object Identifiers

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I delete all or some of the tokens in the CTS store in AM (All versions)?

The purpose of this article is to provide information on how an administrator can clean up tokens in the Core Token Service (CTS) store. This article covers deleting all tokens in the CTS and deleting just a subset (for example, only Refresh tokens). This information should not be used in lieu of a properly configured/tuned CTS.

Overview

By default, AM manages expired tokens using its reaper service, although you can use DS to manage token expiration instead if you prefer. You should configure the CTS reaper and then tune your CTS store appropriately to ensure tokens are being removed in an efficient manner. See the following links for further information:

However, even with the reaper running well and pruning expired tokens as expected, there may be occasions when you need to manually delete all tokens in the CTS or delete just a subset. For example, if you have been load testing, you may want to delete all the test tokens that were created before running further tests. Alternatively, you may need to clean up tokens that have built up as a result of an improperly configured/tuned CTS that is not adequate for your environment or specific deployment needs; if this is the case, you should ensure you tune the CTS properly to prevent a build up in future.

Note

Tuning the CTS is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

This article guides you through each scenario, with different processes depending on the size of your dataset:

Caution

Deleting tokens will end all sessions associated with them.

Example values

These example processes use the following values:

  • A BaseDN of "dc=openam,dc=forgerock,dc=org"
  • The parent DN for tokens is “ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org"
  • A backendID of cts-store for the CTS server database.
  • The LDAP port is 50389
  • The DS admin port is 4444
  • The hostname is: host1.example.com

You should adjust these values as needed for your environment and ensure you include  the --useSsl and --trustAll options if you are using LDAPS.

Deleting and re-creating token parent DN (all tokens, less than 500k entries)

The quickest, easiest and most efficient way to delete all tokens from a small dataset is to delete the parent DN (which holds all the tokens) and re-create it. For large datasets, you should use the LDIF export / import approach described in the following section.

Note

These example steps disable the LDAP/LDAPS connection handler that AM is configured to communicate on to stop updates reaching the CTS instance. You must use an alternative LDAP connector for subsequent LDAP operations. If this is not possible, consider temporarily changing the port or blocking communications at the network level instead.

You can delete all tokens as follows:

  1. Navigate to the bin directory of DS.
  2. Disable the LDAP/LDAPS connector so that AM stops sending traffic to this node providing you have an alternative LDAP connector for subsequent LDAP operations. For example, to disable the LDAP connection handler:
    $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name LDAP --set enabled:false --trustAll --no-prompt 
  3. Create an LDIF of the ou=famrecords DN:
    $ ./ldapsearch --hostname host1.example.com --port 50389 --bindDn "cn=Directory manager" --bindPassword password --baseDn "ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org" --searchScope one "(objectclass=*)" > parent.ldif
  4. Delete the ou=famrecords DN:
    $ ./ldapdelete --hostname host1.example.com --port 50389 --bindDn "cn=Directory manager" --bindPassword password --deleteSubtree "ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org"
  5. Re-create the ou=famrecords DN using the LDIF file you created in step 3:
    $ ./ldapmodify --hostname host1.example.com --port 50389 --bindDn "cn=Directory manager" --bindPassword password -f parent.ldif
  6. Rebuild all indexes:
    $ ./rebuild-index --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "dc=openam,dc=forgerock,dc=org" --rebuildAll
  7. Allow replication to bring all other CTS nodes back into sync with this empty instance (replication should sync the deletes and then adds across all replicas). If you don't want to generate a lot of replication traffic with these deletes/adds, you can speed up the process by re-initializing all other nodes from this instance. For example:
    $ ./dsreplication initialize-all --hostname host1.example.com --port 4444 --baseDN dc=openam,dc=forgerock,dc=org --adminUID admin --adminPassword password --no-prompt
  8. Re-enable the LDAP/LDAPS connector to resume AM sending traffic to this node. For example, to enable the LDAP connection handler:
    $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name LDAP --set enabled:true --trustAll --no-prompt 

LDIF exporting and importing all data excluding tokens (all tokens, more than 500k entries)

This approach removes all tokens and is best suited to a large dataset since you must shut down the CTS instance first. In essence, you create an LDIF file containing all data, but excluding any tokens. You then import this LDIF to override the contents of the database; the import process automatically rebuilds the indexes.

Note

These example steps disable the LDAP/LDAPS connection handler that AM is configured to communicate on to stop updates reaching the CTS instance. You must use an alternative LDAP connector for subsequent LDAP operations. If this is not possible, consider temporarily changing the port or blocking communications at the network level instead.

You can delete all tokens as follows:

  1. Navigate to the bin directory of DS.
  2. Disable the LDAP/LDAPS connector so that AM stops sending traffic to this node providing you have an alternative LDAP connector for subsequent LDAP operations. For example, to disable the LDAP connection handler:
    $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name LDAP --set enabled:false --trustAll --no-prompt 
  3. Shutdown the CTS server.
  4. Take an LDIF export:
    $ ./export-ldif --backendID cts-store --ldifFile /path/to/export.ldif --excludeFilter "(objectclass=frCoreToken)" --offline
  5. Check the file excludes all tokens.
  6. Import the LDIF:
    $ ./import-ldif --backendID cts-store --ldifFile /path/to/export.ldif --skipFile /tmp/skips.txt --rejectFile /tmp/rejects.txt --offline
  7. Start the CTS server.
  8. Re-initialize all other nodes from this instance to bring all other CTS nodes back into sync with this empty instance. For example:
    $ ./dsreplication initialize-all --hostname host1.example.com --port 4444 --baseDN dc=openam,dc=forgerock,dc=org --adminUID admin --adminPassword password --no-prompt
    
  9. Re-enable the LDAP/LDAPS connector to resume AM sending traffic to this node. For example, to enable the LDAP connection handler:
    $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name LDAP --set enabled:true --trustAll --no-prompt 

Defining a subset of tokens

The following example processes delete all Refresh tokens. This is done by filtering/searching on tokens where coreTokenString10 (token type) is set to refresh_token, for example:

"(coreTokenString10=refresh_token)"

You can amend these processes to look for other token types or other LDAP attributes as needed to define a subset of tokens. See How do I know what LDAP attributes are used by CTS tokens in AM (All versions) and OpenAM 13.x? for information on the attributes and values available.

You can use these attributes together to refine your subset further. For instance, you could include the coreTokenExpirationDate attribute as well to filter tokens before or after a certain timestamp. For example, the following would only affect refresh tokens with an expiration date before 01/01/2019:

"(&(coreTokenString10=refresh_token)(coreTokenExpirationDate<=20190101000000.0Z))"

Deleting using ldapsearch and ldapdelete (subset of tokens, less than 500k entries)

The best way to delete a subset of tokens from the CTS for a small dataset is to use ldapsearch to look for all tokens where coreTokenString10 (token type) is set to refresh_token and then issue a delete operation for each one found. For large datasets, you should use the LDIF export / import approach described in the following section.

Note

This process assumes replication will remain in place while executing the following steps. If this is a concern, you can remove this node from the replication topology and re-sync/re-initialize other CTS instances after deletion.

You can delete all Refresh tokens as follows:

  1. Navigate to the bin directory of DS.
  2. Run the following search and delete command:
    $ ./ldapsearch --hostname host1.example.com --port 50389 --bindDN "cn=Directory manager" --bindPassword password --baseDn "ou=famrecords,ou=openam-session,ou=tokens,dc=openam,dc=forgerock,dc=org" "(coreTokenString10=refresh_token)" 1.1 |grep -v '^$' | cut -c5- | ./ldapdelete --hostname host1.example.com --port 50389 --bindDN "cn=Directory manager" --bindPassword password

LDIF exporting and importing (subset of tokens, more than 500k entries)

This approach removes a subset of tokens and is best suited to a large dataset since you must shut down the CTS instance first. In essence, you create an LDIF file containing all data and tokens, except tokens where coreTokenString10 (token type) is set to refresh_token. You then import this LDIF to override the contents of the database; the import process automatically rebuilds the indexes.

You can delete all Refresh tokens as follows:

  1. Navigate to the bin directory of DS.
  2. Shutdown the CTS server.
  3. Take an LDIF export:
    $ ./export-ldif --backendID cts-store --ldifFile /path/to/export.ldif --excludeFilter "(coreTokenString10=refresh_token)" --offline
  4. Check the file excludes all Refresh Tokens (tokens where coreTokenString10=refresh_token).
  5. Import the LDIF:
    $ ./import-ldif --backendID cts-store --ldifFile /path/to/export.ldif --skipFile /tmp/skips.txt --rejectFile /tmp/rejects.txt --offline
  6. Start the CTS server.
  7. Re-initialize all other nodes from this instance to bring all other CTS nodes back into sync with this empty instance. For example:
    $ ./dsreplication initialize-all --hostname host1.example.com --port 4444 --baseDN dc=openam,dc=forgerock,dc=org --adminUID admin --adminPassword password --no-prompt

See Also

Best practices for configuring sessions in AM (All versions) to reduce the impact on the CTS store

Understanding CTS token types in AM/OpenAM

Reference › ldapsearch — perform LDAP search operations

Reference › ldapdelete — perform LDAP delete operations

Reference › ldapmodify — perform LDAP modify, add, delete, mod DN operations

Administration Guide › Rebuilding Indexes

Administration Guide › Importing and Exporting Data

Administration Guide › Initializing Replicas

Related Training

N/A

Related Issue Tracker IDs

N/A


Sessions Configuration


Best practices for configuring sessions in AM (All versions) to reduce the impact on the CTS store

The purpose of this article is to provide best practice advice for configuring sessions in AM to reduce the impact on the Core Token Service (CTS) store. This article includes information on how sessions impact the CTS store and the resulting impact on the DS changelog.

Overview

The impact of sessions on the CTS store depends on session type (where it's stored), the number of writes (which depends on how busy your site is and how sessions are configured) and the storage scheme in use (selectable in AM 6.x). It's worth bearing in mind that an environment with lots of writes to the CTS and/or large session tokens can also impact the DS changelog, which in turn may cause you to run out of disk space.

Session types

Session data is stored in the CTS store as follows depending on type:

  • CTS-based sessions (called Stateful in AM 5.x) - all session data is stored in the CTS store.
  • Client-based sessions (called Stateless in AM 5.x) - all session data is contained within the session cookie (called iPlanetDirectoryPro by default).
Note

You should refer to Authentication and Single Sign-On Guide › Choosing Where to Store Sessions for help with determining which session types are the most appropriate for your environment.

See FAQ: Cookies in AM/OpenAM and Authentication and Single Sign-On Guide › About Sessions for further information.

Summary of recommendations

The following list provides a high-level summary of recommendations to consider for reducing the impact on the CTS store and in turn, the DS changelog; the subsequent sections provide more detail on these points where applicable:

  • Upgrade to AM 6.5 or later and use the Grant-Set storage scheme.
  • Configure sessions appropriately, in particular:
    • Only add necessary session properties.
    • Streamline your authentication process; consider whether you require things like ForceAuth and ensure efficient use of PAPs.
    • Use the &refresh=false action when validating sessions (AM 6 and later).
    • Set the Maximum Session Cache Size and Latest Access Time Update Frequency properties appropriately for your environment.
  • Size replication servers appropriately to avoid disk space issues. See the DS changelog section for further information.
Note

It’s important to note that sizing and configuring sessions for CTS is a tuning process. Each deployment environment is unique and has its own specific set of requirements. The CTS can be different depending on its function as many different components of AM use CTS to store data. Sizing and/or tuning recommendations are outside the scope of ForgeRock support. if you want more tailored advice, consider engaging Deployment Support Services.

Storage schemes

AM 6.5 introduced a new Grant-Set scheme for storing OAuth 2.0 tokens in the CTS store. This scheme groups multiple authorizations for a given OAuth 2.0 client and resource owner pair, and stores them in a single CTS OAUTH2_GRANT_SET entry. This scheme reduces the amount of data stored in the CTS by removing duplication and reduces the number of operations to the CTS.

Note

This scheme is not the default in AM 6.5, but it is highly recommended that you use it once all AM instances are upgraded to AM 6.5. See Installation Guide › OAuth 2.0 CTS Storage Scheme for further information.

Prior to AM 6.5, there is no choice of scheme and each OAuth2 token is mapped to an individual CTS entry.

Session considerations

The following lists some important session considerations that can increase the number of writes to the CTS. You don't need to try to address all of these things; they are just listed to make you aware of them when you are considering what is needed in your environment, and whether you have inefficient processes or settings that are contributing to excessive CTS load:

  • Adding session properties - each extra session property contributes another MODIFY operation to the CTS plus increases the size of the session token that is being written and stored (CoreTokenObject). There is a RFE to batch session properties to reduce the number of writes to the CTS: OPENAM-13788 (AM Session properties can only be added one at a time which is highly inefficient).
  • Using a Post Authentication Plugin (PAP) - any steps that modify or add session properties will increase the number of writes to the CTS.
  • Using the ForceAuth process - Out of the box the ForceAuth process incurs at least eight writes to the CTS (max idle time, max session time, chain, service, upgraded session type set to true, chain, service and role). Introducing a Post Authentication Plugin further increases the number of writes. A single session may hit ForceAuth up to five times; with an assumed total of 10 writes per ForceAuth journey that means 50 writes of the large CoreTokenObject for authentication per session (and 50 entries in the changelogDB).
  • Resetting AM session idle times - each time an idle session time is reset, AM writes to the CTS. By default, the session idle time is reset when the session is validated. In AM 6 and later, you can use the &refresh=false action to mitigate this. See Authentication and Single Sign-On Guide › Validating Sessions for further information. 
  • Setting the Maximum Session Cache Size property incorrectly (see below for further information).
  • Setting the Latest Access Time Update Frequency property incorrectly (see below for further information).

Maximum Session Cache Size

This setting specifies the maximum number of sessions to cache in each AM server’s internal session cache. The cache is an LRU (Least Recently Used) cache, which evicts the least used session (usually the first session to be added to the cache) when this maximum session cache size value is reached. For example, with the default value of 5000: if there are 5000 active sessions within a single AM, when session 5001 arrives, session 1 is evicted. Until then, all sessions remain in the cache until modified and/or deleted. 

This setting applies to each server and assuming sticky load balancing has been applied, a guide to setting this appropriately is to take the maximum number of active sessions at any one time divided by the number of available AM instances.

See Setup and Maintenance Guide › Session Settings for further information on setting this.

Caution

It is critical that the value chosen is thoroughly tested as this cache does consume JVM heap space, more so with additional session properties. If the value is set too high, there is a risk of instability or Out Of Memory exceptions.

Latest Access Time Update Frequency

This setting defines the write interval for the following two timers within the CTS entry that represent a SSO session token: 

  • CoreTokenExpirationDate - defines the token expiry date.
  • coreTokenString04 - defines the token last access time and is used to calculate idle time. 

The default for this parameter is 60 seconds, which means: 

  • If a call to /json/sessions?_action=validate is made within 60 seconds of coreTokenString04 - no write operations occur for that entry in CTS, just optimized reads.
  • If the call is made outside of this 60 second period - two MODIFY operations occur to replace coreTokenExpirationDate (for example, 20181023090859.390+0100) and coreTokenString04 (for example, 1540280339390 - Unix Epoch Time). 

You can increase this write interval to reduce the number of writes to the CTS and reduce the frequency of the two MODIFY operations. This write interval should not exceed 10 minutes.

See Authentication and Single Sign-On Guide › General for further information on setting this.

DS changelog

Each time a coreTokenObject is updated, the entire object is written to the changelog. The coreTokenObject is a relatively large JSON object with nested arrays of attributes that are stored as a single entry. The entries are stored base64 encoded, but neither this encoding or the raw changelogDb offer any compression.

It is possible to enable token compression, which can potentially half the size of token entries in the backend and changelog with minimal increase in CPU. However, this can undermine the security of encryption and should only be considered as a secondary option once session configuration has been optimized. See Installation Guide › Managing CTS Tokens for further information.

Replication changes

Replication changes are kept per the replication purge delay (three days by default), so the size of the changelog is dependent on the actual number of changes received within that time period. You can reduce the replication purge delay to reduce the size of the changelog, but you must ensure it is set appropriately to keep data long enough for replication and data recovery purposes. Information about replication changes is permanently gone once it has been purged from the changelog. See How do I control how long replication changes are retained in DS/OpenDJ (All versions)? for further information.

Once you have set a replication purge delay that is appropriate to your needs, you should do some load testing to determine expected changelog sizes and then size your replication servers accordingly to prevent issues with disk space.

Errors

If you run out of disk space, you will likely see errors similar to the following in the DS Errors logs, which indicate write errors to the CTS:

[20/Feb/2019:10:17:51 +1000] category=SYNC severity=ERROR msgID=26 msg=Error trying to use the underlying database. The Replication Server is going to shut down: ChangelogException: Could not add record 'Record [00000165c86da14665cc008e2763:ModifyMsg content:  protocolVersion: 8 dn: coreTokenId=kOrkxaDZ6fYcUrcE0c3PEMFIGNk=,dc=openam-cts,dc=forgerock,dc=org csn: 0000016613b6f7e40e79074d33e3 uniqueId: 561a1ab7-4bc2-4741-a8ef-ff96624854b9 assuredFlag: false assuredMode: SAFE_DATA_MODE safeDataLevel: 1]' in log file '/opt/ds/changelogDb/1.dom/1000.server/head.log' (BlockLogWriter.java:120 LogFile.java:250 Log.java:422 FileReplicaDB.java:150 FileChangelogDB.java:805 ReplicationServerDomain.java:503 ReplicationServerDomain.java:325 ServerHandler.java:1131 ServerReader.java:103)

See Also

Installation Guide › Implementing the Core Token Service

Installation Guide › General Recommendations for CTS Configuration

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

How do I generate sample user data for performance testing in DS/OpenDJ (All versions)?

Core Token Service (CTS) and sessions in AM/OpenAM

Understanding CTS token types in AM/OpenAM

Performance tuning and monitoring ForgeRock products

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13788 (AM Session properties can only be added one at a time which is highly inefficient)

OPENDJ-1135 (DS sometimes fails to connect to RS after server restart)


How do I change the session cookie name for AM/OpenAM and Policy Agents (All versions)?

The purpose of this article is to provide information on changing the name of the AM/OpenAM session cookie and also updating the agent session cookies to match. The session cookie is called iPlanetDirectoryPro by default but you should change it for security reasons.

Overview

Once you have changed the AM/OpenAM session cookie name, you must also update the session cookie name in your policy agent profiles to match the new session cookie name. You can change the agent cookies, default agent cookies or the agent group cookies to achieve this.

This article contains information on changing the following session cookie names:

REST calls

Once you have changed the AM/OpenAM session cookie name, you must also update any REST calls to use the new cookie name in the header. For example, if your new cookie is called exampleCookie, you would change the following header in your REST calls from:

-H "iPlanetDirectoryPro: AQIC5..."

To:

-H "exampleCookie: AQIC5..."

Renaming the AM/OpenAM session cookie

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Security > Cookie > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Security > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]
    replacing [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: DefaultSecurityProperties
    • Property: com.iplanet.am.cookie.name
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

Renaming the agent session cookie in AM/OpenAM

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

Web Policy Agent

  • AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.cookie.name=[cookiename]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: WebAgents
    • Property: cookieName

Java Policy Agent

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: J2eeAgents
    • Property: amCookieName
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

Renaming the default agent session cookie in AM/OpenAM

You can change the name of this cookie using ssoadm:

Web Policy Agent

Enter the following command:

$ ./ssoadm set-attr-defs -s AgentService -t Organization -u [adminID] -f [passwordfile] -c WebAgent -a com.sun.identity.agents.config.cookie.name=[cookiename]

replacing [adminID], [passwordfile] and [cookiename] with appropriate values.

Java Policy Agent

Enter the following command:

$ ./ssoadm set-attr-defs -s AgentService -t Organization -u [adminID] -f [passwordfile] -c J2EEAgent -a com.iplanet.am.cookie.name=[cookiename]

replacing [adminID], [passwordfile] and [cookiename] with appropriate values.

Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

Renaming the agent group session cookie in AM/OpenAM

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

Web Policy Agent

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > Groups > [Group ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent-grp -e [realmname] -b [agentgroupname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.cookie.name=[cookiename]
    replacing [realmname], [agentgroupname], [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: WebAgentGroups
    • Property: cookieName

Java Policy Agent

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > Groups > [Group ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent-grp -e [realmname] -b [agentgroupname] -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]
    replacing [realmname], [agentgroupname], [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: J2EEAgentGroups
    • Property: amCookieName
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

See Also

Installation Guide › Avoiding Obvious Defaults

Reference › Configuration Reference › Deployment Configuration

Reference › Command Line Tools › ssoadm

Setup and Maintenance Guide › Setting Up Policy Agent Profiles

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-3631 (Renaming of SSO Token Cookie to substring of request URL will cause failed agent evaluation.)


How do I configure session timeouts in AM/OpenAM (All versions)?

The purpose of this article is to provide information on setting session timeouts in AM/OpenAM. There are a number of different session timeouts you can set; this article focuses on setting session timeouts at a global level.

Configuring global session timeouts

There are two global session timeouts: Maximum Session Time, which is the maximum number of minutes that a session can remain active before a user is required to re-authenticate and Maximum Idle Time, which is the maximum number of minutes that a session can be idle before a user must re-authenticate.

You can configure the global session timeouts using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Global Services > Session > Dynamic Attributes and enter the required number of minutes for the maximum session time and / or maximum idle time.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > Session > Dynamic Attributes and enter the required number of minutes for the maximum session time and / or maximum idle time.
  • ssoadm: enter the following command for maximum session time:
    $ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u [adminID] -f [passwordfile] -a iplanet-am-session-max-session-time=[minutes]
    replacing [adminID], [passwordfile] and [minutes] with appropriate values.
  • ssoadm: enter the following command for maximum idle time:
    $ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u [adminID] -f [passwordfile] -a iplanet-am-session-max-idle-time=[minutes]
    replacing [adminID], [passwordfile] and [minutes] with appropriate values.
Note

There is no recommended value for these session timeouts as they depend on your requirements and configuration. For a combination of security and convenience, you should consider setting the maximum session time to a higher value and the maximum idle time to a relatively low value. From a performance perspective, the maximum session time has to be considered when setting the maximum number of sessions. Unless your sessions expire quickly, you will probably need to set a higher limit for active sessions; the number of sessions is relative to the amount of memory being used, which means you need to adjust the Java™ Virtual Machines (JVM) heap size accordingly.  

See Also

How do I configure realm level session timeouts in AM/OpenAM (All versions)?

How do I configure user level session timeouts in AM/OpenAM (All versions)?

How do I configure login page session timeouts in AM/OpenAM (All versions) when using authentication modules?

How do I configure idle timeouts properly in OpenAM 11.x and 12.x for persistent search connections made through a load balancer or firewall?

How do I change the JVM heap size for AM/OpenAM (All versions)?

Best practice for JVM Tuning

FAQ: General AM/OpenAM

Reference › Configuration Reference › Global Services Configuration

Setup and Maintenance Guide › Maintaining an Instance › Tuning an Instance

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I configure realm level session timeouts in AM/OpenAM (All versions)?

The purpose of this article is to provide information on setting realm level session timeouts in AM/OpenAM. This allows you to have different session timeouts per realm and any realm level settings override the global settings for the specific realm.

Configuring realm based session timeouts

There are two realm level session timeouts, which override the global settings: Maximum Session Time, which is the maximum number of minutes that a session can remain active before a user is required to re-authenticate and Maximum Idle Time, which is the maximum number of minutes that a session can be idle before a user must re-authenticate.

Note

You may need to add the Session service if it is not listed under Services by clicking Add a Service or Add and then selecting Session. If you are using ssoadm, you can replace set-realm-svc-attrs in the ssoadm command with add-svc-realm to add this service and set the attributes with the same command.

You can configure the realm session timeouts using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Services > Session and enter the required number of minutes for the maximum session time and / or maximum idle time.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Services > Session and enter the required number of minutes for the maximum session time and / or maximum idle time.
  • ssoadm: enter the following command for maximum session time:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMSessionService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-session-max-session-time=[minutes]
    replacing [realmname], [adminID], [passwordfile] and [minutes] with appropriate values.
  • ssoadm: enter the following command for maximum idle time
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMSessionService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-session-max-idle-time=[minutes]
    replacing [realmname], [adminID], [passwordfile] and [minutes] with appropriate values.

See Also

How do I configure session timeouts in AM/OpenAM (All versions)?

How do I configure user level session timeouts in AM/OpenAM (All versions)?

How do I configure login page session timeouts in AM/OpenAM (All versions) when using authentication modules?

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I configure user level session timeouts in AM/OpenAM (All versions)?

The purpose of this article is to provide information on setting user level session timeouts in AM/OpenAM. This allows you to have different session timeouts per user. Any user level settings override the realm and global settings for the specific user.

Configuring user based session timeouts

There are two user level session timeouts, which override the realm and global settings: Maximum Session Time, which is the maximum number of minutes that a session can remain active before a user is required to re-authenticate and Maximum Idle Time, which is the maximum number of minutes that a session can be idle before a user must re-authenticate.

Warning

You cannot set these timeouts at a user level if you use Active Directory® for your data store as the Session service attributes cannot currently be mapped to this data store.

You must enable Load Schema (select the Load Schema when saved option in pre-AM 6) for your data store prior to specifying user level settings. In AM / OpenAM 13.x, navigate to Realms > [Realm Name] > Data Stores > [Data Store Name]. In Pre-OpenAM 13, navigate to Access Control > [Realm Name] > Data Stores > [Data Store Name]. 

Note

You may need to add the Session service if it is not listed under Services by clicking Add Service or Add and then selecting Session. If you are using ssoadm, you can replace set-identity-svc-attrs in the ssoadm command with add-svc-identity to add this service and set the attributes with the same command.

You can configure the user session timeouts using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Identities > [User Name] > Services > Session and enter the required number of minutes for the maximum session time and/or maximum idle time. 
  • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Subjects > [User Name] > Services > Session and enter the required number of minutes for the maximum session time and/or maximum idle time. 
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Subjects > [User Name] > Services > Session and enter the required number of minutes for the maximum session time and/or maximum idle time. 
  • ssoadm: enter the following command for maximum session time:
    $ ./ssoadm set-identity-svc-attrs -s iPlanetAMSessionService -e [realmname] -t User -i [username] -u [adminID] -f [passwordfile] -a iplanet-am-session-max-session-time=[minutes]
    replacing [realmname], [username], [adminID], [passwordfile] and [minutes] with appropriate values.
  • ssoadm: enter the following command for maximum idle time:
    $ ./ssoadm set-identity-svc-attrs -s iPlanetAMSessionService -e [realmname] -t User -i [username] -u [adminID] -f [passwordfile] -a iplanet-am-session-max-idle-time=[minutes]
    replacing [realmname], [username], [adminID], [passwordfile] and [minutes] with appropriate values.

See Also

How do I configure session timeouts in AM/OpenAM (All versions)?

How do I configure realm level session timeouts in AM/OpenAM (All versions)?

How do I configure login page session timeouts in AM/OpenAM (All versions) when using authentication modules?

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I configure the login page session timeout in AM 5.5.x and 6.x when using authentication trees?

The purpose of this article is to provide information on setting the login page session timeout in AM when you are using authentication trees.

Overview

The login page session timeout specifies the duration in minutes before the AM login page times out and the session (if it is CTS-based) is removed from the CTS store if a user does not log in. The default for the login page session timeout is three minutes.

If a tree-based session times out, you will see errors such as the following in the Authentication debug log:

amAuth:04/15/2019 03:39:02:115 PM BST: Thread[http-nio-8080-exec-240,5,main]: TransactionId[ede0c584-8e19-4888-baba-b6cf2888e289-505507]
ERROR: Unable to construct an appropriate auth session
org.forgerock.openam.core.rest.authn.exceptions.RestAuthException: Failed to create session
   at org.forgerock.openam.core.rest.authn.trees.AuthTrees.constructAuthSession(AuthTrees.java:408)
   at org.forgerock.openam.core.rest.authn.trees.AuthTrees.invokeTree(AuthTrees.java:218)
   at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:203)
   at org.forgerock.openam.core.rest.authn.http.AuthenticationServiceV1.authenticate(AuthenticationServiceV1.java:163)
   at sun.reflect.GeneratedMethodAccessor137.invoke(Unknown Source)
   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
   at java.lang.reflect.Method.invoke(Method.java:498)
...
Caused by: org.forgerock.openam.dpro.session.InvalidSessionIdException: Invalid session ID.Session not found. This likely means it has expired and been removed.

Setting the login page session timeout

Note

Please be aware of the following when setting the login page session timeout:

  • You should set the login page session timeout as a server default rather than for an individual server since the overall authentication process will be the same on all servers. If your timeout is not behaving as expected, you should check the Invalidate Session Max Time setting on individual servers to ensure the default value has not been overridden.
  • If you have authentication processes in any of your realms that include authentication modules/chains, you will need to ensure the login page session timeout value is always greater than the timeout value in the authentication modules and takes account of the longest possible authentication process as detailed in How do I configure login page session timeouts in AM/OpenAM (All versions) when using authentication modules?

You can configure the login page session timeout using either the console, Amster or ssoadm:

  1. Update the login page session timeout:
    • Console: navigate to: Configure > Server Defaults > Session > Session Limits > Invalidate Session Max Time and enter the required number of minutes.
    • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
      • Entity: DefaultSessionProperties
      • Property: com.iplanet.am.session.invalidsessionmaxtime
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.session.invalidsessionmaxtime=[minutes]
      replacing [adminID], [passwordfile] and [minutes] with appropriate values.
  2. Restart the web application container in which AM runs to apply these configuration changes.

See Also

Reference › Session Properties

How do I modify the prompt text shown when authenticating to a tree in AM 5.5.x and 6.x?

FAQ: Customizing, branding and localizing XUI end user pages in AM/OpenAM

Core Token Service (CTS) and sessions in AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I configure login page session timeouts in AM/OpenAM (All versions) when using authentication modules?

The purpose of this article is to provide information on setting login page session timeouts in AM/OpenAM when you are using authentication modules and chains. You can set these at a global level or have realm specific timeouts. The XUI times out the login page session in the background and then automatically creates a new login page session to provide a seamless user experience, that is, the user will see the login page allowing them to authenticate instead of the "Your session has timed out" message, seen with the Classic UI.

Overview

The login page session timeout specifies the number of minutes before the AM/OpenAM login page timeouts if the user has not logged in. There are two components to this session timeout:

  1. The individual authentication module timeout - this can also be set in a localized version and/or in realm specific versions. The default session timeout for an authentication module is two minutes.
  2. The overall login page session timeout - this must be set to a value greater than the overall authentication process (including any multi-page authentication processes). The default for the overall login page session timeout is three minutes.

Simple example

If you have two chained authentication modules, where one has a timeout of three minutes and one has a timeout of five minutes, you must set the overall login page session timeout to at least eight minutes to accommodate the overall authentication process.

Realm example

If you have two realms:

  • employees, which has one authentication module with a timeout of three minutes.
  • customers, which has two chained authentication modules that both have a timeout of two minutes.

You would need an overall login page session timeout of at least four minutes to accommodate the longest possible overall authentication process (in the customers realm).

Note

Updating timeouts for an authentication module uses the same process as updating the text shown on the login page; customizing the login text during testing can be a good way to check that you are seeing the updated module page. See How do I modify the text on the XUI Login page for one or more realms in AM/OpenAM (All versions)? for further information.

Configuring login page session timeouts (global)

To set a global login page session timeout, that is, one that applies to all realms, you must set the timeout in each authentication module you use as well as the overall login page session timeout:

  1. Update the timeout value in the .xml files that correspond to the authentication modules you use. These files are are located in the /path/to/tomcat/webapps/openam/config/auth/default_xx directory where AM/OpenAM is deployed (where _xx is the localized equivalent of the default directory). If you haven't localized any files, you should change the files located in the /path/to/tomcat/webapps/openam/config/auth/default_en directory. For example, if you use the LDAP and Data Store modules, you would update these files as follows:
    • LDAP.xml - in this file, you should look for the following timeout value and change it to the required number of seconds:
      <Callbacks length="0" order="4" timeout="120" template="user_inactive.jsp" error="true"/>
      
    • Datastore.xml - in this file, you should look for the following timeout value and change it to the required number of seconds:
      <Callbacks length="2" order="1" timeout="120" header="Sign in" >
      
  2. Update the overall login page session timeout using either the console or ssoadm, ensuring it is set to a value greater than the overall authentication process (including any multi-page authentication processes):
    • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Session > Session Limits > Invalidate Session Max Time and enter the required number of minutes.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Session > Session Limits > Invalidate Session Max Time and enter the required number of minutes.
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.session.invalidsessionmaxtime=[minutes]
      replacing [adminID], [passwordfile] and [minutes] with appropriate values.
  3. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.
Note

You should set the overall login page session timeout as a server default rather than for an individual server since the overall authentication process will be the same on all servers (as it is determined by authentication modules). If your timeout is not behaving as expected, you should check the Invalidate Session Max Time setting on individual servers to ensure the default value has not been overridden.

Configuring login page session timeouts (realm specific

Assumptions

The following instructions assume you are using the default configuration suffix (dc=openam,dc=forgerock,dc=org) and are changing timeouts for the English locale. You should be aware of the following if either or both of these assumptions are not true of your deployment:

  • Configuration Suffix: where the instructions refer to creating an openam or openam_en directory, the openam prefix refers to the RDN of the configuration suffix dc=openam,dc=forgerock,dc=org.
  • Localization: where the instructions refer to creating an openam_en directory, the _en refers to the English locale. If you want to change timeouts for a different locale, you should create an openam_xx directory that corresponds to your locale of choice. The default directories for supported locales can be found by navigating to the /path/to/tomcat/webapps/openam/config/auth directory.

Depending on your deployment, you may need to make both of these changes by substituting the example directory names openam and openam_en in the instructions to match your RDN and Locale. For example, if you have changed the default configuration suffix to dc=acme,dc=com and you want to change timeouts for the French locale in the employees realm, you would create a directory named acme_fr/services/employees/html directory:

/path/to/tomcat/webapps/openam/config/auth/acme_fr/services/employees/html
Note

It is best practice to make your changes in both the openam directory and the openam_en directory as this ensures all users will see your changes regardless of their locale. Customizations in the openam directory are seen by users whose locale does not match one of the available locales. However, depending on your requirements, it may be sufficient to just make changes in the openam directory.

Instructions

You can set the timeout for authentication modules in the top level realm, an individual realm or all / the majority of realms depending on where you make your changes:

  1. Create a directory in the path that AM/OpenAM will use to look up your customized files. Navigate to the /path/to/tomcat/webapps/openam/config/auth directory and create one or more directories as follows depending on where you want your customizations to apply:
    • openam directory:
      Location Directory to create Resulting path
      Top level realm openam/html /path/to/tomcat/webapps/openam/config/auth/openam/html
      Individual realm openam/services/realmname/html /path/to/tomcat/webapps/openam/config/auth/openam/services/realmname/html
      All or the majority of realms openam/services/html /path/to/tomcat/webapps/openam/config/auth/openam/services/html
    • openam_en directory:
      Location Directory to create Resulting path
      Top level realm openam_en/html /path/to/tomcat/webapps/openam_en/config/auth/openam/html
      Individual realm openam_en/services/realmname/html /path/to/tomcat/webapps/openam_en/config/auth/openam/services/realmname/html
      All or the majority of realms openam_en/services/html /path/to/tomcat/webapps/openam_en/config/auth/openam/services/html
    If you choose to make changes that affect all or the majority of realms, these customizations will affect all realms that do not have a corresponding realmname/html directory.
Note

The realmname directory must all be in lower case for the realm customizations to be located.

  1. Copy the contents of the /path/to/tomcat/webapps/openam/config/auth/default and/or /path/to/tomcat/webapps/openam/config/auth/default_en directory to your new /html directories.
  2. Update the timeout value in the .xml files that correspond to the authentication modules you use, ensuring you update the files in the correct location according to what you set up in step 1. For example, if you use the Data Store and HOTP modules in the employees realm, you would update these files as follows:
    • Datastore.xml (located in /path/to/tomcat/webapps/openam_en/config/auth/openam/services/employees/html) - in this file, you should look for the following timeout value and change it to the required number of seconds:
      <Callbacks length="2" order="1" timeout="120" header="Sign in" >
      
    • HOTP.xml (located in /path/to/tomcat/webapps/openam_en/config/auth/openam/services/employees/html)- in this file, you should look for the following timeout value and change it to the required number of seconds:
      <Callbacks length="2" order="2" timeout="120" header="Please enter your One Time Password, or request a new one">
      
  3. Update the overall login page session timeout using either the console or ssoadm, ensuring it is set to a value greater than the overall authentication process in any realms (including any multi-page authentication processes):
    • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Session > Session Limits > Invalidate Session Max Time and enter the required number of minutes.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Session > Session Limits > Invalidate Session Max Time and enter the required number of minutes.
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.session.invalidsessionmaxtime=[minutes]
      replacing [adminID], [passwordfile] and [minutes] with appropriate values.
  4. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.

You can have a combination of customizations, for example, you can have specific timeouts for the top level realm, different ones for the customers realm and separate ones for all other realms by changing the relevant .xml files in all three places.

Note

You should set the overall login page session timeout as a server default rather than for an individual server since the overall authentication process will be the same on all servers (as it is determined by authentication modules). If your timeout is not behaving as expected, you should check the Invalidate Session Max Time setting on individual servers to ensure the default value has not been overridden.

See Also

How do I modify the text on the XUI Login page for one or more realms in AM/OpenAM (All versions)?

FAQ: Customizing, branding and localizing XUI end user pages in AM/OpenAM

How do I configure session timeouts in AM/OpenAM (All versions)?

How do I configure realm level session timeouts in AM/OpenAM (All versions)?

How do I configure user level session timeouts in AM/OpenAM (All versions)?

Reference › Configuration Reference › Deployment Configuration

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-8433 (JSON Authentication does not provide correct feedback for expired session)

OPENAM-8393 (Incorrect behavior for authentication module timeout when XUI enabled.)

OPENAM-8213 (Invoke Authentication service instead of showing session_timeout.jsp)


How do I change the Maximum Caching Time in AM 5.x, 6 and OpenAM 12.x, 13.x?

The purpose of this article is to provide information on changing the Maximum Caching Time in AM/OpenAM, which affects session caching. You can change this globally, per realm or per user as required, where realm level overrides global setting and user level overrides both realm and global settings.

Background information

The maximum caching time setting has evolved over time and is used as follows depending on your version:

AM 5.x and 6

AM 5 introduced changes to session handling when moving to Autonomous Session Management (the removal of session crosstalk and making the CTS token store the authoritative source for sessions rather than the AM server itself ), which means this setting is no longer used internally by AM sessions and is only used by older policy agents. Since these policy agents are not supported in AM 6.5, this setting is obsolete. See What versions of Policy Agents are compatible with AM/OpenAM? for further details.

OpenAM 12.x and 13.x

The maximum caching time specifies the number of minutes that an OpenAM session is held in memory before it is refreshed. It is also used to recommend the number of minutes that the policy agents (Web 4.x and JEE 3.5.x) should cache the session for. This setting is simply a suggestion though and can be overridden in the policy agent profile.

Changing the global setting

You can configure the global maximum caching time using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Global Services > Session > Dynamic Attributes and enter the required number of minutes for the maximum caching time.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > Session > Dynamic Attributes and enter the required number of minutes for the maximum caching time.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u [adminID] -f [passwordfile] -a iplanet-am-session-max-caching-time=[minutes]
    replacing [adminID], [passwordfile] and [minutes] with appropriate values.

Changing the realm level setting

Note

You may need to add the Session service if it is not listed under Services by clicking Add a Service or Add and then selecting Session. If you are using ssoadm, you can replace set-realm-svc-attrs in the ssoadm command with add-svc-realm to add this service and set the attributes with the same command.

You can configure the realm level maximum caching time using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Services > Session and enter the required number of minutes for the maximum caching time.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Services > Session and enter the required number of minutes for the maximum caching time.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMSessionService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-session-max-caching-time=[minutes]
    replacing [realmname], [adminID], [passwordfile] and [minutes] with appropriate values.

Changing the user level setting

Warning

You cannot set the maximum caching time at a user level if you use Active Directory® for your data store as the Session service attributes cannot currently be mapped to this data store.

You must select the Load Schema when saved option (enable Load Schema in AM 6) for your data store prior to specifying user level settings. In AM / OpenAM 13.x, navigate to Realms > [Realm Name] > Data Stores > [Data Store Name]. In Pre-OpenAM 13, navigate to Access Control > [Realm Name] > Data Stores > [Data Store Name]. 

Note

You may need to add the Session service if it is not listed under Services by clicking Add Service or Add and then selecting Session. If you are using ssoadm, you can replace set-identity-svc-attrs in the ssoadm command with add-svc-identity to add this service and set the attributes with the same command.

You can configure the user level maximum caching time using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Identities > [User Name] > Services > Session and enter the required number of minutes for the maximum caching time.
  • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Subjects > [User Name] > Services > Session and enter the required number of minutes for the maximum caching time.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Subjects > [User Name] > Services > Session and enter the required number of minutes for the maximum caching time. 
  • ssoadm: enter the following command:
    $ ./ssoadm set-identity-svc-attrs -s iPlanetAMSessionService -e [realmname] -t User -i [username] -u [adminID] -f [passwordfile] -a iplanet-am-session-max-caching-time=[minutes]
    replacing [realmname], [username], [adminID], [passwordfile] and [minutes] with appropriate values.

See Also

FAQ: Caching in AM/OpenAM

How do I configure session timeouts in AM/OpenAM (All versions)?

Reference › Configuration Reference › Session

Web Agents 5.5 › Release Notes › Access Management Requirements

Web Agents 5 › Release Notes › Access Management Requirements

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I enable Client-based sessions in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide instructions for enabling client-based sessions in AM/OpenAM. Client-based sessions were referred to as stateless sessions in pre-AM 6 releases.

Enabling client-based sessions

You can enable client-based sessions at a global level or at a realm level, where realm level settings override the global settings for the specific realm.

Global level

You can configure client-based sessions at the global level using either the console or ssoadm:

  • AM 6 and later console: navigate to: Configure > Authentication > Core Attributes > General and enable Use Client-based Sessions.
  • AM 5.x / OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > General and enable Use Stateless Sessions.
  • OpenAM 13 console: navigate to: Configuration > Authentication > Core > General > Use Stateless Sessions and select the Enabled option.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a openam-auth-stateless-sessions=true
    replacing [adminID] and [passwordfile] with appropriate values.

Realm level 

You can configure client-based sessions at the realm level using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Properties and enable Use Client-based Sessions.
  • AM 5.x / OpenAM 13.5 console: navigate to: Realms > [Realm Name] > Properties and enable Use Stateless Sessions.
  • OpenAM 13 console: navigate to: Realms > [Realm Name] > Authentication > Settings > General and enable Use Stateless Sessions.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a openam-auth-stateless-sessions=true
    replacing [realmname], [adminID] and [passwordfile] with appropriate values.

See Also

FAQ: Cookies in AM/OpenAM

FAQ: Installing and using ssoadm in AM/OpenAM

Authentication and Single Sign-On Guide › Choosing Where to Store Sessions.

Authentication and Single Sign-On Guide › About Sessions

Authentication and Single Sign-On Guide › Configuring Session Blacklisting

Authentication and Single Sign-On Guide › Reference › General

Reference › Command Line Tools › ssoadm

Stateless Session Logout in OpenAM 13

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I change the location of the stats logs in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing the location of the stats logs in AM/OpenAM. Stats logs are located in the $HOME/[am_instance]/openam/stats directory by default.

Changing the location of stats logs

You can change the location of stats logs using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Session > Statistics > Directory and enter the new location.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Session > Statistics > Directory and enter the new location.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -u [adminID] -f [passwordfile] -s default -a com.iplanet.services.stats.directory=[location]
    replacing [adminID], [passwordfile] and [location] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

See Also

How do I clear stats logs in AM/OpenAM (All versions)?

How do I stop stats logging in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I clear stats logs in AM/OpenAM (All versions)?

The purpose of this article is to provide information on clearing your stats logs in AM/OpenAM when they get too large and you no longer need them. It assumes you are using a UNIX® or Linux® system. Clearing stats logs as opposed to deleting them negates the need to stop and start your AM/OpenAM server.

Clearing an individual stats log

You can clear an individual stats log as follows from your terminal window:

  1. Change directory to your stats directory (which is typically located in the $HOME/[am_instance]/openam/ directory).
  2. Enter the following command:
    $ cat /dev/null >[filename]
    replacing [filename] with the name of the stats log file you want to clear.

Clearing all stats logs in the stats directory

You can clear all stats logs in the stats directory as follows:

  1. Enter the following command in your terminal window:
    $ for file in /path/to/stats/*; do > $file; done
    For example:
    $ for file in $HOME/openam1/openam/stats/*; do > $file; done
    to empty all the stats log files in the stats directory.

Alias

You could also create an alias to run this command to make it easy to re-use. For example, enter the following command:

$ alias flushamstats='for file in $HOME/openam1/openam/stats/*; do > $file; done'

and then just enter the following command to run it at any time:

$ flushamstats

See Also

How do I change the location of the stats logs in AM/OpenAM (All versions)?

How do I stop stats logging in AM/OpenAM (All versions)?

How do I clear debug logs in AM/OpenAM (All versions)?

How do I rotate AM/OpenAM (All versions) debug logs?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5055 (Having a log rotation on stats log files)


How do I stop stats logging in AM/OpenAM (All versions)?

The purpose of this article is to provide information on stopping stats logging in AM/OpenAM. Stats logs are located in the $HOME/[am_instance]/openam/stats directory by default.

Stopping stats logging

You may want to consider clearing stats logs rather than stopping logging altogether as described in How do I clear stats logs in AM/OpenAM (All versions)?

You can stop stats logging using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Session > Statistics > State and select the Off option.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Session > Statistics > State and select the Off option.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -u [adminID] -f [passwordfile] -s default -a com.iplanet.services.stats.state=off
    replacing [adminID] and [passwordfile] with appropriate values.

To re-enable stats logging, perform the same steps as above and select the File option:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Session > Statistics > State and select the File option.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Session > Statistics >State and select the File option.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -u [adminID] -f [passwordfile] -s default -a com.iplanet.services.stats.state=file
    replacing [adminID] and [passwordfile] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

See Also

How do I monitor session statistics in AM/OpenAM (All versions)?

How do I clear stats logs in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5055 (Having a log rotation on stats log files)

OPENAM-6998 (Session "stats" logging doesn't seem to work)


Session Details


How do I retrieve user attributes from a session using the REST API in AM (All versions) and OpenAM 13.5?

The purpose of this article is to provide information on retrieving user attributes and session properties from a session using the REST API. User attributes and session properties are considered protected properties and can only be retrieved via REST as of OpenAM 13.5. The method varies according to whether you are using AM or OpenAM.

Overview

This process demonstrates retrieving a user's last name and email address from a session using REST, where the LDAP user attributes are:

  • sn - last name
  • mail - email address

If you want to retrieve LDAP user attributes from a session, you must first map them to session attributes and then add them to the whitelist. If you want to retrieve other session properties, you do not need to map them; you just need to add them to the whitelist. See FAQ: REST API in AM/OpenAM (Q. Can I query protected session properties using the REST API?) for a list of available session properties. 

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

Configuring the user attributes and/or whitelist

Note

You may need to add the Session Property Whitelist Service if it is not listed under Services by clicking Add a Service and then selecting Session Property Whitelist Service. If you are using ssoadm, you can replace set-realm-svc-attrs in the ssoadm command with add-svc-realm to add this service and set the attributes with the same command.

You can configure user attributes and/or whitelist as follows, where step 1 is only needed if you want to retrieve LDAP user attributes from a session:

  1. Map the required LDAP user attributes to session attributes using either the console or ssoadm:
    • Console: navigate to: Realms > [Realm Name] > Authentication > Settings > Post Authentication Processing > User Attribute Mapping to Session Attribute and specify the map in the following format: userAttribute|sessionAttribute, where sessionAttribute is a name of your choosing. Create individual mappings for each attribute; for example, to map the sn and mail attribute, you would enter something similar to:
      sn|lastName 
      mail|user.mail
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a sunAMUserAttributesSessionMapping="[userAttribute|sessionAttribute]"
      replacing [realmname], [adminID], [passwordfile] and [userAttribute|sessionAttribute] with appropriate values, where the sunAMUserAttributesSessionMapping attribute must be specified for each individual mapping. For example, to map the sn and mail attribute, you would use the following command:
      $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e / -u amadmin -f pwd.txt -a sunAMUserAttributesSessionMapping="sn|lastName" sunAMUserAttributesSessionMapping="mail|user.mail"
  2. Add the user attributes you just specified and/or other session properties to the whitelist using either the console or ssoadm:
    • Console: navigate to: Realms > [Realm Name] > Services > Session Property Whitelist Service > Whitelisted Session Property Names and enter each session attribute individually with a prefix of am.protected., for example:
      am.protected.lastName
      am.protected.user.mail
      
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-svc-attrs -s SessionPropertyWhitelistService -e [realmname] -u [adminID] -f [passwordfile] -a forgerock-session-property-whitelist=[sessionAttribute]
      
      replacing [realmname], [adminID], [passwordfile] and [sessionAttribute] with appropriate values, where the forgerock-session-property-whitelist attribute must be specified for each individual session attribute. For example, you would use the following command to add the session attributes used in this example:
      $ ./ssoadm set-realm-svc-attrs -s SessionPropertyWhitelistService -e / -u amadmin -f pwd.txt -a forgerock-session-property-whitelist=am.protected.lastName forgerock-session-property-whitelist=am.protected.user.mail

Retrieving the user attributes and/or session properties (AM 5 and later)

In AM 5 and later, you can use the json/sessions?_action=getSessionProperties endpoint. All properties in your whitelist are returned automatically without needing to specify them individually.

Depending on your use case, you may need to authenticate as an admin user:

  • You can retrieve details about your own token by passing it in the tokenId parameter or in the iPlanetDirectoryPro header. If you don't specify the tokenId parameter, the session in the iPlanetDirectoryPro header is inspected instead. An admin token is not required in this scenario.
  • An admin (amadmin or a delegated admin) can retrieve details about someone else's token by passing the admin token in the iPlanetDirectoryPro header and the user's token in the tokenId parameter.

You can retrieve these user attributes and/or session properties as follows:

  1. Authenticate as an admin user if needed. For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Retrieve the user attributes and/or session properties using one of the following curl commands, where the tokenId value is the token of the session you are retrieving properties for; if it is your own session, you only need to pass your token in either the tokenId paramter or the iPlanetDirectoryPro header:
    • AM 5.5 and later:
      $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=3" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -d '{"tokenId" : "BXCCq...NX*1*"}' http://host1.example.com:8080/openam/json/realms/root/sessions?_action=getSessionProperties
    • AM 5 and 5.1.x:
      $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=2" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" "http://host1.example.com:8080/openam/json/realms/root/sessions?_action=getSessionProperties&tokenId=BXCCq...NX*1*"
    Example response:  
    {"am.protected.lastName": "doe", "am.protected.user.mail": "jdoe@example.com"}
    

Retrieving the user attributes and/or session properties (OpenAM 13.5)

In OpenAM 13.5, you should use the json/sessions/?_action=getProperty endpoint and specify the properties you want to retrieve in the --data option. This endpoint is deprecated in AM 5.

You can retrieve these user attributes and/or session properties as follows: 

  1. Authenticate as the user for whom you want to retrieve user attributes and/or session properties. For example:
    $ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console" }
    
  2. Retrieve the user attributes and/or session properties for this user using the following curl command:
    $ curl -X POST -H "Content-Type: application/json" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -d '{"properties": ["am.protected.lastName", "am.protected.user.mail"]}' http://host1.example.com:8080/openam/json/sessions/?_action=getProperty
    Example response:  
    {"am.protected.lastName": "doe", "am.protected.user.mail": "jdoe@example.com"}
    

See Also

How do I validate session tokens and obtain session details using the REST API in AM (All versions)?

FAQ: REST API in AM/OpenAM

How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

How do I change a user's password using the REST API in AM/OpenAM (All versions)?

Using the REST API in AM/OpenAM

Authentication and Single Sign-On Guide › Validating Sessions

Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9129 (Expose the AuthLevel property using newer REST endpoints )


How do I authenticate to another chain but keep the same session token in AM (All versions)?

The purpose of this article is to provide information on authenticating to another chain (using ForceAuth) while keeping the same session tokenId in AM. Keeping the same session tokenId is often a requirement for audit purposes. Session upgrade using the ForceAuth parameter is only supported for CTS-based sessions (called Stateful in AM 5.x).

Overview

The following example demonstrates a user authenticating to one chain and then doing a session upgrade to a second chain with the same session token. When the session is upgraded, the existing session token is checked to ensure it is valid and any existing session properties are copied across to the second chain. The authentication parameters required to achieve this are: sessionUpgradeSSOTokenId and ForceAuth.

Note

You must ensure you use the correct case for the ForceAuth parameter; forceAuth=true will be ignored and the session token will change after you authenticate to the second chain.

This example uses a very simple authentication setup purely for demonstration purposes. You can adapt this to your environment as needed ensuring you use the same authentication parameters to retain the session token.

Example setup

  • Create two authentication modules: DataStore and LDAP.
  • Set different Authentication Levels for each module, for example:
    • DataStore: 10
    • LDAP: 20
  • Create authChain1 and add the DataStore module as required.
  • Create authChain2 and add the LDAP module as required.

Authenticating to another chain with same session token

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

You can authenticate as follows:

  1. Authenticate to the first chain, for example:
    $ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=authChain1
    Example response:
    {
        "tokenId": "35huKgysok9Sg2Uk-MqX6agOArM.*AAJTSQACMDEAAlNLABxJb29DZnN1R1VZU0xNRWd6NDdrTndHVzZzQ1U9AAR0eXBlAANDVFMAAlMxAAA.*",
        "successUrl": "/openam/console",
        "realm": "/"
    }
    
  2. Perform a session upgrade (ForceAuth) to the second chain:
    $ curl -X POST  -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=authChain2&sessionUpgradeSSOTokenId=35huK...AAA.*&ForceAuth=true
    Example response:
    {
        "tokenId": "35huKgysok9Sg2Uk-MqX6agOArM.*AAJTSQACMDEAAlNLABxJb29DZnN1R1VZU0xNRWd6NDdrTndHVzZzQ1U9AAR0eXBlAANDVFMAAlMxAAA.*",
        "successUrl": "/openam/console",
        "realm": "/"
    }
    
  3. Observe that the session token has stayed the same in both responses.

See Also

How do I validate session tokens and obtain session details using the REST API in AM (All versions)?

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

Best practices for configuring sessions in AM (All versions) to reduce the impact on the CTS store

Authentication and Single Sign-On Guide › Session Upgrade

Authentication and Single Sign-On Guide › Performing Session Upgrade

Authentication and Single Sign-On Guide › Using Authentication

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11015 (ForceAuth session upgrade does not work)


How do I obtain the user's session ID in AM/OpenAM (All versions) when browser cookies are disabled?

The purpose of this article is provide information on obtaining a user's session ID in AM/OpenAM when browser cookies are disabled.

Obtaining the user's session ID

The standard AM/OpenAM login page can only deliver the user's session ID in a Set-Cookie header. If your clients do not support browser cookies, you must use a different authentication interface instead, such as the REST API.

The policy agents are capable of extracting the session ID from the URL itself if you set it as a query parameter, for example: 

agent.example.com/index.jsp?iPlanetDirectoryPro=<sessionid>

However, using a query parameter like this can result in your session IDs being logged in your access logs, which is not secure. Therefore, although possible to obtain the session ID when browser cookies are disabled, it is recommended that you do use cookies for the session ID.

See Also

FAQ: Cookies in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Single Sign-On

Development Guide › Developing with the REST API

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I monitor session statistics in AM/OpenAM (All versions)?

The purpose of this article is to provide information on monitoring session statistics in AM/OpenAM. This can provide useful troubleshooting information if you are experiencing unexpectedly high session numbers.

Overview

There are a number of ways you can monitor session statistics in AM/OpenAM depending on your version. These include:

AM 5 and later

  • Session page in the console - navigate to: Realms > [Realm Name] > Sessions to access the Sessions page, which allows you to view and invalidate active CTS-based user sessions per realm.
  • REST API - you can query the /json/sessions endpoint (see the Using the /json/sessions endpoint section below for further information).
  • Amster - you can use Amster to query sessions (see the Using Amster section below for further information).
Note

Changes in AM 5 that made all servers autonomous mean it is the CTS store that holds the session data rather than the AM server itself. As such, the options listed for OpenAM 13.x and earlier cannot be used with AM 5 since they query individual servers. This is a known issue: OPENAM-9817 (JMX CTS session count is broken).

OpenAM 13.x and earlier

Session details

Session management information, including attribute values such as login time, logout time, time out limits, session creations and terminations, are logged in the amSSO.access log file (typically located in the $HOME/[am_instance]/openam/log directory). You will also see session information in the CoreSystems, Authentication and Session debug files ($HOME/[am_instance]/openam/debug directory).

You may notice a difference in session counts if you have just restarted the server; the monitoring API uses beans to store the values, for example, the session count. It is currently implemented such that each counter has an increment and a decrement method. When you log in, the counter gets incremented and when the session is destroyed, it is decremented. When AM/OpenAM starts up, all counters on the local instance are at 0. On the other hand, the counter used to count sessions for the session quotas and the Sessions tab is different; it actually counts the sessions, depending on "server mode" (single instance, multi instance or SFO). If you're using SFO, it counts all sessions from the CTS session store.

If, for example, you have just restarted AM/OpenAM, you may still have all 10 sessions in the session store (depending on how many of them have expired since). So when you start authenticating, two things happen at the same time (let's assume that you already have 10 sessions in the session store):

  • User session quotas are checked and sessions are counted. This will find the existing sessions in LDAP. If the count exceeds the limit, it executes the quota action, for example, "destroy next expiring". This will result in decrementing the session counter in the monitoring bean. At this point it's at 0, so it stays at 0. The number of sessions in the CTS is now 9.
  • Authentication succeeds and the session gets created. 10 sessions in CTS, SNMP counter now reads 1.

Using the /json/sessions endpoint (AM 5 and later)

You can query the /json/sessions endpoint to find session details. For example, to find sessions in the top level realm, you would use a call such as:

$ curl -X GET -H 'Accept: application/json' 'http://host1.example.com:8080/openam/json/sessions?_queryFilter=realm%20eq%20%22%2F%22'

The easiest way to find the relevant command is by using the API Explorer:

  1. Access the API Explorer. You can either access it from the Help icon in the console or from the following URL: 
    http://host1.example.com:8080/openam/XUI/#api/explorer/applications
  2. Navigate to /sessions > Sessions V2.0 > sessions#2.0_query_filter.
  3. Populate the query fields as required; _queryFilter is a required field. For example, to query the top level realm, enter realm eq "/".
  4. Click Try it Out! This returns session details and also provides the curl command you can use in future.

See Development Guide › Developing with the REST API › Introducing the API Explorer and Development Guide › Developing with the REST API › Query for further information.

Using Amster (AM 5 and later)

You can use Amster to query session details using the query Sessions command. For example:

am> query Sessions --realm / --filter 'realm eq "/"'

Example response:

===> [ { "username": "amadmin", "universalId": "id=amadmin,ou=user,dc=example,dc=com", "realm": "/", "sessionHandle": "shandle:4r8SsX6XJj0oAbLBmexqyUsbC7Y.*AAJTSQACMDEAAlNLABxJNEhkVlRlMnNHRzVKUTlOa1hMQ3BiRzZad0E9AAJTMQAA*", "latestAccessTime": "2018-05-01T12:36:54.487Z", "maxIdleExpirationTime": "2018-05-01T13:06:54Z", "maxSessionExpirationTime": "2018-05-01T14:31:23Z", "_rev": "746064345" }, { "username": "demo", "universalId": "id=demo,ou=user,dc=example,dc=com", "realm": "/", "sessionHandle": "shandle:rn3PS1zCIBxmY5qnMtbbqJOLgkQ.*AAJTSQACMDEAAlNLABxNR2JvL0tUenQxc2N1YnU4MkN2YjNkeGY2UTQ9AAJTMQAA*", "latestAccessTime": "2018-05-01T12:36:50.448Z", "maxIdleExpirationTime": "2018-05-01T13:06:50Z", "maxSessionExpirationTime": "2018-05-01T14:36:50Z", "_rev": "856832111" } ]

See Entity Reference › Sessions › query for further information.

Using the amMasterSessionTableStats file (OpenAM 13.x and earlier)

The amMasterSessionTableStats file contains both user and application session data, and is located in the $HOME/[openam_instance]/openam/stats directory. This file shows current and peak values for the following items:

  • Maximum number of sessions in the session table, including both active and timed out sessions.
  • Maximum number of active sessions.
  • Number of Session Notifications in the queue.
Note

There is a known issue with stats logging not working in OpenAM 13.0: OPENAM-6998 (Session "stats" logging doesn't seem to work). This is fixed in OpenAM 13.5.

Using ssoadm (OpenAM 13.x and earlier)

The ssoadm list-sessions command lists all the current sessions on a specified server with session details, for example:

$ ./ssoadm list-sessions -u amadmin -f pwd.txt -t http://host1.example.com:8080/openam

Example response:

[Current Session] User Id: amAdmin Time Remain: 1199999 Max Session Time: 1200000 Idle Time: 0 Max Idle Time: 300000
Index: 0 User Id: user1 Time Remain: 1199991 Max Session Time: 1200000 Idle Time: 8 Max Idle Time: 300000
Index: 1 User Id: user7 Time Remain: 1199850 Max Session Time: 1200000 Idle Time: 139 Max Idle Time: 300000
Index: 2 User Id: user12 Time Remain: 1199993 Max Session Time: 1200000 Idle Time: 6 Max Idle Time: 300000
Index: 3 User Id: user3 Time Remain: 1199862 Max Session Time: 1200000 Idle Time: 137 Max Idle Time: 300000
Index: 4 User Id: user19 Time Remain: 1199997 Max Session Time: 1200000 Idle Time: 2 Max Idle Time: 300000
Index: 5 User Id: user28 Time Remain: 1199992 Max Session Time: 1200000 Idle Time: 7 Max Idle Time: 300000
Index: 6 User Id: user17 Time Remain: 1199998 Max Session Time: 1200000 Idle Time: 1 Max Idle Time: 300000
To invalidate sessions, enter the index numbers
[CR without a number to exit]:

You can run the command with the -q option, which does not prompt you to invalidate sessions and can add a grep command after to just return a total, for example:

$ ./ssoadm list-sessions -u amadmin -f pwd.txt -t http://host1.example.com:8080/openam -q | grep "User Id" | wc -l

Example response (which matches the number of sessions listed above):

8

Using SNMP monitoring (OpenAM 13.x and earlier)

First you must enable SNMP monitoring; you can do this using either the console or ssoadm:

  • OpenAM 13.5 console: navigate to: Configure > Global Services > System > Monitoring and enable Monitoring SNMP interface status.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > System > Monitoring > Monitoring SNMP interface status and select the Enabled option.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMMonitoringService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-monitoring-snmp-enabled=true
    
    replacing [adminID] and [passwordfile] with appropriate values.

By default, this allows you to listen on port 8085 for SNMP monitoring. You can change the port via the console or ssoadm (iplanet-am-monitoring-snmp-port attribute) using the same navigation / service as above. 

Note

You must restart the web application container in which OpenAM runs to apply these configuration changes. 

Once enabled, you can use the snmpwalk command to provide specific session details. For example, the following command (assuming you are using port 8085) gives the number of active sessions on the current OpenAM server instance:

snmpwalk -c public -v 2c :8085 enterprises.42.2.230.3.1.1.2.1.11.1.0
Note

This command gives the same output as the SessionActiveCount JMX attribute; where both are reset to 0 when the OpenAM instance is restarted.

You can check which SNMP definitions are supported in the mib/FORGEROCK-OPENAM-SESSION.mib file (enterprises 36733), which can be found in the openam.war/WEB-INF/lib/openam-mib-schema-1.x.x.jar file. See Administration Guide › Monitoring OpenAM Services › SNMP Monitoring for other session related OIDs you can use.

See Also

Out of Memory exception causes AM/OpenAM (All versions) to hang due to increasing number of open policy agent sessions

Setup and Maintenance Guide › Maintaining an Instance › Managing Sessions

Reference › Configuration Reference › Session Properties

Setup and Maintenance Guide › Maintaining an Instance › Monitoring CTS Tokens

Installation Guide › Reference › Core Token Service (CTS) Object Identifiers

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-11976 (XUI Session query session by username does not work with +)

OPENAM-11700 (ssoadm list-sessions fails with Failed to get the valid sessions from the specified server)

OPENAM-11178 (RFE: XUI Sessions List - provide an overview of all sessions)

OPENAM-9817 (JMX CTS session count is broken)

OPENAM-9738 (Enable CTS segregation to allow each token type to write to a different CTS instance)

OPENAM-9728 (Provide ability for all monitoring ports per OpenAM instance and not globally. )

OPENAM-6998 (Session "stats" logging doesn't seem to work)

OPENAM-6002 ("stats" logs directory and contents are not documented)


Frequently Asked Questions


FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding CTS and session high availability in AM/OpenAM. Session high availability was formerly referred to as session failover.

Frequently asked questions

Q. Can I use any LDAP server for the CTS store?

A. No, DS/OpenDJ is the only supported backend for the CTS store. See Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)  for further information.

Q. Can I used the embedded CTS store in production?

A. We recommend that you use an external CTS store in production as it allows you to tune the LDAP server containing the CTS store separately to the LDAP server containing the configuration store. Typically, a directory containing tokens that change frequently and are relatively large (CTS store) needs different tuning to a directory containing data that is relatively stable (configuration store). Being able to tune these stores separately gives you greater control over performance. 

However, if you have a small scale deployment that is relatively simple, the embedded CTS store may be suitable for your needs; you should performance test this option to check it is appropriate to use the embedded CTS store.

This is discussed in more detail in Installation Guide › General Recommendations for CTS Configuration.

Q. Is the CTS store only used for session tokens?

A. No, the CTS store is used for a variety of tokens, such as OAuth, SAML and REST.

See Understanding CTS token types in AM/OpenAM for further information.

Q. Is it normal for a session token to be a negative number?

A. Yes it is normal due to the way in which session tokens (or coreTokenId attributes) are generated; it does not indicate an error. Session tokens are generated as follows:

  • They are composed of:
    <storage key (generated using SecureRandom)> + <legacy sessionID extension>
  • This value is then encrypted to a string.
  • This string is then converted to a String object using Hex.decodeHex() when the session token is generated. This step can sometimes produce a negative number.

Example

You may see session tokens with negative numbers, for example:

CTS: Create: Created SESSION Token -662229285778566861

Or see them represented as a coreTokenId attribute in your LDAP browser, for example:

Attribute Description                   Value
---------------------                   -----
coreTokenId                             -662229285778566861

Q. Can I use a load balancer with my CTS deployment?

A. You should avoid using a load balancer in front of the CTS stores as detailed in Installation Guide › General Recommendations for CTS Configuration.

See Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)  for further information.

Q. Can I improve CTS performance?

A. Yes, you can tune the DS/OpenDJ server to improve CTS performance as discussed in FAQ: DS/OpenDJ performance and tuning.

All requests are made asynchronously in the background, which increases performance as CPU and memory are better utilized. There are also two properties available (queue size and queue timeout) which can be set to tune CTS further as detailed in Installation Guide › CTS Tuning Considerations.

As of OpenAM 13.0, indexes have been optimized to further improve the performance of CTS.

Q. Can I configure the external CTS token store using ssoadm?

A. Yes you can providing the external CTS token store already exists (and you just want to modify its configuration using ssoadm) or you have taken steps to prepare the external DS/OpenDJ instance for CTS first. See How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm? for further information.

Q. What does session failover mean?

A. Session failover refers to the concept of persisting SSO sessions, which are stored in the CTS store. This store is shared with other servers in the same site to allow for persisting sessions. If a server (AM1) stops responding, other servers in the site can access the session information in the CTS; this means that a user who authenticated to AM1 does not have to log in again.

Session failover has been replaced in AM 5 with the concept of session high availability; this is enabled by default for all AM deployments. See AM 5 Release Notes › What's New › Cloud for further information.

Q. Do I need to configure session failover in sub-realms or will they inherit the settings from the top level realm?

A. Session failover is a system-wide setting so is not something that needs to be adjusted on a per-realm basis.

However, session timeouts can be adjusted on a per-realm basis as detailed in How do I configure realm level session timeouts in AM/OpenAM (All versions)?

Q. How do I enable session failover using ssoadm?

A. You can enable session failover in pre-AM 5 using one of the following ssoadm commands:

  • OpenAM 13.x
    $ ./ssoadm create-sub-cfg -u [adminID] -f [passwordfile] -s iPlanetAMSessionService -b [sitename] -g Site -a iplanet-am-session-sfo-enabled=true
    replacing [adminID], [passwordfile] and [sitename] with appropriate values.
  • Pre-OpenAM 13
    $ ./ssoadm create-sub-cfg -u [adminID] -f [passwordfile] -s iPlanetAMSessionService -b Site -g [sitename] -a iplanet-am-session-sfo-enabled=true
    replacing [adminID], [passwordfile] and [sitename] with appropriate values.

In summary, the difference between these commands is that the -b and -g options have swapped round in OpenAM 13.x. 

Note

Session failover has been replaced in AM 5 with the concept of session high availability; this is enabled by default for all AM deployments. See AM 5 Release Notes › What's New › Cloud for further information.

Q. Are sessions replicated across AM/OpenAM servers?

A. No, sessions are not replicated across AM/OpenAM servers; the CTS tokens that represent the user's session are replicated to all DS/OpenDJ nodes for which you have configured replication.

This is discussed in more detail in Installation Guide › CTS Backups and Directory Services Replication Purge Delay.

Q. Can I disable replication-purge-delay for the CTS backend?

A. No, the replication-purge-delay property is a system-wide setting and applies to the entire replication server; it is not possible to set this for an individual backend.

See Also

Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)

Best practice for using Core Token Service (CTS) Affinity based load balancing in AM (All versions) and OpenAM 13.5.1, 13.5.2

How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm?

Installation Guide › Implementing the Core Token Service

Core Token Service (CTS) and sessions in AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-4673 (External CTS Root DN is hardcoded)

OPENAM-3447 (CTS update fails due to attribute conflict)


FAQ: Session crosstalk and the Core Token Service (CTS) in OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding session crosstalk and the CTS in OpenAM. Crosstalk only applies to OpenAM 13.5.x and earlier. As of AM 5.0, crosstalk and the concept of a home server have been removed.

Frequently asked questions

Q. What is session crosstalk?

A. When a user authenticates, the session is created on the OpenAM server and is cached in memory on that server; this means that a session can only be validated on the originating (Home) server. In a multi-server deployment, a session may need to be validated on a different server to the one receiving the request. In this situation, the server receiving the request will make a HTTP request via a back channel to the Home server to retrieve the session. This mode of communication between servers for the purpose of validating sessions is referred to as session crosstalk. 

Any requests which update session objects such as log out, reset idle times or set a session attribute always use crosstalk to ensure the integrity. 

Q. What is the Home server?

A. The Home server is the server on which the session was created (the originating server). This may be the local server or a remote server depending on which server is receiving the request.

Note

As of AM 5.0, the concept of a Home server no longer applies; see Release Notes › What's New › New Features for further information on these changes. 

Q. How does OpenAM identify the Home server?

A. OpenAM uses the information contained in the session cookie (iPlanetDirectoryPro cookie) to identify the originating site and server as described in FAQ: Cookies in AM/OpenAM (Q. What information is contained in the AM/OpenAM session cookie?).

Q. When is session crosstalk used?

A. Session crosstalk happens when the session originates from a different OpenAM instance to one receiving the request.

Typically, OpenAM tries to resolve sessions in the following order upon receiving a request:

  1. Retrieves the session from the Home server as follows, in order:
    1. Looks up the cached session in memory if either it originates from the OpenAM instance receiving the request or it has been cached from a previous crosstalk attempt.
    2. Uses crosstalk to resolve the session on the remote server where the session originated if the remote server is up and running. The check of whether a server instance is alive is done by ClusterStateService. If the remote server is not running, OpenAM will try to find the next candidate. The retrieved session is then cached on the requesting server (non-Home server) to enable future requests to be resolved quickly. This session is stored per the Maximum Caching Time setting as detailed in How do I change the Maximum Caching Time in AM 5.x, 6 and OpenAM 12.x, 13.x? Additionally, a callback listener is registered with the Home server to enable notifications about session changes to be received to ensure the cached session does not become out-of-date.
  2. Looks up the session in the CTS store if all the other remote servers are down. If the other remote servers are running, AM/OpenAM will try to find the next candidate and perform crosstalk. This behavior is different when the Reduced Crosstalk option is set:
    1. When Reduced Crosstalk option is set, AM/OpenAM first tries to retrieve the session from the CTS for read operations. Any operation that requires the session state to be changed (e.g. Logout, set property , or reset idle time) will need to be delegated to the authoritative server (home server) and this is achieved using crosstalk.
    2. You should not disable reduced crosstalk unless advised to do so by ForgeRock Support. 
Note

Requests to update sessions, such as requests to log out, reset the session idle time, or set a session attribute, always use crosstalk to ensure the integrity of the update requests. See  Request Forward Caveats for further details including load balancer considerations. 

Q. How do OpenAM servers communicate with each other for crosstalk?

A. OpenAM uses the server URL for back channel communication. You should ensure that all OpenAM instances can communicate with each other via this URL. The URIs are:

  • /sessionservice for session related requests.
  • /namingservice for ClusterStateService.

You can check what port etc they are communicating on as follows:

  • OpenAM 13.5 console: navigate to Deployment > Servers.
  • Pre-OpenAM 13.5 console: navigate to Configuration > Servers and Sites.

For crosstalk, OpenAM performs a HTTP request against the remote Home server's sessionservice PLL endpoint (sent as XML) and receives back the session details in XML format (SessionInfo).

Q. How can I tell if crosstalk is being used?

A. You will see POST requests being made to the sessionservice endpoint from one OpenAM server to another. For example, you will see something similar to the following in the Apache Tomcat™ access logs, which in this example shows the call originating from IP address: 198.51.100.20:

198.51.100.20 - - [21/Jun/2017:10:07:11 +0100] "POST /openam/sessionservice HTTP/1.1" 200 403

You will also see requests being sent and received in the Session logs, for example:

PLLClient:03/06/2017 09:22:34:656 PM GMT: Thread[http-bio-8443-exec-23,5,main]
Send RequestSet Session XML :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RequestSet vers="1.0" svcid="session" reqid="198">
<Request><![CDATA[<SessionRequest vers="1.0" reqid="127">
<GetSession reset="true">
<SessionID>AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.*</SessionID>
</GetSession>
</SessionRequest>]]></Request>
</RequestSet>
PLLClient:03/06/2017 09:22:34:656 PM GMT Thread[http-bio-8443-exec-23,5,main]
Response XML :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseSet vers="1.0" svcid="session" reqid="198">
<Response dtdid=""><![CDATA[<SessionResponse vers="1.0" reqid="127">
<GetSession>
<Session sid="AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.*" stype="user" cid="uid=user1, ou=employees, ou=People, dc=example, dc=com" cdomain="o=users,ou=services,dc=amconfig,dc=example,dc=com" maxtime="900" maxidle="120" maxcaching="3" timeidle="2" timeleft="53980" state="valid">
<Property name="CharSet" value="UTF-8"></Property>
<Property name="UserId" value="user1"></Property>
<Property name="FullLoginURL" value="/openam/XUI/#login"></Property>
<Property name="successURL" value="/openam/XUI/#profile/></Property>
<Property name="cookieSupport" value="true"></Property>
<Property name="AuthLevel" value="0"></Property>
<Property name="SessionHandle" value="shandle:AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.*"></Property>
<Property name="UserToken" value="user1"></Property>
<Property name="loginURL" value="/openam/XUI/#login"></Property>
<Property name="maxTokenLifeMinutes" value="10080"></Property>
<Property name="IndexType" value="service"></Property>
<Property name="Principals" value="uid=user1, ou=employees, ou=People, dc=example, dc=com"></Property>
<Property name="Service" value="ldap"></Property>
<Property name="PostAuthProcessInstance" value="org.forgerock.openam.authentication.modules.persistentcookie.PersistentCookieAuthModule"></Property>
<Property name="sun.am.UniversalIdentifier" value="id=user1,ou=user,o=users,ou=services,dc=amconfig,dc=example,dc=com"></Property>
<Property name="amlbcookie" value="02"></Property>
<Property name="Organization" value="o=users,ou=services,dc=amconfig,dc=example,dc=com"></Property>
<Property name="Locale" value="en_GB"></Property>

A key line to note in the above log extract is the following, since reset="true" is what triggers crosstalk:

<GetSession reset="true">

If you see reset="false" instead, this means the CTS store will be used.

Q. How can I tell if the session is being retrieved from a local or remote server?

A. You can tell from the Session logs if the session is local or remote as follows:

  • Local:
    amSession:06/11/2017 03:29:01:534 AM GMT: Thread[tomcat-http--13,5,main]: TransactionId[d9f5bb96-71e6-463e-11755-2f7ea3950543-63]
    Local fetch SessionInfo for AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.*
    
  • Remote:
    amSession:06/11/2017 03:29:01:534 AM GMT: Thread[tomcat-http--13,5,main]: TransactionId[d9f5bb96-71e6-463e-11755-2f7ea3950543-63]
    Remote fetch SessionInfo for AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.*
    

Q. What impact does crosstalk have on network traffic?

A. Crosstalk generates network traffic, which can have an impact on performance. The HTTP requests made between servers are blocking calls, so you have an outgoing and incoming request when crosstalk is happening, and potentially a third request if the crosstalk is occurring between sites as well. This means a single user request can keep two or three request processing threads busy at a time. 

It is important to tune your timeout settings according to your network speed or latency; in particular, you need to set the following advanced server properties (in milliseconds) appropriately for your deployment:

com.sun.identity.url.readTimeout              (default is 30000 ms)
org.forgerock.openam.url.connectTimeout       (default is 10000 ms)

You can set these properties using either the console or ssoadm:

  • OpenAM 13.5 console: navigate to Deployment > Servers > [Server Name] > Advanced and add the required property and value.
  • Pre-OpenAM 13.5 console: navigate to Configuration > Servers and Sites > [Server Name] > Advanced and add the required property and value.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s [serverName] -u [adminID] -f [passwordfile] -a [property=value]
    replacing [serverName], [adminID], [passwordfile] and [property=value] with appropriate values.

If these timeouts are set too low to allow a remote server to respond, crosstalk will fail and you will see errors such as the following in your logs:

  • CoreSystem log:
    amXMLHandler:06/11/2017 03:29:01:532 AM GMT: Thread[http-nio-8080-exec-41,5,main]
    Error Response String : <Exception errorCode="Read timed out"></Exception>
    PLLClient:06/11/2017 03:29:01:532 AM GMT: Thread[http-nio-8080-exec-34,5,main]
    WARNING: PLLClient.send: exception: 
    java.net.SocketTimeoutException: Read timed out
  • Sessions log:
    amSession:06/11/2017 03:29:01:532 AM GMT: Thread[SystemTimer,5,main]: TransactionId[d9f5bb96-71e6-463e-11755-2f7ea3950543-63]
    ERROR: 20218:ClusterStateService.checkServerUp():: timeout too small 10000
    
    amSession:06/11/2017 03:29:01:534 AM GMT: Thread[SystemTimer,5,main]: TransactionId[d9f5bb96-71e6-463e-11755-2f7ea3950543-63]
    ERROR: 20218:ClusterStateService.checkServerUp():: error while checking server 01
    java.net.SocketTimeoutException: connect timed out
    amSession:06/11/2017 03:29:01:534 AM GMT: Thread[tomcat-http--13,5,main]: TransactionId[d9f5bb96-71e6-463e-11755-2f7ea3950543-63]
    processSessionRequest caught exception: connect timed out
    com.iplanet.dpro.session.SessionException: connect timed out

Q. What happens if the CTS store is down?

A. This depends on whether the Reduced Crosstalk option is set or not: 

  • If it is not set, OpenAM should retrieve the session from the Home server as described in Q. When is session crosstalk used? 
  • If it is set, OpenAM will try to retrieve the session from the CTS store but will fail.

Q. Are policy agent sessions stored in the CTS store?

A. No, policy agent sessions (Application SSOSession) are not stored in the CTS store by default as they are not subject to session failover. Therefore, crosstalk is always used with policy agent sessions.

However, if the Reduced Crosstalk option is set, policy agent session validation will always fail since the session does not exist in the CTS store and crosstalk is not used for agent sessions when this option is set. When this happens, you will see errors such as the following in the agent logs (debug.log or amAgent):

2017-06-09 11:03:47.002 Error 4786:7fc8f789bae0 AM_SSO_SERVICE: SSOTokenService::getSessionInfo(): Error 35 for sso token ID AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.* 
2015-08-12 12:59:59.002 Error 4786:7fc8f789bae0 PolicyEngine: am_policy_evaluate: InternalException in Service::update_policy with error message:Session query failed. and code:35

Storing policy agent sessions in the CTS store

You can change the configuration to store policy agent sessions in the CTS store by setting the com.iplanet.am.session.agentSessionIdleTime property to force idle policy agent sessions to expire.

The default is 0 (policy agent sessions never expire) but you can also set it to a value of 30 or above (no maximum) to indicate the number of minutes a session can be idle. When set to 30 or above, the agent application token is stored in the CTS token store rather than locally. 

You can set this property using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Advanced > com.iplanet.am.session.agentSessionIdleTime and amend the required number of minutes.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced > com.iplanet.am.session.agentSessionIdleTime and enter the required number of minutes.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.session.agentSessionIdleTime=[minutes]
    replacing [adminID], [passwordfile] and [minutes] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)

Sessions

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9731 (Occasional failure to find server from ID in Webtop/Naming )

OPENAM-5632 (Occasional failure of OpenAM configurator tool)


Known Issues


CTS


ERROR: CTS Async: Task Processor Error: interrupt detected when shutting down AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you encounter an "ERROR: CTS Async: Task Processor Error: interrupt detected" when shutting down the AM/OpenAM server.

Symptoms

The following error is shown in the Session debug log when shutting down AM/OpenAM:

amCoreTokenService:11/09/2016 03:19:01:018 PM UTC: Thread[CTSWorkerPool-4,5,main]: TransactionId[393810d1-634a-45e0-b105-a3e040775526-0]
ERROR: CTS Async: Task Processor Error: interrupt detected
java.lang.InterruptedException
   at java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject.reportInterruptAfterWait(AbstractQueuedSynchronizer.java:2014)
   at java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject.await(AbstractQueuedSynchronizer.java:2048)
   at java.util.concurrent.LinkedBlockingQueue.take(LinkedBlockingQueue.java:442)
   at org.forgerock.openam.sm.datalayer.impl.SeriesTaskExecutorThread.run(SeriesTaskExecutorThread.java:91)
   at org.forgerock.openam.audit.context.AuditRequestContextPropagatingRunnable.run(AuditRequestContextPropagatingRunnable.java:42)

Recent Changes

Restarted or shut down the AM/OpenAM server.

Causes

This error occurs when AM/OpenAM is shutdown while debug mode is enabled. It implies that the operation was canceled or the AM/OpenAM server was shutting down whilst processing requests. It can occur even if you are not using CTS.

Solution

This is a harmless error that can be ignored as it only occurs during shut down.

See Also

N/A

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8219 (After restarting an OpenAM it is necessary to login again with an user when is used external CTS and Site contains only one server)


Continuous query listener has lost its connection and insufficient access rights errors in AM 5.x and 6.0.x

The purpose of this article is to provide assistance if you encounter "Continuous query listener has lost its connection" warnings accompanied by "The request control with Object Identifier (OID) "" cannot be used due to insufficient access rights" errors in AM.

Symptoms

The following warning is shown repeatedly in the IdRepo debug log, which shows the connection being established, but the persistent control connection request failing:

PersistentSearch:10/11/2018 03:09:14:594 PM GMT: Thread[SystemTimerPool,5,main]: TransactionId[743b0898-31f8-4a43-b30f-e30784c19ef5-94]
Starting persistent search against baseDN: dc=cts,dc=example,dc=com, scope: sub, filter: (&(coreTokenType=NOTIFICATION)(objectClass=frCoreToken)), attrs: [coreTokenObject, dn] against org.forgerock.openam.cts.monitoring.impl.connections.MonitoredCTSConnectionFactory@334410e7
org.forgerock.openam.notifications.integration.brokers.CTSNotificationBroker:10/11/2018 03:09:14:595 PM GMT: Thread[OpenDJ LDAP SDK Client Worker(726),5,main]: TransactionId[743b0898-31f8-4a43-b30f-e30784c19ef5-649444]
WARNING: Continuous query listener has lost its connection
PersistentSearch:10/11/2018 03:09:14:596 PM GMT: Thread[OpenDJ LDAP SDK Client Worker(726),5,main]: TransactionId[743b0898-31f8-4a43-b30f-e30784c19ef5-649444]
Restarting persistent search connection against: org.forgerock.openam.cts.monitoring.impl.connections.MonitoredCTSConnectionFactory@334410e7

A corresponding insufficient access rights error is shown, for example:

  • CTS ldap-access.audit.json log:
    {"eventName":"DJ-LDAP","client":{"ip":"192.0.2.0","port":36424},"server":{"ip":"192.0.2.1","port":36890},"request":{"protocol":"LDAP","operation":"SEARCH","connId":10,"msgId":184,"dn":"dc=cts,dc=example,dc=com","scope":"sub","filter":"(&(coreTokenMultiString01=2a1e1c55-1353-44f3-83d6-04eb060cc53f)(objectClass=frCoreToken))","attrs":["coreTokenString05","dn"]},"transactionId":"d893c6b2-557a-49de-9c72-6a831765ee8d-231/158","response":{"status":"FAILED","statusCode":"12","elapsedTime":1,"elapsedTimeUnits":"MILLISECONDS","detail":"The request control with Object Identifier (OID) \"2.16.840.1.113730.3.4.3\" cannot be used due to insufficient access rights","nentries":0},"timestamp":"2018-11-10T15:09:14.594Z","_id":"05afe287-a4c5-48dd-a65f-f86d1193c0f0-18723"}
    
  • Session debug log:
    amCoreTokenService:10/11/2018 03:09:14:594 PM GMT: Thread[CTSWorkerPool-15,5,main]: TransactionId[345e5867-025f-46db-b441-ea699659f91a-0] 
    Failed to delete SESSION token with id KXMgkwZWiTevm5WTe0kvziKj3p0= 
    org.forgerock.openam.cts.exceptions.CoreTokenException: 
    CTS: 
    CTS: Operation failed: 
    Result Code: Unavailable Critical Extension 
    Diagnostic Message: The request control with Object Identifier (OID) "1.3.6.1.1.12" cannot be used due to insufficient access rights 
    Matched DN: 
       at org.forgerock.openam.cts.reaper.PromiseResultHandler.processError(PromiseResultHandler.java:39) 
       at org.forgerock.openam.sm.datalayer.api.AbstractTask.processError(AbstractTask.java:41) 
       at org.forgerock.openam.sm.datalayer.api.AbstractTask.execute(AbstractTask.java:63) 
       at org.forgerock.openam.sm.datalayer.impl.SeriesTaskExecutor$TaskDecorator.execute(SeriesTaskExecutor.java:231) 
       at org.forgerock.openam.sm.datalayer.impl.SimpleTaskExecutor.execute(SimpleTaskExecutor.java:59) 
       at org.forgerock.openam.sm.datalayer.impl.SeriesTaskExecutorThread.run(SeriesTaskExecutorThread.java:86) 
       at org.forgerock.openam.audit.context.AuditRequestContextPropagatingRunnable.run(AuditRequestContextPropagatingRunnable.java:34) 
       at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511) 
       at java.util.concurrent.FutureTask.run(FutureTask.java:266) 
       at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149) 
       at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624) 
       at java.lang.Thread.run(Thread.java:748) 
    Caused by: org.forgerock.openam.sm.datalayer.api.LdapOperationFailedException: 
    CTS: Operation failed: 
    Result Code: Unavailable Critical Extension 
    Diagnostic Message: The request control with Object Identifier (OID) "1.3.6.1.1.12" cannot be used due to insufficient access rights 
    

Recent Changes

Installed, or upgraded to AM 5.x or 6.0.x.

Configured an external CTS token store.

Causes

The "Continuous query listener has lost its connection" message is a generic warning signifying a CTS connection issue. In conjunction with an insufficient access rights error, it implies that the required ACI has not been set up correctly for the CTS admin user:

  • The "2.16.840.1.113730.3.4.3" OID is the persistent search control, which is required by the CTS admin user.
  • The "1.3.6.1.1.12" OID is a default global ACI that gives authenticated users LDAP read access; this must be specified during the setup if DS is configured in productionMode.
Note

Configuring these ACIs is a required step detailed in the Install guide for implementing the CTS: Installation Guide › Non-Admin User Creation and ACI Import.

Solution

This issue can be resolved by configuring the ACIs correctly for the CTS admin user:

  • If you haven't followed the steps in the Install guide, you should work through these steps to set up your CTS admin user correctly: To Create a Non-Admin User.
  • If you have followed the steps in the Install guide, something went wrong with the setup process. To identify and fix the issue, you should:
    • Double-check you followed all the steps in the Install Guide.
    • Check you applied the ACIs to the correct user; you can search the access log for the BIND request with the same ConnId noted in the CTS ldap-access.audit.json log to identify the user who does not have the appropriate ACIs. See How do I use the Access log to troubleshoot DS/OpenDJ (All versions)? (Finding out more about the operation section) for further information on searching the access log.
    • Check your configuration for typos or malformed LDIFs; each line in the LDIFs must begin with the field name, followed by a colon and the value. If your LDIFs are badly formed, you can reformat them and reapply with the ldifmodify command.
Note

These configuration steps are automated in AM 6.5 (using the am-cts profile in DS), which prevents common misconfigurations of the CTS admin user in AM 6.5 and later. See Installation Guide › Configuring CTS in AM for further information.

See Also

Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)

How do I know what the default Global ACIs are used for in DS/OpenDJ (All versions)?

Installation Guide › Preparing an External Configuration Data Store

Security Guide › Using ACIs or Global Access Policies

Related Training

N/A

Related Issue Tracker IDs

N/A


AM 5, 5.1.x and OpenAM 13.5.1 cannot access external CTS after configuration is changed via the console

The purpose of this article is to provide assistance if AM/OpenAM cannot access the external Core Token Service (CTS) after the configuration has been changed via the console. You will also see a "CTS: Configuration was invalid" error in your logs when this happens.

Symptoms

AM/OpenAM cannot access the external CTS store after configuration changes are made via the console (using either the CTS or Advanced option under Server Defaults). You are unable to access the console If AM/OpenAM is restarted after saving your configuration changes.

You will see the following error in the AM CoreSystem debug logs:

Caused by: java.lang.RuntimeException: org.forgerock.openam.sm.datalayer.api.DataLayerException:
CTS: Configuration was invalid
   at org.forgerock.openam.core.guice.CoreGuiceModule.getCTSWorkerExecutorService(CoreGuiceModule.java:382)
   at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
   at java.lang.reflect.Method.invoke(Method.java:606)
   at com.google.inject.internal.ProviderMethod.get(ProviderMethod.java:104)
   at com.google.inject.internal.InternalFactoryToProviderAdapter.get(InternalFactoryToProviderAdapter.java:40)
   at com.google.inject.internal.InjectorImpl$4$1.call(InjectorImpl.java:978)
   at com.google.inject.internal.InjectorImpl.callInContext(InjectorImpl.java:1031)
   at com.google.inject.internal.InjectorImpl$4.get(InjectorImpl.java:974)
   at com.google.inject.spi.ProviderLookup$1.get(ProviderLookup.java:89)
   at com.google.inject.internal.InternalFactoryToProviderAdapter.get(InternalFactoryToProviderAdapter.java:40)
   at com.google.inject.internal.SingleParameterInjector.inject(SingleParameterInjector.java:38)
   at com.google.inject.internal.SingleParameterInjector.getAll(SingleParameterInjector.java:62)
   at com.google.inject.internal.ConstructorInjector.construct(ConstructorInjector.java:84)

If you check the CTS configuration via the console, you will notice the bind password field is empty; similarly, the bind password (org.forgerock.openam.services.cts.store.password) will also be missing from DS/OpenDJ.

On the DS/OpenDJ side, you will see failures in the access log similar to the following:

[21/Oct/2017:15:21:29 +0100] BIND REQ conn=11 op=0 msgID=1 version=3 type=SIMPLE dn="cn=Directory Manager"
[21/Oct/2017:15:21:29 +0100] BIND RES conn=11 op=0 msgID=1 result=49 authFailureReason="The password provided by the user did not match any password(s) stored in the user's entry" authDN="cn=Directory Manager" etime=1

Run an ldapsearch against the AM/OpenAM configuration store to check if "org.forgerock.services.cts.store.password" exists, for example:

$./ldapsearch --port 50389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN ou=services,dc=openam,dc=forgerock,dc=org "objectclass=*" | grep "serverconfig=org.forgerock.services.cts.store.password"

If the entry exists, you will see the following sunKeyValue returned with the encrypted password:

sunKeyValue: serverconfig=org.forgerock.services.cts.store.password=AQICJGRFB44klBpzNjYQZpUyFhh73lmwivHG

Recent Changes

Configured an external CTS via the console.

Made changes to the external CTS configuration using the console.

Causes

There is a known issue: OPENAM-11987 (SmsServerPropertiesResource removes password when unchanged.) where saving CTS configuration changes via the console inadvertently removes the saved bind password for the external CTS store, which in turn prevents access to the CTS due to invalid credentials.

Solution

This issue can be resolved by upgrading to AM 5.5.1 or later, or OpenAM 13.5.2; you can download this from BackStage.

Workaround

You can workaround this issue by re-entering the bind password before saving CTS configuration changes in the console or by using ssoadm to update the CTS configuration instead: How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm?

If you have already saved your configuration changes, you can re-enter the password using either the console (providing you have not restarted AM/OpenAM), Amster (AM 5 and later) or ssoadm:

  • Console: navigate to: Configure > Server Defaults > CTS > External Store Configuration > Password and enter the bind password.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: CtsDataStoreProperties
    • Property: org.forgerock.services.cts.store.password
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a org.forgerock.services.cts.store.password=[bindPassword]
    replacing [adminID], [passwordfile] and [bindPassword] with appropriate values.

See Also

How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11987 (SmsServerPropertiesResource removes password when unchanged.)

OPENAM-11834 (Passwords being set to empty strings in tabbed forms in XUI)

OPENAM-11763 ("Saving" CTS configuration overwrites the bind password)


CoreSystem debug log grows rapidly in OpenAM 13.0 and 13.5 when CTS connection fails

The purpose of this article is to provide assistance if the CoreSystem debug log fills up quickly in OpenAM 13.0 and 13.5 when the CTS connection fails. You will see "Cannot start task executor" and "Diagnostic Message: No operational connection factories available" errors repeating continually in the debug log. This log growth can fill the disk up, bypassing the log rotation maximum value and eventually bring OpenAM down.

Symptoms

The following error is shown in the CoreSystem debug log when the log fills up:

amThreadManager:01/26/2016 02:14:47:633 PM GMT: Thread[amThreadManager-1,5,ServerService ThreadGroup]: TransactionId[300c2122-7500-4b31-abdc-39a19681ff30-2]
ERROR: ThreadMonitor: Thread WatchDog detected error, restarting
java.util.concurrent.ExecutionException: java.lang.IllegalStateException: Cannot start task executor
   at java.util.concurrent.FutureTask.report(FutureTask.java:122)
   at java.util.concurrent.FutureTask.get(FutureTask.java:192)
   at org.forgerock.openam.shared.concurrency.ThreadMonitor$WatchDog.run(ThreadMonitor.java:231)
   at org.forgerock.openam.audit.context.AuditRequestContextPropagatingRunnable.run(AuditRequestContextPropagatingRunnable.java:42)
   at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
   at java.util.concurrent.FutureTask.run(FutureTask.java:266)
   at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
   at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
   at java.lang.Thread.run(Thread.java:745)
Caused by: java.lang.IllegalStateException: Cannot start task executor
   at org.forgerock.openam.sm.datalayer.impl.SeriesTaskExecutorThread.run(SeriesTaskExecutorThread.java:85)
   ... 6 more
Caused by: org.forgerock.openam.sm.datalayer.api.LdapOperationFailedException: 
CTS: Operation failed:
Result Code: Connect Error
Diagnostic Message: No operational connection factories available
Matched DN: 
   at org.forgerock.openam.sm.datalayer.providers.LdapConnectionFactoryProvider$LdapConnectionFactory.create(LdapConnectionFactoryProvider.java:158)
   at org.forgerock.openam.sm.datalayer.providers.LdapConnectionFactoryProvider$LdapConnectionFactory.create(LdapConnectionFactoryProvider.java:126)
   at org.forgerock.openam.cts.monitoring.impl.connections.MonitoredCTSConnectionFactory.create(MonitoredCTSConnectionFactory.java:71)
   at org.forgerock.openam.sm.datalayer.impl.SimpleTaskExecutor.start(SimpleTaskExecutor.java:59)
   at org.forgerock.openam.sm.datalayer.impl.SeriesTaskExecutorThread.run(SeriesTaskExecutorThread.java:83)
   ... 6 more
Caused by: org.forgerock.opendj.ldap.ConnectionException: Connect Error 

The final Caused by statement varies depending on the root cause, but you may see one of the following causes instead:

Caused by: org.forgerock.opendj.ldap.ConnectionException: Connect Error: Connection refused

Caused by: org.forgerock.opendj.ldap.ConnectionException: Server Connection Closed 

Caused by: org.forgerock.opendj.ldap.AuthenticationException: Invalid Credentials
Note

You will still encounter this issue even if you have debug log rotation set up since OpenAM does not currently delete old log files once they are rotated.

Recent Changes

Upgraded to, or installed OpenAM 13.0 or 13.5.

Made configuration changes to CTS.

CTS Configuration is set to incorrect value for "Login Id".

Causes

OpenAM cannot connect to the CTS token store; this may be because CTS is misconfigured or there is a connection issue, such as the CTS token store is down or a firewall is refusing the connection between the two servers.

There is a known issue where this situation results in the errors being continually logged in the CoreSystem debug log, which causes it to grow rapidly: OPENAM-8202 (If the "Login Id" in the External Store Configuration(CTS) is set to incorrect value,CoreSystem debug log is full of duplicate error).

Solution

This issue can be resolved by upgrading to OpenAM 13.5.1 or later; you can download this from BackStage.

Workaround

Alternatively, this issue can be resolved as follows:

  1. Clear your CoreSystem debug log.
  2. Correct the root cause.

Clear your CoreSystem debug log: You can clear the debug file as detailed in How do I clear debug logs in AM/OpenAM (All versions)? This should make the system responsive again, although the CoreSystem debug log will immediately start filling again so you need to be quick. If you do not have time to rectify your issue before the log fills up again, you can run the following command to continually clear the debug file on a loop to give you more time:

$ while true; do cat /dev/null > CoreSystem; done

Alternatively, you can temporarily switch OpenAM back to using the default embedded CTS token store (rather than external) using the following ssoadm command to give you more time: 

$ ./ssoadm update-server-cfg -s [serverName] -u [adminID] -f [passwordfile] -a org.forgerock.services.cts.store.location=default

replacing [serverName], [adminID] and [passwordfile] with appropriate values. You can use default for [serverName] if you want to change the Default Server Settings. 

Correct the root cause: Depending on whether you made any configuration changes or not, you should:

See Also

How do I configure an external CTS token store in AM/OpenAM (All versions) using Amster or ssoadm?

Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

Installation Guide › Implementing the Core Token Service

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8202 (If the "Login Id" in the External Store Configuration(CTS) is set to incorrect value,CoreSystem debug log is full of duplicate error)


Sessions


Sessions in AM 5, 5.1 and OpenAM 13.x exceed the session quota limit without expiring

The purpose of this article is to provide assistance if you notice that sessions in AM/OpenAM are not expiring, meaning the total number of sessions for a user can exceed the session quota limit. This can happen when the session quota behavior is set to DESTROY_NEXT_EXPIRING (default setting), DESTROY_OLDEST_SESSION or DESTROY_LAST.

Symptoms

There are two notable symptoms associated with this issue:

  • An individual user can have more concurrent sessions than are permitted, where some of the sessions have an idle time that exceeds the idle timeout limit. This can be seen in the console or using other session monitoring methods as detailed in How do I monitor session statistics in AM/OpenAM (All versions)? Although these sessions are visible in the console, the amadmin user may not always be able to invalidate them. This issue with concurrent sessions can also cause SAML requests to fail, where concurrent requests are received.
  • Old sessions are not expired as expected. You will intermittently see one of the following messages in your browser or in response to a REST call, even though the sessions should be destroyed automatically to prevent the maximum number being reached:
    Maximum Sessions Limit Reached
    
    Maximum sessions limit reached or session quota has exhausted
    
    Retrying often resolves it and allows you to log in.

You will also witness this behavior in the logs. The following examples show the type of errors you may see depending on your setup / use cases:

  • amAuthentication.error log:
    "2017-05-03 11:42:12" "Maximum Sessions Limit Reached." 198.51.100.0 "cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org" id=jdoe@example.com,ou=user,ou=employees,dc=openam,dc=forgerock,dc=org "Not Available" nasacom "Not Available" ou=employees,dc=openam,dc=forgerock,dc=org INFO 198.51.100.0 AUTHENTICATION-200
    
  • Authentication debug log:
    amAuth:04/05/2017 11:32:54:495 AM GMT: Thread[ajp-apr-8009-exec-220,5,main]
    Error message is : Maximum Sessions Limit Reached.
    amAuthUtils:04/05/2017 11:32:54:495 AM GMT: Thread[ajp-apr-8009-exec-220,5,main]
    URL name : PostProcessLoginFailureURL Value : Not set - null or empty string
    amAuth:04/05/2017 11:32:54:495 PM GMT: Thread[ajp-apr-8009-exec-220,5,main]
    processURL : null
    amAuthREST:04/05/2017 11:32:54:495 PM GMT: Thread[ajp-apr-8009-exec-220,5,main]
    AuthenticationService.authenticate() :: Rest Authentication Exception
    org.forgerock.openam.forgerockrest.authn.exceptions.RestAuthErrorCodeException: Maximum Sessions Limit Reached.
       at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.processAuthentication(RestAuthenticationHandler.java:284)
       at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.processAuthentication(RestAuthenticationHandler.java:251)
       at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:160)
       at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.initiateAuthentication(RestAuthenticationHandler.java:93)
       at org.forgerock.openam.forgerockrest.authn.restlet.AuthenticationServiceV1.authenticate(AuthenticationServiceV1.java:133)
    
  • Session debug log:
    amSession:05/04/2017 10:48:39:378 AM EST: Thread[http-0.0.0.0:8080-1,5,main]
    SessionConstraint.checkQuotaAndPerformAction: Session quota exhausted.
    
    
    amSession:05/04/2017 10:49:18:378 AM EST: Thread[http-0.0.0.0:8080-1,5,main]
    Failed to destroy the next expiring session.
    com.iplanet.dpro.session.SessionException: Session is in a destroyed state
       at com.iplanet.dpro.session.Session.getSession(Session.java:1170)
       at com.iplanet.dpro.session.Session.getSession(Session.java:1133)
       at com.iplanet.dpro.session.Session.getSession(Session.java:1118)
    
    
  • Federation debug log:
    libSAML2:05/04/2017 10:45:02:306 PM GMT: Thread[http-nio-8080-exec-34,5,main] 
    ERROR: spAssertionConsumer.jsp: SSO failed. 
    com.sun.identity.saml2.common.SAML2Exception: Login Failed 
    Maximum Sessions Limit Reached.|maxSessions.jsp 
       at com.sun.identity.saml2.profile.SPACSUtils.processResponse(SPACSUtils.java:1328) 
       at org.apache.jsp.saml2.jsp.spAssertionConsumer_jsp._jspService(spAssertionConsumer_jsp.java:255) 
    
       at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70) 
       ...
    Caused by: com.sun.identity.plugin.session.SessionException: Login Failed 
    Maximum Sessions Limit Reached.|maxSessions.jsp 
       at com.sun.identity.plugin.session.impl.FMSessionProvider.createSession(FMSessionProvider.java:285) 
       at com.sun.identity.saml2.profile.SPACSUtils.processResponse(SPACSUtils.java:1307) 
    ... 35 more 
    Caused by: com.sun.identity.authentication.spi.AuthLoginException: Login Failed 
    

Recent Changes

Enabled session quota constraints.

Changed the session quota behavior to DESTROY_NEXT_EXPIRING (default setting), DESTROY_OLDEST_SESSION or DESTROY_LAST.

Causes

Concurrent attempts to authenticate are not subject to quota constraints. These concurrent attempts can originate from either a single server or a multi-server deployment.

This issue happens because the time interval to persist the session in CTS (and get it replicated to other CTS instances) is longer than a second instance trying to query for active sessions. The session quota is always checked before activating a new session, so if the session hasn't been persisted to another CTS instance by the time the check is done, then it is possible to exceed the session quota.

Solution

This issue can be resolved by upgrading to AM 5.5 and later, or OpenAM 13.5.1; you can download this from BackStage.

Note

It is still possible to exceed the quota constraints set but AM/OpenAM will recover properly when a new authentication attempt is made.

Workaround

A suggested workaround for this issue is to set the session quota behavior to DESTROY_OLD_SESSIONS; once the session quota is reached, this option invalidates all previous sessions and resets the session count to 0.

See Also

Session quotas not limiting active user sessions in AM/OpenAM (All versions) when persistent cookies are used

How do I monitor session statistics in AM/OpenAM (All versions)?

Authentication and Single Sign-On Guide › Session Quotas

Related Training

N/A

Related Issue Tracker IDs

OPENAM-10332 (Quota constraints exceeded - Interim Fix)

OPENAM-5864 (Quota constraints exceeded in multi-instance with LB and CTS enabled)


Session quotas not limiting active user sessions in AM/OpenAM (All versions) when persistent cookies are used

The purpose of this article is to provide information when session quotas do not appear to be limiting the number of active user sessions in AM/OpenAM when persistent cookies are used.

Symptoms

The number of active sessions per user appears to exceed the number specified in Active User Sessions.

Recent Changes

Configured session quotas with Resulting behavior if session quota exhausted option set to anything other than DENY_ACCESS.

Enabled persistent cookies.

Causes

The persistent cookie feature enables a previously destroyed session to be resumed by refreshing the browser. When used in conjunction with session quotas, it can appear that there are more sessions than the quota should allow. In fact, each time a session is resumed using refresh, a session in another browser is destroyed, thereby maintaining the quota; as this all occurs seamlessly, it can appear that there are endless sessions, but actually the number of active sessions never exceeds the limit specified.

Solution

The functionality is working correctly and sessions are limited as per the session quota.

See Also

Authentication and Single Sign-On Guide › Implementing Session Options › Implementing Session Quotas

Authentication and Single Sign-On Guide › Implementing Authentication › Persistent Cookie Module

Session Quota basics

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-2414 (Session quota does not work when SFO is enabled)


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...