Installing and configuring AM/OpenAM

This book provides information on installing and configuring AM/OpenAM, including frequently asked questions and known issues.


General


What automation tools are available for installing, upgrading and configuring AM/OpenAM deployments (All versions)?

The purpose of this article is to provide information on the tools available to automate your AM/OpenAM deployments. These tools let you perform silent installations and upgrades, as well as configure or update a deployed AM/OpenAM server from a configuration file or using the REST API.

Automation tools

The following automation tools are available in AM/OpenAM:

See Also

Install and configuration

ssoadm

REST API

Amster

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


What versions of DS/OpenDJ are compatible with AM/OpenAM?

The purpose of this article is to provide compatibility information between DS/OpenDJ and AM/OpenAM versions. This includes the embedded DS/OpenDJ versions shipped with AM/OpenAM and, the supported Java® versions for each combination.

DS/OpenDJ and AM/OpenAM compatibility

Embedded DS/OpenDJ

Embedded DS/OpenDJ versions are shipped with AM/OpenAM and cannot be upgraded; however, when you upgrade to a newer version of AM/OpenAM, the embedded DS/OpenDJ instance is also upgraded. The following embedded DS/OpenDJ versions are included with AM/OpenAM:

AM/OpenAM versions Embedded DS/OpenDJ version
AM 6.5.2 DS 6.5.2
AM 6.5.1 DS 6.5.1
AM 6.5 DS 6.5
AM 6 DS 6
AM 5.5 and 5.5.1 DS 5.5
AM 5 and 5.1.x DS 5
OpenAM 13.5.2 OpenDJ 3.5.3
OpenAM 13.5.1 OpenDJ 3.5.2
OpenAM 13.5 OpenDJ 3.5
OpenAM 13.0 OpenDJ 3.0
OpenAM 12.0.4 OpenDJ 2.6.4
OpenAM 12.0.0 to 12.0.3 OpenDJ 2.6.2

External DS/OpenDJ

The following matrix indicates compatibility between AM/OpenAM and external DS/OpenDJ versions:

  DS 6.x DS 5.x OpenDJ 3.x OpenDJ 2.6.x
AM 6.x Yes Yes Yes --
AM 5.5 Yes Yes Yes --
AM 5 and 5.1.x Yes Yes Yes Partly (User Store only)
OpenAM 13.x -- -- Yes Yes
OpenAM 12.x -- -- -- Yes
Note

It is strongly recommended that you always upgrade to the latest maintenance releases for whichever versions of AM/OpenAM and DS/OpenDJ you have deployed.

Java Compatability

Java 11

  • AM 6.5 and later.
  • DS 6.5 and later.

Java 9

  • DS 6 only.

Java 8

  • AM 5 and later; OpenAM 12.0.0 and later
  • DS 5 and later; OpenDJ 2.6.2 and later

Java 7

  • AM 5 and 5.1.x; OpenAM 12.x and 13.x
  • OpenDJ 2.6.x and 3.x. Java 7 can be used in DS 5 but support for it is deprecated.

Software and Hardware requirements

AM/OpenAM

DS/OpenDJ

See Also

What operating systems are ForgeRock products supported on?

Checking your product versions are supported

FAQ: Installing AM/OpenAM

FAQ: Upgrading AM/OpenAM

FAQ: Installing and configuring DS/OpenDJ

Installing and configuring AM/OpenAM

Installing and Administering DS/OpenDJ

Related Training

N/A

Related Issue Tracker IDs

N/A


What versions of Policy Agents are compatible with AM/OpenAM?

The purpose of this article is to provide compatibility information between Policy Agents and AM/OpenAM versions. Also included is the supported Java® versions for each combination.

Policy Agents and AM/OpenAM compatibility

Caution

Web policy agents 4.x and JEE policy agents 3.5.x are not supported in AM 6.5; you will need to upgrade to the latest Agents 5 release ahead of upgrading to AM 6.5. 

Web policy agents

The following matrix indicates compatibility between AM/OpenAM and Web policy agent versions:

  Web Agents 5.x Web Policy Agents 4.x
AM 6.5.x Yes (5.0.1 or later) --
AM 6 Yes (5.0.1 or later) Yes *
AM 5.5 Yes Yes
AM 5 and 5.1.x -- Yes
OpenAM 13.x -- Yes
OpenAM 12.x -- Yes

* New Agents Profiles on AM 6 are not compatible with Web Agents 4.x by default and will require setting the AM Login URL and AM Logout URL to work with AM 6. Additionally, the experimental REST login mode that was introduced in Web Agents 4.1.0.30 will not work with AM 6.0.0.x. See How do I configure AM 6.0.0.x to work with older policy agents (Web 4.x and JEE 3.5.x)? for details. 

Java policy agents

The following matrix indicates compatibility between AM/OpenAM and Java policy agent versions:

  Java Agents 5.x JEE Policy Agents 3.5.x
AM 6.5.x Yes (5.0.1 or later) --
AM 6 Yes (5.0.1 or later) Yes *
AM 5.5 Yes Yes
AM 5 and 5.1.x -- Yes
OpenAM 13.x -- Yes
OpenAM 12.x -- Yes

* New Agents Profiles on AM 6 are not compatible with JEE Agents 3.5.x by default and will require setting the AM Login URL and AM Logout URL to work with AM 6. See How do I configure AM 6.0.0.x to work with older policy agents (Web 4.x and JEE 3.5.x)? for details.

Note

It is strongly recommended that you always upgrade to the latest maintenance releases for the specific versions of AM/OpenAM and Policy Agents you have deployed.

Java Compatability

Java 11

  • AM 6.5 and later.
  • Java Agents 5.6 and later.

Java 8

  • AM 5 and later; OpenAM 12.x and 13.x
  • JEE Policy Agents 3.5 and later

Java 7

  • AM 5.0 and 5.1.x; OpenAM 12.x and 13.x
  • JEE Policy Agents 3.5

Java 6

  • OpenAM 12.x
  • JEE Policy Agents 3.5

Software and Hardware requirements

AM/OpenAM

Web Policy Agents

Java EE Policy Agents

See Also

What versions of DS/OpenDJ are compatible with AM/OpenAM?

What operating systems are ForgeRock products supported on?

FAQ: Configuring Policy Agents in AM/OpenAM

Installing and configuring AM/OpenAM

Maintenance and Patch availability policy

ForgeRock End of Service Life (EOSL) policy

Related Training

N/A

Related Issue Tracker IDs

N/A


What versions of IG/OpenIG are compatible with AM/OpenAM?

The purpose of this article is to provide compatibility information between IG/OpenIG and AM/OpenAM versions. Also included is the supported Java® versions for each combination.

IG/OpenIG and AM/OpenAM compatibility

The following matrix indicates compatibility between AM/OpenAM and IG/OpenIG versions:

  IG 6.5.1 IG 6.5 IG 6, 6.1 IG 5.5.x IG 5 OpenIG 4.x
AM 6.5.1 Yes Yes Yes -- -- --
AM 6.5 All features except mTLS Yes Yes -- -- --
AM 6 All features except mTLS Yes Yes -- -- --
AM 5.5 All features except mTLS Yes Yes Yes -- --
AM 5, 5.1.x Partly * (most features) Partly * (most features) Partly * (most features) Yes Yes --
OpenAM 13.5.x Partly * (limited features) Partly * (limited features) Partly * (limited features) Partly * (most features) Yes Yes
OpenAM 13 -- -- -- -- -- Yes

* For details of the specific features supported in these versions, please refer to the relevant IG release notes:

Note

It is strongly recommended that you always upgrade to the latest maintenance releases for whichever versions of AM/OpenAM and IG/OpenIG you have deployed.

Java Compatability

Java 11

  • AM 6.5 and later.
  • IG 6.5 and later (OpenJDK only).

Java 8

  • AM 5 and later; OpenAM 13.x
  • IG 5 and later; OpenIG 4.x

Java 7

  • AM 5 and 5.1.x; OpenAM 13.x
  • IG 5 and OpenIG 4.x

Software and Hardware requirements

AM/OpenAM

IG/OpenIG

See Also

What operating systems are ForgeRock products supported on?

Checking your product versions are supported

FAQ: Installing AM/OpenAM

FAQ: Upgrading AM/OpenAM

FAQ: Installing and configuring IG/OpenIG

Installing and configuring AM/OpenAM

Installing and configuring IG/OpenIG


What versions of AM/OpenAM are compatible with IDM/OpenIDM?

The purpose of this article is to provide compatibility information between AM/OpenAM and IDM/OpenIDM versions. This includes the supported Java® versions for each combination.

Compatibility

The following matrix indicates compatibility between IDM/OpenIDM and AM/OpenAM for integration purposes:

  AM 6.5.x AM 6 AM 5.5.x AM 5, 5.1 OpenAM 13.5.x OpenAM 13
IDM 6.5.x Yes -- -- -- -- --
IDM 6 -- Yes -- -- -- --
IDM 5.5.x -- -- Yes -- -- --
IDM 5 -- -- -- Yes -- --
OpenIDM 4.5.x -- -- -- -- Yes --
OpenIDM 4 -- -- -- -- --- Yes
Note

It is strongly recommended that you always upgrade to the latest maintenance releases for whichever versions of IDM/OpenIDM and AM/OpenAM you have deployed.

The authentication modules available for integration vary according to product versions as follows:

  IDM 6.x IDM 5.5.x IDM 5 OpenIDM 4.x
OAUTH_CLIENT Yes Yes -- --
OPENID_CONNECT -- -- Yes --
OPENAM_SESSION -- Yes * Yes Yes

* The OPENAM_SESSION authentication module is deprecated in IDM 5.5. You should use the OAUTH_CLIENT module instead for integrating IDM with AM.

Java Compatability

Java 11

  • IDM 6.5 and later.
  • AM 6.5 and later.

Java 8

  • IDM 5 and later; OpenIDM 4.x
  • AM 5 and later; OpenAM 13.x

Java 7

  • IDM 5; OpenIDM 4.x
  • AM 5 and 5.1.x; OpenAM 13.x

Software and Hardware requirements

IDM/OpenIDM

AM/OpenAM

See Also

What operating systems are ForgeRock products supported on?

Checking your product versions are supported

Integrator's Guide › Supported Authentication Modules

Samples Guide › Integrating IDM With the ForgeRock Identity Platform

How does the OIDC authorization flow work when IDM (All versions) is integrated with AM?

How do I correctly configure the OPENAM_SESSION authentication module in OpenIDM 4.5?

FAQ: Upgrading IDM/OpenIDM

FAQ: Installing and configuring IDM/OpenIDM

FAQ: Upgrading AM/OpenAM

FAQ: Installing AM/OpenAM

Administering and configuring IDM/OpenIDM

Installing and configuring AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I check if a particular AM/OpenAM (All versions) instance is running?

The purpose of this article is to provide information on checking whether a particular AM/OpenAM instance is running in your web application container and who the process owner is for that instance. This information applies to Linux® and Unix® systems.

Checking if an AM/OpenAM instance is running

You can check if a particular AM/OpenAM instance is running using the ps command to display process information. The following example assumes AM/OpenAM is deployed on a Apache Tomcat™ web application container:

  1. Enter the following command:
    $ ps –ef |grep tomcat
    Observe the result, which will indicate if the instance is running:
    • Example output for an AM5 instance running on Tomcat (shows the path as /opt/tomcat/am5, which is the path to AM5 instance in this example): 
      forgero+  2240     1  3 10:34 pts/1    00:01:31 /usr/lib/jvm/java-8-oracle/bin/java -Djava.util.logging.config.file=/opt/tomcat/am5/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Xms2048m -Xmx2048m -XX:MaxPermSize=512m -Xss256k -XX:+UseParallelGC -XX:MaxGCPauseMillis=1500 -XX:GCTimeRatio=9 -server -XX:+DisableExplicitGC -Djava.endorsed.dirs=/opt/tomcat/am5/endorsed -classpath /opt/tomcat/am5/bin/bootstrap.jar:/opt/tomcat/am5/bin/tomcat-juli.jar -Dcatalina.base=/opt/tomcat/am5 -Dcatalina.home=/opt/tomcat/am5 -Djava.io.tmpdir=/opt/tomcat/am5/temp org.apache.catalina.startup.Bootstrap start
      forgero+  2966  2193  0 11:14 pts/1    00:00:00 grep --color=auto tomcat
      
      You can also see the process id (2240), the process owner (forgero+) and the current JVM options.
    • Example output when the instance is not running:
      forgero+  3025  2193  0 11:15 pts/1    00:00:00 grep --color=auto tomcat
Note

This command will show details for all instances running if you have multiple instances running on the same Tomcat web application container.

See Also

How do I check if AM/OpenAM (All versions) is up and running?

How do I check that a Policy Agent (All versions) can connect to AM/OpenAM?

How do I perform a heartbeat check against DS/OpenDJ (All versions)?

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I check what version of AM/OpenAM (All versions) I have installed?

The purpose of this article is to provide information on finding the AM/OpenAM product version whether the server is running or not.

Finding the AM/OpenAM version

There are a number of different ways to find the product version. The following sections demonstrate how you can find the version number using different options, with the ones that require a running server noted:

Using the console (running server only)

You can find the version number using the admin console by navigating to any of the following places:

  • Check the footer at the bottom of the AM/OpenAM console. The footer shows the version number once you are logged in as amadmin (unless you have customized your pages to remove it). For example:

  • Check the value of the com.iplanet.am.version property in the console: 
    • AM / OpenAM 13.5: navigate to: Configure > Server Defaults > Advanced
    • Pre-OpenAM 13.5: navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced.
  • Navigate directly to the /json/serverinfo/version endpoint once you are logged into the console as amadmin, for example: 
    http://host1.example.com:8080/openam/json/serverinfo/version

Using standard Unix and Linux commands

You can use any of the following CLI commands to find the version number:

$ cat /path/to/tomcat/webapps/openam/WEB-INF/classes/serverdefaults.properties | grep am.version
 
$ find /path/to/tomcat/webapps/openam -name openam*.jar | grep openam-core

$ cat /path/to/openam/.version 

Example: the following is a hidden .version file located in the $HOME/[am_instance] directory:

$ cat /opt/openam/.version 
ForgeRock Access Management 6.5.1 Build 24e379e3e1 (2019-April-05 09:02)

Using REST (running server only)

You can use the REST API to find the version number as follows:

  1. Authenticate as an admin user. For example:
    • AM 5 and later:
      $ 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
      
    • Pre-AM 5:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Request the server version using the following curl command:
    $ curl -X GET -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/json/serverinfo/version 
    Example response:
    {"_id":"version","_rev":"-1907117234","version":"6.5.1","fullVersion":"ForgeRock Access Management 6.5.1 Build 24e379e3e1 (2019-April-05 09:02)","revision":"24e379e3e1","date":"2019-April-05 09:02"}
    

​​​​​​​Using the patchinfo utility

You can use the patchinfo utility to find the version number if you have it installed. See How do I use the patchinfo utility to check what patches are installed for AM/OpenAM (All versions) or IG/OpenIG (All versions)? for further information.

Using ssoadm (running server only)

You can use the following ssoadm command to find the version number, for example:

$ ./ssoadm list-server-cfg -u amadmin -f pwd.txt -s default | grep am.version

Example response:

com.iplanet.am.version=ForgeRock Access Management 6.5.1 Build 24e379e3e1 (2019-April-05 09:02)

See Also

AM/OpenAM (All versions) upgrade fails when com.iplanet.am.version is empty or corrupted

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I upgrade Apache Tomcat for an existing AM/OpenAM (All versions) install?

The purpose of this article is to provide information on migrating an existing AM/OpenAM install to a new Apache Tomcat® version.

Background information

AM/OpenAM's configuration is located in the $HOME directory of the user running the web application container by default, which means it is separate to the Tomcat installation directory unless it's configured otherwise. However, any customizations you’ve made are located in the AM/OpenAM deployment path within the Tomcat directory /path/to/tomcat/webapps/openam (typically in the WEB-INF and XUI directories). The /openam directory referred to here and subsequent references to openam.war are based on a default installalation; your directories and war file may have a different name if configured otherwise. 

By default, there are two directories created in the user's home directory: the configuration is stored in the ~/openam/ directory and there is a hidden directory named ~/.openamcfg/. The hidden directory contains a file that represents the path to the directory where the openam.war file is deployed and is used when AM/OpenAM starts up to locate its configuration. For example, if your openam.war file is deployed in /opt/tomcat/webapps/openam, the file would be called AMConfig_opt_tomcat_webapps_openam_ This file contains the path to your configuration directory.

Caution

Depending on your version of Tomcat, the trailing underscore (_) at the end of the filename may or may not be needed. Versions 8.0.0 to 8.0.21 do not need the trailing underscore, whereas it is required in Tomcat 8.0.22 and later. See Bug 57556 (getServletContext().getRealPath("/") returns path not ending with /) for further information.

Supported versions

You should ensure the Tomcat version you are upgrading to is a supported container for your AM/OpenAM version:

Upgrading Tomcat

The recommended way to upgrade Tomcat for an existing install is as follows:

  1. Install the new Tomcat version to create an upgraded Tomcat instance. See Apache Tomcat for further information.
  2. Stop the Tomcat instance in which AM/OpenAM is currently running.
  3. Copy the openam.war file and the /path/to/tomcat/webapps/openam directory from your existing deployment to the new Tomcat instance. 
  4. Navigate to the ~/.openamcfg/ directory:
    $ cd ~/.openamcfg/
  5. Create a new AMconfig_ file using a filename that represents the path to the new location of the openam.war file. For example, if the new location is: /opt/newTomcat/webapps/openam, then you would name the file as follows:
    AMConfig_opt_newTomcat_webapps_openam_
  6. Edit the new AMConfig_ file and add the path to your existing ~/openam configuration directory, for example:
    /home/userName/openam
  7. Start the new Tomcat instance. Your existing AM/OpenAM install should now be available on the upgraded Tomcat.
Note

Tomcat 8.5 and later enforces stricter checking for valid cookie domain values; this change prevents the login page loading and causes ssoadm to fail. The necessary steps to resolve this are documented in the following Solution article: Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9.

See Also

Default Configuration page shown instead of Login page in AM/OpenAM (All versions)

Upgrading AM/OpenAM

Installing and configuring AM/OpenAM

Upgrade Guide

Installation Guide

Related Training

N/A

Related Issue Tracker IDs

N/A


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 export and import Service configurations for AM/OpenAM (All versions)?

The purpose of this article is to provide information on exporting and importing your Service configuration for AM/OpenAM. These options are used when making changes to your service configuration file. Additionally, exporting the service configuration is commonly used by Administrators and Support to validate configuration settings.

Overview

You can use the following approaches to export and import service configurations:

Amster (AM 5 and later)

You can use Amster to export and import configurations as detailed in:

With Amster, it is also possible to import a Service configuration that was created in a different version of AM/OpenAM. For example, you can export a configuration from AM 5 and import it into AM 5.5.

Note

If you have custom modules, you must ensure you have installed and registered the custom module first as detailed in How do I import Service configurations in AM (All versions) using Amster when there are custom modules?

ssoadm

You can export and import service configuration using ssoadm as follows:

Note

You cannot import a Service configuration that was created in a different version of AM/OpenAM using ssoadm. 

Export

You can export your Service configurations using the following ssoadm command:

$ ./ssoadm export-svc-cfg -u [adminID] -f [passwordfile] -e [secretkey] -o [outputfile]

replacing [adminID], [passwordfile], [secretkey] and [outputfile] with appropriate values, where [secretkey] can be any value and is used to encrypt passwords from the configuration. You must then use the same key when importing the configuration through ssoadm import-svc-cfg.

Import

You can import your Service configurations using the following ssoadm command:

$ ./ssoadm import-svc-cfg -u [adminID] -f [passwordfile] -e [secretkey] -X [XMLfile]

replacing [adminID], [passwordfile], [secretkey] and [XMLfile] with appropriate values, where [secretkey] is the same value you used when you exported the configuration.

Restart the web application container in which AM/OpenAM runs to update the configuration.

Known issues

The following known issues may prevent you from exporting or importing Service configurations using ssoadm:

See Also

How do I import Service configurations in AM (All versions) using Amster when there are custom modules?

How do I make a backup of configuration data in AM/OpenAM (All versions)?

How do I enable Message level debugging in AM/OpenAM (All versions) debug files?

How do I collect all the data required for troubleshooting AM/OpenAM and Policy Agents (All versions)?

Troubleshooting AM/OpenAM and Policy Agents

Setup and Maintenance Guide › Backing Up and Restoring Configurations

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-12089 (13.5.1 ssoadm import-svc-cfg fails with "An registered exception occurred." error exception )

OPENAM-8169 (OpenAM Policies not shown after importing service configuration xml via ssoadm)

OPENAM-7928 (ssoadm export-svc-cfg / import-svc-cfg should mention that 'ldif-export / ldif-import' can only be used on the same deployment)


How do I make a backup of configuration data in AM/OpenAM (All versions)?

The purpose of this article is to provide information on backing up configuration data in AM/OpenAM, using DS/OpenDJ tools to provide a more reliable and comprehensive backup than using ssoadm.

Background information

The Configuration directory ($HOME/[am_instance]) contains files created during the install process. Some of these files contain critical information that is required when AM/OpenAM initializes; AM/OpenAM cannot start if these files become corrupt or are missing. For this reason, it is essential to back up the Configuration directory to enable you to recover AM/OpenAM to its original state if needed. The files used when AM/OpenAM initializes includes all the files in the /opends directory and the following files:

  • bootstrap or boot.json depending on your version of AM/OpenAM.
  • keystore.jceks or keystore.jks depending on which keystore you are using.
  • certificate stores
  • openam_mon_auth (used in web based monitoring). This file is not required in AM 5 and later.
  • .version

There are two options available for using DS/OpenDJ tools to back up your configuration directory: 

  • DS/OpenDJ backup and restore - this option is the preferred approach; it should be used when you want to back up configuration data with the intention that you can restore it at a later date, if needed, and it would be replicated to other servers.
  • Export-ldif and import-ldif commands - this option is only required if you may need to revert changes from all replicating servers in the future. Typically this isn't required for configuration data, as you can simply reverse a change if it is no longer required. For example, if you change a configuration setting to TRUE, you can change it back to FALSE to revert the change.

In a replicated environment, the replication changelog has a purge delay of 3 days (by default). With either of these backup options, If you restore a backup taken within this period, the restored server will be able to re-sync with the other DS/OpenDJ servers; if you have an older backup, it will never be able to re-sync. It is therefore important to take periodic backups. 

Caution

It is also recommended that you take a file system backup of the directories for each AM/OpenAM server in your deployment as described in Upgrade Guide › Backing Up the Deployment. If you ever need to restore a corrupted AM/OpenAM server, it is essential to have a backup of your configuration store and the file system backup. Additionally, you should back up the $HOME/.openamcfg/ directory; the file used to bootstrap (the bootstrap locator file) is located in this directory.

Using DS/OpenDJ backup and restore

You can use a backup command such as the following to back up your configuration directory:

$ ./backup --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backUpAll --backupDirectory /path/to/ds/bak --start 0
Note

You only need to specify a start time if you are scheduling the backup; you can use --start 0 to perform the backup immediately.

You can tell that the backup command was successful by checking the error log (located in the $HOME/[am_instance]/opends/logs directory). If the backup was successful, you should see messages similar to this:

[30/Oct/2016:10:49:19 +0000] category=BACKEND severity=NOTICE msgID=9896349 msg=Backup task 20131030104919093 started execution
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend schema
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend tasks
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend userRoot
[30/Oct/2016:10:49:19 +0000] category=JEB severity=NOTICE msgID=8847446 msg=Archived: 00000000.jdb
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944795 msg=The backup process completed successfully
[30/Oct/2016:10:49:19 +0000] category=BACKEND severity=NOTICE msgID=9896350 msg=Backup task 20131030104919093 finished execution

You can restore changes using the restore command as follows:

$ ./restore --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backupDirectory /path/to/ds/bak

Using export-ldif and import-ldif

Note

The export-ldif  and import-ldif commands must be on the same deployment as the one where the encryption keys are located.

You can back up and restore the configuration directory using export-ldif and import-ldif as follows:

  1. Back up the configuration directory using an export-ldif command such as:
    $ ./export-ldif --hostname ds1.example.com --port 4444 --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/backupfile.ldif
  2. Prepare the replicated domain prior to importing the ldif data: You must specify the baseDN of the data you are going to be changing (that is, the one for which you exported ldif data), for example:
    $ ./dsreplication pre-external-initialization --hostname ds1.forgerock.com --port 4444 --baseDN dc=example,dc=com --adminUID admin --adminPassword password --trustAll --no-prompt
    
  3. Restore the configuration on all servers using an import-ldif command such as:
    $ ./import-ldif --hostname ds1.example.com --port 4444 --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/backupfile.ldif
  4. Enter the following command on one of the servers to set the new generation ID for the entire domain:
    $ ./dsreplication post-external-initialization --hostname ds1.forgerock.com --port 4444 --baseDN dc=example,dc=com --adminUID admin --adminPassword password --trustAll --no-prompt 

The above steps alter the generation ID of the replicated domain. "Old" changes will not get replayed because they were targeting the data using the previous generation ID. The final step calculates a new generation ID for the domain and broadcasts it to all the servers, which allows them to replicate again.

Replication will now proceed as normal, but from the restored point in time.

See Also

FAQ: Backing up AM/OpenAM

How do I export and import Service configurations for AM/OpenAM (All versions)?

Installing and configuring AM/OpenAM

Setup and Maintenance Guide › Backing Up and Restoring Configurations

Administration Guide › Backing Up and Restoring Data

Administration Guide › Managing Directory Data

Reference › Tools Reference

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

The purpose of this article is to provide information on making AM/OpenAM communicate with a secured LDAP (LDAPS) server such as DS/OpenDJ (SSL/TLS enabled). This information applies whether you are using the DS/OpenDJ generated self-signed certificate or a CA-signed certificate for a CA that may or may not already be present in the security store.

Making AM/OpenAM communicate with a secured LDAP server

When your LDAP server uses LDAP secured access (LDAPS), you must import the LDAP server certificate into the JVM truststore used by AM/OpenAM. This allows the JVM to trust the LDAP server certificate and enables AM/OpenAM to connect to the secured LDAP server. Additionally,  there are some version specific issues you should be aware of to ensure your setup is successful. See the Known issues section for further information.

Once you have resolved any version specific issues, you can proceed to import the LDAP server certificate into the JVM truststore used by AM/OpenAM; the following instructions differ depending on whether you are using the default JVM truststore or a non-default one:

See How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL? for further information.

Known issues

The following known issues affect specific AM / Java® versions:

AM/OpenAM version Java version Issue

AM 5.x and 6.0.0.x

ssoadm in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x

JDK 1.8.0_192 or later;

JDK 11

These versions of AM and ssoadm ​​​​do not correctly support the TLSv1.2 protocol.

AM 5.1.x; AM 6 or later

JDK 1.7.0_191;

JDK 1.8.0_181

These versions of AM introduce stricter hostname validation.

Lack of TLS 1.2 protocol support

AM 5.x and 6.0.0.x, and certain ssoadm versions (in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x) ​​​​do not correctly support the TLSv1.2 protocol, whereas using more secure ciphers or installing DS in production mode forces the protocol version to TLSv1.2. In Java versions prior to JDK 1.8.0_192, unsupported cipher suites were simply ignored, which is why these connections continued to work despite the mismatch in protocol versions.

Changes were introduced in JDK 1.8.0_192 (JDK-8162362 : Introduce system property to control enabled ciphersuites), which changed how the JDK determined which cipher suites (and resulting protocol) to use. As a consequence of these Java changes, AM and ssoadm cannot communicate with DS using a SSL/TLS secured connection because it uses different cipher suites and protocol to the DS server; both the client and server must support the same cipher suites and protocol agreed upon when attempting to establish a secure connection.

You can resolve this issue as follows:

  • If the issue is on the AM side, you can upgrade to AM 6.5 or later; you can download this from BackStage.
  • If the issue is on the ssoadm side, you can upgrade to AM 6.5.0.2 or AM 6.5.1, and then upgrade ssoadm to version 5.1.2.3; you can download this from BackStage.

See AM 5.x and 6.0.0.x, IDM 6.x and Rest2LDAP cannot connect to DS 5.x or 6 after restricting DS cipher suites or Java upgrade and Cannot install or use ssoadm in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x after restricting configuration store (DS/OpenDJ) cipher suites or Java upgrade for further information and workarounds.

Stricter hostname validation

Changes introduced in AM 5.1.x; AM 6 or later, and DS 5.5.1 or later have made LDAP SSL hostname validation stricter. AM checks the hostname in the LDAP server certificate correctly matches the hostname used to connect to the secured directory server (for example, DS or Active Directory®) and DS checks that the server it is trying to connect to has a certificate that matches the hostname.

Java 1.7.0_191 and 1.8.0_181 introduced changes to improve LDAP support by enabling endpoint identification algorithms by default for LDAPS connections; this also results in stricter hostname validation.

As a result of these changes, you must ensure the hostname you are connecting to the LDAP server with matches the hostnames specified in the server certificate via the SAN (Subject Alternative Name). See LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 6.x and DS 5.5.1, 5.5.2, 6.x for further information.

Using the default JVM truststore

You can do this as follows:

  1. If you are using the DS/OpenDJ generated self-signed certificate, you must first export this with its alias of 'server-cert' using the following keytool command:
    $ keytool -export -alias server-cert -file server-cert.crt -keystore /path/to/ds/config/keystore -storetype [storetype] -storepass:file /path/to/ds/config/keystore.pin
    
    If you want to export the certificate in PEM format, you should use the following command instead:
    keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storetype [storetype] -storepass [storepassword] -rfc -file [keyStore.pem]
  2. Import the generated self-signed certificate or the issuer certificate of the CA who signed the LDAP server certificate (if it is not already present in the store) into the JVM truststore used by AM/OpenAM using the following keytool command:
    $ keytool -importcert -alias [alias_of_certificate_entry] -file [path_to_certificate_file] -trustcacerts -keystore /path/to/truststore -storetype [storetype]
    For example, your command would look similar to this if you were importing the DS/OpenDJ generated self-signed certificate into the JVM truststore, where AM/OpenAM is deployed and running on Apache Tomcat™ web container:
    $ keytool -importcert -alias server-cert -file /path/to/server-cert.crt -trustcacerts -keystore $JAVA_HOME/jre/lib/security/cacerts -storetype JKS

Finally, AM/OpenAM should be configured to connect to the LDAP server on the secured port as required.

Using a non-default truststore

You can do this as follows:

  1. If you are using the DS/OpenDJ generated self-signed certificate, you must first export this with its alias of 'server-cert' using the following keytool command:
    $ keytool -export -alias server-cert -file server-cert.crt -keystore /path/to/ds/config/keystore -storetype [storetype] -storepass:file /path/to/ds/config/keystore.pin
    
    If you want to export the certificate in PEM format, you should use the following command instead:
    keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storetype [storetype] -storepass [storepassword] -rfc -file [keyStore.pem]
  2. Add the following JVM option to the web container or application server on which you have deployed AM/OpenAM to identify your truststore:
    -Djavax.net.ssl.trustStore=/path/to/truststore
  3. Import the generated self-signed certificate or the issuer certificate of the CA who signed the LDAP server certificate (if it is not already present in the store) into your truststore using the following keytool command:
    $ keytool -importcert -alias [alias_of_certificate_entry] -file [path_to_certificate_file] -trustcacerts -keystore /path/to/truststore -storetype [storetype]

Finally, AM/OpenAM should be configured to connect to the LDAP server on the secured port as required.

See Also

AM/OpenAM (All versions) fails to connect to DS/OpenDJ using a secured connection with an ERROR: Connection factory became offline

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

FAQ: SSL certificate management in AM/OpenAM and Policy Agents

FAQ: SSL certificate management in DS/OpenDJ

Setup and Maintenance Guide › Setting Up Keys and Keystores

Installation Guide › Securing Installations › Using Self-Signed Certificates

Installation Guide › Preparing for Installation › Preparing an External Configuration Data Store

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I enable SSL in AM/OpenAM (All versions) post-install?

The purpose of this article is to provide information on enabling SSL in AM/OpenAM post-install for a new installation.

Enabling SSL post-install

Note

If this is a NEW install, it is preferable to reinstall AM/OpenAM rather than making lots of configuration changes. This article steps you through an easy process that allows you to start fresh and reconfigure AM/OpenAM for SSL. For existing installations that cannot be reconfigured from scratch, you can enable SSL as described in How do I enable SSL in AM/OpenAM (All versions) for an existing installation?

To enable SSL:

  1. Stop the web application container in which AM/OpenAM runs.
  2. Enable SSL on your web application container per your vendors instructions. Ensure the truststore used by the JVM running AM/OpenAM has the necessary certificates installed. See example: Installation Guide › Securing Installations › Using Self-Signed Certificates
  3. Take a backup of your configuration data to ensure you have it for reference or in case you want to restore your current configuration. See How do I make a backup of configuration data in AM/OpenAM (All versions)? for further information.
  4. Delete the AM/OpenAM configuration files, which are typically under the $HOME directory of the user running the web application container. You can use the following command if you only have one AM/OpenAM instance and your configuration files are under $HOME:
    $ rm -rf $HOME/openam $HOME/.openamcfg
    This command also deletes the embedded directory server and all of its contents if you are using the internal AM/OpenAM configuration store.
  5. Delete the entries under the configured AM/OpenAM suffix (by default dc=openam,dc=forgerock,dc=org) if you use an external configuration store.
  6. Restart the web application container in which AM/OpenAM runs.
  7. Navigate to the initial AM/OpenAM configuration page in your browser, for example, http://host1.example.com:8080/openam.
  8. Reconfigure AM/OpenAM from scratch, ensuring you select the SSL/TLS Enabled option and specify the corresponding port.
Note

Once you have enabled SSL in AM/OpenAM, you should include details of the truststore that contains the required certificates in the setup or setup.bat script prior to installing ssoadm and in the ssoadm or ssoadm.bat script once it is installed. This is described in FAQ: Installing and using ssoadm in AM/OpenAM (Q. How do I install the ssoadm administration tool if I am using SSL?).

See Also

How do I enable SSL in AM/OpenAM (All versions) for an existing installation?

How do I make a backup of configuration data in AM/OpenAM (All versions)?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

Installation Guide › Securing Installations › Using Self-Signed Certificates

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I enable SSL in AM/OpenAM (All versions) for an existing installation?

The purpose of this article is to provide information on enabling SSL in AM/OpenAM for an existing installation. It assumes you have already enabled SSL on your web application container and the truststore used by the JVM running AM/OpenAM has the necessary certificates installed.

Enabling SSL for an existing installation

Note

If this is an existing install, you can enable SSL as described in this article. If it is a new install, it is preferable to reinstall AM/OpenAM rather than making lots of configuration changes as described in How do I enable SSL in AM/OpenAM (All versions) post-install?

To enable SSL:

  1. Enable SSL on your web application container per your vendors instructions. Ensure the truststore used by the JVM running AM/OpenAM has the necessary certificates installed. See example: Installation Guide › Securing Installations › Using Self-Signed Certificates
  2. Take a backup of your configuration data to ensure you have it for reference or in case you want to restore your current configuration. See How do I make a backup of configuration data in AM/OpenAM (All versions)? for further information.
  3. Log into the console as the admin user (typically amadmin).
  4. Clone the server configuration:
    • AM / OpenAM 13.5 console: navigate to: Deployment > Servers and select the vertical ellipsis > Clone on the AM/OpenAM instance you want to change to an SSL enabled installation.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites and select the check box next to the server you want to change to an SSL enabled installation. Click Clone to clone this server configuration.
  5. Enter the new server URL in the Server URL field using the https protocol instead of http and changing the port as appropriate. For example, if your existing server URL was: http://host1.example.com:8080/openam, you would change it to something similar to: https://host1.example.com:8443/openam
  6. Update the Realm DNS alias in the top level realm if the hostname has changed: 
    • AM / OpenAM 13.x console: navigate to: Realms > Top Level Realm / > Properties > Realm/DNS Aliases.
    • Pre-OpenAM 13 console: navigate to: Access Control > (Top Level Realm) > General > Realm/DNS Aliases.
  7. Update the cookie domain if the hostname domain has changed: 
    • AM 5 and later console: navigate to: Configure > Global Services > Platform > Cookie Domains.
    • OpenAM 13.5 console: navigate to: Configure > Global Services > System > Platform > Cookie Domains.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > System > Platform > Cookie Domains.
  8. Logout of the console.
  9. Edit the bootstrap file (located in $HOME) to point to the new server.
    • AM 5 and later: $HOME/openam/boot.json
    • OpenAM 13.x: $HOME/openam/bootstrap
  10. Restart the web application container in which AM/OpenAM runs.
  11. Navigate to the new server URL that you specified in step 5 to ensure it works as expected.
  12. If the new server is operational, remove the old server and Realm DNS alias associated with the old hostname (if different).
Note

Once you have enabled SSL in AM/OpenAM, you should include details of the truststore that contains the required certificates in the setup or setup.bat script prior to installing ssoadm and in the ssoadm or ssoadm.bat script once it is installed. This is described in FAQ: Installing and using ssoadm in AM/OpenAM (Q. How do I install the ssoadm administration tool if I am using SSL?).

See Also

How do I enable SSL in AM/OpenAM (All versions) post-install?

How do I make a backup of configuration data in AM/OpenAM (All versions)?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

Installation Guide › Securing Installations › Using Self-Signed Certificates

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I configure the heartbeat timeout in AM/OpenAM (All versions)?

The purpose of this article is to provide information on configuring the heartbeat timeout in AM/OpenAM. This allows you to tune the heartbeat timeout if you experience issues with heartbeat timeouts.

Overview

Heartbeat timeout is the time spent on AM/OpenAM sending and receiving the heartbeat request and is not pure processing time on DS/OpenDJ.

The default heartbeat timeout of 3 seconds is configurable (since OpenAM 12.0.3), which is useful if you are experiencing heartbeat timeouts. You will see errors such as the following in your logs if you are experiencing heartbeat timeouts:

  • Session debug log (when debug level is set to Message):
    Caused by: org.forgerock.opendj.ldap.ConnectionException: Server Connection Closed: Heartbeat timed out after 500 ms
    
  • IdRepo debug log (when debug level is set to Message):
    org.forgerock.opendj.ldap.ConnectionException: Server Connection Closed: Heartbeat timed out after 500 ms
    
  • Web application container log (for example, catalina.out for Apache Tomcat™):
    WARNING: No heartbeat detected for connection 'LDAPConnection(/192.10.210.10:8080,host1.example.com/192.10.210.15:18080)'
    

If you do see errors such as the above, you should increase the heartbeat timeout; it is recommended that you initially increase it to 10 seconds and then slowly increase it further if you continue to see errors.

Configuring the heartbeat timeout

You can configure the heartbeat timeout using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Deployment > Servers > [Server Name] > Advanced and add the org.forgerock.openam.ldap.heartbeat.timeout property and enter the heartbeat timeout in seconds for the value. To add the property as a server default, navigate to: Configure > Server Defaults > Advanced instead. Once you have entered the property and value, click + to add followed by Save Changes.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > [Server Name] > Advanced and add the org.forgerock.openam.ldap.heartbeat.timeout property and enter the heartbeat timeout in seconds for the value. You can configure this for all servers using Default Server Settings instead of [Server Name]. 
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s [servername] -u [adminID] -f [passwordfile] -a org.forgerock.openam.ldap.heartbeat.timeout=[seconds]
    
    replacing [servername], [adminID], [passwordfile] and [seconds] with appropriate values, where [servername] can be default if you want to change the default server settings instead. For example:
    $ ./ssoadm update-server-cfg -s default -u amadmin -f pwd.txt -a org.forgerock.openam.ldap.heartbeat.timeout=10
Note

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

See Also

How do I perform a heartbeat check against DS/OpenDJ (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3266 (Heartbeat timeouts can occur during operation)


How do I register or re-register a custom authentication module in AM 5.5.x and 6.x?

The purpose of this article is to provide assistance on registering a custom authentication module in AM. If you make changes to the custom module code, you will need to re-register it to apply the changes.

Overview

As of AM 5.5, modules are loaded using a service loader. As a result, the process to register custom authentication modules has been simplified and involves deploying a JAR file instead of using ssoadm. See Release Notes › Important Changes to Existing Functionality for further information. If you make changes to your custom module once it has been registered, you must re-register it to apply your changes.

See the following sections for further details:

Preparing the JAR file

You must ensure you have a valid JAR file before registering or re-registering your module.

The JAR file must contain the following files, which are needed to register the module with AM:

META-INF/services/org.forgerock.openam.plugins.AmPlugin
org/forgerock/openam/examples/SampleAuthPlugin.java

Where:

  • The org.forgerock.openam.plugins.AmPlugin file holds the fully qualified class name of the AmPlugin that registers the custom implementations. The org.forgerock.openam.plugins.AmPlugin file must not be renamed or placed in a different directoryFor example:
    $ cat META-INF/services/org.forgerock.openam.plugins.AmPlugin
    ..........
    
    # This file is used by the service loader to find implementations of org.forgerock.openam.plugins.AmPlugin
    # In this case, we are providing our new plugin, which will then be picked up and executed by OpenAM.
    # For more information on service loading, see the javadoc for the ServiceLoader class.
    
    org.forgerock.openam.examples.SampleAuthPlugin
    
    
    The above file would find the org.forgerock.openam.examples.SampleAuthPlugin file and execute the file.
  • The SampleAuthPlugin Java class implements the org.forgerock.openam.plugins.AmPlugin interface. This class registers the SampleAuth implementation and the amAuthSampleAuth.xml service schema. See Authentication and Single Sign-On Guide › About the Sample Authentication Module for further information on the usage of the sample files.  

You can build the JAR file using Apache Maven™ as detailed in How do I customize authentication modules using source code in AM/OpenAM (All versions)? and Authentication and Single Sign-On Guide › Creating a Custom Authentication Module.

Registering a custom module

You can register a custom module as follows:

  1. Copy the custom authentication module JAR file to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory, for example:
    $ cp custom-module-X.X.X.jar /path/to/tomcat/webapps/openam/WEB-INF/lib
    
  2. Restart the web application container in which AM runs to complete the registration of the custom module.  

See Authentication and Single Sign-On Guide › Installing the Module for further information.

Re-registering a custom module

If you make any changes to your custom module, you must re-register the module with AM as follows:

  1. Take a backup of your configuration prior to making any changes in case you need to revert: How do I make a backup of configuration data in AM/OpenAM (All versions)? 
  2. Uninstall the custom module using ssoadm, for example:
    $ ./ssoadm delete-svc -u amadmin -f pwd.txt -s [service_name​]​​​​​​
    
    Service was deleted.
    Replacing [service_name] with the service name specified in the xml service schema file. For example, in the sample amAuthSampleAuth.xml file, the service name is iPlanetAMAuthSampleAuthService:
    <Service name="iPlanetAMAuthSampleAuthService" version="1.0">
    
  3. Delete the module sub-entry in the configuration store using ldapdelete, for example: 
    $ ./ldapdelete --hostname host1.example.com --port 50389 --bindDN "cn=Directory Manager" --bindPassword password "ou=[plugin_name],ou=plugins,ou=default,ou=GlobalConfig,ou=1.0,ou=amPluginService,ou=services,[configuration_suffix]"
    
    # DELETE operation successful for DN ou=[plugin_name],ou=plugins,ou=default,ou=GlobalConfig,ou=1.0,ou=amPluginService,ou=services,[configuration_suffix]
    
    Replacing [plugin_name] and [configuration_suffix] as follows:
    • [plugin_name] - for example, org.forgerock.openam.examples.SampleAuthPlugin. You can find this in your META-INF/services/org.forgerock.openam.plugins.AmPlugin file, for example: 
      $ cat META-INF/services/org.forgerock.openam.plugins.AmPlugin
      ..........
      
      # This file is used by the service loader to find implementations of org.forgerock.openam.plugins.AmPlugin
      # In this case, we are providing our new plugin, which will then be picked up and executed by OpenAM.
      # For more information on service loading, see the javadoc for the ServiceLoader class.
      
      org.forgerock.openam.examples.SampleAuthPlugin
    • [configuration_suffix] - for example, dc=openam,dc=forgerock,dc=org
  4. Delete the old JAR file in the /path/to/tomcat/webapps/openam/WEB-INF/lib directory and replace with the updated JAR file.
  5. Restart the web application container in which AM runs to apply the changes.

See Also

How do I import Service configurations in AM (All versions) using Amster when there are custom modules?

API Javadoc › Interface AmPlugin

ServiceLoader API specification

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12347 (AmPlugin Custom Authentication Module cannot be uninstalled or reregistered)


How do I delete an AM/OpenAM instance (All versions) from a site along with the replicated embedded DS/OpenDJ server?

The purpose of this article is to provide information on decommissioning an AM/OpenAM instance and the replicated embedded DS/OpenDJ server from a site.

Deleting an AM/OpenAM instance and a replicated embedded DS/OpenDJ server from a site

You can remove the AM/OpenAM instance and the replicated embedded DS/OpenDJ server from a site as follows:

  1. Delete the AM/OpenAM instance using the console:
    • AM / OpenAM 13.5 console: navigate to Deployment > Servers and select the vertical ellipsis > Delete on the AM/OpenAM instance you want to remove.
    • Pre-OpenAM 13.5 console: navigate to Configuration > Servers and Sites, select the OpenAM instance you want to remove and click Delete. 
  2. Stop replication on the embedded DS/OpenDJ server using the dsreplication command applicable to your version:
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication unconfigure --unconfigureAll --port 4444 --hostname ds1.example.com --bindDn "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
    • Pre-DS 5 (pre-AM 5):
      $ ./dsreplication disable --disableAll --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
    This command removes the server's replication configuration from all other servers in the replication topology, meaning the remaining servers will not try to replicate to this server.
Note

If the dsreplication disable --disableAll command (Pre-DS 5) has failed to stop replication, you can use the Replica Removal tool as detailed in How do I use the Replica Remover tool in OpenDJ 2.6.x and 3.x to remove replication when the --disableAll command has failed?

See Also

javax.naming.AuthenticationException: [LDAP: error code 49 - Invalid Credentials] error when reinstalling an AM/OpenAM (All versions) instance

How do I repair replication configuration in DS/OpenDJ (All versions) when dsreplication has failed?

Administration Guide › Managing Data Replication › Configuring Replication

Administration Guide › Managing Data Replication › To Stop Replication Permanently For a Replica 

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-3029 (dsreplication disable --disableAll does not remove all replication data from other instances cn=admin data backend.)

OPENAM-8943 (Deleting a replicated embedded config store from "Servers and Sites" does not disable replication)


How do I configure AM 6.0.0.x to work with older policy agents (Web 4.x and JEE 3.5.x)?

The purpose of this article is to provide information on using Web and JEE policy agents with AM 6. This is a supported combination but requires setting the AM Login URL and AM Logout URL for new installs and new agent profiles. Otherwise, you will encounter "unable to find active OpenAM server URL" errors.

Configuring AM 6.0.0.x

Note

The experimental REST login mode that was introduced in Web Agents 4.1.0.30 will not work with AM 6.0.0.x. This feature is only officially supported with Web Agents 4.2. If you wish to use this login mode with Web Agents 4.x and AM 6.0.0.x, you must use Web Agents 4.2.

AM 6 introduced profile changes to support Agents 5, which removed the legacy login and logout URL property values required by older policy agents. If you try to use Web policy agents 4.x or JEE policy agents 3.5.x without setting these properties, you may encounter 403 Forbidden responses and will see the following error in the agent  debug.log:

2018-10-11 11:37:26.436 +1000   ERROR [0x7fe007f1c8c0:40] handle_exit(): unable to find active OpenAM server URL

New installs and new profiles

If you have a new install of AM 6 or add a new profile, you must populate the AM Login URL and AM Logout URL using either the console, REST or ssoadm:

  • Console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or Java] > [Agent Name] > AM Services and specify both the AM Login URL and AM Logout URL including the realm. The URL should be in the correct format, for example: 
    http://host1.example.com:8080/openam/XUI?realm=/#login/
  • REST: update the com.sun.identity.agents.config.login.url and com.sun.identity.agents.config.logout.url properties as described in How do I create and update an agent in AM/OpenAM (All versions) using the REST API?
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.login.url[0]=[loginURL] com.sun.identity.agents.config.logout.url[0]=[logoutURL]
    replacing [realmname], [agentname], [adminID], [passwordfile], [loginURL] and [logoutURL] with appropriate values.

Upgrades

If you upgrade to AM 6, existing profiles will not be affected and older policy agents will work without any changes needed. 

Caution

Web policy agents 4.x and JEE policy agents 3.5.x are not supported in AM 6.5; you will need to upgrade to the latest Agents 5 release ahead of upgrading to AM 6.5.

See Also

What versions of Policy Agents are compatible with AM/OpenAM?

Best practice for upgrading to AM 6.x

Upgrading AM/OpenAM

Agents and policies in AM/OpenAM

Setup and Maintenance Guide › Creating Agent Profiles

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-2070 (AM_AGENT_REST_LOGIN does not work with AM 6)

OPENAM-13565 (agent 4 ft for ssl requires login.url set in profile when using with AM 6)

OPENAM-12666 (Agent OAuth 2 provider does not support custom login URLs)


How do I remove console access in AM/OpenAM (All versions)?

The purpose of this article is to provide information on removing console access in AM/OpenAM to secure your deployment.

Background information

AM / OpenAM 13.x uses a mix of the old JATO console (Classic UI) and the new XUI JavaScript®-based administration pages. From an end-users' perspective, everything is now XUI-based. Moving fully to XUI is a phased process, which should be complete in a future release. During this process, the Classic UI is still available although the XUI is now the default and recommend interface to use. The Classic UI has been deprecated in OpenAM 13 and is likely to be removed in a future release.

The server-only war file in previous versions of OpenAM excluded the /console directory, meaning the JATO-based Classic UI did not function at all. Additionally, this exclusion prevented the user profile page (/idm/EndUser) from working when the XUI was disabled. The server-only war file was removed as of OpenAM 13.

The changes described in this article apply both to the JATO console (Classic UI) and the XUI administrative pages.

Note

As with any customizations, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. 

Removing console access

There are four approaches to removing console access and securing AM/OpenAM:

A whitelist on a load balancer or proxy could be used in combination with a blacklist elsewhere in the infrastructure. For example, a blacklist rule could be created to deny access to /json/users/amadmin, which would effectively prevent the amadmin administrative user from being able to login. 

Remove the /console directory

In AM / OpenAM 13.x, the /console directory contains:

  • The legacy JATO admin console, responsible for configuration, federation and some parts of the realm configuration.
  • The user profile and self service pages when the XUI is disabled.

If you want the above features to be removed from your deployment, you can remove the /console directory from the /path/to/tomcat/webapps/openam directory where AM/OpenAM is deployed.

Remove the administrative UI components of the new console (pre-AM 6 only)

The following two directories are responsible for delivering the UI content of the newer (XUI) parts of the admin console in pre-AM 6:

  • XUI/templates/admin/
  • XUI/org/forgerock/openam/ui/admin/

If you want the above features to be removed from your deployment, you can remove these directories from the path/to/tomcat/webapps/openam directory where AM/OpenAM is deployed.

Note

Removing these directories will not remove the REST endpoints that these features use in the background.

Whitelist approach

The recommended way of creating a whitelist is as follows:

  1. Establish all use cases involving AM/OpenAM.
  2. Test these use cases against AM/OpenAM servers in a load balanced pool. During testing, you can use browser developer tools such as those in Chrome™, tools such as Wireshark or the logs on a load balancer to analyze the endpoints used in each use case. This will give you a list of all endpoints used.
  3. Update this list of endpoints to include any sub-realms in use.
  4. Add the following endpoints to this list if you use SAML 2 functionality; these should suffice in most cases, but you should test them in your environment to be sure:
    saml2/jsp/<all paths>
    SSORedirect/<all paths>
    IDPSloRedirect/<all paths>
    Consumer/<all paths>
    ArtifactResolver/<all paths>
    IDPSloPOST/<all paths>
    IDPSloSoap/<all paths>
    idpsaehandler/<all paths>
  5. Configure your load balancer or proxy to only allow this list of endpoints.

Example using HAProxy 

This example demonstrates creating a whitelist in HAProxy where the following endpoints are used for the purposes of authentication and showing user components in the XUI:

UI/Login
json/authenticate
json/serverinfo/*
XUI/<all paths>
json/users/<all paths>
json/users?_action=idFromSession
json/sessions?_action=getMaxIdle
json/sessions/<all paths>?_action=validate
json/sessions/<all paths>?_action=logout

This example has one sub-realm called customers, resulting in these additional endpoints:

json/customers/authenticate
json/customers/users/<all paths>
json/customers/serverinfo/*
Note

Realm paths have changed in AM 5, so the paths to the customers realm would be in the format /json/realms/root/realms/customers. See Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls for further information.

The following shows the configuration required in HAProxy (haproxy.cfg) to block these example endpoints plus the ones identified above for SAML 2 functionality:

global
 log 127.0.0.1 local0
 log 127.0.0.1 local1 notice

defaults
 log global
 mode http
 option httplog
 option dontlognull
 retries 3
 option redispatch
 maxconn 2000
 timeout connect 5000
 timeout client 50000
 timeout server 50000

frontend fe
 bind host1.example.com:8000
 default_backend be
 acl wl_topRealm path /
 acl wl_topRealm path /openam/
 acl wl_topRealm path /openam/UI/Login
 acl wl_topRealm path /openam/json/authenticate
 acl wl_topRealm path /openam/json/serverinfo/*
 acl wl_topRealm path_beg /openam/XUI/
 acl wl_topRealm path_beg /openam/json/users/

 acl wl_customersRealm path_beg /openam/json/customers/users/
 acl wl_customersRealm path /openam/json/customers/authenticate
 acl wl_customersRealm path /openam/json/customers/serverinfo/*

 acl wl_user_idFromSession path /openam/json/users
 acl wl_user_idFromSession urlp(_action) idFromSession

 acl wl_sessions_getMaxIdle path /openam/json/sessions
 acl wl_sessions_getMaxIdle urlp(_action) getMaxIdle

 acl wl_sessions_validateLogout path_beg /openam/json/sessions/
 acl wl_sessions_validateLogout urlp(_action) validate
 acl wl_sessions_validateLogout urlp(_action) logout

 acl wl_saml2 path_beg /openam/saml2/jsp/
 acl wl_saml2 path_beg /openam/SSORedirect/
 acl wl_saml2 path_beg /openam/IDPSloRedirect/
 acl wl_saml2 path_beg /openam/Consumer/
 acl wl_saml2 path_beg /openam/ArtifactResolver/
 acl wl_saml2 path_beg /openam/IDPSloPOST/
 acl wl_saml2 path_beg /openam/IDPSloSoap/
 acl wl_saml2 path_beg /openam/idpsaehandler/
 http-request deny unless wl_topRealm or wl_customersRealm or wl_user_idFromSession or wl_sessions_getMaxIdle or wl_sessions_validateLogout or wl_saml2

backend be
 option httpchk GET /openam/isAlive.jsp
 cookie amlbcookie #insert nocache
 balance roundrobin
 server openam1 host1.example.com:18080 cookie 01 id 1000 check inter 2000 rise 2 fall 2
 server openam2 host2.example.com:28080 cookie 02 id 1001 check inter 2000 rise 2 fall 2

Blacklist approach

Caution

The following URLs are provided as a starting point only and you should perform your own security auditing and testing to ensure it meets your needs. Although this is a comprehensive list, it may not prevent administrative access to some endpoints in OpenAM 13 or future versions.

The URLs listed below still provide all user functionality, such as profile changes and self service, namely against the json/users endpoint. You should be particularly careful with this endpoint (and the realm specific version) because it has specific uses. Some examples of these uses are as as follows:

  • GET json/users?_queryId=*  - this is used to enumerate users. It would only ever be used by an administrator.
  • GET json/users?_action=idFromSession - this is used in all login scenarios (user and admin) with the XUI.
  • GET/POST/PUT json/users/{username}  - this could be used by both a user (on their username only) and an administrator, depending on the context.

The following URLs can be blocked in a proxy, web application firewall (WAF) or load balancer to prevent access to the administrative REST endpoints in AM/OpenAM:

  • Rest Endpoints (with json/realms/root or json part removed):
    REST endpoint AM 6.5.x AM 6 AM 5.5.x AM 5 and 5.1.x OpenAM 13.5 OpenAM 13
    /global-audit  Yes Yes Yes Yes Yes Yes
    /*/realm-audit  Yes Yes Yes Yes Yes Yes
    /global-config/agents*  Yes Yes Yes Yes -- --
    /global-config/agents/*  Yes Yes Yes Yes -- --
    /global-config/authentication*  Yes Yes Yes Yes -- --
    /global-config/authentication/*  Yes Yes Yes Yes -- --
    /global-config/realms Yes Yes Yes Yes Yes Yes
    /global-config/secrets* Yes -- -- -- -- --
    /global-config/secrets/*  Yes -- -- -- -- --
    /global-config/servers*  Yes Yes Yes Yes Yes --
    /global-config/servers/*  Yes Yes Yes Yes Yes --
    /global-config/services*  Yes Yes Yes Yes -- --
    /global-config/services/*  Yes Yes Yes Yes -- --
    /global-config/sites*  Yes Yes Yes Yes Yes --
    /global-config/webhooks*  Yes Yes -- -- -- --
    /realm-config/*  Yes Yes Yes Yes Yes Yes
    /*/realm-config/*  Yes Yes Yes Yes Yes Yes
    /realm-config/agents*  Yes Yes Yes Yes -- --
    /*/realm-config/agents  Yes Yes Yes Yes -- --
    /realm-config/authentication*  Yes Yes Yes Yes -- --
    /*/realm-config/authentication  Yes Yes Yes Yes -- --
    /realm-config/federation*  Yes Yes Yes Yes -- --
    /*/realm-config/federation Yes Yes Yes Yes -- --
    /realm-config/secrets*  Yes -- -- -- -- --
    /*/realm-config/secrets Yes -- -- -- -- --
    /realm-config/services*  Yes Yes Yes Yes Yes --
    /*/realm-config/services  Yes Yes Yes Yes Yes --
    /realm-config/webhooks*  Yes Yes -- -- -- --
    /*/realm-config/webhooks  Yes Yes -- -- -- --
    /users/amadmin  Yes Yes Yes Yes Yes Yes
    /realms  Yes Yes Yes Yes Yes Yes
    /*/realms  Yes Yes Yes Yes Yes Yes
    /scripts  Yes Yes Yes Yes Yes Yes
    /scripts/*  Yes Yes Yes Yes Yes Yes
    /*/scripts  Yes Yes Yes Yes Yes Yes
    /*/scripts/*  Yes Yes Yes Yes Yes Yes
    /policies  Yes Yes Yes Yes Yes Yes
    /*/policies  Yes Yes Yes Yes Yes Yes
    /policies/*  Yes Yes Yes Yes Yes Yes
    /*/policies/*  Yes Yes Yes Yes Yes Yes
    /applications  Yes Yes Yes Yes Yes Yes
    /applications/*  Yes Yes Yes Yes Yes Yes
    /*/applications  Yes Yes Yes Yes Yes Yes
    /*/applications/*  Yes Yes Yes Yes Yes Yes
    /subjectattributes  Yes Yes Yes Yes Yes Yes
    /*/subjectattributes  Yes Yes Yes Yes Yes Yes
    /resourcetypes  Yes Yes Yes Yes Yes Yes
    /resourcetypes/*  Yes Yes Yes Yes Yes Yes
    /*/resourcetypes  Yes Yes Yes Yes Yes Yes
    /*/resourcetypes/*  Yes Yes Yes Yes Yes Yes
    /applicationtypes  Yes Yes Yes Yes Yes Yes
    /applicationtypes/*  Yes Yes Yes Yes Yes Yes
    /decisioncombiners  Yes Yes Yes Yes Yes Yes
    /decisioncombiners/*  Yes Yes Yes Yes Yes Yes
    /conditiontypes  Yes Yes Yes Yes Yes Yes
    /conditiontypes/*  Yes Yes Yes Yes Yes Yes
    /subjecttypes  Yes Yes Yes Yes Yes Yes
    /subjecttypes/*  Yes Yes Yes Yes Yes Yes
    /groups  Yes Yes Yes Yes Yes Yes
    /groups/*  Yes Yes Yes Yes Yes Yes
    /*/groups  Yes Yes Yes Yes Yes Yes
    /*/groups/*  Yes Yes Yes Yes Yes Yes
    /agents  Yes Yes Yes Yes Yes Yes
    /agents/*  Yes Yes Yes Yes Yes Yes
    /*/agents Yes Yes Yes Yes Yes Yes
    /*/agents/*  Yes Yes Yes Yes Yes Yes
    /tokens/* -- -- -- Yes Yes Yes
    /records/*  Yes Yes Yes Yes Yes Yes
    rest-sts-publish/publish/* Yes Yes Yes Yes Yes Yes
  • XUI admin console endpoints:
    XUI/templates/admin/*
    XUI/org/forgerock/openam/ui/admin/*
  • JATO admin console endpoints:
    console/*
    realm/*
    idm/*
    agentconfig/*
    sts/*
    task/*
    service/*
    federation/*
    config/*
    session/*

Example method of filtering URLs using web.xml

If you are using Apache Tomcat™, you can block these endpoints by setting a <security-constraint> element in the web.xml file (located in the /path/to/tomcat/webapps/openam/WEB-INF directory where AM/OpenAM is deployed).

Note

This approach does not prevent redirects from occurring on URL patterns inside of the constraint. It also requires that the endpoints for each realm are defined. Consider applying rules in a reverse proxy or load balancer instead, which will likely offer a more robust solution. 

The following example shows the <security-constraint> element set in the web.xml file with all the applicable OpenAM 13.0 endpoints blocked, where there is one sub-realm called realm-one:

  <security-constraint>
     <web-resource-collection>
       <web-resource-name >OpenAM restricted URLs</web-resource-name>
       <url-pattern>/json/global-config/*</url-pattern>
       <url-pattern>/json/realm-config/*</url-pattern>
       <url-pattern>/json/realm-one/realm-config/*</url-pattern>
       <url-pattern>/json/users/amadmin</url-pattern>
       <url-pattern>/json/realms</url-pattern>
       <url-pattern>/json/realm-one/realms</url-pattern>
       <url-pattern>/json/scripts</url-pattern>
       <url-pattern>/json/scripts/*</url-pattern>
       <url-pattern>/json/realm-one/scripts</url-pattern>
       <url-pattern>/json/realm-one/scripts/*</url-pattern>
       <url-pattern>/json/policies</url-pattern>
       <url-pattern>/json/realm-one/policies</url-pattern>
       <url-pattern>/json/policies/*</url-pattern>
       <url-pattern>/json/realm-one/policies/*</url-pattern>
       <url-pattern>/json/applications</url-pattern>
       <url-pattern>/json/applications/*</url-pattern>
       <url-pattern>/json/realm-one/applications</url-pattern>
       <url-pattern>/json/realm-one/applications/*</url-pattern>
       <url-pattern>/json/subjectattributes</url-pattern>
       <url-pattern>/json/realm-one/subjectattributes</url-pattern>
       <url-pattern>/json/resourcetypes</url-pattern>
       <url-pattern>/json/resourcetypes/*</url-pattern>
       <url-pattern>/json/realm-one/resourcetypes</url-pattern>
       <url-pattern>/json/realm-one/resourcetypes/*</url-pattern>
       <url-pattern>/json/applicationtypes</url-pattern>
       <url-pattern>/json/applicationtypes/*</url-pattern>
       <url-pattern>/json/decisioncombiners</url-pattern>
       <url-pattern>/json/decisioncombiners/*</url-pattern>
       <url-pattern>/json/conditiontypes</url-pattern>
       <url-pattern>/json/conditiontypes/*</url-pattern>
       <url-pattern>/json/subjecttypes</url-pattern>
       <url-pattern>/json/subjecttypes/*</url-pattern>
       <url-pattern>/json/dashboard/available</url-pattern>
       <url-pattern>/json/realm-one/dashboard/available</url-pattern>
       <url-pattern>/json/groups</url-pattern>
       <url-pattern>/json/groups/*</url-pattern>
       <url-pattern>/json/realm-one/groups</url-pattern>
       <url-pattern>/json/realm-one/groups/*</url-pattern>
       <url-pattern>/json/agents</url-pattern>
       <url-pattern>/json/agents/*</url-pattern>
       <url-pattern>/json/realm-one/agents</url-pattern>
       <url-pattern>/json/realm-one/agents/*</url-pattern>
       <url-pattern>/json/tokens</url-pattern>
       <url-pattern>/json/records</url-pattern>
       <url-pattern>/rest-sts-publish/publish/*</url-pattern>
       <url-pattern>/XUI/templates/admin/*</url-pattern>
       <url-pattern>/XUI/org/forgerock/openam/ui/admin/*</url-pattern>
       <url-pattern>/console/*</url-pattern>
       <url-pattern>/realm/RealmProperties</url-pattern>
       <url-pattern>/idm/*</url-pattern>
       <url-pattern>/agentconfig/*</url-pattern>
       <url-pattern>/sts/*</url-pattern>
       <url-pattern>/task/*</url-pattern>
       <url-pattern>/service/*</url-pattern>
       <url-pattern>/federation/*</url-pattern>
       <url-pattern>/config/*</url-pattern>
       <url-pattern>/session/*</url-pattern>
     </web-resource-collection>
     <auth-constraint/>
   </security-constraint>

If you use this example as the basis of your changes, you must replace the realm-one realm name with a realm that you are using, and possibly add other endpoints for other realms you may have configured. If you are not using sub-realms, then you can remove these endpoints.

Testing

The example bash script provides a means of testing these blocked URLs using repeated curl commands. This script authenticates against AM/OpenAM and then runs various GET calls against the list of URLs defined in endpoints.txt. It then outputs HTTP response codes (200, 400, 401, 403 etc) which indicate the type of response.

The following is an example output from the script:

200 http://host1.example.com:8080/am1300/json/policies?_queryId=*
200 http://host1.example.com:8080/am1300/json/realm-one/policies?_queryId=*
404 http://host1.example.com:8080/am1300/json/policies/example-policy
404 http://host1.example.com:8080/am1300/json/realm-one/policies/example-policy

With the URL filters in place, the script should return 403 for all the URLs tested, except for:

  • The /json/users endpoint
  • The /console endpoint, which does a redirect (302) to /console/* that is blocked.

Without any filters in place, the script would return 200 codes, except on queries where no existing object is in place to query. In that case, a 404 (not found) would be returned.

For example, a GET on the endpoint json/realm-one/policies/example-policy would return:

  • 403 if it is blocked by a rule in web.xml or on a load balancer, WAF etc.
  • 404 if the URL is not blocked and the policy called “example-policy” does not exist in the realm called “realm-one”.
  • 200 if the URL is not blocked and the policy called “example-policy” does exist in the realm called “realm-one”.

The attached endpoints.sh script and endpoints.txt file can be used as the basis for your own testing. They have been created based on the default endpoints that need blocking in OpenAM 13.0 with one sub-realm (realm-one) defined. The cli tool jq needs to be installed in order to execute this script. This can be installed using operating system package tools, such as apt-get, yum and brew.

The endpoints.sh file contains the following script, which can be used as the basis for your testing:

#!/bin/bash

AM_JSN='Content-Type: application/json'
AM_URL='http://host1.example.com:8080/am1300'
AM_USR='X-OpenAM-Username: amadmin'
AM_PWD='X-OpenAM-Password: cangetinam'

AM_TOKEN=$(curl -k -sS -H "${AM_JSN}" -H "${AM_USR}" -H "${AM_PWD}" --request POST "${AM_URL}/json/authenticate" | jq .tokenId -r)

echo "$AM_TOKEN"

while read u; do
  curl -k -sS -H "${AM_JSN}" -H "iPlanetDirectoryPro: ${AM_TOKEN}" -w "%{http_code} %{url_effective} \n" -o /dev/null --request GET "${AM_URL}/$u" 
done <endpoints.txt

 The endpoints.txt file contains the following URLs, which can be used as a basis for your testing:

json/global-config/realms
json/realm-config/authentication
json/realm-one/realm-config/authentication
json/users/amadmin
json/users?_queryId=*
json/realm-one/users/demo
json/realm-one/users?_queryId=*
json/realms?_queryId=*
json/realm-one/realms?_queryId=*
json/scripts?_queryId=*
json/scripts/9de3eb62-f131-4fac-a294-7bd170fd4acb
json/realm-one/scripts?_queryId=*
json/realm-one/scripts/9de3eb62-f131-4fac-a294-7bd170fd4acb
json/policies?_queryId=*
json/realm-one/policies?_queryId=*
json/policies/example-policy
json/realm-one/policies/example-policy
json/applications?_queryId=*
json/applications/sunAMDelegationService
json/realm-one/applications?_queryId=*
json/realm-one/applications/sunAMDelegationService
json/subjectattributes?_queryId=*
json/realm-one/subjectattributes?_queryId=*
json/resourcetypes?_queryId=*
json/resourcetypes/20a13582-1f32-4f83-905f-f71ff4e2e00d
json/realm-one/resourcetypes?_queryId=*
json/realm-one/resourcetypes/20a13582-1f32-4f83-905f-f71ff4e2e00d
json/applicationtypes?_queryId=*
json/applicationtypes/sunAMDelegationService
json/decisioncombiners?_queryId=*
json/decisioncombiners/DenyOverride
json/conditiontypes?_queryId=*
json/conditiontypes/AMIdentityMembership
json/subjecttypes?_queryId=*
json/subjecttypes/AND
json/dashboard/available
json/realm-one/dashboard/available
json/groups?_queryId=*
json/groups/testgroup
json/realm-one/groups?_queryId=*
json/realm-one/groups/testgroup
json/agents?_queryId=*
json/agents/testwebagent
json/realm-one/agents?_queryId=*
json/realm-one/agents/testwebagent
json/tokens
json/records
rest-sts-publish/publish
XUI/templates/admin/views/realms/RealmsListTemplate.html?v=13.0.0
XUI/org/forgerock/openam/ui/admin/views/realms/RealmsListView.js?v=13.0.0
console
realm/RealmProperties
idm/Entities
agentconfig/Agents
sts/STSHome
task/CreateHostedIDP
service/SCConfigConsole
federation/Federation
config/
session/SMProfile

See Also

Best practice for blocking the top level realm in a proxy for AM/OpenAM (All versions)

AM 6.5 Reference › Service Endpoints › REST API Endpoints

AM 6 Reference › Service Endpoints › REST API Endpoints

AM 5.5 Reference › Service Endpoints › REST API Endpoints

AM 5 Reference › Service Endpoints › REST API Endpoints

OpenAM 13.5 Reference › Service Endpoints › REST API Endpoints

OpenAM 13 Reference › Service Endpoints › REST API Endpoints

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7839 (Server Only distribution includes XUI part of admin console)


Best practice for blocking the top level realm in a proxy for AM/OpenAM (All versions)

The purpose of this article is to provide best practice advice on preventing access to the top level realm in AM/OpenAM. It is often a security requirement to prevent access to this realm since it is where the most privileged AM/OpenAM accounts are located. This article discusses common approaches to doing this in a proxy, web application firewall (WAF) or load balancer.

Caution

The recommendations made in this article are not an exhaustive list of approaches for preventing access to the top level realm or for securing your deployment. These recommendations are provided without any warranty or liability to ForgeRock.

You should read How do I remove console access in AM/OpenAM (All versions)? before following any guidance in this article.

Background Information

There is often a security requirement to prevent access to the top level realm as this realm is where the most privileged AM/OpenAM accounts are located. This article discusses common approaches to doing this in a proxy, web application firewall (WAF) or load balancer, and includes the following sections:

Common mistakes

  • Using realm DNS aliases for security. When a client reaches a realm by http://alias.example.com, they can navigate to other realms using http://alias.example.com?realm=/. Unfortunately the OpenAM 12.x documentation implies that you can use DNS aliases for security, see: OPENAM-11081 (Realm DNS aliases can not be used to control access to realms).
  • Not blocking access to the application authentication module (built in module for use by policy agents and ssoadm), which can always be reached even if module based authentication is disabled. The amadmin account can authenticate on this module in the top level realm.
  • Creating rules just for endpoints, rather than the query strings on those endpoints.
  • Not creating the equivalent rules for authIndexType= and authIndexValue= when creating rules for the service= and module= query strings.
  • Not blocking access to legacy endpoints such as /sessionservice, /profileservice, /policyservice, /namingservice, /loggingservice, /authservice and /notificationservice.
  • Configuring in memory time based account lockout for administrative accounts to prevent brute force attacks. This feature has no affect on the amadmin account.
  • Creating whitelist (allow) rules for URL query parameters. These can be specified multiple times; different implementations handle this situation in different ways. AM/OpenAM takes the first instance of a URL query parameter that is found. If you create a whitelist for parameters, specifying multiples of the parameter can be used to circumvent the rule.
  • Not considering URL encoding when creating rules. For example, realm=/ may be blocked, but is realm=2F blocked?

AM/OpenAM configuration best practice

You should ensure you comply with the following best practice advice when configuring AM/OpenAM: 

  • Follow all the security guidance in Installation Guide › Securing Installations.
  • Disable module based authentication. When enabled, this can be used to circumvent multi-factor authentication if multiple modules are configured in a chain with the same authLevel.
  • Create realms for your organization(s) and separate administrative users from end users as recommended in Installation Guide › Securing Administration. It is recommended to use the top level realm for administrative users. Access to that realm should be tightly controlled. 
  • Ensure the top level realm does not contain federation entities, agent profiles, authorizations, OAuth2/OIDC or STS services to reduce the attack surface on this realm.
  • Create separate administrative instances of AM/OpenAM that are outside of the load balanced pool. Endpoints that are not used in the user facing instances can have unused endpoints removed from the web.xml file and the console folder can be deleted.
  • Use realm DNS aliases only for convenience, to “prettyfy” URLs and to mask the configuration of the AM/OpenAM deployment. Do not use them as a means of securing the deployment.

See How do I mitigate brute force attacks in AM/OpenAM (All versions)? for additional considerations for mitigating brute force attacks. 

Proxy/WAF rules best practice

You should ensure you comply with the following best practice advice for proxy/WAF rules: 

  • Use a combination of whitelist (allow) and blacklist (deny) rules, making sure to create rules for endpoints AND the query strings used on those endpoints.
  • Create whitelist (allow) rules to only allow access on the endpoints that are used in your use cases. This will have the added benefit of blocking legacy endpoints, which could be used for authentication. Create additional blacklist (deny) rules that prevent navigation by query string to the top level realm. For example, deny the query string realm=/ on the authenticate endpoint in each realm. Make sure that these rules are also effective when URL encoding is used, for example, realm=2F
  • Create blacklist (deny) rules that prevent the Application authentication module from being called externally. You should be aware that this endpoint is also used as follows and can be accessed even when module based authentication is disabled:
    • Web/Java policy agents use this endpoint in versions 4.x and lower.
    • ssoadm uses this endpoint.
    • json/authenticate uses this endpoint if used with the following parameters:
      authIndexType=module&authIndexValue=Application
      The XUI will understand the syntax module=Application and convert it to the above format on the authenticate endpoint.
    • Legacy endpoints such as /UI/Login use the format module=Application.
  • Deny the query string realm=/ on the /oauth2/authorize and /oauth2/access_token endpoints if an OAuth2 provider is required in the top level realm for administrative use internally (not recommended).
  • Ensure that only hostnames that are supposed to be used externally are permitted; this prevents AM/OpenAM from redirecting to the default site URL, which may not be suitable. This situation can occur if an attacker tries to access AM/OpenAM via the IP address of a front end load balancer, instead of the hostname.

Endpoints that allow authentication in the top level realm

The following endpoints can provide an SSO token for users in the top level realm or can provide tokens that can then be exchanged for SSO tokens of users in the top level realm; these endpoints use example realms /europe and /customers. Consider blocking these endpoints (substituting your realm names for the example ones) if you wish to deny access to the top level realm. 

Endpoint AM 5 and later OpenAM 12.x and 13.x
/json/realms/root/authenticate Yes --
/json/realms/root/realms/root/authenticate Yes --
/json/realms/root/authenticate?realm=/ Yes --
/json/realms/root/realms/europe/authenticate?realm=/ Yes --
/json/realms/root/realms/europe/realms/customers/authenticate?realm=/ Yes --
/json/realms/root/realms/europe/authenticate?realm=/&realm=/customers Yes --
/json/authenticate Yes Yes
/json/authenticate?realm=/ Yes Yes
/json/authenticate?realm=/&realm=/europe Yes Yes
/json/europe/authenticate?realm=/ Yes Yes
/json/europe/customers/authenticate?realm=/ Yes Yes
/UI/Login?realm=/ Yes Yes
/UI/Login Yes Yes

Additionally, the following legacy authentication endpoints can also allow authentication in the top level realm.

  • /UI/Login
  • /authservice
  • /identity/authenticate
  • /cdcservlet
  • /SSOPOST
  • /SSORedirect

Sample proxy configuration

HaProxy Whitelist style (recommended)

This configuration permits (whitelists) only the endpoints that are required for the service that AM performs. In this example, AM is only required to expose endpoints required for authentication and there is one /customers realm. In addition, query strings that allow navigation to the top level realm are denied. 

   acl xui path_beg /am/XUI
   acl legacy_ui_login path /am/UI/Login
   acl legacy_ui_logout path /am/UI/Logout

   acl authN path /am/json/realms/root/realms/customers/authenticate

   acl authZ path /am/oauth2/realms/root/realms/customers/authorize
   acl access_token path /am/oauth2/realms/root/realms/customers/access_token
   acl userinfo path /am/oauth2/realms/root/realms/customers/userinfo
   acl endSession path /am/oauth2/realms/root/realms/customers/connect/endSession

   acl jsonsessions path /am/json/realms/root/realms/customers/sessions
   acl jsonusers path_beg /am/json/realms/root/realms/customers/users
   acl jsonserverinfo path /am/json/realms/root/realms/customers/serverinfo/*
   acl jsonsessionstop path /am/json/sessions
   acl jsonuserstop path /am/json/users

   acl realmNav query -m sub "realm="
   acl rootRealmQueries query,url_dec -m reg -i (realm=\/($|&)|(authIndexValue|module)=Application)


   http-request allow if !acl_am
   http-request allow if authN !rootRealmQueries
   http-request allow if authZ
   http-request allow if access_token
   http-request allow if userinfo
   http-request allow if endSession
   http-request allow if jsonusers #METH_GET
   http-request allow if jsonuserstop
   http-request allow if jsonsessions
   http-request allow if jsonsessionstop
   http-request allow if jsonserverinfo
   http-request allow if xui
   http-request allow if legacy_ui_login realmNav !rootRealmQueries
   http-request allow if legacy_ui_logout

   http-request deny

HaProxy Blacklist style (not recommended)

This configuration denies endpoints and query strings that can be used to authenticate against the top level realm (blacklist approach). This approach does not follow the principal of least privilege; it therefore carries the risk of exposing endpoints that may allow an attacker to take advantage of the service.

   acl rootAuthNpaths path_reg -i \/UI\/Login$|(\/json|\/realms\/root)(\/authenticate$)
   acl subAuthNpaths path_reg -i \/json\/((.*)|\/)authenticate
   acl rootRealmQueries query,url_dec -m reg -i (realm=\/($|&)|(authIndexValue|module)=Application)
   acl realmNav query -m sub "realm="
   acl legacyEndpoints path_reg -i (\/am\/(sessionservice|profileservice|policyservice|namingservice|authservice|notificationservice))
   
   http-request allow if !acl_am
   http-request deny if rootAuthNpaths !realmNav
   http-request deny if rootAuthNpaths rootRealmQueries
   http-request deny if subAuthNpaths rootRealmQueries
   http-request deny if legacyEndpoints

See Also

How do I understand what privileges apply to amadmin and delegated administrators in AM/OpenAM (All versions)?

Installing and configuring AM/OpenAM

Installation Guide

Deployment Planning Guide

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I safely enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM/OpenAM (All versions)?

The purpose of this article is to provide information on the recommended ways to enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM/OpenAM. Setting this Apache Tomcat™ property to true can introduce a security vulnerability when Tomcat is deployed behind a reverse proxy.

Caution

The recommendations made in this article are not an exhaustive list of the potential mitigations, workarounds or remedies for this issue. These recommendations are provided without any warranty or liability to ForgeRock.

Background information

When Tomcat is deployed behind a reverse proxy, enabling this setting (org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true) can expose you to a directory traversal security vulnerability (CVE-2007-0450); see Apache Tomcat 6.x Vulnerabilities for further information. However, there are certain scenarios where enabling this setting is useful, for example:

  • Making REST calls where the resource name includes a forward slash. This includes resources such as SAML2 entities, policy names, application names and user names.
  • Importing or exporting configurations using Amster where the resource name includes a forward slash.

Mitigations

The best approach is to avoid resource names that contain forward slashes to avoid this issue completely.

If you already use this naming convention and do not wish to migrate away from such names at this time, you should consider the following suggested mitigations or workarounds if you need to enable this setting:

  • Only enable the setting for a small window of time while you carry out a task that requires it (for example, Amster import, updating SAML entities etc) and then disable it again immediately afterwards.
  • Only enable the setting on a server that has been removed from the load balancer or is otherwise unreachable from an untrusted network. For instance, consider having a dedicated admin console server that is firewalled off from the internet and is just used to update the configuration store in LDAP.
  • Ensure that Tomcat cannot read files outside of its context root (this is the default). If you must allow Tomcat to read files outside of the context root, then:
    • ensure sensitive files are not readable from Tomcat or are installed into unpredictable locations (for example, rather than install AM/OpenAM into ~/openam, install into ~/<some-long-random-string>).
    • never enable directory listings.
  • Adjust your reverse proxy URL filtering rules to match how Tomcat performs path handling (this may not be possible depending on how much control the reverse proxy provides).

See Also

400 response with json/users endpoint in AM/OpenAM (All versions) if username contains forward slash

400 response when adding or updating resources via REST or Amster when the resource name contains forward slashes in AM/OpenAM (All versions)

How do I mitigate brute force attacks in AM/OpenAM (All versions)?

Best practice for blocking the top level realm in a proxy for AM/OpenAM (All versions)

Installation Guide › Preparing Apache Tomcat

Installation Guide › Securing Installations

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I update the certificate alias for the signing key in the AM/OpenAM (All versions) keystore?

The purpose of this article is to provide information on updating the certificate alias for the signing key in the AM/OpenAM keystore. You will need to do this if you change the signing key or the keystore. The signing key for the default keystore has an alias of test and this signing key is used to encrypt JSON Web Token (JWT) tokens for OAuth2 and JWT cookies in the Persistent Cookie module.

Background information

AM/OpenAM uses a JCEKS keystore as its default keystore as of OpenAM 13.5. The default location is: %BASE_DIR%/%SERVER_URI%/keystore.jceks; you can change this by navigating to: Configure > Server Defaults > Security > Key Store > Keystore File.

Prior to OpenAM 13.5, OpenAM stores its default signing key in a Java Keystore file located in the $HOME/openam/openam/keystore.jks; you can check the location of this keystore in the OpenAM console by navigating to: Configuration > Servers and Sites > Default Server Settings > Security > Key Store.

Updating the certificate alias for the signing key

You can update the alias for the signing key globally or in a specific realm, where realm level take precedence over the global level:

Global

You can update this value globally using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • OpenAM 13 console: navigate to: Configuration > Authentication > Core > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • Pre-OpenAM 13 console: navigate to: Configuration > Authentication > Core > Security > Organization Authentication Certificate Alias and enter the alias of the new signing key.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[signingkeyalias]
    replacing [adminID], [passwordfile] and [signingkeyalias] with appropriate values.

Realm

You can update this value in a specific realm using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Security > Organization Authentication Certificate Alias and enter the alias of the new signing key.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[signingkeyalias]
    replacing [realmname], [adminID], [passwordfile] and [signingkeyalias] with appropriate values.
Note

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

See Also

Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore

Unable to login to OpenAM console 12.x and 13.x or access REST API after changing the Federation Signing Key

How do I change the Signing Key for Federation in OpenAM 12.x and 13.x?

Setup and Maintenance Guide › Setting Up Keys and Keystores

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4370 (NPE when trying to authenticate via the REST authentication service)

OPENAM-5660 (NPE when the keyalias does not exist or does not contain a certificate)


How do I update the authentication signing secret in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on updating the value of the authentication signing secret in AM/OpenAM. The signing secret is a random key that AM/OpenAM generates upon startup and uses to sign the authentication token (authID). You can replace the generated value with a static value if required.

Updating the value of the signing secret

You should generate a random string that is at least 128 bit and base64 encoded for your signing secret. For example, you could a use a random number generator and then encode it using the DS/OpenDJ base64 tool or you could use openssl:

$ openssl rand -base64 32

You can then update the value of the signing secret globally or in a specific realm using this generated string, where realm level take precedence over the global level:

Global

You can update this value globally using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Security > Organization Authentication Signing Secret and enter the value of your shared secret.
  • OpenAM 13 console: navigate to: Configuration > Authentication > Core > Security > Organization Authentication Signing Secret and enter the value of your shared secret.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-hmac-signing-shared-secret=[sharedSecret]
    replacing [adminID], [passwordfile] and [sharedSecret] with appropriate values.

Realm level

You can update this value in a specific realm using either the console or ssoadm:

  • Console: navigate to: Realms > [Realm Name] > Authentication > Settings > Security > Organization Authentication Signing Secret and enter the value of your shared secret.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -u [adminID] -f [passwordfile] -s iPlanetAMAuthService -e [realmname] -a iplanet-am-auth-hmac-signing-shared-secret=[sharedSecret]
    
    replacing [adminID], [passwordfile], [realmname] and [sharedSecret] with appropriate values.
Note

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

See Also

Authentication fails in OpenAM 13.0 with an AuthId JWT Signature not valid error

Authentication and Single Sign-On Guide › Reference › Security

Reference › Tools Reference › base64

Related Training

N/A

Related Issue Tracker IDs

 OPENAM-8264 (insufficient validator for service property 'iplanet-am-auth-hmac-signing-shared-secret')

 OPENAM-8269 ("AuthId JWT Signature not valid" error in multi-instance deployments on 13)


How do I configure AM/OpenAM (All versions) to check the HTTP header for the user certificate?

The purpose of this article is to provide information on configuring AM/OpenAM to check the HTTP header for the user (X.509) certificate. This setup can be used if you are SSL offloading at a load balancer or reverse proxy in front of AM/OpenAM, the user certificate is passed to AM/OpenAM in the HTTP header (in PEM format) and the Certificate Authentication module is used to authenticate users.

Configuring AM/OpenAM

Note

If you use IG/OpenIG as your reverse proxy, IG/OpenIG will just pass the HTTP header containing the user certificate (providing you have not configured IG/OpenIG to explicitly remove headers as part of a Filter configuration). If however you want IG/OpenIG to retrieve the user certificate and pass it to AM/OpenAM, you will need to configure IG/OpenIG as detailed in How do I configure IG/OpenIG (All versions) to retrieve the user certificate and pass it to AM/OpenAM in the HTTP header?

You can configure the Certificate Authentication module to check the HTTP header for user certificates using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > [Certificate Module] and update the following fields:
    • Trusted Remote Hosts - Add the IP of the host supplying the HTTP header that contains the user certificate. You can add "any" instead of a specific IP to allow any host; however, this option is not as secure. Remove the "none" value.
    • HTTP Header Name for Client Certificate - Enter the HTTP header name for the client certificate that is inserted by the load balancer or reverse proxy. This should be the full PEM encoded certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- boundary lines. In between these boundary lines, there should be the Base64 encoding output of the DER encoded certificate.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Module Instances > [Certificate Module] and update the Trusted Remote Hosts and HTTP Header Name for Client Certificate fields as detailed above.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthCertService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-cert-gw-cert-auth-enabled=[hostIP] sunAMHttpParamName=[header]
    
    replacing [realmname], [adminID], [passwordfile], [hostIP] and [header] 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 configure IG/OpenIG (All versions) to retrieve the user certificate and pass it to AM/OpenAM in the HTTP header?

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

Gateway Guide › Understanding OpenIG › Handlers, Filters, and Chains

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5938 (Cert Auth module should not read cert from HTTP request when 'iplanet-am-auth-cert-gw-cert-auth-enabled' is set)


How do I set up Realm DNS Aliases in AM/OpenAM (All versions)?

The purpose of this article is to provide information on setting up Realm DNS Aliases in AM/OpenAM.

Setting up Realm DNS Aliases

Realm DNS aliases are an alternative to using Fully Qualified Domain Names (FQDNs) in AM/OpenAM as they implicitly add the realm to the request. For example, http://host1.example.com:8080/openam/XUI/#login/ is interpreted as http://host1.example.com:8080/openam/XUI/#login/&realm=myrealm when realm DNS aliases are used.

Warning

Realm DNS aliases must be unique; you cannot have the same realm DNS alias configured in more than one realm, this can cause the server to become unresponsive.

AM 5 and later

See Setup and Maintenance Guide › Setting Up Realms › To Configure DNS Aliases for Accessing a Realm for further information. 

Pre-AM 5

You can set up realm DNS aliases in sub-realms as follows:

  1. Specify the realm DNS alias in the sub-realm using either the console or ssoadm:
    • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Properties > Realm/DNS Aliases and ensure the appropriate DNS aliases are specified.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Realm/DNS Aliases and ensure the appropriate DNS aliases are specified.
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] -p -a sunOrganizationAliases=[DNSAlias]
      replacing [realmname], [adminID], [passwordfile] and [DNSAlias] with appropriate values.
  2. Map the FQDN to the realm DNS alias using either the console or ssoadm:
    • OpenAM 13.5 console: navigate to Configure > Server Defaults > Advanced and add the com.sun.identity.server.fqdnMap[realmDNSalias] property with a value of realmDNSalias for each realm DNS alias. For example: 
      property name: com.sun.identity.server.fqdnMap[host1.example.com]
      property value: host1.example.com
      
    • Pre-OpenAM 13.5 console: navigate to Configuration > Servers and Sites > Default Server Settings > Advanced and add the com.sun.identity.server.fqdnMap[realmDNSalias] property with a value of realmDNSalias for each realm DNS alias.
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -u [adminID] -f [passwordfile] -s default -a com.sun.identity.server.fqdnMap[realmDNSalias1]=realmDNSalias1 com.sun.identity.server.fqdnMap[realmDNSalias2]=realmDNSalias2 
      replacing [adminID], [passwordfile] and realmDNSalias with appropriate values. The first instance of the realmDNSalias mapping must be contained within [ ]. For example:
      $ ./ssoadm update-server-cfg -u amadmin -f pwd.txt -s default -a com.sun.identity.server.fqdnMap[host1.example.com]=host1.example.com com.sun.identity.server.fqdnMap[openam.example.net]=openam.example.net 
  3. Restart the web application container in which OpenAM runs to apply these configuration changes.

See Also

How do I set up Realm DNS Aliases in AM/OpenAM (All versions) when CDSSO is configured?

Setup and Maintenance Guide › Setting Up Realms

Setup and Maintenance Guide › Setting Up Realms › To Configure DNS Aliases for Accessing a Realm

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-10337 (PUT to /json/global-config/realms/ fails if Accept-API-Version is missing/doesn't specify Protocol.)

OPENAM-8836 (Realm alias in XUI Admin Console should be reflected in fqdnMap)

OPENAM-8416 (Matching DNS alias in realms breaks user authentication and locks out amadmin)

OPENAM-8207 (OpenAM allows creation of duplicate realm mappings - rendering logon impossible)

OPENAM-5892 (same Realm/DNS alias can be configured in two different realms)


How do I set up Realm DNS Aliases in AM/OpenAM (All versions) when CDSSO is configured?

The purpose of this article is to provide information on setting up Realm DNS Aliases in AM/OpenAM when Cross Domain Single Sign On (CDSSO) is configured. It assumes CDSSO is operating correctly and you already have a site configured.

Prerequisites

If you don't already have a site configured, you must add a site to the server before you can add a secondary site URL. Here is an example site configuration:

  • Site URL: http://lb.example.com:8080/openam
  • Primary server URL: http://host1.example.com:8080/openam
  • Secondary server URL: http://openam.cdssoexample.com:8080/openam

Additionally, you must update the policy agent to use the site URL (load balancer) as the naming URL:

  • Web policy agent - You can do this by editing the com.sun.identity.agents.config.naming.url property in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory) or by adding the property in the console by navigating to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Custom Properties.
  • JEE policy agent 3.5.x - You can do this by editing the com.iplanet.am.naming.url property in the OpenSSOAgentBootstrap.properties file (located in the /path/to/agent/config/directory where the policy agent is installed). This property is not used in Java agents 5 and later as the site URL is derived instead. See Release Notes › Important Changes to Existing Functionality (Changes to the Java Agent's Startup Sequence) for further information.

Using the example site configuration above, you would add the following naming URL:

http://lb.example.com:8080/openam/

Setting up Realm DNS Aliases

Realm DNS aliases are an alternative to using Fully Qualified Domain Names (FQDNs) in AM/OpenAM as they implicitly add the realm to the request. For example, http://host1.example.com:8080/openam/UI/Login is interpreted as http://host1.example.com:8080/openam/UI/Login?realm=myrealm when realm DNS aliases are used.

Warning

Realm DNS aliases must be unique; you cannot have the same realm DNS alias configured in more than one realm, this can cause the server to become unresponsive.

You can set up realm DNS aliases as follows when CDSSO is configured:

  1. Add the CDSSO AM/OpenAM URL (sub-realm URL) as a secondary server URL (for example,  http://openam.cdssoexample.com:8080/openam) using either the console or ssoadm:
    • AM / OpenAM 13.5 console: navigate to: Deployment > Sites > [Site Name] > Secondary URLs and add the new secondary server URL.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Sites > [Site Name] > Secondary URLs and add the new secondary server URL.
    • ssoadm: enter the following command:
      $ ./ssoadm add-site-sec-urls -s [sitename] -u [adminID] -f [passwordfile] -a [secondaryserverURL]
      replacing [sitename], [adminID], [passwordfile] and [secondaryserverURL] with appropriate values.
  2. Add the CDSSO FQDN as the realm DNS alias for the sub-realm (for example, openam.cdssoexample.com) using either the console or ssoadm: 
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Properties > Realm/DNS Aliases and ensure the appropriate DNS aliases are specified.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Realm/DNS Aliases and add the DNS alias.
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] -p -a sunOrganizationAliases=[DNSAlias]
      replacing [realmname], [adminID], [passwordfile] and [DNSAlias] with appropriate values.
  3. Add the primary domain to the list of cookie domains (for example, example.com) using either the console or ssoadm: 
    • AM 5 and later console: navigate to: Configure > Global Services > Platform > Cookie Domains and add the primary domain.
    • OpenAM 13.5 console: navigate to: Configure > Global Services > System > Platform > Cookie Domains and add the primary domain.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > System > Platform > Cookie Domains and add the primary domain.
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s iPlanetAMPlatformService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-platform-cookie-domains=[primarydomain]
      replacing [adminID], [passwordfile] and [primarydomain] with appropriate values.
Note

If you are using Agents 5 and later (Web or Java), you can skip step 4 (but must restart per step 5) as this configuration is no longer needed since AM now provides CDSSO using the OAuth 2.0 protocol and the oauth2/authorize endpoint. The former method of providing SSO, CDCServlet, is no longer used. See Web Agents 5 Release Notes › Major Improvements and Java Agents 5 Release Notes › Major Improvements for further information. 

  1. Pre-Agents 5 only: Update the policy agent configuration to use the new secondary server URL for the CDSSO server, login and logout URLs (without the realm parameter). For example:
    http://openam.cdssoexample.com:8080/openam/cdssoservlet
    http://openam.cdssoexample.com:8080/openam/UI/Login
    http://openam.cdssoexample.com:8080/openam/UI/Logout
    You can do this using either the console or ssoadm:
    • AM 5 and later console:
      • CDSSO server URL: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] > SSO > CDSSO Servlet URL and add the new CDSSO server URL.
      • Login URL: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Login URL > OpenAM Login URL and add the new login URL.
      • Logout URL: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Logout URL > OpenAM Logout URL and add the new logout URL.
    • OpenAM 13.x console:
      • CDSSO server URL: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > SSO > CDSSO Servlet URL and add the new CDSSO server URL.
      • Login URL: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Login URL > OpenAM Login URL and add the new login URL.
      • Logout URL: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Logout URL > OpenAM Logout URL and add the new logout URL.
    • Pre-OpenAM 13 console:
      • CDSSO server URL: navigate to: Access Control > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > SSO > CDSSO Servlet URL and add the new CDSSO server URL.
      • Login URL: navigate to: Access Control > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Login URL > OpenAM Login URL and add the new login URL.
      • Logout URL: navigate to: Access Control > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Logout URL > OpenAM Logout URL and add the new logout URL.
    • ssoadm: enter the following command:
      $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.cdsso.cdcservlet.url=[CDSSOserverURL] com.sun.identity.agents.config.login.url[0]=[loginURL] com.sun.identity.agents.config.logout.url[0]=[logoutURL]
      replacing [realmname], [agentname], [adminID], [passwordfile], [CDSSOserverURL], [loginURL] and [logoutURL] with appropriate values.
  2. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.

See Also

How do I set up Realm DNS Aliases in AM/OpenAM (All versions)?

Multiple mappings found for organization identifier error when logging into AM/OpenAM (All versions)

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

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I configure which pages are displayed upon successful and failed logins in AM/OpenAM (All versions)?

The purpose of this article is to provide information on configuring which pages are displayed upon successful and failed logins in AM/OpenAM. If you have added a RelayState parameter or a goto parameter to the login URL, these parameters (RelayState takes precedence over goto) are used in preference to the settings described in this article.

Configuring pages to display for successful logins (global)

You can configure pages to display for successful logins using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Post Authentication Processing > Default Success Login URL and add the required URLs.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Authentication > Core > Post Authentication Processing > Default Success Login URL and add the required URLs.
  • ssoadm:
    1. Create a data file (called DATA_FILE to match the next command) with the following contents:
      iplanet-am-auth-login-success-url=[URL1]
      iplanet-am-auth-login-success-url=[URL2]
      ...
      replacing [URLn] with your required URLs.
    2. Enter the following command:
      $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -D DATA_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. 

Configuring pages to display for successful logins (realm)

You can configure pages to display for successful logins to a realm using either the console or ssoadm:

Note

Realm level successful URLs take precedence over the global level successful URLs if both are specified and the user logs into the realm.

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Settings > Post Authentication Processing > Default Success Login URL and add the required URLs.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Core > Default Success Login URL and add the required URLs.
  • ssoadm:
    1. Create a data file (called DATA_FILE to match the next command) with the following contents:
      iplanet-am-auth-login-success-url=[URL1]
      iplanet-am-auth-login-success-url=[URL2]
      ...
      replacing [URLn] with your required URLs.
    2. Enter the following command:
      $ ./ssoadm set-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -D DATA_FILE
      replacing [realmname], [adminID] and [passwordfile] with appropriate values.
Note

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

Configuring pages to display for failed logins (global)

You can configure pages to display for failed logins using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Post Authentication Processing > Default Failure Login URL and add the required URLs.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Authentication > Core > Post Authentication Processing > Default Failure Login URL and add the required URLs.
  • ssoadm:
    1. Create a data file (called DATA_FILE to match the next command) with the following contents:
      iplanet-am-auth-login-failure-url=[URL1]
      iplanet-am-auth-login-failure-url=[URL2]
      ...
      replacing [URLn] with your required URLs.
    2. Enter the following command:
      $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -D DATA_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. 

Configuring pages to display for failed logins (realm)

You can configure pages to display for failed logins to a realm using either the console or ssoadm:

Note

Realm level failed URLs take precedence over the global level failed URLs if both are specified and the user attempts to log into the realm.

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Settings > Post Authentication Processing > Default Failure Login URL and add the required URLs.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Core > All Core Settings > Post Authentication Processing > Default Failure Login URL and add the required URLs.
  • ssoadm:
    1. Create a data file (called DATA_FILE to match the next command) with the following contents:
      iplanet-am-auth-login-failure-url=[URL1]
      iplanet-am-auth-login-failure-url=[URL2]
      ...
      replacing [URLn] with your required URLs.
    2. Enter the following command:
      $ ./ssoadm set-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -D DATA_FILE
      replacing [realmname], [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 configure a list of valid goto URL resources in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM/OpenAM (All versions)?

Authentication and Single Sign-On Guide › Reference › Post Authentication Processing

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-1254 (Success/Failure URLs can be lost if multiple PAPs are used)

OPENAM-3939 (json response for failed authentication doesn't contain the Default Failure Login URL)

OPENAM-4848 ('terms of usage' / consent auth module needed)


How do I configure a list of valid goto URL resources in AM/OpenAM (All versions)?

The purpose of this article is to provide information on configuring a list of valid goto URL resources to which users can be redirected after authentication in AM/OpenAM. This is good practice to increase security against possible phishing attacks through open redirect. When you specify a URL resource list, the resource of the URL stated in the goto or gotoOnFail parameter must exist on the URL resource list for the user to be redirected. If you do not specify a URL resource list, all resources included in URLs specified in the goto or gotoOnFail parameter are considered valid.

Configuring a list of valid goto URL resources (global)

You can configure this URL resource list using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Global Services > Validation Service and add the valid goto URL resources.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > Validation Service and add the valid goto URL resources.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s validationService -t organization -u [adminID] -f [passwordfile] -a openam-auth-valid-goto-resources=[resource]
    replacing [adminID], [passwordfile] and [resource] with appropriate values.

You can add as many resources as required by adding multiple openam-auth-valid-goto-resources properties separated by a space with the resource in quotes. For example:

$ ./ssoadm set-attr-defs -s validationService -t organization -u amadmin -f pwd.txt -a openam-auth-valid-goto-resources="http://website.example.com/*" openam-auth-valid-goto-resources="http://website.example.com/*?*"

See Authentication and Single Sign-On Guide › Using Authentication › Constraining Post-Login Redirects for examples of URL pattern matching to help you populate your URL resource list.

Configuring a list of valid goto URL resources (realm)

Realm level URL resource lists take precedence over the global level URL resource lists if both are specified and the user is logged into the realm.

Note

You may need to add the Validation Service if it is not listed under Services by clicking Add a Service or Add and then selecting Validation 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 this URL resource list using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Services > Validation Service and add the valid goto URL resources.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Services > Validation Service and add the valid goto URL resources. 
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s validationService -e [realmname] -u [adminID] -f [passwordfile] -a openam-auth-valid-goto-resources=[resource]
    replacing [realmname], [adminID], [passwordfile] and [resource] with appropriate values.

You can add as many resources as required by adding multiple openam-auth-valid-goto-resources properties separated by a space with the resource in quotes. For example:

$ ./ssoadm set-realm-svc-attrs -s validationService -e / -u amadmin -f pwd.txt -a openam-auth-valid-goto-resources="http://website.example.com/*" openam-auth-valid-goto-resources="http://website.example.com/*?*"

See Authentication and Single Sign-On Guide › Using Authentication › Constraining Post-Login Redirects for examples of URL pattern matching to help you populate your URL resource list.

See Also

Installation Guide › Securing Installations › Avoiding Obvious Defaults

Authentication and Single Sign-On Guide › Using Authentication › Constraining Post-Login Redirects

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-1773 (DAS does not handle goto whitelisting)

OPENAM-3462 (Adding URL to goto URLs should be dynamic)


How do I automate the creation of scripts in AM/OpenAM (All versions)?

The purpose of this article is to provide information on automating the creation of scripts in AM/OpenAM rather than using the console to create scripts.

Overview

You can use different approaches to automate the creation of scripts depending on your preference and which version of AM/OpenAM you are using:

  • AM 5 and later: You can use Amster, REST or ssoadm (deprecated).
  • OpenAM 13.x: You can use REST or ssoadm.

This article covers the steps required using REST and Amster which are the preferred approaches; you should refer to the documentation for information on using ssoadm: Development Guide › Managing Scripts With the ssoadm Command.

Once you have created your script, you can verify it has been created in the console by navigating to: Realms > [Realm Name] > Scripts > [Script Name], for example:

Using REST

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM 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 a valid resource version (AM 5 and later).

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

The following examples demonstrate creating a simple script using the REST API according to which version of AM/OpenAM you are using; see Development Guide › Managing Scripts With the REST API for details of what values can be used in the language and context fields.

AM 5 and later

  1. Generate a base64 encoded version of your script (you could use the DS/OpenDJ base64 tool to do this). For example, if your script was:
    logger.message("hello world"); 
    
    It would become the following after it was base64 encoded:
    bG9nZ2VyLm1lc3NhZ2UoImhlbGxvIHdvcmxkIik7
    
  2. Authenticate as an admin user. 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": "/" }
    
  3. Create the script using the following curl command where the script value is the base64 encoded value you generated in step 1 and the script ID is specified in the URL. For example:
    $ curl -X PUT -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.1" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -d '{
             "name" : "myScript",
             "description" : "myDescription",
             "script" : "bG9nZ2VyLm1lc3NhZ2UoImhlbGxvIHdvcmxkIik7",
             "language" : "GROOVY",
             "context" : "POLICY_CONDITION"
    }' "http://host1.example.com:8080/openam/json/realms/root/scripts/myScriptID"
    
    Example response:
    {
      "_id": "myScriptID",
      "name": "myScript",
      "description": "myDescription",
      "script": "bG9nZ2VyLm1lc3NhZ2UoImhlbGxvIHdvcmxkIik7",
      "language": "GROOVY",
      "context": "POLICY_CONDITION",
      "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
      "creationDate": 1475754099280,
      "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
      "lastModifiedDate": 1475754099280
    }
    

OpenAM 13.x

  1. Generate a base64 encoded version of your script (you could use the DS/OpenDJ base64 tool to do this). For example, if your script was:
    logger.message("hello world"); 
    
    It would become the following after it was base64 encoded:
    bG9nZ2VyLm1lc3NhZ2UoImhlbGxvIHdvcmxkIik7
    
  2. Authenticate as an admin user. For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate 
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
    
  3. Create the script using the following curl command where the script value is the base64 encoded value you generated in step 1. For example:
    $ curl -X POST -H "Content-Type: application/json" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -d '{
             "name" : "myScript", 
             "description" : "myDescription",
             "script" : "bG9nZ2VyLm1lc3NhZ2UoImhlbGxvIHdvcmxkIik7",
             "language" : "GROOVY",
             "context" : "POLICY_CONDITION"
    }' "http://host1.example.com:8080/openam/json/scripts?_action=create"
    
    The response will contain the automatically assigned id for the script, for example:
    {
      "_id": "ee8a36c2-9d67-4d39-94d2-d2146b6a56f6",
      "name": "myScript",
      "description": "myDescription",
      "script": "bG9nZ2VyLm1lc3NhZ2UoImhlbGxvIHdvcmxkIik7",
      "language": "GROOVY",
      "context": "POLICY_CONDITION",
      "createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
      "creationDate": 1475754099280,
      "lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
      "lastModifiedDate": 1475754099280
    }
    

Using Amster (AM 5 and later)

The following example demonstrates creating a simple script using Amster; see Entity Reference › Scripts › create for details of what values can be used in the language and context fields:

  1. Generate a base64 encoded version of your script (you could use the DS/OpenDJ base64 tool to do this). For example, if your script was:
    logger.message("hello world"); 
    
    It would become the following after it was base64 encoded:
    bG9nZ2VyLm1lc3NhZ2UoImhlbGxvIHdvcmxkIik7
  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. Create the script, where the id is your script ID and the script value is the base64 encoded value you generated in step 1. For example:
    am> create Scripts --realm / --id myScriptID --body '{"name":"myScript","description":"myDescription","script":"bG9nZ2VyLm1lc3NhZ2UoImhlbGxvIHdvcmxkIik7","language":"GROOVY","context":"POLICY_CONDITION"}'
    

See Also

How do I add logging to server-side scripts in AM (All versions) and OpenAM 13.x?

What automation tools are available for installing, upgrading and configuring AM/OpenAM deployments (All versions)?

Installing and configuring AM/OpenAM

Using the REST API in AM/OpenAM

Using Amster in AM

Development Guide › Developing with Scripts

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

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I re-create a bootstrap file for OpenAM 12.x and 13.x if the bootstrap file has become corrupt?

The purpose of this article is to provide assistance if you need to re-create a bootstrap file for OpenAM if the bootstrap file has become corrupt. This article also provides information about the bootstrap file, including what information it contains.

Overview

OpenAM uses the bootstrap file to find its configuration when initializing.

Initially, OpenAM looks at the path specified in the bootstrap locator file (AMConfig_[path_to_openam], which is located in the $HOME/.openamcfg/ directory of the user running the web application container). This file identifies the configuration directory where the bootstrap file is located; the bootstrap file contains details of the configuration store.

A typical bootstrap file (with URL encoding removed to improve readability) looks like this:

ldap://localhost:50389/http://openam.example.com:8080/openam?user=cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org&pwd=AQIC5wM2LY4z9R5f8R&dsbasedn=dc=openam,dc=forgerock,dc=org&dsmgr=cn=Directory Manager&dspwd=AQIC5wM2LY4z9R5f8R&ver=1.0

Where:

  • localhost:50389 - hostname and port of the directory server used for the OpenAM configuration store.
  • http://openam.example.com:8080/openam - URL of the OpenAM instance.
  • cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org - DN of the dsameuser (see How do I change the dsameuser password in AM/OpenAM (All versions)? for further information on this user).
  • AQIC5wM2LY4z9R5f8R (1st occurrence) - encrypted password for dsameuser.
  • dc=openam,dc=forgerock,dc=org - Base DN.
  • cn=Directory Manager - directory admin user.
  • AQIC5wM2LY4z9R5f8R (2nd occurrence) - encrypted password for the directory admin user.
Note

By default, the dsameuser has the same password as amadmin and the Directory Manager if you are using an embedded configuration store.

Re-creating a bootstrap file

Ideally you should restore the bootstrap from a backup; if you do not have a valid backup, you should re-create the bootstrap file as follows:

Install a new separate OpenAM instance using the same passwords and configuration store as the one for which you are trying to re-create the bootstrap file. The passwords are hashed in the bootstrap file, but providing you use the same passwords, the resulting passwords hash will be the same. You can then copy the bootstrap file from this new instance to the instance with the corrupted bootstrap file.

See Also

How do I change the amadmin password in AM/OpenAM (All versions)?

How do I change the dsameuser password in AM/OpenAM (All versions)?

Default Configuration page shown instead of Login page in AM/OpenAM (All versions)

How do I migrate from an embedded to external DS/OpenDJ in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5971 (The Bootstap file needs a method for fast recovery in the event of corruption)


Frequently Asked Questions


FAQ: Installing AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing AM/OpenAM.

Frequently asked questions

Q. Is AM/OpenAM compatible with Oracle Java Development Kit (JDK) 11?

A. Yes, as of AM 6.5, Oracle JDK 11 is supported, however, there is a known issue with the display of some pages in the admin console. See Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x for further information.

You should only use supported versions to prevent compatibility issues.

Q. Why does AM/OpenAM require a JDK rather than just a JRE?

A. AM/OpenAM primarily requires a JDK to compile the bundled JSP files. Most web application containers include a JDK, although Tomcat does not. However, Tomcat includes a JSP engine (Jasper) that will compile JSPs. Although AM/OpenAM should run if deployed on Tomcat without a JDK, it should be noted that this is not supported. Additionally, utilities such as jar and jstack, which are referred to in the product documentation and used for troubleshooting, are only available when the JDK is installed.

Q. Can AM/OpenAM be used with OpenJDK?

A. Yes, OpenJDK 8 is supported as of AM 5. Prior to this, OpenJDK has not been tested with OpenAM, but is expected to work since OpenJDK is a compliant JDK and is fully compatible. However, as it has not been tested, there may be incompatibility issues with other third-party products.

Q. Is the Pivotal TC Server supported?

A. The Pivotal TC Server is a Web application server based on open-source Apache Tomcat™, but it is customized in a way that the configuration filename and its location etc are not compliant with the default Tomcat server. For example:

pivotal-tc-server-developer-3.1.7.RELEASE/templates/base-tomcat-7/conf $ls
catalina-fragment.properties    catalina.policy      logging-fragment.properties    server-fragment.xml  web-fragment.xml

pivotal-tc-server-developer-3.1.7.RELEASE/tomcat-7.0.72.B.RELEASE $ls
LICENSE    NOTICE    bin    lib

As such, AM/OpenAM cannot install on the Pivotal TC Server by default, it has not been tested nor is it supported. If you encounter any issues running on the Pivotal TC Server, you will be asked to reproduce them on a supported container.

Q. Does AM/OpenAM support IPv6?

A. Yes, Internet Protocol version 6 (IPv6) is fully supported in addition to IPv4.

Note

When deploying OpenAM 13.0 components on Microsoft® Windows® in an IPv6 environment, you must use the Java® 7 Development Kit on Windows (due to JDK-6230761, which is fixed only in Java 7).

Q. Can I install AM/OpenAM on a system configured with SELinux in Enforcing mode?

A. Yes you can, but you must perform some additional steps prior to installing AM/OpenAM, otherwise the installation will never complete.

See How do I install OpenAM with Apache Web Policy Agent 4.x on Red Hat Enterprise Linux or CentOS configured with SELinux? for further information.

Q. Do I need to be a root user to install and administer AM/OpenAM?

A. No, AM/OpenAM does not require root user usage. Providing Apache Tomcat™ does not attempt to use ports below 1024, you can use any user for AM/OpenAM. When running as a non-root user, the web application container must be able to write to its own home directory as this is where AM/OpenAM stores its configuration files.

Q. Can I use an IP address for the AM/OpenAM server URL?

A. No, you must use a Fully Qualified Domain Name (FQDN) for the AM/OpenAM server URL, otherwise cookies will not work. The FQDN should be in the format hostname.domainname for the AM/OpenAM server, for example, http://<hostname.domain>:8080/openam 

See Installation Guide › Preparing a Fully Qualified Domain Name for further information.

Note

You must never use the localhost domain for AM/OpenAM, not even for testing purposes.

Q. How do I debug issues when I am installing or upgrading AM/OpenAM?

A. You can enable Message level debugging in the web application container as described in How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions) ?

Q. How do I add a new server to a Site configuration?

A. You can follow the procedure outlined in the documentation: Installation Guide › To Add a Server to a Site.

Note

You must restart all servers in the Site configuration (including existing ones) to complete the setup. This is a known issue in OpenAM 13.5.1 and earlier: OPENAM-480 (Adding a server to a site requires restart of OpenAM) and OPENAM-10874 (Adding a new server (site) requires a Restart on all the old servers), which is resolved in OpenAM 13.5.2 and later. 

Q. What is the difference between the primary URL and secondary URLs?

A. Sites have a primary URL, which is normally the VIP through which all access to the site is routed.

One or more secondary site URLs can be included, which is useful for internal VIPs or as alternate entry point to the site. It’s essentially there to make AM/OpenAM aware that it should handle other FQDNs in addition to the primary URL. The secondary site URLs are not used by any AM/OpenAM clients like policy agents or SDK; the way that AM/OpenAM functions means only the primary site ID will be included in the SSOToken and therefore policy agents will always use the primary site URL to communicate with AM/OpenAM.

See Reference › Deployment Configuration for further information.

Q. Can I use the embedded configuration and/or user stores in production?

A. You can for small systems, but it is not generally recommended for large-scale production systems. You should also consider that using external data stores allows you to tune your LDAP servers separately, which gives you greater control over performance. If you have a small scale deployment that is relatively simple, the embedded stores may be suitable for your needs; you should performance test this option to check it is appropriate before continuing.

Note

If you plan on using external configuration/user stores, it is recommended that you start with the external stores rather than migrating to them after you have gone live. 

This advice also applies to the CTS store; see FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM (Q. Can I used the embedded CTS store in production?) for further information.

Q. Can I have the user store and configuration store on the same DS/OpenDJ instance?

A. It is best practice to keep the user store and configuration store in separate DS/OpenDJ installations. This means you can cache and index these stores differently. Additionally, by having two installations you will have separate Java Virtual Machines (JVM), which means you can tune the stores differently as well.

Q. Can two separate instances of AM/OpenAM share the same DS/OpenDJ user store?

A. Yes they can.

Q. Does AM/OpenAM support user stores with a dynamic groups LDAP structure?

A. Yes it does. You should ensure the Attribute Name for Group Membership property is set to isMemberOf in your data store configuration; AM/OpenAM will use this attribute to fetch group membership, which includes dynamic groups. See Setup and Maintenance Guide › Setting Up Identity and Data Stores for further information.

See isMemberOf attribute does not return current group membership details for a user in AM/OpenAM (All versions) for details of returning group membership details via REST.

Resolved RFE: OPENAM-9030 (Improve group management implementation)

Q. Can I have a fully operational AM/OpenAM cluster where the nodes are running different AM/OpenAM versions?

A. It is not recommended other than for upgrade purposes and will always depend on the actual differences between the releases. If there are changes to the AM/OpenAM schema and these changes are replicated to all the other configuration stores, it is very likely that the old nodes will not be compatible and may not be fully functional.

Although it is usually possible to have a mix of AM/OpenAM versions in a cluster for upgrade purposes, you should not make any changes to the configuration until all nodes in the cluster have been updated. As a precaution, it is also recommended that you temporarily remove old nodes from the cluster once the first node has been upgraded and that you remove the node that is currently being upgraded to prevent your users seeing an Upgrade AM/OpenAM page.

See Also

How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions) ?

FAQ: Installing and using ssoadm in AM/OpenAM

FAQ: Upgrading AM/OpenAM

FAQ: Configuring AM/OpenAM

FAQ: AM/OpenAM compatibility with third-party products

FAQ: Source code in AM/OpenAM

FAQ: General AM/OpenAM

Installing and configuring AM/OpenAM

Installation Guide

User Guide › Installing Access Management with Amster

Related Training

ForgeRock Access Management Core Concepts (AM-400)


FAQ: Configuring AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding configuring AM/OpenAM.

Frequently asked questions

Q. How can I configure an AM/OpenAM server without using the console?

A. You can use the configurator.jar tool (for example, openam-configurator-tool-14.1.1.3.jar for AM 6) to configure a deployed AM/OpenAM server. This tool allows you to easily configure an AM/OpenAM server in a silent, unattended manner (whether for a new install, upgrade or even in a scenario where you are moving to new servers and want to replicate an existing configuration) all without using the console. This tool can be included in scripts to automate the configuration process if required.

Note

The configurator.jar tool is included in AM/OpenAM but is not installed by default.

See Installation Guide › Setting up Configuration Tools for an overview of the process. The most important part is creating a valid comprehensive config.file as this is used for the actual configuration. A sampleconfiguration file is included when you install the configuration tools, which you should use as the basis of your configuration file; the properties that can be set within this file are described in Reference › configurator.jar. When AM/OpenAM is installed from the console, the parameters that would be used in the configuration.jar configuration file are written to the install log. This can be used as a quick way to generate such a configuration file.

Note

If you are configuring multiple AM/OpenAM servers within a site, you must ensure the AM_ENC_KEY property in the configuration file has the same value for each server. An RFE exists for this: OPENAM-8726 (Using configurator CLI should not require setting the correct encryption key when setting up additional servers).

As of AM 5, you can also use Amster to configure AM as detailed in User Guide › Installing ForgeRock Access Management with Amster.  

Q. How do I configure multiple AM/OpenAM instances using the configurator tool?

A. You need to include the following property in the config.file for the second AM/OpenAM instance to point to the first instance:

existingserverid=http://server1.example.com:8080/openam

Additionally, the following properties must be identical in the config.file for both instances:

locale
PLATFORM_LOCALE
AM_ENC_KEY
ADMIN_PWD
AMLDAPUSERPASSWD
COOKIE_DOMAIN
ACCEPT_LICENSES
DATA_STORE
DIRECTORY_SSL
DIRECTORY_SERVER
DIRECTORY_PORT
DIRECTORY_ADMIN_PORT
DIRECTORY_JMX_PORT
ROOT_SUFFIX
DS_DIRMGRDN
DS_DIRMGRPASSWD

See Installation Guide › Setting up Configuration Tools for further information about the configurator.jar tool; a sampleconfiguration file is included when you install the configuration tools, which you should use as the basis of your config.file.

Note

It is not recommended to configure a site during the initial configuration. You should either use the console or ssoadm to set up the site and perform all subsequent configuration changes.  

Q. Do I use the configuration property DIRECTORY_SSL=SSL when I'm configuring AM/OpenAM using the configurator.jar tool and want to configure HTTPS?

A. No, to configure HTTPS, you should set the configuration property as follows: DIRECTORY_SSL=SIMPLE and specify the HTTPS URL against the SERVER_URL property. There is a known documentation issue that is fixed in AM 5: OPENAM-7412 (Configurator tool HTTPS example is incorrect in the Install Guide).

You should not use DIRECTORY_SSL=SSL alongside DATA_STORE=embedded as this will break the installation since there is no LDAPS port on an embedded DS/OpenDJ. This should be left as 'SIMPLE' unless you are using an external configuration store with LDAPS.

Q. How do I integrate IDM, AM and DS?

A. You should refer to Integrating IDM, AM, and DS, which collects the information you need to set up integration in one place. For additional features, refer to the following chapters from IDM documentation: Samples Guide › Integrating IDM With the ForgeRock Identity Platform and the Integrator's Guide › Setting Up User-Managed Access (UMA), Trusted Devices, and Privacy.

Q. How can I secure AM/OpenAM?

A. See Installation Guide › Securing Installations for best practice advice on securing AM/OpenAM.

Q. How can I restrict access to the console based on IP address?

A. One way to achieve this would be to use a reverse proxy or IG/OpenIG to only allow access to the console from particular IP addresses. 

Note

This type of question and deployment is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Q. Is there a maximum number of realms permitted in AM/OpenAM?

A. There is not an absolute maximum number of realms allowed but there are limitations; in general, you should avoid large numbers of realms.

The following things should be considered when planning realm numbers:

  • Each realm loads certain organizational configuration schema, which is cached on the AM/OpenAM instance; this means you must have enough JVM heap assigned based on load testing.
  • Any changes to global configuration triggers the cache to be cleared; this means you may find global configuration changes take longer than expected if you have a lot of realms with cached data.
  • The console may be slow or may not be able to load all realms depending on your configuration.
  • Policy / referral evaluation may be slow or hang if you have policies under each realm, depending on your policy configuration. 
  • The CTS token store must be carefully designed depending on the number of users residing under each realm.
  • DS/OpenDJ has an index-entry-limit and if the number of indexes (that is, sunxmlKeyValue, which stores realm alias names) exceeds this limit, the search will be an unindexed search, which will impact performance.
  • DS/OpenDJ user stores will need to be tuned carefully to handle the additional overhead of persistent searches and connections pools generated by each realm's data stores and/or LDAP authentication modules.
  • A large number of realms can exhaust system resources such as file descriptors. For example, each realm will have a series of listeners each with an open file descriptor; factoring in other open file descriptors in use on the system and operating system limitations, we tend to advise against a very large number of realms to avoid nearing maximum file descriptor limits. Please consult your operating system documentation for your particular deployment and refer to Installation Guide › Setting Maximum File Descriptors for further information.

Q. Can I use multiple identity repositories in the same realm?

A. As per the Installation Guide › Preparing an External Identity Repository:

You should not configure more than one writeable identity repository in a single realm. AM will try to perform write operations on each identity repository configured in a realm, and there is no way to configure which repository is written to.

To manage identities and reconcile differences between multiple identity repositories, use ForgeRock Identity Management.

Q. Can I use wildcards (for example *) in Realm/DNS alias settings?

A. No, the Realm/DNS aliases must follow standard FQDN conventions and only exact matches are permitted.

Q. Can I change the configuration store suffix (for example, dc=openam,dc=forgerock,dc=org) in between doing an export and import?

A. No. If you attempt this (using export-svc-cfg and import-svc-cfg), references to the old configuration store suffix will be imported into your new configuration store and related functionality will silently cease to work.

Q. Which authentication modules work with HTTP Basic Authentication?

A. The following authentication modules work with HTTP Basic Authentication:

  • Active Directory
  • Data Store
  • LDAP

Q. Can I change session timeouts during the session and/or the authentication process?

A. As of OpenAM 13, the maximum session timeout (AMMaxSessionTime) and maximum idle timeout (AMMaxIdleTime) can be updated as Session properties during post authentication processing. These timeouts can be set as follows:

ssoToken.setProperty("AMMaxSessionTime", "timeout_in_minutes");
ssoToken.setProperty("AMMaxIdleTime", "timeout_in_minutes");

See Designing Your Post-Authentication Plugin and Building Your Sample Post-Authentication Plugin for further information.

Note

Creating a custom PAP is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

There is a known issue where the session does not reflect the change but the change is enacted: OPENAM-9278 (Setting Session properties via SSOToken#setProperty is not reflected in Session). For example, setting the Maximum Session Time to "1", will automatically log out the user in 1 minutes time.

Resolved RFE: OPENAM-2374 (Need a way to update max session time per session).

Q. Does AM/OpenAM have a maximum password length?

A. No AM/OpenAM does not restrict the maximum length of password. If you are using the LDAP authentication module, you can enforce a minimum password length.

See Authentication and Single Sign-On Guide › LDAP Authentication Module for further information.

Q. Does AM/OpenAM support XACML?

A. Yes, AM/OpenAM does support XACML for importing and exporting policies as detailed in Authorization Guide › Importing and Exporting Policies.

See Also

Best practice for blocking the top level realm in a proxy for AM/OpenAM (All versions)

How do I remove console access in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

FAQ: Installing AM/OpenAM

FAQ: Upgrading AM/OpenAM

FAQ: AM/OpenAM compatibility with third-party products

FAQ: AM/OpenAM performance and tuning

FAQ: General AM/OpenAM

Installing and configuring AM/OpenAM

Setup and Maintenance Guide

Installation Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)


FAQ: Patches in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding patches in AM/OpenAM, including Security Advisory patches.

Frequently asked questions

Q. How do I install a patch?

A. You can install a patch as detailed in How do I install an AM/OpenAM patch (All versions) supplied by ForgeRock support?

For security advisory patches, you should refer to the README.X file contained in the security advisory patch zip file for instructions on installing the patch.

Q. How does the patch work?

A. The patched classes contain updated code to resolve your issue(s). When you extract the patch to the /path/to/tomcat/webapps/openam directory, AM/OpenAM loads the patched class from that directory first before loading the other class from the jar file, meaning the patched class will always take precedence.

Q. How can I check that I have applied the patch successfully?

A. You can compare the contents of the filesystem layout in the zip file and the /WEB-INF/classes directory to ensure the new class files (and corresponding directory structure) have been created.. If you want further reassurance, you can check that the changed classes are being loaded from the /WEB-INF/classes directory rather than a jar file. The following example uses the Apache Tomcat™ web container:

  1. Add the following line to the setenv.sh file (typically located in the /tomcat/bin/ directory). If this file doesn't exist, you should create it in the same directory as the catalina.sh file (also located in the /tomcat/bin/directory):
    export CATALINA_OPTS="$CATALINA_OPTS -verbose:class"
  2. Restart the web application container in which AM/OpenAM runs.
  3. Check the catalina.out file to verify that the changed classes are now loaded from the individually unzipped class files. For example, you will see something similar to the following at the end of the catalina.out file if they are:
    [Loaded com.sun.identity.setup.AMSetupServlet from file: /path/to/tomcat/webapps/openam/WEB-INF/classes/com/sun/identity/setup/AMSetupServlet.class]
Note

You won't necessarily see all classes loaded straight away as some of them might not be needed until certain functionality is used, but if you check that one or two of them are being loaded and the others were unzipped to the same directory, then this is a fairly reliable check.

An RFE has been raised for this: OPENAM-2651 (Formalized patching mechanism).

Q. How do I check for conflicting patches that have already been installed?

A. You can check the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where AM/OpenAM is deployed to ensure that the classes contained in the patch don't already exist in the WEB-INF/classes directory. If one or more classes do already exist, it may mean you have a conflicting patch installed. If this is the case, you should seek advice from ForgeRock support prior to applying the patch. 

See How do I use the patchinfo utility to check what patches are installed for AM/OpenAM (All versions) or IG/OpenIG (All versions)? and How do I check what patches are installed for ForgeRock products? for further information.

Q. What happens to my patches when I upgrade to a later version?

A. When you upgrade AM/OpenAM, all previously installed patches are overridden by the new release. If the issue you received the patch for has not been resolved in the new release, you will need to request a new patch by raising a ticket with ForgeRock support.

You can check if an issue has been resolved by checking the Fix Version/s field in Bugster for your issue ID. 

Q. What happens to my patches when I install a security advisory?

A. Existing patches are unaffected when you install a security advisory, although the security advisory may cause conflicts with your previous patches. If you have patches installed, you should seek advice from ForgeRock support prior to installing the security advisory.

Q. Do I have to install each security advisory patch individually for my version of AM/OpenAM?

A. No, you should install the latest security advisory patch for your version of AM/OpenAM and that will include all patches from previous security advisories that apply to your version. Alternatively, you can upgrade to a recommended version that contains the fixes and again that will include previous security advisory patches. 

Note

It is recommended that you apply the latest security patches to ensure your systems remain protected.

See Also

How do I install an AM/OpenAM patch (All versions) supplied by ForgeRock support?

How do I make a backup of configuration data in AM/OpenAM (All versions)? 

Maintenance and Patch availability policy


FAQ: General AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked general questions regarding AM/OpenAM.

Frequently asked questions

Q. How can I protect AM/OpenAM from Clickjacking?

A. AM 5 introduced improvements to protect your deployments from clickjacking. These improvements are:

  • The X-Frame-Options header is now set to SAMEORIGIN to prevent the page being framed by a malicious site. Per RFC 7034, "A browser receiving content with this header field MUST NOT display this content in any frame from a page of different origin than the content itself."
  • A new /* url-pattern has been added to the list of protected resources.

The relevant snippets in the web.xml file (located in the /path/to/tomcat/webapps/openam/WEB-INF directory) are:

  <filter>
    <filter-name>SecurityHeaders</filter-name>
    <filter-class>org.forgerock.openam.headers.SetHeadersFilter</filter-class>
    <init-param>
      <param-name>X-Frame-Options</param-name>
      <param-value>SAMEORIGIN</param-value>
    </init-param>
  </filter>
....
  <filter-mapping>
    <filter-name>SecurityHeaders</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

In pre-AM 5, you should add these additions to the web.xml file yourself to protect against clickjacking.

Note

You can use Content-Security-Policy headers instead of X-Frame-Options headers if you'd prefer as detailed in Q. How do I set Content-Security-Policy headers in AM/OpenAM?

Q. How do I set Content-Security-Policy (CSP) headers in AM/OpenAM?

A. You can define Content-Security-Policy headers in AM/OpenAM (providing you are using at least OpenAM 12.0.1) by updating the web.xml file (located in the /path/to/tomcat/webapps/openam/WEB-INF directory). The SetHeadersFilter class sets the headers, where <param-name> sets the header value and <param-value> can be used to specify any directives. Content-Security-Policy headers can be used for a variety of security-related headers to reduce the risks of XSS, Clickjacking etc.

For example, you would add something similar to this to the web.xml file, ensuring you define appropriate URL-patterns for all the resources you want to protect: 

<filter>
  <filter-name>ContentSecurityPolicyFilter</filter-name>
  <filter-class>org.forgerock.openam.headers.SetHeadersFilter</filter-class>
        <init-param>
           <param-name>default-src</param-name>
           <param-value>'none'</param-value>
        </init-param>
       <init-param>
           <param-name>img-src</param-name>
            <param-value>http://host1.example.com</param-value>
        </init-param>       
        <init-param>
           <param-name>script-src</param-name>
           <param-value>'self' js.example.com</param-value>
        </init-param>
</filter>
...
<filter-mapping> 
   <filter-name>ContentSecurityPolicyFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>

There is a related RFE: OPENAM-11855 (Add support for Content-Security-Policy headers).

Q. Can I remove the YUI 2.3.0 library (/openam/assets/lib/yui)?

A. Yes you can. This library is only used by the configurator during the installation; you can remove it post-install as it is not used.

You may see this being used in URLs such as:

http://host1.example.com:8080/openam/assets/lib/yui/animation/animation-min.js 
http://host1.example.com:8080/openam/assets/lib/yui/button/button-beta-min.js
...

Q. Is Elasticsearch 6 supported for audit logging?

A. No, Elasticsearch 6.x is not currently supported for audit logging because 6.0 introduced a breaking change with regards to how indices are handled (you can now only have one _type per index). An RFE exists to provide this support in a future release: CAUD-424 (ElasticSearch Audit Handler: provide support for ElasticSearch 6.0).

Per the Elasticsearch documentation (Removal of mapping types):

Indices created in Elasticsearch 6.0.0 or later may only contain a single mapping type. Indices created in 5.x with multiple mapping types will continue to function as before in Elasticsearch 6.x. Mapping types will be completely removed in Elasticsearch 7.0.0. 

This is considered a "phased roll-in" intended to give vendors and implementers some phase-in time. As a result, a possible workaround is to create the index in Elasticsearch 5 and then upgrade to Elasticsearch 6.

Q. Does AM/OpenAM support syslog for audit logging?

A. Yes syslog for audit logs is supported. See Setup and Maintenance Guide › Setting Up Audit Logging › Audit Logging to a Syslog Server for further information.

As of OpenAM 13.0, the audit logs (CAUD) are compliant with RFC 5424; you should ensure syslog is configured to log using this format (STRUCTURED-DATA). For example, if you are using Rsyslog, you would need to add the following to your template:

RSYSLOG_SyslogProtocol23Format

See RSYSLOG - RFC5424 and OPENAM-8436 (Syslog handler always sends useless information during XUI operations) for further information.

Q. Why are the timestamps displayed in the audit logs and debug logs different?

A. The timestamps used in the logs are different as the logs serve different purposes:

  • Audit logs use timestamps in UTC format (for example, 2018-07-18T08:48:00.160Z); UTC is a unified standard that is not affected by daylight saving time changes. The format used in audit logs is not configurable since UTC provides the consistency needed for auditing when AM servers are deployed globally across different timezones.
  • Debug logs use the system time since they are primarily used for diagnosing issues where local timestamps are needed in troubleshooting analysis.

This does mean that timestamps will be different if your system uses a format other than UTC.

Q. Can I change the delimiter used in the log files?

A. No, AM/OpenAM uses a tab space as the delimiter in log files and there is no way of changing this.

You could log to a database as this provides greater flexibility or you could use a custom formatter to customize the output of the log files. The ELF formatter is currently used and its source can be found here to give you some background on what it does.

Q. Can I rotate the debug log files?

A. Yes, you can rotate the debug log files (typically located in the $HOME/[am_instance]/openam/debug directory) as detailed in How do I rotate AM/OpenAM (All versions) debug logs?

You can also clear these files if required: How do I clear debug logs in AM/OpenAM (All versions)?

Q. Can I rotate the audit log files?

A. Audit log files (located in $HOME/[am_instance]/openam/log by default) can be rotated.

There are two Audit logging services in AM/OpenAM:

  • Audit Logging Service (REST-based) - AM 5 and later.
  • Classic Logging Service (JAVA-SDK based) - All versions but deprecated in AM 5.

Audit Logging Service

The following JSON files are generated by the Audit Logging Service (by default this is the Global JSON Handler):

  • config.audit.json 
  • activity.audit.json 
  • authentication.audit.json 
  • access.audit.json

Configuration for this handler can be found in: Configure > Global Services > Audit Logging > Secondary Configurations > Edit the Global JSON Handler. See Setup and Maintenance Guide › Configuring JSON Audit Event Handlers for further information on configuring the handler, including file rotation, logs files etc.

Classic Logging Service

The following files (among others) are generated by the Classic Logging Service:

  • amSSO.access 
  • entitlement.access 

Configuration for this service can be found in: Configure > Global Services > Logging (rotation settings can be found in the File tab). See Setup and Maintenance Guide › Implementing the Classic Logging Service for further information on configuring this service; if you are using the Audit Logging Service, you can switch off the classic logging service.

See How do I configure audit logging via ssoadm in AM (All versions) and OpenAM 13.x? for further information on configuring these services using ssoadm.

Q. Can I rotate the stats log files?

A. No, you cannot rotate the stats log files (typically located in the $HOME/[am_instance]/openam/stats directory); you can only clear them as detailed in How do I clear stats logs in AM/OpenAM (All versions)?

An RFE has been raised for this: OPENAM-5055 (Having a log rotation on stats log files).

Q. Are the duplicate endpoint warnings I am getting when starting AM/OpenAM on Apache Tomcat™ a concern?

A. The following warnings shown when starting Tomcat on an AM/OpenAM server are harmless and can be ignored:

WARNING: JAXRPCSERVLET17: duplicate endpoint name

This warning is caused by duplicate entries in the jaxrpc-ri-runtime.xml file and is only an issue in pre-12.0.0 versions of OpenAM.

WARNING: A sub-resource method, public javax.ws.rs.core.Response org.forgerock.openam.forgerockrest.authn.AuthenticationRestService.getMethodNotSupported(), with URI template, "/", is treated as a resource method

This warning is not required and is also a known issue: OPENAM-3093 (WARNING: A sub-resource method, with URI template, "/", is treated as a resource method).

Q. Do translation memory files exist for AM/OpenAM locales?

A. No, we do not have any translation files for AM/OpenAM.

See Also

FAQ: Upgrading AM/OpenAM

FAQ: Installing AM/OpenAM

FAQ: Configuring AM/OpenAM

FAQ: AM/OpenAM performance and tuning

Where can I find useful logs for troubleshooting ForgeRock products?

Installing and configuring AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)


FAQ: AM/OpenAM compatibility with third-party products

The purpose of this FAQ is to provide answers to commonly asked questions regarding AM/OpenAM compatibility with third-party products.

Frequently asked questions

Q. Can I integrate AM/OpenAM with Microsoft Sharepoint?

A. Yes you can. See the following links for further information:

There is a known limitation with policy agents and Kerberos, which means you would need to log in to AM/OpenAM in order for this to work and you would need to use persistent cookies and password replay. An RFE exists to remove the reliance on password replay: AMAGENTS-187 (Enable Agent Kerberos support by reading ticket from Isa session).

Q. Can I integrate AM/OpenAM with Outlook Web Access?

A. Yes, typically integration between AM/OpenAM and Outlook® Web Access (OWA) is achieved using the Password Replay options available via the IIS Web Agent as detailed in Web Agents User Guide › Enable IIS Basic Authentication and Password Replay Support. The documentation only provides an example using Active Directory®; if you use a different user store, you can still use the Password Replay options but should ensure the samaccountname attribute exists in your LDAP server if you require Microsoft Windows logon.

Note

If your users log in to AM/OpenAM via Windows Desktop SSO (Kerberos™ tokens), the AM/OpenAM Password Replay feature cannot be used since AM/OpenAM does not have access to the users' passwords. 

You can also use IG/OpenIG to integrate with OWA. See Gateway Guide › Getting Login Credentials From AM for information to help get you started.

Q. Can I use Facebook, Google or LinkedIn for social authentication in AM/OpenAM?

A. Yes, you can integrate AM/OpenAM with third parties such as Facebook, Google and LinkedIn to provide social authentication using OAuth. See the following links for further information:

Q. Can I use the Google Authenticator app with the ForgeRock Authenticator module?

A. No, the ForgeRock Authenticator (OATH) module is not compatible with the Google Authenticator app and there are no plans to introduce compatibility in the future. You should use the ForgeRock Authenticator app with this module for two step verification.

Q. Can I integrate with Twitter for social authentication?

A. No, you cannot integrate with Twitter for social authentication, since Twitter only supports OAuth1.0a for user authentication and AM/OpenAM supports OAuth 2.0. If you require this integration, you will need to write a custom authentication module that works with the OAuth1.0a protocol.

Note

Writing a custom authentication module is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Q. Does AM/OpenAM support RSA SecurID?

A. Yes, SecurID is fully supported. The RSA SecurID library (authapi-2005-08-12.jar) is not included in the AM/OpenAM distribution. SecurID authentication will fail unless you obtain the library directly from RSA and place it in your classpath. See SecurID authentication module login fails in AM/OpenAM (All versions) with java.lang.NoClassDefFoundError for further details on this issue.

Q. Is AM/OpenAM FIPS 140-2 compliant?

A. ForgeRock conforms to FIPS 140-2 for encryption and hashing ciphers for both inflight messaging, protocol tunnels and credential storage. In addition, the ForgeRock solution has been certified in deployments against rigorous DoD STIG requirements and is in process at FedRAMP certification. All of these certifications require proper FIPS 140-2 compliance. The solution allows deployments to choose ciphers; the most common ones used in deployments tend to be SHA-256 and AES-256, however we support stronger key lengths on both of these. A common trend for mobility is support for elliptical curve cryptography due to its high security yet low process power nature and of course is also recommended by NIST as part of FIPS 140-2.

Regarding FIPS 140-2 certification, ForgeRock does not write its own crypto modules, but our software can utilize underlying crypto modules (usually those associated with Java®) which have options to be executed in FIPS-compliant mode.

Q. Does AM/OpenAM integrate with the Spring Security framework?

A. The Spring Security framework supports standard OAuth2/OIDC integration, which means it will work with AM/OpenAM. It can also call AM/OpenAM's REST APIs.

Q. Can I use Cisco Unified Communications Manager with AM/OpenAM?

A. Yes you can. Cisco have actually provided guidance on this in their own documents and they integrate it with Microsoft Windows and Active Directory.

See Cisco - Single Sign-On for further information.

Q. Does AM/OpenAM support PostgreSQL?

A. No, PostgreSQL is not supported for the CTS data store, configuration data store or the user data store.

See Release Notes › Data Store Requirements for further information on the currently supported data stores.

See Also

FAQ: Installing AM/OpenAM

FAQ: Configuring AM/OpenAM

FAQ: Upgrading AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)


Known Issues


An illegal reflective access operation has occurred when using Java 11 with ForgeRock products

The purpose of this article is to provide assistance if you encounter "An illegal reflective access operation has occurred" warning when using ForgeRock products with Java® 11. This issue affects AM 6.5.x, DS 6.5.x, IDM 6.5.x, IG 6.5.x and Java Agent 5.6.x.

Symptoms

You will see An illegal reflective access operation has occurred warning when installing and using AM (including Amster and ssoadm tools), Java Agents, DS, IDM and IG. The subsequent two lines following this warning vary depending on which product you are using and what you were doing at the time it occurred.

Here are some examples of the types of error you will see by product:

  • AM:
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.codehaus.groovy.vmplugin.v7.Java7$1 (file:/path/to/tomcat/webapps/openam/WEB-INF/lib/groovy-2.4.6.jar (about:blank)) to constructor java.lang.invoke.MethodHandles$Lookup(java.lang.Class,int)
    WARNING: Please consider reporting this to the maintainers of org.codehaus.groovy.vmplugin.v7.Java7$1
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    
  • Java Agent:
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.forgerock.openam.sdk.com.google.inject.internal.cglib.core.$ReflectUtils$1 (file:/tmp/5.6.0/java/java_agents/tomcat_agent/lib/jee-agents-installtools-5.6.0.jar) to method java.lang.ClassLoader.defineClass(java.lang.String,byte[],int,int,java.security.ProtectionDomain)
    WARNING: Please consider reporting this to the maintainers of org.forgerock.openam.sdk.com.google.inject.internal.cglib.core.$ReflectUtils$1
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    
  • DS:
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.opends.server.util.Platform$PlatformIMPL (file:/path/to/ds/lib/opendj.jar) to constructor sun.security.tools.keytool.CertAndKeyGen(java.lang.String,java.lang.String)
    WARNING: Please consider reporting this to the maintainers of org.opends.server.util.Platform$PlatformIMPL
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    
  • IDM:
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.apache.felix.framework.ext.ClassPathExtenderFactory$DefaultClassLoaderExtender (file:/path/to/idm/bin/felix.jar) to method java.net.URLClassLoader.addURL(java.net.URL)
    WARNING: Please consider reporting this to the maintainers of org.apache.felix.framework.ext.ClassPathExtenderFactory$DefaultClassLoaderExtender
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    

Recent Changes

Upgraded to Java 11.

Installed AM 6.5.x, DS 6.5.x, IDM 6.5.x or IG 6.5.x with Java 11.

Installed Java Agent 5.6.x with Java 11.

Causes

These warnings occur when using Groovy with Java 11. For reference, these known issues are:

Whenever you use functionality that accesses Groovy scripting, you will see these warnings.  

Additionally, there is a similar compatibility issue with Felix: FELIX-5765 (An illegal reflective access operation has occurred).

Solution

These messages can be safely ignored because they do not impact the use or functionality of ForgeRock products. However, if you do not want to see them, you can downgrade Java to JDK 1.8 or whitelist these warnings.

See Also

SSLHandshakeException or ClassCastException when using an HSM and Java 11 with ForgeRock products

Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x

How do I disable TLS 1.3 when running DS 6.5 with Java 11?

Cannot install or use ssoadm in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x after restricting configuration store (DS/OpenDJ) cipher suites or Java upgrade

AM 5.x and 6.0.0.x, IDM 6.x and Rest2LDAP cannot connect to DS 5.x or 6 after restricting DS cipher suites or Java upgrade

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14478 (AM on JDK11 shows warning when Groovy access with "Illegal reflective access by org.codehaus.groovy.vmplugin.v7.Java7$1")

OPENIDM-11765 (Warnings on startup when using embedded DS repo with Java 11)

OPENDJ-5664 (JDK 11: illegal reflective access warning during import-ldif)

OPENDJ-5663 (JDK 11: illegal reflective access warning on setup (without profile))

OPENDJ-5660 (JDK 11: illegal reflective access warning on setup (with profile))

AMAGENTS-2616 (Java agent installer makes warning messages when JDK 11 is used)


Install


AM/OpenAM (All versions) install fails with emb.creatingfamsuffix.failure error when installing on a Unix or Linux system

The purpose of this article is to provide assistance if the AM/OpenAM install fails with an "emb.creatingfamsuffix.failure" error when installing on a Unix® or Linux® system with an embedded DS/OpenDJ configuration store. You will also see a 'Connect Error' followed by "Error loading OpenAM suffix 1" when this happens.

Symptoms

The installation fails when attempting to create the AM/OpenAM suffix after the embedded configuration store is installed.

You can see this failure in the browser if you are configuring AM/OpenAM via the browser:

Installing OpenAM configuration store in /openam/conf/opends...Success.
Creating OpenAM suffix You have provided options for scheduling this operation as a task but options provided for connecting to the server's tasks backend resulted in the following error: 'Connect Error'

Error loading OpenAM suffix 1

emb.creatingfamsuffix.failure, refer to install.log under /openam/conf for more information.

The install.log (located in $HOME directory) also shows the same error, with additional details:

Installing OpenAM configuration store in /openam/conf/opends...Success.
Creating OpenAM suffix You have provided options for scheduling this operation as a task but options provided for connecting to the server's tasks backend resulted in the following error: 'Connect Error'

Error loading OpenAM suffix 1
AMSetupServlet.processRequest: error com.sun.identity.setup.ConfiguratorException: emb.creatingfamsuffix.failure
  at com.sun.identity.setup.EmbeddedOpenDS.setup(EmbeddedOpenDS.java:266)
  at com.sun.identity.setup.AMSetupServlet.setupEmbeddedDS(AMSetupServlet.java:964)
  at com.sun.identity.setup.AMSetupServlet.setupSMDatastore(AMSetupServlet.java:1020)
  at com.sun.identity.setup.AMSetupServlet.configure(AMSetupServlet.java:1092)
  at com.sun.identity.setup.AMSetupServlet.processRequest(AMSetupServlet.java:692)
  at com.sun.identity.config.DefaultSummary.createDefaultConfig(DefaultSummary.java:131)
...

Recent Changes

Installed fresh build of AM/OpenAM server on Unix or Linux OS.

Causes

The hostname for AM/OpenAM is not resolvable. You can check this as follows:

  1. Find your hostname using the following command:
    $ hostname
  2. Check if the hostname returned in step 1 is resolvable using the following command:
    $ ping [hostname]
    If it is not resolvable, you will see the following response instead of the ping results:
    ping: cannot resolve host1.example.com: Unknown host
    

If your hostname is resolvable, it could be because you have previously installed an external version of DS/OpenDJ on the same server as the one you are now attempting to install AM/OpenAM. The external DS/OpenDJ installation created a $HOME/.opendj/tools.properties file with its own configuration, which is overriding the connection details (hostname, port etc) for the embedded configuration data store. 

Solution

The solution depends on the cause identified:

  • If your AM/OpenAM hostname is not resolvable: this issue can be resolved by ensuring you use a Fully Qualified Domain Name (FQDN) for AM/OpenAM. This hostname must be resolvable, meaning either a DNS entry or an entry in the /etc/hosts file must exist. See Installation Guide › Preparing for Installation › Preparing a Fully Qualified Domain Name for further information.
  • If a $HOME/.opendj/tools.properties file exists: this issue can be resolved by removing the $HOME/.opendj/tools.properties file prior to re-installing AM/OpenAM.

See Also

Installation Guide › Preparing for Installation

Installation Guide › Preparing for Installation › Preparing a Fully Qualified Domain Name

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2798 (Installation fails when hostname is not resolvable)

OPENAM-4983 (Commands for embedded DJ should use --noPropertiesFile switch)


javax.naming.AuthenticationException: [LDAP: error code 49 - Invalid Credentials] error when reinstalling an AM/OpenAM (All versions) instance

The purpose of this article is to provide assistance if you encounter a "javax.naming.AuthenticationException: [LDAP: error code 49 - Invalid Credentials]" error when reinstalling an AM/OpenAM instance in a multi-server environment.

Symptoms

The following error is shown when you reinstall an AM/OpenAM instance in a site configuration:

The following errors were encountered reading the configuration of the existing servers:

Error on host1.example.com:4444: An error occurred connecting to the server. Details: javax.naming.AuthenticationException: [LDAP: error code 49 - Invalid Credentials]

The replication tool will to try to update the configuration of all the servers in a best-effort mode. However it cannot guarantee that the servers that are generating errors will be updated.

However, the install proceeds and replication continues to work.

Recent Changes

Deleted an AM/OpenAM instance without stopping replication and then attempted to reinstall the instance in the site configuration.

Causes

The replication configuration is not removed when you delete an AM/OpenAM instance from a site, which means the remaining instances still have an entry for the removed instance.

You can observe this in the admin-backend.ldif file (located in /db/adminRoot in DS 6.5 and later, /db/admin in DS 6 or /config in pre-DS 6). For example, if you started with two instances (host1 and host2) and deleted host2, you will still see the entry associated with the removed instance:

objectClass: groupOfUniqueNames
uniqueMember: cn=host1.example.com:5444
uniqueMember: cn=host2.example.com:4444

When you attempt to reinstall the second instance in the site configuration, a conflict occurs as the remaining instances' configuration has not been updated.

Solution

This issue can be resolved using one of the following approaches to update the remaining instances' configuration after deleting the AM/OpenAM instance:

  • Restart the AM/OpenAM instances that remain in the site after you have removed the instance but prior to reinstalling the instance. Restarting the other AM/OpenAM instances updates their configuration and therefore removes the entry of the removed instance.
  • Stop replication on the DS/OpenDJ server associated with the instance you want to remove prior to removing it. You should use the dsreplication command applicable to your version:
    • DS 5 and later:
      $ ./dsreplication unconfigure --unconfigureAll --port 4444 --hostname ds1.example.com --bindDn "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
    • Pre-DS 5:
      $ ./dsreplication disable --disableAll --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
    This command removes the server's replication configuration from all other servers in the replication topology, meaning the remaining servers will not try to replicate to this server.

See How do I delete an AM/OpenAM instance (All versions) from a site along with the replicated embedded DS/OpenDJ server? for further details.

See Also

Installing and configuring AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8646 (Clean up embedded OpenDJ replication config when a server is removed)


Installing OpenAM 12.x or 13.x with an external OpenDJ instance fails with a NPE

The purpose of this article is to provide assistance if installing or configuring OpenAM with an external OpenDJ instance fails with a "Setting up monitoring authentication file.AMSetupServlet.processRequest: errorjava.lang.NullPointerException" error.

Symptoms

The installation fails when attempting to set up the monitoring authentication file.

You can see this failure in the browser if you are configuring OpenAM via the browser:

Checking configuration directory /openam/conf....Success.
Reinitializing system properties....Done
Configuring server instance....Done
Setting up monitoring authentication file.

null, refer to install.log under /openam/conf for more information.

The install.log (located in $HOME directory) also shows the same error, with additional details:

Checking configuration directory /openam/conf....Success.
Reinitializing system properties....Done
Configuring server instance....Done
Setting up monitoring authentication file.AMSetupServlet.processRequest: errorjava.lang.NullPointerException
   at java.net.URLEncoder.encode(URLEncoder.java:205)
   at com.sun.identity.setup.BootstrapCreator.getBootStrapURL(BootstrapCreator.java:189)
   at com.sun.identity.setup.BootstrapCreator.update(BootstrapCreator.java:104)
   at com.sun.identity.setup.BootstrapCreator.updateBootstrap(BootstrapCreator.java:82)
   at com.sun.identity.common.configuration.ServerConfigXMLObserver.update(ServerConfigXMLObserver.java:108)
...

Recent Changes

Installed, upgraded or reconfigured OpenAM with an external OpenDJ instance.

Causes

The external data store already contains some entries, perhaps from a failed install, which is causing the install to fail.

Solution

This issue can be resolved by removing the old entries from the data store before reinstalling or reconfiguring.

You can do this by importing an LDIF file that just contains the data store root suffix (for example, dc=example,dc=com); this will remove the backend with any entries and replace with the base entry. You can use an import-ldif command such as:

$ ./import-ldif --hostname ds1.example.com --port 4444 --backendID userRoot --includeBranch dc=example,dc=com --ldifFile /path/to/remove.ldif 

See Also

OpenDJ Reference › Tools Reference › import-ldif

Related Training

N/A

Related Issue Tracker IDs

OPENAM-1793 (Configurator throws NPE when Setting up monitoring authentication file if there are entries in the data store under the ROOT DN)


Startup and Shutdown


Error during shutdown message when stopping an AM 6 instance running on Apache Tomcat

The purpose of this article is to provide assistance if you encounter an "Error during shutdown" message when stopping an AM instance running on Apache Tomcat™. This is an intermittent issue.

Symptoms

The AM instance is not fully shut down after issuing the shutdown command. You can observe this using the ps command, which will show the process is still running. See How do I check if AM/OpenAM (All versions) is up and running? for further information.

The following error is shown in the CoreSystem debug log when this happens:

SystemTimer:05/08/2018 11:50:07:525 PM BST: Thread[localhost-startStop-2,5,main]: TransactionId[ec243db4-0458-4907-a387-9ef923cf96d0-1188]
ERROR: TimerPool:shutdown() terminating remaining worker thread[189]
amUtil:05/08/2018 11:50:08:461 PM BST: Thread[localhost-startStop-2,5,main]: TransactionId[ec243db4-0458-4907-a387-9ef923cf96d0-1188]
ERROR: Error during shutdown
java.util.concurrent.RejectedExecutionException: Task java.util.concurrent.FutureTask@6566ca14 rejected from java.util.concurrent.ThreadPoolExecutor@146e55b4[Terminated, pool size = 0, active threads = 0, queued tasks = 0, completed tasks = 2446]
   at java.util.concurrent.ThreadPoolExecutor$AbortPolicy.rejectedExecution(ThreadPoolExecutor.java:2047)
   at java.util.concurrent.ThreadPoolExecutor.reject(ThreadPoolExecutor.java:823)
   at java.util.concurrent.ThreadPoolExecutor.execute(ThreadPoolExecutor.java:1369)
   at java.util.concurrent.AbstractExecutorService.submit(AbstractExecutorService.java:112)
   at org.forgerock.openam.audit.context.AuditRequestContextPropagatingExecutorService.submit(AuditRequestContextPropagatingExecutorService.java:111)
   at com.iplanet.dpro.session.monitoring.SessionMonitoringStore.storeRefreshTime(SessionMonitoringStore.java:90)
   at com.iplanet.dpro.session.monitoring.MonitoredOperations.refresh(MonitoredOperations.java:84)
   at com.iplanet.dpro.session.service.SessionService.refresh(SessionService.java:339)
   at com.iplanet.sso.providers.dpro.SSOProviderImpl.isValidToken(SSOProviderImpl.java:264)
   at com.iplanet.sso.SSOTokenManager.isValidToken(SSOTokenManager.java:459)
   at com.iplanet.sso.SSOTokenManager.isValidToken(SSOTokenManager.java:444)
   at com.sun.identity.security.AdminTokenAction.run(AdminTokenAction.java:186)
   at com.sun.identity.security.AdminTokenAction.run(AdminTokenAction.java:67)
   at java.security.AccessController.doPrivileged(Native Method)
   at com.sun.identity.idm.plugins.internal.SpecialRepo.removeListener(SpecialRepo.java:526)
   at com.sun.identity.idm.server.IdRepoPluginsCache.clearIdRepoPluginsCache(IdRepoPluginsCache.java:318)
   at com.sun.identity.idm.server.IdServicesImpl.clearIdRepoPlugins(IdServicesImpl.java:2592)
   at com.sun.identity.idm.server.IdCachedServicesImpl$1.shutdown(IdCachedServicesImpl.java:153)
   at com.sun.identity.common.ShutdownManager.shutdown(ShutdownManager.java:217)
   at com.sun.identity.common.ShutdownServletContextListener.contextDestroyed(ShutdownServletContextListener.java:51)
   at org.apache.catalina.core.StandardContext.listenerStop(StandardContext.java:4837)
   at org.apache.catalina.core.StandardContext.stopInternal(StandardContext.java:5484)
   at org.apache.catalina.util.LifecycleBase.stop(LifecycleBase.java:232)
   at org.apache.catalina.core.ContainerBase$StopChild.call(ContainerBase.java:1575)
   at org.apache.catalina.core.ContainerBase$StopChild.call(ContainerBase.java:1564)
   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)

The following messages are shown in catalina.out:

May 08, 2018 11:50:07 PM org.apache.catalina.core.StandardServer await
INFO: A valid shutdown command was received via the shutdown port. Stopping the Server instance.
May 08, 2018 11:50:07 PM org.apache.coyote.AbstractProtocol pause
INFO: Pausing ProtocolHandler ["http-bio-28080"]
May 08, 2018 11:50:07 PM org.apache.coyote.AbstractProtocol pause
INFO: Pausing ProtocolHandler ["ajp-bio-28009"]
May 08, 2018 11:50:07 PM org.apache.catalina.core.StandardService stopInternal
INFO: Stopping service Catalina
May 08, 2018 11:50:08 PM org.apache.catalina.loader.WebappClassLoader clearReferencesThreads
SEVERE: The web application [/openam] appears to have started a thread named [RxSchedulerPurge-1] but has failed to stop it. This is very likely to create a memory leak.
May 08, 2018 11:50:08 PM org.apache.catalina.loader.WebappClassLoader clearReferencesThreads
SEVERE: The web application [/openam] appears to have started a thread named [RxCachedWorkerPoolEvictor-1] but has failed to stop it. This is very likely to create a memory leak.
May 08, 2018 11:50:08 PM org.apache.catalina.loader.WebappClassLoader clearReferencesThreads
SEVERE: The web application [/openam] appears to have started a thread named [OpenDJ LDAP SDK Default Scheduler] but has failed to stop it. This is very likely to create a memory leak.
...

If you restart the instance, the browser will show a Loading... message and you will be unable to use the console.

Recent Changes

Shut down an AM 6 instance.

Causes

Threads not being terminated upon shutdown is a known issue: OPENAM-13008 (Occasional shutdown error for AM).

Solution

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

Workaround

You can workaround this issue using one of the following options:

  • Forcibly end process using kill -9
  • Define CATALINA_PID environment variable to issue kill -9  only if needed

Forcibly end process

  1. Identify the process ID using the following command:
    $ ps –ef |grep tomcat
    Example response, where process ID is 2240:
    forgero+  2240     1  3 10:34 pts/1    00:01:31 /usr/lib/jvm/java-8-oracle/bin/java -Djava.util.logging.config.file=/opt/tomcat/am6/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Xms2048m -Xmx2048m -XX:MaxPermSize=512m -Xss256k -XX:+UseParallelGC -XX:MaxGCPauseMillis=1500 -XX:GCTimeRatio=9 -server -XX:+DisableExplicitGC -Djava.endorsed.dirs=/opt/tomcat/am6/endorsed -classpath /opt/tomcat/am6/bin/bootstrap.jar:/opt/tomcat/am6/bin/tomcat-juli.jar -Dcatalina.base=/opt/tomcat/am6 -Dcatalina.home=/opt/tomcat/am6 -Djava.io.tmpdir=/opt/tomcat/am6/temp org.apache.catalina.startup.Bootstrap start
    forgero+  2966  2193  0 11:14 pts/1    00:00:00 grep --color=auto tomcat
  2. End the process using the following command and the identified process ID, for example:
    $ kill -9 2240 
  3. Repeat step 2 if more than one process is running for the AM instance you are trying to shut down (this can happen if you started and stopped the instance again).

You can now restart the AM instance successfully.

Define CATALINA_PID environment variable

You can configure Tomcat to mitigate this issue in the future by defining the CATALINA_PID environment variable in the setenv.sh file (typically located in the /tomcat/bin/ directory). If this file doesn't exist, you should create it in the same directory as the catalina.sh file (also typically located in the /tomcat/bin/ directory). 

  1. End the process if it is still running using the steps above (identify process ID and use kill -9).
  2. Add the following line to the setenv.sh file:
    CATALINA_PID="$CATALINA_BASE/bin/catalina.pid"
  3. Restart the web container.

You can now shut down AM 6 instances by appending the shutdown command with -force, which issues a kill -9 command for the relevant process after 5 seconds if it has not shutdown cleanly. For example:

$ ./shutdown.sh -force

See Also

Best practice for upgrading to AM 6.x

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13008 (Occasional shutdown error for AM)


AM/OpenAM (All versions) fail to start due to SEVERE: ContainerBase.addChild: start: error on Apache Tomcat

The purpose of this article is to provide assistance if AM/OpenAM fail to start due to "SEVERE: ContainerBase.addChild: start: org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[/openam]]" error on Apache Tomcat™. Caused by: java.lang.NullPointerException at org.apache.tomcat.util.IntrospectionUtils.getProperty(IntrospectionUtils.java:425).

Symptoms

An error similar to the following is shown in catalina.out when AM/OpenAM fails to start:

Oct 12, 2015 4:19:21 PM org.apache.catalina.core.ContainerBase addChildInternal
SEVERE: ContainerBase.addChild: start:
org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[/openam]]
   at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:154)
   at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:901)
   at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:877)
   at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:632)
   at org.apache.catalina.startup.HostConfig.deployWAR(HostConfig.java:1073)
   at org.apache.catalina.startup.HostConfig$DeployWar.run(HostConfig.java:1857)
   at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:471)
   at java.util.concurrent.FutureTask.run(FutureTask.java:262)
   at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145)
   at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)
   at java.lang.Thread.run(Thread.java:744)
Caused by: java.lang.NullPointerException
   at org.apache.tomcat.util.IntrospectionUtils.getProperty(IntrospectionUtils.java:425)
   at org.apache.catalina.connector.Connector.getProperty(Connector.java:271)
   at org.apache.catalina.connector.Connector.getAttribute(Connector.java:290)
   at org.apache.catalina.core.ApplicationContext.populateSessionTrackingModes(ApplicationContext.java:1210)
   at org.apache.catalina.core.ApplicationContext.<init>(ApplicationContext.java:124)
   at org.apache.catalina.core.StandardContext.getServletContext(StandardContext.java:2367)
   at org.apache.catalina.core.StandardContext.postWorkDirectory(StandardContext.java:6309)
   at org.apache.catalina.core.StandardContext.startInternal(StandardContext.java:5284)
   at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:150)
   ... 10 more
Oct 12, 2015 4:19:21 PM org.apache.catalina.startup.HostConfig deployWAR
SEVERE: Error deploying web application archive /opt/apps/openam/webapps/openam.war
java.lang.IllegalStateException: ContainerBase.addChild: start: org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[/openam]]
   at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:904)
   at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:877)
   at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:632)
   at org.apache.catalina.startup.HostConfig.deployWAR(HostConfig.java:1073)
   at org.apache.catalina.startup.HostConfig$DeployWar.run(HostConfig.java:1857)
   at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:471)
   at java.util.concurrent.FutureTask.run(FutureTask.java:262)
   at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145)
   at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)
   at java.lang.Thread.run(Thread.java:744)

Recent Changes

Made configuration changes to Tomcat, for example, updated the server.xml file.

Causes

This issue is not caused by AM/OpenAM, it is related to the configuration of Tomcat. If Tomcat is misconfigured, then AM/OpenAM will fail to start. 

Solution

This issue can be resolved by fixing the misconfiguration errors in Tomcat. Typically these errors suggest the misconfiguration relates to SSL or port configuration, but not always. You should check the following files for issues and fix any you find:

  • server.xml - in particular, focus on any recent changes you have made to the configuration.
  • web.xml - in particular, check the following elements:
    • <servlet-mapping> details - ensure all the mapped servlets exist. If a servlet does not exist, you can comment out the mapping.
    • <servlet-class> details - ensure all the servlet classes specified exist in a jar file in the path/to/tomcat/webapps/openam/WEB-INF/lib directory. If they don't, locate the missing jar file that contains the servlet class and add it to the WEB-INF/lib directory.

Once you have resolved your Tomcat misconfiguration issues, AM/OpenAM will start as normal.

See Also

Memory leak messages when shutting down Apache Tomcat web container running AM/OpenAM (All versions)

Installation Guide › Preparing for Installation › Preparing Apache Tomcat

Related Training

N/A

Related Issue Tracker IDs

N/A


Memory leak messages when shutting down Apache Tomcat web container running AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you see memory leak messages when shutting down the Apache Tomcat™ web container running AM/OpenAM. You will see messages such as "WARNING: The web application [sso] appears to have started a thread named [ ] but has failed to stop it. This is very likely to create a memory leak." and "SEVERE: The web application [sso] created a ThreadLocal with key of type [ ] (value [ ]) and a value of type [ ] (value [0]) but failed to remove it when the web application was stopped. Threads are going to be renewed over time to try and avoid a probable memory leak."

Symptoms

Messages similar to the following are shown in catalina.out when shutting down the Tomcat web container:

15-Mar-2016 18:19:43 PM org.apache.catalina.loader.WebappClassLoaderBase clearReferencesThreads
WARNING: The web application [sso] appears to have started a thread named [com.google.inject.internal.util.$Finalizer] but has failed to stop it. This is very likely to create a memory leak. Stack trace of thread:
 java.lang.Object.wait(Native Method)
 java.lang.ref.ReferenceQueue.remove(Unknown Source)
 java.lang.ref.ReferenceQueue.remove(Unknown Source)
 com.google.inject.internal.util.$Finalizer.run(Finalizer.java:114)
...
15-Mar-2016 18:19:43 PM org.apache.catalina.loader.WebappClassLoaderBase checkThreadLocalMapForLeaks
SEVERE: The web application [sso] created a ThreadLocal with key of type [com.sun.identity.common.LDAPConnectionPool$ThreadLocalConnection$2] (value [com.sun.identity.common.LDAPConnectionPool$ThreadLocalConnection$2@23233749]) and a value of type [java.lang.Integer] (value [0]) but failed to remove it when the web application was stopped. Threads are going to be renewed over time to try and avoid a probable memory leak.
...

Or:

15-Mar-2016 18:19:43.888 WARNING [localhost-startStop-2] org.apache.catalina.loader.WebappClassLoaderBase.clearReferencesThreads The web application [openam] appears to have started a thread named [Time Thread] but has failed to stop it. This is very likely to create a memory leak. Stack trace of thread:
 sun.misc.Unsafe.park(Native Method)
 java.util.concurrent.locks.LockSupport.parkNanos(LockSupport.java:215)
 java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject.awaitNanos(AbstractQueuedSynchronizer.java:2078)
...
15-Mar-2016 18:19:44.914 INFO [Directory Server Shutdown Hook] org.apache.catalina.loader.WebappClassLoaderBase.checkStateForResourceLoading Illegal access: this web application instance has been stopped already. Could not load [org.opends.server.extensions.JMXAlertHandler]. The following stack trace is thrown for debugging purposes as well as to attempt to terminate the thread which caused the illegal access.
 java.lang.IllegalStateException: Illegal access: this web application instance has been stopped already. Could not load [org.opends.server.extensions.JMXAlertHandler]. The following stack trace is thrown for debugging purposes as well as to attempt to terminate the thread which caused the illegal access.
...
Note

These messages can also occur if you repeatedly redeploy the AM/OpenAM war whilst Tomcat is running; AM/OpenAM is not intended to be un-deployed/deployed without a container restart.

Recent Changes

N/A

Causes

You can find more information on these memory leak messages at Tomcat Wiki - MemoryLeakProtection.

Solution

These messages can be safely ignored providing Tomcat is not prevented from shutting down. As they occur during shutdown, any memory leaks will cease once the process has ended.

See Also

AM/OpenAM (All versions) fail to start due to SEVERE: ContainerBase.addChild: start: error on Apache Tomcat

Tomcat Wiki - MemoryLeakProtection

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3133 (SEVERE: The web application [/openam] created a ThreadLocal...but failed to remove it)


Login Page


Default Configuration page shown instead of Login page in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if the Default Configuration page is shown instead of the Login page when attempting to log into AM/OpenAM. The Default Configuration page is normally displayed when installing AM/OpenAM.

Symptoms

When logging into AM/OpenAM using the usual login URL, the Default Configuration page is displayed instead of the Login page, even though AM/OpenAM has already been configured and previously functioned correctly.

The configuration appears to be lost.

Recent Changes

Restarted AM/OpenAM.

Causes

AM/OpenAM attempts to find its configuration when bootstrapping by looking at the path specified in the bootstrap locator file (located in the $HOME/.openamcfg/ directory of the user running the web application container).

This issue occurs when AM/OpenAM fails to find the configuration when bootstrapping, which can be caused by one of the following:

  • Configuration store not running.
  • Missing $HOME/.openamcfg/ directory; the file used to bootstrap (the bootstrap locator file) is located in this directory.
  • Redeploying openam.war to a different location; the bootstrap locator file is named according to where AM/OpenAM is deployed.
  • Starting AM/OpenAM as a different user to the one who initially configured it; the $HOME/.openamcfg/ directory is user specific.

Solution

The solution depends on the cause; you should check the following to establish the cause and then rectify accordingly:

Configuration store

  • Check that the configuration store is up and running, and that AM/OpenAM can successfully communicate with it: 
    • You can check this by running the OpenDJ status command (located in /path/to/ds/bin) or if using the embedded Configuration store (located in the $HOME/[am_instance]/opends/bin directory). The server status returned to you should be: Server Run Status: Started.
    • You can also send a request to the isAlive.jsp endpoint. If AM/OpenAM is running and the directory server used for the configuration store is not reachable, the page will return Server is DOWN as described in How do I check if AM/OpenAM (All versions) is up and running?

$HOME/.openamcfg/ directory

  • Check the $HOME/.openamcfg/ directory exists for the process owner and contains the bootstrap locator file (AMConfig). This is a file called AMConfig_[path_to_openam], for example, AMConfig_opt_tomcat_webapps_openam if /opt/tomcat/webapps/openam is the deployment path of AM/OpenAM. 

Deployment path

Process owner

  • Check the process owner; if AM/OpenAM is installed on a Linux® or Unix® system and is deployed on an Apache Tomcat™ web container, you can check the process owner using the following command:
    ps -ef |grep tomcat
    
    The process owner must be same as the user who restarted AM/OpenAM.

Configuration directory

  • Check that the AMConfig file contains the path to a valid configuration directory, which is $HOME/openam by default.
  • Check the configuration directory referenced in the AMConfig file contains a file called bootstrap or boot.json (depending on your version of AM/OpenAM); check the contents of the bootstrap or boot.json file to ensure the configuration store details it contains are correct. Example configuration store details look like this:
    • boot.json (AM 5 and later):
        "configStoreList" : [ {
          "baseDN" : "dc=openam,dc=forgerock,dc=org",
          "dirManagerDN" : "cn=Directory Manager",
          "ldapHost" : "localhost",
          "ldapPort" : 50389,
          "ldapProtocol" : "ldap"
        } ]
      
      
    • bootstrap (Pre-AM 5):
      ldap://localhost:50389/http%3A%2F%2Fhost1.example.com%3A8080%2Fopenam?user=cn%3Ddsameuser%2Cou%3DDSAME+Users%2Cdc%3Dopenam%2Cdc%3Dforgerock%2Cdc%3Dorg&pwd=AQIC5wM2LY4z9R5f8R&dsbasedn=dc%3Dopenam%2Cdc%3Dforgerock%2Cdc%3Dorg&dsmgr=cn%3DDirectory+Manager&dspwd=AQIC5wM2LY4z9R5f8R&ver=1.0
      

See Also

How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions) ?

AM 5 Installation Guide › Preparing for Installation › Preparing for JBoss and WildFly

OpenAM 13 Installation Guide › Preparing For Installation › Preparing OpenAM for JBoss and WildFly

OpenAM 12 Installation Guide › Preparing For Installation › Preparing OpenAM & JBoss AS 7 / EAP 6

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


Attempting to access AM/OpenAM (All versions) fails with ConfigurationException: Configuration store is not available

The purpose of this article is to provide assistance if accessing AM/OpenAM results in an HTTP Status 500 - "ConfigurationException: Configuration store is not available".

Symptoms

The following message is shown in the browser when you try to access the console:

HTTP Status 500 - AMSetupFilter.doFilter

type Exception report

message AMSetupFilter.doFilter

description The server encountered an internal error that prevented it from fulfilling this request.

exception 

javax.servlet.ServletException: AMSetupFilter.doFilter
	com.sun.identity.setup.AMSetupFilter.doFilter(AMSetupFilter.java:136)

root cause

com.sun.identity.common.configuration.ConfigurationException: Configuration store is not available.
	com.sun.identity.setup.AMSetupFilter.doFilter(AMSetupFilter.java:109)

note The full stack trace of the root cause is available in the Apache Tomcat/7.0.35 logs.

The following error is shown in the web application container log (for example, catalina.out for Apache Tomcat™):

com.sun.identity.common.configuration.ConfigurationException: Configuration store is not available.
	at com.sun.identity.setup.AMSetupFilter.doFilter(AMSetupFilter.java:109)
	at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:243)
	at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:210)
	at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:222)
	at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:123)
	at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:472)
	at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:171)
	at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:99)
	at org.apache.catalina.valves.AccessLogValve.invoke(AccessLogValve.java:931)
	at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:118)
	at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:407)
	at org.apache.coyote.http11.AbstractHttp11Processor.process(AbstractHttp11Processor.java:1004)
	at org.apache.coyote.AbstractProtocol$AbstractConnectionHandler.process(AbstractProtocol.java:589)
	at org.apache.tomcat.util.net.JIoEndpoint$SocketProcessor.run(JIoEndpoint.java:310)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)
	at java.lang.Thread.run(Thread.java:745)

Recent Changes

Restarted AM/OpenAM.

Made configuration changes.

Installed or upgraded to a different version of AM/OpenAM.

Changed the cn=Directory Manager password on the directory server but not in AM/OpenAM. 

Made environmental changes, such as networking, firewall or operating system changes.

Deleted a previously configured server and then re-added it to a site.

Changed debug level to message in OpenAM 13.0.

Causes

This error indicates that AM/OpenAM is unable to communicate with its configuration store. This can occur for a number of reasons, including:

  • The configuration store is not running or AM/OpenAM cannot access the configuration store due to a network failure, or a network issue such as a firewall preventing access. This can also happen in OpenAM 13.0 where the EmbeddedDJ debug log becomes too full and prevents OpenAM from writing to the configuration store. This is a known issue, which is fixed in OpenAM 13.5: OPENAM-8696 (OpenAM 13 EmbeddedDJ log spam )  
  • The bootstrap file is empty (0 bytes) or corrupt. The bootstrap file can be empty if the disk was out of space when the AM/OpenAM server was started.
  • The $HOME/.openamcfg/ directory is missing for the current user; the file used to bootstrap (the bootstrap locator file) is located in this directory for the process owner. If you're not the process owner, this directory will not exist.
  • The cn=Directory Manager password has been changed on the directory server but not in AM/OpenAM. AM/OpenAM uses this password to connect to the configuration store.
  • The server that was deleted and re-added to a site has lost all its configuration and has been given the default server settings again.
  • The admin-backend.ldif file (located in the $HOME/[am_instance]/ opends/config directory) is empty (only applicable if you are running a pre-2.6.3 version of OpenDJ). The most common cause for this is the server running out of disk space.

Solution

The solution depends on the cause; you should check the following to establish the cause and then rectify accordingly:

Configuration store

  • Check that the configuration store is up and running, and that AM/OpenAM can successfully communicate with it: 
    • You can check this by running the OpenDJ status command (located in /path/to/ds/bin) or if using the embedded Configuration store (located in the $HOME/[am_instance]/opends/bin directory). The server status returned to you should be: Server Run Status: Started.
    • You can also send a request to the isAlive.jsp endpoint. If AM/OpenAM is running and the directory server used for the configuration store is not reachable, the page will return Server is DOWN as described in How do I check if AM/OpenAM (All versions) is up and running?

If you are using OpenAM 13.0 and have a large EmbeddedDJ debug log, you should clear the log file to allow OpenAM to write to the configuration store again.

Bootstrap file

$HOME/.openamcfg/ directory

  • Check the $HOME/.openamcfg/ directory exists for the process owner and contains the bootstrap locator file (AMConfig). This is a file called AMConfig_[path_to_openam], for example, AMConfig_opt_tomcat_webapps_openam if /opt/tomcat/webapps/openam is the deployment path of AM/OpenAM. 

Process owner

  • Check the process owner; if AM/OpenAM is installed on a Linux® or Unix® system and is deployed on an Apache Tomcat™ web container, you can check the process owner using the following command:
    ps -ef |grep tomcat
    
    The process owner must be same as the user who restarted AM/OpenAM.

Configuration directory

  • Check that the AMConfig file contains the path to a valid configuration directory, which is $HOME/openam by default.
  • Check the configuration directory referenced in the AMConfig file contains a file called bootstrap; check the contents of the bootstrap file to ensure the configuration store details it contains are correct. Example configuration store details look like this:
    ldap://localhost:50389/http%3A%2F%2Fhost1.example.com%3A8080%2Fopenam?user=cn%3Ddsameuser%2Cou%3DDSAME+Users%2Cdc%3Dopenam%2Cdc%3Dforgerock%2Cdc%3Dorg&pwd=AQIC5wM2LY4z9R5f8R&dsbasedn=dc%3Dopenam%2Cdc%3Dforgerock%2Cdc%3Dorg&dsmgr=cn%3DDirectory+Manager&dspwd=AQIC5wM2LY4z9R5f8R&ver=1.0
    

cn=Directory Manager password

Revert the cn=Directory Manager password to its old value on the directory server to allow access to AM/OpenAM again.

You can then update it as follows:

  1. Update the directory bind (configuration store) password on all AM/OpenAM servers using the console (see How do I change the password for the configuration store in AM/OpenAM (All versions)? for details on doing this via ssoadm):
    • AM / OpenAM 13.5 console: navigate to: Deployment > Servers > [Server Name] > Directory Configuration > Bind Password and enter your new amadmin password.​
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > [Server Name] > Directory Configuration > Bind Password and enter your new password.​
    This configuration is server specific and must be changed on all servers in your site.
  2. Update the password for cn=Directory Manager on all directory servers to match your new password. This configuration is server specific and must be changed on all directory servers. If you use OpenDJ, refer to  Administration Guide › Troubleshooting Server Problems › Resetting Administrator Passwords for further information. If you use the embedded DS/OpenDJ, you must restart the web application container in which AM/OpenAM runs to restart the DS/OpenDJ server.

Server configuration

Note

When you reconfigure the server, you might need to change the inheritance settings to prevent default server settings being applied again. In AM / OpenAM 13.5, you can change these settings within the server configuration; a closed lock means the property is inherited from the defaults. To change an inherited value, click the lock to unlock it; you can now enter a server specific value. In OpenAM 13.0 and earlier,  you must navigate to Configuration > Servers and Sites > [Server Name] > Inheritance Settings and deselect any properties that you want to override; you can now enter server specific values for these properties when updating the server configuration.

The server that was deleted and re-added to a site needs to be reconfigured as follows:

  1. Stop replication on this server if it is enabled:
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication unconfigure --unconfigureAll --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
    • Pre-DS 5 (pre-AM 5):
      $ ./dsreplication disable --disableAll --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt
  2. Reconfigure the server from a working server:
    • AM / OpenAM 13.5 console: navigate to: Deployment > Servers > [Server Name]
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > [Server Name]
  3. In particular, you should check/change the following properties:
    • General > System: Base installation directory.
    • Security > Encryption: Password Encryption Key and the Authentication Service Share Secret.
    • Directory Configuration: all options.
    • Advanced: all options.
  4. Re-enable replication on this server if needed:
    • DS 5 and later (AM 5 and later):
      $ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds2.example.com --port1 4444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 8989 --host2 ds1.example.com --port2 4444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 8989 --trustAll --no-prompt
    • Pre-DS 5 (pre-AM 5):
      $ ./dsreplication enable --adminUID admin --adminPassword password --baseDN dc=example,dc=com --host1 ds2.example.com --port1 4444 --bindDN1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 8989 --host2 ds1.example.com --port2 4444 --bindDN2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 8989 --trustAll --no-prompt
  5. Restart the web application container in which AM/OpenAM runs.

Admin-backend.ldif file

See Also

How do I re-create a bootstrap file for OpenAM 12.x and 13.x if the bootstrap file has become corrupt?

Default Configuration page shown instead of Login page in AM/OpenAM (All versions)

How do I change the amadmin password in AM/OpenAM (All versions)?

How do I change the password for the configuration store in AM/OpenAM (All versions)?

Reference › Configuration Reference › Configuring Servers

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8696 (OpenAM 13 EmbeddedDJ log spam )


Login page in AM/OpenAM (All versions) hangs on Loading when CORS is enabled

The purpose of this article is to provide assistance if you experience issues where the AM/OpenAM login page displays a "Unknown Error - Please contact your Administrator" message and hangs on Loading ... when Cross-origin resource sharing (CORS) is enabled and you are using the Chrome™ browser.

Symptoms

The following error is shown when accessing the login page using a URL such as: http://host1.example.com:18080/openam/XUI/#login/

Unknown Error - Please contact your Administrator

When the message disappears, AM/OpenAM hangs and displays a Loading... message.

Variants of this issue can be seen when accessing AM/OpenAM over SSL (for example, using a URL such as: https://host1.example.com:18443/openam/XUI/#login/) or through a load balancer.

Disabling CORS allows access.

This only affects the Chrome browser; using Firefox® works.

Recent Changes

Enabled the CORS filter.

Added a load balancer in front of AM/OpenAM when CORS was already enabled and working.

Enabled SSL on AM/OpenAM when CORS was already enabled and working.

Added a realm DNS alias when CORS was already enabled and working.

Causes

Some browsers, such as Chrome, send the Origin Header in the request, even in Same-Origin scenarios.

Solution

This issue can be resolved by adapting the CORS filter configuration to allow all possible server origins. You may have to include the hostname with both http and https protocols, the server name and the load balancer FQDN, and the port number if it is not the default. See Installation Guide › Preparing for Installation › Enabling CORS Support for general instructions on setting up a CORS filter:

  • If you need to access more than one hostname, for example, you access AM/OpenAM through a load balancer and also have direct access to the AM/OpenAM server, you should remove or comment out the Expected Hostname section in the CORS filter as this only allows one hostname:
  1. <!--init-param>
        <description>
            Expected Hostname (Optional):
            The name of the host expected in the request Host header.
        </description>
        <param-name>expectedHostname</param-name>
        <param-value>host1.example.com:18080</param-value>
    </init-param-->
    
    An RFE exists to allow a list of hostnames to be specified instead: OPENAM-9890 (Allow list in expected Hostname section of CORS Filter).
  • Add each URL that is allowed to the Accepted Origins section. Include the protocol and the port if it is not the default. For example, if you want to allow access to https://lb.example.com:443/openam and http://host1.example.com:18080/openam, as well as a real cross-origin URL such as https://other.origin.example.com:443/myApp, the Accepted Origins section in the CORS filter on openam1 would look like this:
     <init-param>
         <description>
             Accepted Origins (Required):
             A comma separated list of origins from which to accept CORS requests.
         </description>
         <param-name>origins</param-name>
         <param-value>
          http://host1.example.com:18080,https://lb.example.com,https://other.origin.example.com    
         </param-value>
    </init-param>
    
Note

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

See How do I troubleshoot issues with the CORS filter in AM/OpenAM (All versions)? if these changes do not resolve your issues.

See Also

Installation Guide › Preparing for Installation › Enabling CORS Support

How do I troubleshoot issues with the CORS filter in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9890 (Allow list in expected Hostname section of CORS Filter)


Multiple mappings found for organization identifier error when logging into AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive a 500 Internal Server Error "Multiple mappings found for organization identifier" error when attempting to log into AM/OpenAM using the XUI interface. If you are using OpenAM 12.0.0 or 12.0.1, you will also see a blank page with "Loading ..." when this happens.

Symptoms

The following error is shown in the web application container log (for example, catalina.out for Apache Tomcat™):

Could not get orgName
Message:Multiple mappings found for organization identifier: [realm/DNS alias]

If you record the HTTP flow in your browser's developer tool when trying to access the login page, you will see the following server response for the request to .../json/serverinfo/:

{"code":500,"reason":"Internal Server Error","message":"Multiple mappings found for organization identifier: [realm/DNS alias]"}

OpenAM 12.0.0 and 12.0.1

A blank page with "Loading ..." is shown when you attempt to authenticate to OpenAM (this affects all users including the administrator). This relates to a known issue (which is fixed in 12.0.2): OPENAM-6293 (XUI freezes at startup when serverinfo service call fails); this is specific to the 500 response but not necessarily the Multiple mappings error. You should check your browser's developer tools and/or web application container log to verify it's the Multiple mappings error.

Recent Changes

Upgraded to, or installed AM 5 or later.

Upgraded to, or installed OpenAM 12.0.0 or later, and using the XUI interface.

Configured realm/DNS aliases for one or more realms.

Causes

Realm/DNS aliases are incorrectly configured, for example, you have the same realm/DNS alias configured in more than one realm. A realm/DNS alias should be unique.

Solution

This issue can be resolved by configuring your realm/DNS aliases correctly and removing any duplicate realm/DNS aliases:

  • If you already have an administrator session running, you can temporarily amend the login URL to include the top level realm (&realm=/) in order to log into the console. You can then modify your realm/DNS aliases as needed and remove any duplicates. See How do I set up Realm DNS Aliases in AM/OpenAM (All versions)? or How do I set up Realm DNS Aliases in AM/OpenAM (All versions) when CDSSO is configured? for further information.
  • If you do not have an administrator session running, you can use the following ssoadm command to delete one of the duplicate realm/DNS aliases:
    $ ./ssoadm delete-realm-attr -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] -a sunOrganizationAliases
    
    replacing [realmname], [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 set up Realm DNS Aliases in AM/OpenAM (All versions)?

How do I set up Realm DNS Aliases in AM/OpenAM (All versions) when CDSSO is configured?

Setup and Maintenance Guide › Setting Up Realms

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-6293 (XUI freezes at startup when serverinfo service call fails)

OPENAM-6000 (Accessing XUI through a FQDN that is resolvable but not mapped throws an internal server error)

OPENAM-5999 (XUI hangs with "Loading ..." when receiving a HTTP 500 response)


Login page does not load when using authentication trees with custom or Marketplace nodes in AM 6.5.x

The purpose of this article is to provide assistance if the login page does not load when using authentication trees in AM 6.5.x and the tree editor in the console is missing nodes. These issues occur when you have custom or Marketplace nodes. You will see "Unsupported node type" errors when this happens.

Symptoms

Note

The Unsupported node type referenced in the following errors does not indicate the custom or Marketplace node causing the issues; instead it refers to one of the nodes in the tree you are accessing.

Login page

The browser shows a Loading... message but nothing else happens.

Errors similar to the following are shown when this happens:  

  • CoreSystem debug log:
    frRest:12/19/2018 02:34:05:080 pm GMT: Thread[http-nio-48080-exec-5,5,main]: TransactionId[8447c05f-4bc1-4d38-bae0-ad6b3cca7b44-69807]
    ERROR: Could not invoke method:
    java.lang.reflect.InvocationTargetException
       at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
       at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
       at java.base/java.lang.reflect.Method.invoke(Method.java:566)
       at org.forgerock.openam.http.annotations.AnnotatedMethod.invoke(AnnotatedMethod.java:76)
       at org.forgerock.openam.http.annotations.Endpoints$1.handle(Endpoints.java:64)
       at org.forgerock.http.routing.Router.handle(Router.java:100)
       at org.forgerock.openam.audit.AbstractHttpAccessAuditFilter.filter(AbstractHttpAccessAuditFilter.java:59)
    Caused by: java.lang.IllegalArgumentException: Unsupported node type ZeroPageLoginNode
       at org.forgerock.openam.auth.trees.engine.NodeFactory.createNode(NodeFactory.java:122)
       at org.forgerock.openam.auth.trees.engine.AuthTreeExecutor.process(AuthTreeExecutor.java:97)
       at org.forgerock.openam.core.rest.authn.trees.AuthTrees.processTree(AuthTrees.java:389)
       at org.forgerock.openam.core.rest.authn.trees.AuthTrees.evaluateTreeAndProcessResult(AuthTrees.java:245)
       at org.forgerock.openam.core.rest.authn.trees.AuthTrees.invokeTree(AuthTrees.java:237)
       at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:203)
       at org.forgerock.openam.core.rest.authn.http.AuthenticationServiceV1.authenticate(AuthenticationServiceV1.java:164)
       ... 89 more
    
  • Authentication debug log:
    amAuth:12/19/2018 02:34:06:437 pm GMT: Thread[http-nio-48080-exec-7,5,main]: TransactionId[8447c05f-4bc1-4d38-bae0-ad6b3cca7b44-69841]
    ERROR: Unsupported node type ZeroPageLoginNode
    

Console

You will notice one or more of the following symptoms in the AM console when you select a tree to edit:

  • The authentication tree designer is completely empty; it does not include any nodes nor the Start and Failure entry/exit points. An empty pink warning message box briefly displays upon selecting the tree.
  • The Components panel is missing all or some of the available nodes.
  • The required node appears in the Components panel but does not have any outcomes when dragged onto the authentication tree designer. An empty pink warning message box briefly displays upon moving the node.

An error similar to the following may be shown in the CoreSystem debug log when this happens:

frRest:12/19/2018 10:19:59:093 am GMT: Thread[http-nio-48080-exec-7,5,main]: TransactionId[8447c05f-4bc1-4d38-bae0-ad6b3cca7b44-1420]
ERROR: A runtime exception occurred during the CREST request handling
java.lang.IllegalStateException: Exception from invocation expected to be handled by promise
   at org.forgerock.json.resource.AnnotatedMethod.invoke(AnnotatedMethod.java:100)
   at org.forgerock.json.resource.AnnotatedMethod.invoke(AnnotatedMethod.java:65)
   at org.forgerock.json.resource.AnnotationCollectionInstance.handleRead(AnnotationCollectionInstance.java:51)
   at org.forgerock.json.resource.FilterChain$Cursor.handleRead(FilterChain.java:105)
   at org.forgerock.json.resource.Resources$CollectionInstanceIdContextFilter.filterRead(Resources.java:528)
...
Caused by: java.lang.reflect.InvocationTargetException
   at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
   at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
   at java.base/java.lang.reflect.Method.invoke(Method.java:566)
   at org.forgerock.json.resource.AnnotatedMethod.invoke(AnnotatedMethod.java:96)
   ... 141 more
Caused by: java.lang.IllegalArgumentException: Unsupported node type UsernameCollectorNode
   at org.forgerock.openam.auth.trees.engine.NodeFactory.getOutcomeProvider(NodeFactory.java:173)
   at org.forgerock.openam.auth.trees.engine.NodeFactory.getNodeOutcomes(NodeFactory.java:199)
   at org.forgerock.openam.core.rest.sms.AuthTreesCollectionProvider.read(AuthTreesCollectionProvider.java:296)
   ... 146 more

Recent Changes

Upgraded to, or installed AM 6.5.x.

Installed a custom or Marketplace node. For example, the Have I Been Pwned Authentication Marketplace node. 

Causes

The dependency on forgerock-guava was removed in AM 6.5 and instead these libraries are retrieved directly from Google Guava. For example, all the node .java files have been updated as follows:

import com.google.common.collect.ImmutableList;
//import org.forgerock.guava.common.collect.ImmutableList;

The custom or Marketplace node fails because it uses one of the 'org.forgerock.guava' classes; these classes have been removed from the classpath since they are no longer supported.

Solution

This issue can be resolved either by updating the node so that it does not use any org.forgerock.guava classes or by adding a dependency on Guava.

Remove org.forgerock.guava classes

You can either use simple replacements from the standard JDK collections classes or one of the following methods:

  • Collections.singletonMap
  • Collections.singletonList
  • Arrays.asList

Add a dependency

If you want to continue using these org.forgerock.guava classes, you should add a dependency on Guava and bundle it properly per the instructions in Authentication Node Development Guide › The Maven Project for an Authentication Node.

Note

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

See Also

Authentication trees in AM

Authentication Node Development Guide

Guava: Google Core Libraries for Java

Using the BackStage Marketplace

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14092 (Custom node can prevent all default nodes appearing in admin view)


Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

The purpose of this article is to provide assistance if the login page does not load or ssoadm fails in AM running on Apache Tomcat™ 8.5 or 9. The following error is shown when this happens: "An invalid domain [.example.com] was specified for this cookie".

Symptoms

Note

OpenAM 12.x and 13.x support Tomcat 8.0.x, but not 8.5.x; Tomcat 8.5.x is supported in AM 5 and later; Tomcat 9 is supported in AM 6 and later.

Login page

The browser shows a Loading... message; no errors are logged when trying to accessing the login page in AM. 

ssoadm

The following response is shown when ssoadm fails:

Logging configuration class "com.sun.identity.log.s1is.LogConfigReader" failed
com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction:  FATAL ERROR: Cannot obtain Application SSO token.

 The corresponding error is shown in the CoreSystem log when this happens:

ERROR: Exception during LoginIndex
java.lang.IllegalArgumentException: An invalid domain [.example.com] was specified for this cookie
        at org.apache.tomcat.util.http.Rfc6265CookieProcessor.validateDomain(Rfc6265CookieProcessor.java:183)
        at org.apache.tomcat.util.http.Rfc6265CookieProcessor.generateHeader(Rfc6265CookieProcessor.java:125)
        at org.apache.catalina.connector.Response.generateCookieString(Response.java:989)
        at org.apache.catalina.connector.Response.addCookie(Response.java:937)

Recent Changes

Upgraded Tomcat to 8.5 or 9.

Installed AM 5 or later in a new environment that is running Tomcat 8.5 or 9.

Causes

Tomcat enforces stricter checking for valid cookie domain values per RFC 1034 and RFC 6265. In Tomcat 8.0.x, a leading dot was required for cookie domains, whereas this is no longer permitted in 8.5 and later.

Solution

This issue can be resolved by correcting your cookie domain name as follows:

  1. Revert Tomcat to use the legacy cookie processor in order to get your system back up and running. Add the following line to the context.xml file (you should create this file in the /path/to/tomcat/webapps/openam/META-INF directory if it does not already exist):
    <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />
    
    A default context.xml file exists in the /path/to/tomcat/conf directory; this applies to all web applications, but it is preferable to create separate contexts for individual web applications as needed. See Apache Tomcat 8.5 Configuration Reference - Defining a context for further information on contexts.
  2. Modify the cookie domain name to remove the leading dot. You can remove the leading dot from your cookie domain name (for example, example.com rather than .example.com) using either the console or ssoadm:
    • Console: navigate to: Configure > Global Services > Platform > Cookie Domains and modify the cookie domain.
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s iPlanetAMPlatformService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-platform-cookie-domains=["domainname"]
      
      replacing [adminID], [passwordfile] and ["domainname"] with appropriate values.
  3. Reinstate the default cookie processor in Tomcat by removing the line you added in step 1.

See Also

Apache Tomcat 8.5 Configuration Reference - The Cookie Processor Component

Apache Tomcat 8.5 Configuration Reference - Defining a context

FAQ: Cookies in AM/OpenAM

AM/OpenAM (All versions) fail to start due to SEVERE: ContainerBase.addChild: start: error on Apache Tomcat

ssoadm fails in AM/OpenAM (All versions) with FATAL ERROR: Cannot obtain Application SSO token

OpenAM 13.5 Release Notes › OpenAM Web Application Container Requirements

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8668 (Fresh install of OpenAM doesn't load the login page on some Tomcat versions)

OPENAM-1983 (Configuration fail with second level FQDN like "example.com")


XUI Login URL with goto parameter causes redirect loop or prevents OpenAM 12.x and 13.x login page loading

The purpose of this article is to provide assistance if you encounter a redirect loop between OpenAM 12.x and 13.x and Web Policy Agents when using the XUI Login URL with a goto parameter. Alternatively, you may notice that the OpenAM login page gets stuck on the Loading message instead of redirecting.

Symptoms

Upon authenticating, the user is redirected back to the protected resource and then back to the OpenAM login page for authentication, thereby creating a redirect loop. This does not happen if you use the Chrome™ browser; you just get redirected back to the protected resource without an error.

The browser shows a Loading... message and the URL is similar to the following where there is a ? between the login URL and the goto parameter:

http://openam.example.com:8080/openam/XUI/#login/&realm=employees?goto=http%3A%2F%2Fagent.test.com%2F

Recent Changes

Enabled XUI.

Upgraded to OpenAM 12.0.0 or later, which uses the XUI by default.

Changed the default OpenAM Login URL from /openam/UI/Login to the XUI equivalent: /openam/XUI/#login

Configured the OpenAM Conditional Login URL.

Causes

The policy agent appends the OpenAM Login URL or the OpenAM Conditional Login URL with ?goto= instead of &goto= which is not compatible with the XUI login URL. Instead of redirecting as expected to the protected resource after authentication, the goto parameter is treated as the realm parameter for login. Since this parameter cannot be resolved as a realm, the login page fails to load resulting in the redirect loop.

Solution

This issue can be resolved by updating the OpenAM Login URL or OpenAM Conditional Login URL as follows:

  • All versions of OpenAM: Revert to the classic UI format (which redirects users to /openam/XUI/#login/&goto= when XUI is enabled). For example:
    http://openam.example.com:8080/openam/UI/Login
  • Pre-OpenAM 13 versions only: Append it with & which causes the agent to normalize with &goto= instead. For example:
    http://openam.example.com:8080/openam/XUI/#login/&
    http://openam.example.com:8080/openam/XUI/#login/&realm=employees&

You can change the the OpenAM Login URL using either the OpenAM console or ssoadm as detailed in How do I configure policy agents (Web 4.x and JEE 3.5.x) to authenticate users against a specific realm in AM 6, 5.x and OpenAM (All versions)?

The OpenAM Conditional Login URL is not yet maintainable in the OpenAM console. You can either add it as an advanced property in the OpenAM console or via ssoadm:

  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Custom Properties and add the com.forgerock.agents.conditional.login.url property. For example:
    com.forgerock.agents.conditional.login.url[0] = example.com|http://openam.example.com:8080/openam/XUI/#login/&
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Custom Properties and add the com.forgerock.agents.conditional.login.url property.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a "com.forgerock.agents.conditional.login.url[0]=[conditionalloginURL]"
    replacing [realmname], [agentname], [adminID], [passwordfile] and [conditionalloginURL] with appropriate values, where [conditionalloginURL] consists of the domain|login URL. For example:
    $ ./ssoadm update-agent -e / -b Web -u amadmin -f pwd.txt -a "com.forgerock.agents.conditional.login.url[0]=example.com|http://openam.example.com:8080/openam/XUI/#login/&"

See Web Policy Agent Guide › Reference › Configuring Access Management Services Properties for further information on the required format for this property.

See Also

How do I configure policy agents (Web 4.x and JEE 3.5.x) to authenticate users against a specific realm in AM 6, 5.x and OpenAM (All versions)?

Web Policy Agent Guide › Reference › Configuring Access Management Services Properties 

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5547 (Agent behaviour when appending goto= to LoginURLs is not compatible with XUI login URL)

OPENAM-8173 (OpenAM Login URL in the agent profile should support XUI login URL)


Configuration


Cannot recover key error shown when renewing expired certificates or changing the password for the keystore or truststore in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive the "java.security.UnrecoverableKeyException: Cannot recover key" error when renewing expired certificates or changing the password for the keystore or truststore. This can affect you if you are using AM/OpenAM for SAML2 federation or as an OAuth provider.

Symptoms

The symptoms vary slightly depending on whether you are using AM/OpenAM for SAML2 federation or as an OAuth provider.

SAML2 federation

The following error is shown in the Federation debug log if you are using AM/OpenAM for SAML2 federation:

libSAML:29/08/2016 03:27:14:805 PM GMT: Thread[http-bio-8443-exec-8,5,main]
ERROR: Cannot recover key
libSAML2:29/08/2016 03:27:14:805 PM GMT: Thread[http-bio-8443-exec-8,5,main]
ERROR: FMSigProvider.sign: Either input xml string or id value or private key is null.
libSAML2:29/08/2016 03:27:14:805 PM GMT: Thread[http-bio-8443-exec-8,5,main]
ERROR: IDPSSOFederate.doSSOFederate: Unable to do sso or federation.
com.sun.identity.saml2.common.SAML2Exception: Null input.
   at com.sun.identity.saml2.xmlsig.FMSigProvider.sign(FMSigProvider.java:138)
   at com.sun.identity.saml2.assertion.impl.AssertionImpl.sign(AssertionImpl.java:674)
   at com.sun.identity.saml2.profile.IDPSSOUtil.signAssertion(IDPSSOUtil.java:2433)
...
Caused by: java.security.UnrecoverableKeyException: Cannot recover key

An error similar to the following is also seen in the container log. For example, this error is shown in the catalina.out log for Apache Tomcat™:

SEVERE: Failed to initialize connector [Connector[HTTP/1.1-8443]]
org.apache.catalina.LifecycleException: Failed to initialize component [Connector[HTTP/1.1-8443]]
   at org.apache.catalina.util.LifecycleBase.init(LifecycleBase.java:106)
   at org.apache.catalina.core.StandardService.initInternal(StandardService.java:559)
   at org.apache.catalina.util.LifecycleBase.init(LifecycleBase.java:102)
   at org.apache.catalina.core.StandardServer.initInternal(StandardServer.java:781)
   at org.apache.catalina.util.LifecycleBase.init(LifecycleBase.java:102)
   at org.apache.catalina.startup.Catalina.load(Catalina.java:595)
   at org.apache.catalina.startup.Catalina.load(Catalina.java:620)
...
Caused by: java.security.UnrecoverableKeyException: Cannot recover key
   at sun.security.provider.KeyProtector.recover(KeyProtector.java:311)
   at sun.security.provider.JavaKeyStore.engineGetKey(JavaKeyStore.java:121)
   at sun.security.provider.JavaKeyStore$JKS.engineGetKey(JavaKeyStore.java:38)
   at java.security.KeyStore.getKey(KeyStore.java:763)

OAuth provider

The following error is shown in the OAuth2Provider debug log if you are using AM/OpenAM as an OAuth provider:

OAuth2Provider:29/08/2016 03:27:14:198 AM MDT: Thread[tomcat-http--16,5,main]: TransactionId[2d899296-1b0b-4ee0-9e23-f1261f659ba3-137]
14631:: 400 server_error : 
Internal Server Error (500) - The server encountered an unexpected condition which prevented it from fulfilling the request
    at org.restlet.resource.ServerResource.doHandle(ServerResource.java:539)
    at org.restlet.resource.ServerResource.get(ServerResource.java:742)
    at org.restlet.resource.ServerResource.doHandle(ServerResource.java:617)
    at org.restlet.resource.ServerResource.doNegotiatedHandle(ServerResource.java:678)
    at org.restlet.resource.ServerResource.doConditionalHandle(ServerResource.java:356)
    at org.restlet.resource.ServerResource.handle(ServerResource.java:1043)
...
Caused by: org.forgerock.json.jose.utils.KeystoreManagerException: java.security.UnrecoverableKeyException: Cannot recover key
    at org.forgerock.json.jose.utils.KeystoreManager.getPrivateKey(KeystoreManager.java:139)
    at org.forgerock.openam.utils.OpenAMSettingsImpl.getServerKeyPair(OpenAMSettingsImpl.java:181)
    at org.forgerock.openam.oauth2.OpenAMOAuth2ProviderSettings.getServerKeyPair(OpenAMOAuth2ProviderSettings.java:610)
    at org.forgerock.openam.oauth2.OpenAMTokenStore.createOpenIDToken(OpenAMTokenStore.java:253)
    at org.forgerock.openidconnect.IdTokenResponseTypeHandler.handle(IdTokenResponseTypeHandler.java:61)
    at org.forgerock.oauth2.core.AuthorizationTokenIssuer.issueTokens(AuthorizationTokenIssuer.java:105)
    at org.forgerock.oauth2.core.AuthorizationServiceImpl.authorize(AuthorizationServiceImpl.java:155)
    at org.forgerock.oauth2.restlet.AuthorizeResource.authorize(AuthorizeResource.java:95)
    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 org.restlet.resource.ServerResource.doHandle(ServerResource.java:523)
    ... 76 more
Caused by: java.security.UnrecoverableKeyException: Cannot recover key
    at sun.security.provider.KeyProtector.recover(KeyProtector.java:328)
    at sun.security.provider.JavaKeyStore.engineGetKey(JavaKeyStore.java:138)
    at sun.security.provider.JavaKeyStore$JKS.engineGetKey(JavaKeyStore.java:55)
    at java.security.KeyStore.getKey(KeyStore.java:792)
    at org.forgerock.json.jose.utils.KeystoreManager.getPrivateKey(KeystoreManager.java:137)
    ... 88 more

Recent Changes

Changed the password for an AM/OpenAM keystore or truststore.

Renewed expired certificates.

Causes

Most likely there's a mismatch between the key passphrase and keystore passphrase.

This can also happen if you have a site configuration and have made changes to your certificate or passwords but not copied the files to all servers in the site.

Solution

This issue can be resolved by synchronizing the passwords using the keytool command:

  1. Update .storepass or .keypass respectively with the new password to ensure they match. You should also ensure they match on all servers if you have a site configuration. For example, you can use keytool commands such as the following depending on your keystore format:
    • JCEKS format:
      $ keytool -storepasswd -new newpassword -keystore keystore.jceks -storetype JCEKS
      $ keytool -keypasswd -alias yourfqdnalias -new newpassword -keystore keystore.jceks -storetype JCEKS
    • JKS format:
      $ keytool -storepasswd -new newpassword -keystore keystore.jks
      $ keytool -keypasswd -alias yourfqdnalias -new newpassword -keystore keystore.jks
  2. Restart the web application container in which AM/OpenAM runs to apply the changes.

Default keystore details - AM 5 and later; OpenAM 13.5.x

After installing AM/OpenAM, a default keystore is available in /path/to/openam/openam/keystore.jceks. The default password is changeit and is stored in /path/to/openam/openam/.storepass. This keystore contains multiple default test aliases; the exact test aliases included vary by version as shown in the documentation:

See Setup and Maintenance Guide › Setting Up Keys and Keystores for further information.

Default keystore details - Pre-OpenAM 13.5

After installing OpenAM, a default keystore is available in the OpenAM configuration directory $HOME/openam/openam/keystore.jks. The default password is changeit and is stored in $HOME/openam/openam/.storepass. The only key in this keystore is for a self-signed certificate (default alias: test). The default password is also changeit and is stored in $HOME/openam/openam/.keypass

See Also

How do I update the certificate alias for the signing key in the AM/OpenAM (All versions) keystore?

How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)?

How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)?

Setup and Maintenance Guide › Setting Up Keys and Keystores

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8670 (description of the SAML keystore and key passwords is inaccurate)


Unable to retrieve certificate with alias 'test' from keystore after making changes to the keystore in AM (All versions)

The purpose of this article is to provide assistance if you receive an "Internal Server Error" response to the jwk_uri or the well-known OAuth2 endpoints in AM after making changes to the keystore. You will also see the following error in the logs: "Unable to retrieve certificate with alias 'test' from keystore". This issue also occurs when IDM is integrated with AM with a "Cannot find resolver for issuer" error.

Symptoms

For calls made to the jwk_uri endpoint or the well-known endpoint, for example:

  • GET http://host1.example.com:8080/openam/oauth2/realms/root/connect/jwk_uri
  • GET http://host1.example.com:8080/openam/oauth2/realms/root/.well-known/openid-configuration

You will receive the following response (or possibly an empty response):

{"error":"server_error","error_description":"Internal Server Error"} 

The following error is shown in the OAuth2Provider debug log (warning or message level) when this happens:

OAuth2Provider:03/08/2018 10:22:57:121 AM MDT: Thread[tomcat-http--22,5,main]: TransactionId[269d260b-ebd3-4014-b6f0-13eaa880161f-1034]
WARNING: Unhandled exception: Internal Server Error (500) - The server encountered an unexpected condition which prevented it from fulfilling the request
Internal Server Error (500) - The server encountered an unexpected condition which prevented it from fulfilling the request
   at org.restlet.resource.ServerResource.doHandle(ServerResource.java:539)
   at org.restlet.resource.ServerResource.get(ServerResource.java:742)
   at org.restlet.resource.ServerResource.doHandle(ServerResource.java:617)
...
   at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)
   at java.lang.Thread.run(Thread.java:744)
Caused by: java.lang.NullPointerException
   at org.forgerock.oauth2.core.AgentOAuth2ProviderSettings.getJWKSet(AgentOAuth2ProviderSettings.java:363)
   at org.forgerock.openidconnect.restlet.OpenIDConnectJWKEndpoint.getJWKSet(OpenIDConnectJWKEndpoint.java:73)
...

An error similar to the following is shown in the CoreSystem debug log at the same time:

amSecurity:03/08/2018 10:22:57:116 AM MDT: Thread[tomcat-http--22,5,main]: TransactionId[269d260b-ebd3-4014-b6f0-13eaa880161f-1034]
ERROR: Unable to retrieve certificate with alias 'test' from keystore '/path/to/openam/keystore.jks'

IDM/AM integration

If you have integrated IDM with AM, you will see the following error in the IDM log when this happens:

Caused by: org.forgerock.oauth.OAuthException: Cannot find resolver for issuer https://host1.example.com:8080/openam/oauth2
   at org.forgerock.oauth.clients.oidc.OpenIDConnectClient.lambda$getJwtClaimsSet$3(OpenIDConnectClient.java:367)
   at java.util.Optional.orElseThrow(Optional.java:290)
   at org.forgerock.oauth.clients.oidc.OpenIDConnectClient.getJwtClaimsSet(OpenIDConnectClient.java:367)
   at org.forgerock.oauth.clients.oidc.OpenIDConnectClient.lambda$validateNonce$0(OpenIDConnectClient.java:270)
...

Recent Changes

Upgraded to AM 5 or later.

Created a new keystore.

Changed the default key alias (called test).

Causes

AM 5 introduced a new configuration property for the signing key alias used by Agents 5, which defaults to test. If you have changed your keystore and/or the default key alias without updating this key alias, you will see this error.

Solution

This issue can be resolved by updating the key alias used by Agents 5 using either the console, Amster or ssoadm:

  • Console: navigate to: Configure > Global Services > OAuth2 Provider > Global Attributes > ID Token Signing Key Alias for Agent Clients and update the test key alias to one that exists.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: OAuth2Provider
    • Property: agentIdTokenSigningKeyAlias
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s OAuth2Provider -t global -u [adminID] -f [passwordfile] -a agentIdTokenSigningKeyAlias=[keyAlias]
    replacing [adminID], [passwordfile] and [keyAlias] with appropriate values.

You should double-check you have updated the key alias in all the places noted in the documentation: Setup and Maintenance Guide › Changing Default Key Aliases.

See Also

Cannot recover key error shown when renewing expired certificates or changing the password for the keystore or truststore in AM/OpenAM (All versions)

How do I update the certificate alias for the signing key in the AM/OpenAM (All versions) keystore?

How does the OIDC authorization flow work when IDM (All versions) is integrated with AM?

OpenID Connect 1.0 Guide › OAuth2 Provider

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11492 (OpenID Jwk_uri URL returns Internal Server Error )


AM/OpenAM (All versions) Login flow fails with java.lang.IllegalArgumentException: Request header too large

The purpose of this article is to provide assistance if you encounter a "java.lang.IllegalArgumentException: Request header is too large" error when authentication flows fail. You may also see an HTTP 400 - Bad Request response. This issue occurs when AM/OpenAM is deployed on Apache Tomcat™.

Symptoms

Authentication flows involving AM/OpenAM fail.

The following error is shown in catalina.out when the request fails:

Nov 29, 2018 2:37:41 PM org.apache.coyote.http11.AbstractHttp11Processor process
INFO: Error parsing HTTP request header
 Note: further occurrences of HTTP header parsing errors will be logged at DEBUG level.
java.lang.IllegalArgumentException: Request header is too large
   at org.apache.coyote.http11.InternalInputBuffer.fill(InternalInputBuffer.java:515)
   at org.apache.coyote.http11.InternalInputBuffer.fill(InternalInputBuffer.java:504)
   at org.apache.coyote.http11.InternalInputBuffer.parseHeader(InternalInputBuffer.java:396)
   at org.apache.coyote.http11.InternalInputBuffer.parseHeaders(InternalInputBuffer.java:271)
   at org.apache.coyote.http11.AbstractHttp11Processor.process(AbstractHttp11Processor.java:1007)

The following response is shown if you examine network traffic using your browser's Developer Tools or capture a HAR file: 

HTTP 400 - Bad Request

You can capture a HAR file as described in: How do I create a HAR file for troubleshooting AM/OpenAM (All versions)?

Recent Changes

N/A

Causes

AM/OpenAM does not put a limit on token sizes. This issue can occur when the token being sent by the browser is bigger than the max header size specified in Tomcat's configuration file (server.xml). This can happen with authentication flows that utilize client-based sessions, since the session is stored in the cookie and transferred in the header (most browsers will prevent a cookie being larger than 4096 bytes per RFC 6265).

The default max header size in Tomcat is 8KB:

<Connector port="443" maxHttpHeaderSize="8192" protocol="HTTP/1.1" SSLEnabled="true"

The maxHttpHeaderSize attribute may not be present in the server.xml file, but still defaults to 8KB.

Solution

This issue can be resolved by increasing the max header size in Tomcat. You should increase it to a size that will accommodate your expected token sizes; examining network traffic using your browser's Developer Tools or capturing a HAR file when authentication fails can help you determine the size of the token being passed in the header. Otherwise, increasing it to 16KB is a good starting point; this is recommended as the minimum for client-based sessions in the documentation: Authentication and Single Sign-On Guide › Planning for Client-Based Sessions.

Caution

Increasing the header size may consume more memory; you should test this to determine the optimal size in your environment.

To increase max header size:

  1. Edit the server.xml file and amend the maxHttpHeaderSize value, for example, to increase it to 16KB:
    <Connector port="443" maxHttpHeaderSize="16384" protocol="HTTP/1.1" SSLEnabled="true"
    
    
    If this attribute is not present, you should add it with the new value.

See Apache Tomcat 8 Configuration Reference for further information.

Note

If you have a load balanced environment, you should ensure you have configured the HTTP headers size for the load balancer appropriately as well.

See Also

WDSSO/Kerberos authentication fails in AM/OpenAM (All versions) with an HTTP 400 Bad Request response

Authentication fails with IDM (All versions) integrated AM when session-jwt cookie size exceeds browser limits

FAQ: Cookies in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9365 (Social authentication + Stateless fails if stateless token is too big)


The CertAndKeyGen security class cannot be found error when configuring OpenAM 13.x

The purpose of this article is to provide assistance if you encounter a "The CertAndKeyGen security class cannot be found" error when configuring OpenAM on JBoss®. This error only occurs if you have also upgraded to JDK 8.

Symptoms

An error similar to the following is shown when running the configurator tool:

2017-06-11 12:57:03,196 ERROR [stderr] (http-198.51.100.0:8080) Caused by: java.lang.ExceptionInInitializerError: The CertAndKeyGen security class cannot be found, consider setting -Dorg.forgerock.opendj.CertAndKeyGenProvider=

2017-06-11 12:57:03,211 ERROR [org.apache.catalina.core.ContainerBase.[jboss.web].[default-host].[/login].[AMSetupServlet]] (http-198.51.100.0:8080) JBWEB000236: Servlet.service() for servlet AMSetupServlet threw exception: java.lang.ExceptionInInitializerError: The CertAndKeyGen security class cannot be found, consider setting -Dorg.forgerock.opendj.CertAndKeyGenProvider=
   at org.opends.server.util.Platform$PlatformIMPL.<clinit>(Platform.java:171) [opendj-server-legacy-3.5.0.jar:]
   at org.opends.server.util.Platform.<clinit>(Platform.java:80) [opendj-server-legacy-3.5.0.jar:]
   at org.opends.server.util.CertificateManager.generateSelfSignedCertificate(CertificateManager.java:272) [opendj-server-legacy-3.5.0.jar:]
   at org.opends.server.config.AdministrationConnector.createSelfSignedCertificateIfNeeded(AdministrationConnector.java:547) [opendj-server-legacy-3.5.0.jar:]
   at org.opends.server.core.DirectoryServer.startServer(DirectoryServer.java:1534) [opendj-server-legacy-3.5.0.jar:]
   at org.opends.server.util.EmbeddedUtils.startServer(EmbeddedUtils.java:78) [opendj-server-legacy-3.5.0.jar:]
   at com.sun.identity.setup.EmbeddedOpenDS.startServer(EmbeddedOpenDS.java:465) [openam-core-13.5.0.jar:13.5.0 - 2016-Jul-13 07:32:29]
   at com.sun.identity.setup.EmbeddedOpenDS.setup(EmbeddedOpenDS.java:262) [openam-core-13.5.0.jar:13.5.0 - 2016-Jul-13 07:32:29]
   at com.sun.identity.setup.AMSetupServlet.setupEmbeddedDS(AMSetupServlet.java:741) [openam-core-13.5.0.jar:13.5.0 - 2016-Jul-13 07:32:29]
   at com.sun.identity.setup.AMSetupServlet.setupSMDatastore(AMSetupServlet.java:789) [openam-core-13.5.0.jar:13.5.0 - 2016-Jul-13 07:32:29]
   at com.sun.identity.setup.AMSetupServlet.configure(AMSetupServlet.java:833) [openam-core-13.5.0.jar:13.5.0 - 2016-Jul-13 07:32:29]
   at com.sun.identity.setup.AMSetupServlet.processRequest(AMSetupServlet.java:500) [openam-core-13.5.0.jar:13.5.0 - 2016-Jul-13 07:32:29]
   at com.sun.identity.setup.AMSetupServlet.doPost(AMSetupServlet.java:439) [openam-core-13.5.0.jar:13.5.0 - 2016-Jul-13 07:32:29]
...

Recent Changes

Upgraded to, or installed OpenAM 13.x.

Upgraded to Oracle® Java Development Kit (JDK) 8.

Causes

The CertAndKeyGen class is not loaded by the JVM even when the following JVM option is set correctly:

-Dorg.forgerock.opendj.CertAndKeyGenProvider=sun.security.tools.keytool.CertAndKeyGen

Solution

This issue can be resolved by updating the jboss-deployment-structure.xml file to include paths to the Sun x509 security module (sun/security/x509) and the keytool (sun/security/tools/keytool). For example, the revised file would now look similar to this:  

<paths> 
   <path name="sun/security/x509" /> 
   <path name="sun/security/tools/keytool" /> 
   <path name="com/sun/org/apache/xpath/internal" /> 
   <path name="com/sun/org/apache/xerces/internal/dom" /> 
   <path name="com/sun/org/apache/xml/internal/utils" /> 
</paths>

See Also

A security class cannot be found in this JVM because of the following reason: sun.security.x509.CertAndKeyGen error in OpenDJ 2.6.0, 2.6.1, 2.6.2 and 2.6.3

FAQ: Configuring AM/OpenAM

FAQ: Installing AM/OpenAM

FAQ: Upgrading AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x

The purpose of this article is to provide assistance if you encounter a "java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder" error and find Federation related pages are not accessible in the AM 6.5.x console. This issue only occurs if you are using Java® 11 and affects the pages for SAML2 entity providers, WS-Federation entity providers and all Federation related common tasks (from the Dashboard option).

Symptoms

JATO pages do not display when you attempt to access them via the console. JATO pages are pages from the Classic UI that have not yet been converted to XUI and include pages for SAML2 entity providers, WS-Federation entity providers and the common tasks wizards that are accessed from the Dashboard option: 

  • When you attempt to access the entity provider pages (navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers), you see the following message and nothing happens:
    Redirecting... 
    
  • When you attempt to access one of the common tasks wizards (navigate to Realms > [Realm Name] > Dashboard > Common Tasks), you see the following error:
    An error occurred while processing this request. Contact your administrator.
    

The following error is shown in the Configuration debug log when this happens:

amConsole:12/14/2018 14:54:07:337 am GMT: Thread[http-nio-8080-exec-2,5,main]: TransactionId[93267741-6ba5-4845-91a8-16c614605daa-1780]
ERROR: ConsoleServletBase.onUncaughtException
javax.servlet.ServletException: java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder
   at org.apache.jasper.runtime.PageContextImpl.handlePageException(PageContextImpl.java:667)
   at org.apache.jsp.console.task.ConfigureOAuth2_jsp._jspService(ConfigureOAuth2_jsp.java:505)
   at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70)
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:741)
   at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:477)
   at org.apache.jasper.servlet.JspServlet.serviceJspFile(JspServlet.java:386)
   at org.apache.jasper.servlet.JspServlet.service(JspServlet.java:330)
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:741)
...
Caused by: java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder
   at java.base/java.lang.ClassLoader.defineClass1(Native Method)
   at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1016)
   at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:174)

Recent Changes

Upgraded to, or installed AM 6.5.x.

Upgraded to Java 11.

Causes

The JATO pages are not compatible with Java 11.

Solution

You can workaround this issue using one of the following options:

  • Downgrade to Java 8.
  • Use Amster or REST instead of the console for the affected configuration options (ssoadm can also be used in AM 6.5.1 but not AM 6.5).

See Also

Cannot install or use ssoadm in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x after restricting configuration store (DS/OpenDJ) cipher suites or Java upgrade

SAML Federation in AM/OpenAM

OAuth 2.0 in AM/OpenAM

Using Amster in AM

Using the REST API in AM/OpenAM

Using ssoadm in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14139 (AM Documentation should state limitations of using Java 11)


Unidentified properties or Invalid properties message when adding custom advanced server properties in AM (All versions) and OpenAM 13.5

The purpose of this article is to provide assistance if you see a "Server Profile was updated. Unidentified properties" or "Invalid properties" message when adding custom advanced server properties in AM/OpenAM. You may also notice that previously added custom server properties disappear upon upgrade.

Symptoms

The following error is shown when you add a custom server property using the console:

Server Profile was updated. Unidentified properties, my.custom.server.property

The following error is shown when you add a custom server property using ssoadm:

Invalid properties

Custom server properties added in earlier versions of OpenAM disappear after upgrading to AM / OpenAM 13.5.  

Recent Changes

Upgraded to, or installed AM 5.0 or later.

Upgraded to, or installed OpenAM 13.5.

Causes

AM / OpenAM 13.5 warns you when an unknown custom server property is added; however, the property is successfully added. In earlier versions of OpenAM, you did not see the warning.

Solution

To prevent this warning being displayed, you can add the property to the validserverconfig.properties file (located in the /path/to/tomcat/webapps/openam/WEB-INF/classes/ directory). You should add your custom server property to the end of this file. For example, if your property is called my.custom.server.property, you would add:

my.custom.server.property=

You can then add the custom server property using either the console or ssoadm:

  • Console: navigate to: Deployment > Servers > [Server Name] > Advanced and add the required property and value. To add the property as a server default, navigate to: Configure > Server Defaults > Advanced instead. Once you have entered the property and value, click + to add followed by Save Changes.
  • 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, where [serverName] is either the name of the server or default.
Note

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

 Upgrade

To avoid existing custom server properties being lost when you upgrade to AM / OpenAM 13.5, you can follow this process to preserve them:

  1. Stop the web application container in which AM/OpenAM runs.
  2. Remove the openam folder and openam.war file from the /path/to/tomcat/webapps directory.
  3. Copy the new AM/OpenAM war file to the /path/to/tomcat/webapps directory (ensuring it is called openam.war).
  4. Start the web application container in which AM/OpenAM runs.
  5. Update the validserverconfig.properties file with any custom server properties you have added in previous versions of AM/OpenAM.
  6. Restart the web application container in which AM/OpenAM runs.
  7. Run the upgrade process as you normally would, using either the upgrade.jar or the console.

See Also

Reference › Configuration Reference › Advanced Properties

Related Training

N/A

Related Issue Tracker IDs

N/A


OpenAM 13.5 redirects to server URL instead of site URL in load balanced environment

The purpose of this article is to provide assistance if OpenAM incorrectly redirects you to the server URL instead of to the expected site URL in a load balanced environment. You will also see a 400 Bad Request response with a message: "FQDN \"lb.example.com\" is not valid."

Symptoms

OpenAM redirects you to the server URL instead of to the expected site URL in a load balanced environment.

You may see the following response if you use a REST call or examine network traffic using your browser's Developer Tools:

{"code": 400,"reason": "Bad Request", "message":"FQDN \"lb.example.com\" is not valid."}

where lb.example.com is the site URL (load balancer).

You will also see this message if you make changes to the default Advanced server properties, and then try to view or change realm details in the OpenAM console.

Other symptoms may include:

  • End users get an error if the server URL is not accessible externally when they access the site URL.
  • Restarting the server can restore expected behavior since this resets the FQDN map.

Recent Changes

Made changes to any of the server properties via the OpenAM console on the site URL (which points to the load balancer). 

Causes

The site hostname is automatically added to the in-memory FQDN map; however, saving subsequent changes to server properties causes getFqdnMap in FqdnValidator.java to reinitialize the FQDN map to 0. At this point, anyone accessing the site URL will get redirected to the default server FQDN since the site URL has been removed from the FQDN map.

This issue is caused by changes made in OpenAM 13.5 that removed the need to restart the server after updating the FQDN map: OPENAM-7914 (Make the attribute com.sun.identity.server.fqdnMap hot-swappable ).

Solution

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

Workaround

Alternatively, you can map the FQDN to the site URL. For example, where the site URL is lb.example.com:

  • OpenAM console: navigate to Configure > Server Defaults > Advanced and add the com.sun.identity.server.fqdnMap[siteURL] property. For example: 
    com.sun.identity.server.fqdnMap[lb.example.com] = lb.example.com
    
    Once you have entered the property and value, click + to add followed by Save Changes.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.sun.identity.server.fqdnMap[siteURL]=[siteURL] 
    replacing [adminID], [passwordfile] and [siteURL] with appropriate values. For example:
    $ ./ssoadm update-server-cfg -s default -u amadmin -f pwd.txt  -a com.sun.identity.server.fqdnMap[lb.example.com]=lb.example.com
Note

You do not need to restart the web application container in which OpenAM runs to apply this change in OpenAM 13.5.

See Also

How do I set up Realm DNS Aliases in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7914 (Make the attribute com.sun.identity.server.fqdnMap hot-swappable )

OPENAM-9628 (Strange 400 response after changing advanced default server properties from site URL)


Authentication fails in OpenAM 13.0 with an AuthId JWT Signature not valid error

The purpose of this article is to provide assistance if you cannot authenticate to OpenAM 13.0 and you receive an "AuthId JWT Signature not valid" error. This issue can occur when you have a multi-instance deployment or you have a single-instance deployment but have disabled caching.

Symptoms

The following error is shown in the browser when you attempt to authenticate:

AuthId JWT Signature not valid 

The following response is received when authenticating using the REST API:

{"code":400,"reason":"Bad Request","AuthId JWT Signature not valid"}

The following error is shown in the Authentication debug log file:

amAuthREST:02/02/2016 09:21:02:559 AM CET: Thread[http-bio-192.162.94.74-8080-exec-1,5,main]: TransactionId[64a9e309-2739-4c68-994e-894b04cfa9f2-4875]
AuthenticationService.authenticate() :: Rest Authentication Exception
org.forgerock.openam.core.rest.authn.exceptions.RestAuthException: AuthId JWT Signature not valid
	at org.forgerock.openam.core.rest.authn.AuthIdHelper.verifyAuthId(AuthIdHelper.java:194)
	at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:152)
	at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.continueAuthentication(RestAuthenticationHandler.java:114)
	at org.forgerock.openam.core.rest.authn.http.AuthenticationServiceV1.authenticate(AuthenticationServiceV1.java:136)
...

This will appear to be an intermittent issue and you will find that sometimes your authentication attempt succeeds.

Recent Changes

Upgraded to, or installed OpenAM 13.0 in a multi-instance deployment.

Added an instance to your single-instance deployment.

Disabled caching on your single-instance deployment by setting the following caching properties to false:

com.iplanet.am.sdk.caching.enabled=false
com.sun.identity.idm.cache.enabled=false
com.sun.identity.sm.cache.enabled=false

Causes

The authentication token (authID) is signed by a shared secret in OpenAM 13, which is a random key that OpenAM generates upon startup; these keys are different for each instance in a multi-instance deployment and change each time you restart OpenAM: 

  • If the server where authentication takes place (AM2) is different to the server where the authentication token was generated (AM1), the server (AM2) will not be able to validate the authentication token and will generate the "AuthId JWT Signature not valid" error.
  • If authentication takes place on the server that generated the authentication token, it will succeed, which is why it appears to be an intermittent issue.

Similarly, the shared secret value will be regenerated each time the service configuration is accessed if you have disabled caching.

Solution

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

Alternatively, this issue can be resolved by replacing the shared secret with a static value.

  1. Generate a random string that is at least 128 bit and base64 encoded. For example, you could use the OpenDJ base64 tool to do this. 
  2. Update the shared secret on one OpenAM instance using either the OpenAM console or ssoadm:
    • OpenAM console: navigate to: Realms > Top Level Realm / > Authentication > Settings > Security > Organization Authentication Signing Secret and paste in the string you generated in step 1.
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-svc-attrs -u [adminID] -f [passwordfile] -s iPlanetAMAuthService -e / -a iplanet-am-auth-hmac-signing-shared-secret=[sharedSecret]
      
      replacing [adminID], [passwordfile] and [sharedSecret] with appropriate values, where [sharedSecret] is the string you generated in step 1.
  3. Restart all web application containers in which your OpenAM instances run to apply these configuration changes.
Note

It is important that the string you generate is at least 128 bit and base64 encoded, otherwise you will encounter OPENAM-8264 (insufficient validator for service property 'iplanet-am-auth-hmac-signing-shared-secret').

See Also

Best practice for upgrading to OpenAM 13.x

OpenDJ Reference › Tools Reference › base64

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8264 (insufficient validator for service property 'iplanet-am-auth-hmac-signing-shared-secret')

OPENAM-8269 ("AuthId JWT Signature not valid" error in multi-instance deployments on 13)


Error when flushing the writer message when AM (All versions) and OpenAM 13.x is under high load with audit logging enabled

The purpose of this article is to provide assistance if you encounter "Error when flushing the writer" messages when AM/OpenAM is under high load and you have enabled audit logging. This issue only occurs when log rotation is enabled for a maximum size and the default buffering settings are unchanged.

Symptoms

The following error is shown in the CoreSystem debug log when AM/OpenAM is under high load:

ERROR: Error  when flushing the writer
java.io.IOException: Stream closed
   at java.io.BufferedWriter.ensureOpen(BufferedWriter.java:116)
   at java.io.BufferedWriter.flushBuffer(BufferedWriter.java:126)
   at java.io.BufferedWriter.flush(BufferedWriter.java:253)
   at org.forgerock.audit.events.handlers.writers.RotatableWriter.flush(RotatableWriter.java:341)
   at org.forgerock.audit.events.handlers.writers.AsynchronousTextWriter.flush(AsynchronousTextWriter.java:170)
   at org.forgerock.audit.events.handlers.writers.TextWriterAdapter.flush(TextWriterAdapter.java:65)
   at org.forgerock.audit.handlers.csv.StandardCsvWriter.flush(StandardCsvWriter.java:138)
   at org.forgerock.audit.handlers.csv.CsvAuditEventHandler.writeEvent(CsvAuditEventHandler.java:317)
   at org.forgerock.audit.handlers.csv.CsvAuditEventHandler.publishEventWithRetry(CsvAuditEventHandler.java:262)
   at org.forgerock.audit.handlers.csv.CsvAuditEventHandler.publishEvent(CsvAuditEventHandler.java:240)
   at org.forgerock.audit.AuditServiceImpl.publishEventToHandlers(AuditServiceImpl.java:275)
   at org.forgerock.audit.AuditServiceImpl.handleCreate(AuditServiceImpl.java:216)
   at org.forgerock.audit.AuditServiceProxy.handleCreate(AuditServiceProxy.java:115)
   at org.forgerock.openam.audit.DefaultAuditServiceProxy.handleCreate(DefaultAuditServiceProxy.java:66)
   at org.forgerock.json.resource.InternalConnection.createAsync(InternalConnection.java:44)
   at org.forgerock.json.resource.AbstractAsynchronousConnection.create(AbstractAsynchronousConnection.java:44)
   at org.forgerock.openam.audit.AuditEventPublisherImpl.publishForRealm(AuditEventPublisherImpl.java:97)
   at org.forgerock.openam.audit.AuditEventPublisherImpl.tryPublish(AuditEventPublisherImpl.java:66)
   at org.forgerock.openam.audit.AbstractHttpAccessAuditFilter.auditAccessSuccess(AbstractHttpAccessAuditFilter.java:120)
   at org.forgerock.openam.audit.AbstractHttpAccessAuditFilter.access$000(AbstractHttpAccessAuditFilter.java:49)
   at org.forgerock.openam.audit.AbstractHttpAccessAuditFilter$1.apply(AbstractHttpAccessAuditFilter.java:77)
   at org.forgerock.openam.audit.AbstractHttpAccessAuditFilter$1.apply(AbstractHttpAccessAuditFilter.java:73)

Recent Changes

Enabled audit logging.

Configured your audit event handler to rotate logs based on a maximum size and left the default buffering settings unchanged.

Causes

The actions to rotate a log file and buffer a log file are not mutually exclusive, which causes this write error. These messages are harmless though and will not cause the loss of any audit events. 

Solution

You can either ignore these messages as they are harmless or you can resolve this issue in one of the following ways:

  • Switch off buffering. 
  • Configure audit logging to Flush Each Event Immediately, although this setting may impact performance so should be tested in a pre-production environment first.

You can make these changes at the global or realm level using either the console or ssoadm:

Global

  • AM / OpenAM 13.5 console: navigate to: Configure > Global Services > Audit Logging > [Event Handler Name] > Buffering and either deselect the Enabled option for Buffering Enabled or select the Enabled option for Flush Each Event Immediately.
  • OpenAM 13 console: navigate to: Configuration > Global > Audit Logging > [Event Handler Name] > Buffering and either deselect the Enabled option for Buffering Enabled or select the Enabled option for Flush Each Event Immediately.
  • ssoadm: enter one of the following commands depending on which approach you want to take:
    • To switch off buffering:
      $ ./ssoadm set-sub-cfg -s AuditService -u [adminID] -f [passwordfile] -g [eventHandlerName] -o set -a bufferingEnabled=false
      
      replacing [realmname], [adminID], [passwordfile] and [eventHandlerName] with appropriate values.
    • To enable Flush Each Event Immediately:
      $ ./ssoadm set-sub-cfg -s AuditService -u [adminID] -f [passwordfile] -g [eventHandlerName] -o set -a bufferingAutoFlush=true
      
      replacing [realmname], [adminID], [passwordfile] and [eventHandlerName] with appropriate values.
    For example, to switch off buffering for the Global CSV Handler:
    $ ./ssoadm set-sub-cfg -s AuditService -u amadmin -f pwd.txt -g "Global CSV Handler" -o set -a bufferingEnabled=false

Realm

  • AM / OpenAM 13.5 console: navigate to: Realms > [Realm Name] > Services > Audit Logging > Secondary Configurations > [Event Handler Name] > Buffering and either enable Flush Each Event Immediately or disable Buffering Enabled.
  • OpenAM 13 console: navigate to: Realms > [Realm Name] > Services > Audit Logging > [Event Handler Name] > Buffering and either deselect the Enabled option for Buffering Enabled or select the Enabled option for Flush Each Event Immediately.
  • ssoadm: enter one of the following commands depending on which approach you want to take:
    • To switch off buffering:
      $ ./ssoadm set-sub-cfg -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -g [eventHandlerName] -o set -a bufferingEnabled=false
      
      replacing [realmname], [adminID], [passwordfile] and [eventHandlerName] with appropriate values.
    • To enable Flush Each Event Immediately:
      $ ./ssoadm set-sub-cfg -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -g [eventHandlerName] -o set -a bufferingAutoFlush=true
      
      replacing [realmname], [adminID], [passwordfile] and [eventHandlerName] with appropriate values.

See Also

How do I configure audit logging via ssoadm in AM (All versions) and OpenAM 13.x?

Reference › Configuration Reference › Audit Logging

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9112 (Audit logging outputs errors in debug log under high load)


SNMP monitoring fails in AM 5.5.1 with No Monitoring interfaces started exception

The purpose of this article is to provide assistance if SNMP monitoring fails in AM with a "No Monitoring interfaces started; monitoring disabled" exception. You will also see "Ports are unable to be accessed resulting in".

Symptoms

The following error is shown in the CoreSystem debug log when SNMP monitoring fails:

Ports are unable to be accessed resulting in:

ERROR: Failed to start monitoring adapters - ignoring
com.sun.identity.monitoring.MonitoringStartupException: No Monitoring interfaces started; monitoring disabled.
   at com.sun.identity.monitoring.MonitoringAdapters.<init>(MonitoringAdapters.java:231)
   at com.sun.identity.monitoring.MonitoringManager$MonitoringProvider.startMonitoringAdapters(MonitoringManager.java:93)
   at com.sun.identity.monitoring.MonitoringManager$NoopMonitoringProvider.startMonitoring(MonitoringManager.java:134)
   at com.sun.identity.monitoring.MonitoringManager.startMonitoring(MonitoringManager.java:58)
   at com.sun.identity.common.MonitoringConfigurator.init(MonitoringConfigurator.java:63)

Recent Changes

Upgraded to, or installed AM 5.5.1.

Enabled SNMP monitoring.

Causes

The OpenDMK library (opendmk.jar) was removed, which prevents the SNMP ports from starting per known issue: OPENAM-12244 (Monitoring services unable to connect to Port).

Solution

This issue can be resolved by upgrading to AM 6 or later; you can download this from BackStage. Once you have upgraded, you must follow the steps in Setup and Maintenance Guide › To Enable the SNMP Monitoring Interface to install the OpenDMK library and enable monitoring.

Workaround

You can workaround this issue by manually installing the OpenDMK library (opendmk.jar) that is shipped with DS 5.5.0, as follows:

  1. Download DS 5.5.0.zip from BackStage.
  2. Extract the zip into a temporary directory, for example: temp/dj-5.5.0:
    $ cd temp/dj-5.5.0
    $ unzip DS-5.5.0.zip
    
  3. Run the OpenDMK library extractor (this launches a UI, so should be run on a local machine rather than via a SSH connection):
    $ cd temp/dj-5.5.0
    $ java -jar snmp/opendmk.jar
  4. Review and accept the license.
  5. Install the the OpenDMK library into the temporary directory, for example: temp/opendmk.
  6. Copy the extracted jdmkrt.jar (located in the temp/opendmk/OpenDMK-bin/lib directory) to the relevant AM server(s):
    1. Stop the web application container in which AM runs. 
    2. Copy the jdmkrt.jar to /path/to/tomcat/webapps/openam/WEB-INF/lib directory where AM is deployed.
    3. Restart the web application container in which AM runs.

See Also

Performance tuning and monitoring ForgeRock products

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12244 (Monitoring services unable to connect to Port)


Patches


How do I check what patches are installed for ForgeRock products?

The purpose of this article is to provide details for checking what patches are installed for AM/OpenAM, DS/OpenDJ, IDM/OpenIDM and IG/OpenIG.

Overview

This article provides details for checking what patches are installed by product:

You can also use the patchinfo utility in AM/OpenAM and IG/OpenIG as detailed in How do I use the patchinfo utility to check what patches are installed for AM/OpenAM (All versions) or IG/OpenIG (All versions)? 

Checking for patches in AM/OpenAM

Providing you have unzipped your patches directly in the openam directory as recommended, you can check what patches are installed as follows:

$ cd /path/to/tomcat/webapps/openam/WEB-INF
$ ls README.*

README.1.12345    README.201608

Where each README represents a set of installed patches. READMEs are named to indicate either the ticket number where the patch was given (README.1.12345) or the security advisory ID (README.201608).

Embedded DS/OpenDJ

You can check what patches are installed using the status -V command as follows:

$ cd $HOME/[am_instance]/opends/bin
$ ./status -V

Wed Nov 29 11:27:09 MST 2017
ForgeRock Directory Services 5.5.0+OPENDJ-1234,OPENDJ-5678
Build 20171019141329

Any installed patches will be listed after the product name and version as an issue tracker ID (JIRA).

Checking for patches in Policy Agents

You can check the debug log to see what patch version you have installed, for example:

######################################################
 # OpenAM Web Agent                                   #
 # Version: 4.1.0-27                                  #
 # Revision: 39e5be3                                  #
 # Container: IIS 7.5, 8.x WINNT 32/64bit/WINNT       #
 # Build date: Nov  2 2017 13:42:43                   #
 ######################################################

For Web policy agents 4.x, you can also check the version using the agentadmin --v command as follows:

$ ./agentadmin --v

OpenAM Web Agent for Apache Server 2.2.x 64bit 
Version: 4.1.0-25 
Revision: 42ff535 
Build machine: delacroix 
Build date: Sep 15 2017 16:44:11

Checking for patches in DS/OpenDJ

You can check what patches are installed using the status -V command as follows:

$ cd /path/to/ds/bin
$ ./status -V

Wed Nov 29 11:27:09 MST 2017
ForgeRock Directory Services 5.5.0+OPENDJ-1234,OPENDJ-5678
Build 20171019141329

Any installed patches will be listed after the product name and version as an issue tracker ID (JIRA).

Checking for patches in IDM/OpenIDM

You can check what patches are installed using the PS command when running IDM/OpenIDM interactively, for example:

ps
START LEVEL 12
   ID   State         Level  Name
[   0] [Active     ] [    0] System Bundle (4.2.1)
[   1] [Resolved   ] [    1] javax.transaction API v.1.1 (3.1.1)
[   2] [Active     ] [    1] OpenIDM System Bundle (4.5.0)
...
[ 135] [Active     ] [   10] OpenIDM Core Bundle (4.5.0.OPENIDM-1234-5678)
...

Any installed patches will be listed after a product bundle as an issue tracker ID (JIRA). Patches only apply to a bundle (not the whole product), so you will need to check all bundles for patches, focusing on any that start OpenIDM, ForgeRock or OpenICF. You can search for version.JIRA_prefix to easily find the patched bundles, for example:

(4.5.0.OPENIDM
(4.5.0.OPENICF
(4.5.0.CREST

Checking for patches in IG/OpenIG

Providing you have unzipped your patches directly in the top-level IG/OpenIG WAR directory as recommended, you can check what patches are installed as follows:

$ cd /path/to/jetty/webapps/root/WEB-INF
$ ls README.*

README.1.12345    README.201606

Where each README represents a set of installed patches. READMEs are named to indicate either the ticket number where the patch was given (README.1.12345) or the security advisory ID (README.201606).

See Also

How do I install an AM/OpenAM patch (All versions) supplied by ForgeRock support?

FAQ: Patches in AM/OpenAM

How do I install a DS/OpenDJ patch (All versions) supplied by ForgeRock support?

How do I install an IDM/OpenIDM patch (All versions) supplied by ForgeRock support?

How do I install an IG/OpenIG patch (All versions) supplied by ForgeRock support?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2651 (Formalized patching mechanism)


How do I install an AM/OpenAM patch (All versions) supplied by ForgeRock support?

The purpose of this article is to provide information on installing an AM/OpenAM patch that has been supplied by ForgeRock support.

Installing a patch

Note

Unzipping the patch directly in the openam directory provides a full history of all the patches installed in your AM/OpenAM environment, where each README.X or patchInfo.X.json file indicates a set of installed patches (and the corresponding ticket ID).

Apache Tomcat™

  1. Back up the /path/to/tomcat/webapps/openam directory where AM/OpenAM is deployed.
  2. Check the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where AM/OpenAM is deployed to ensure that the classes contained in the patch do not already exist in the directory. If one or more classes do already exist, it may mean you have a conflicting patch installed. If this is the case, you should seek advice from ForgeRock support prior to applying the patch. 
  3. Stop the web application container in which AM/OpenAM runs. 
  4. Go to the /path/to/tomcat/webapps/openam/ directory where AM/OpenAM is deployed:
    $ cd /path/to/tomcat/webapps/openam/
  5. Extract the patch zip:
    $ unzip /path/to/patch/X.zip
  6. Restart the web application container in which AM/OpenAM runs.
Note

You can remove the patch by replacing the /openam directory with your backup.

JBoss® Application Server / Wildfly® AS

The JBoss Application Server and Wildfly AS web application containers deploy applications to different temporary directories each time you restart the container; this means any patches need to be applied directly to the openam.war file as follows: 

  1. Make a backup of the original openam.war file
  2. Stop the web application container in which AM/OpenAM runs.
  3. Unpack the openam.war file to a temporary directory.
  4. Go to the openam/ directory in the unpacked openam.war file:
    $ cd /tmp/unpacked/openam.war/openam
  5. Extract the patch zip:
    $ unzip /path/to/patch/X.zip
  6. Repack the openam.war file.
  7. Redeploy the openam.war file and restart the web application container in which AM/OpenAM runs.
Note

You can remove the patch by redeploying your original openam.war file.

See Also

FAQ: Patches in AM/OpenAM

How do I make a backup of configuration data in AM/OpenAM (All versions)? 

Maintenance and Patch availability policy

How do I install a DS/OpenDJ patch (All versions) supplied by ForgeRock support?

How do I use the patchinfo utility to check what patches are installed for AM/OpenAM (All versions) or IG/OpenIG (All versions)?

How do I check what patches are installed for ForgeRock products?

Related Training

N/A

Related Issue Tracker IDs

N/A


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

This content has been optimized for printing.

Loading...