Installation
This guide shows you how to install PingAM for access and federation management.
Unless you are planning a demo or test installation, read the Release notes before you get started.
Prepare the environment for deployment
Prerequisites for deploying PingAM software.
Prepare the Java container
Prepare the application server of your choice.
Install AM
Install AM servers for high availability.
Prepare datastores
Store identities, configuration, CTS, policies and applications, and UMA-related data in LDAP directories.
Store configuration in files
Store configuration data in JSON files
Remove installations
Uninstall AM and start over.
Troubleshoot installations
Troubleshoot or repair an AM installation.
Name changes for ForgeRock products
Product names changed when ForgeRock became part of Ping Identity.
The following name changes have been in effect since early 2024:
| Old name | New name |
|---|---|
ForgeRock Identity Cloud |
PingOne Advanced Identity Cloud |
ForgeRock Access Management |
PingAM |
ForgeRock Directory Services |
PingDS |
ForgeRock Identity Management |
PingIDM |
ForgeRock Identity Gateway |
PingGateway |
Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.
Download AM
The Backstage download site hosts downloads,
including a .zip file with all of the AM components,
the .war file, AM tools, the configurator, web and Java agents, PingGateway, and documentation.
Review the Software License and Subscription Agreement presented before you download AM files.
For each release of AM, you can download the entire package as a .zip file,
only the AM .war file, or only the administrative tools as a .zip archive.
After you download the .zip file, create a new directory for AM,
and unzip the .zip file to access the content.
$ cd ~/Downloads $ mkdir am && cd am $ unzip ~/Downloads/AM-8.0.1.zip
When you unzip the archive of the entire package, you get samples, snmp and legal-notices directories in addition to the following files:
| File | Description | ||
|---|---|---|---|
|
The distribution During installation, the This file is also available to download individually. |
||
|
A utility with some cryptographic functionality used for creating Docker images.
|
||
|
A command-line tool ( The
|
||
|
Configuration and upgrade tools for installing and maintaining your server. The
|
||
|
Configuration file upgrade tool. Find more information on converting configuration files for import into AM in
the |
||
|
An AM Fedlet, a light-weight SAML v2.0 service provider. The Fedlet lets you set up a federated deployment without the need of a fully-featured service provider. |
||
|
An IdP Discovery Profile (SAMLv2 binding profile) for its IdP Discovery service. The profile keeps track of the identity providers for each user. |
||
|
Sample authentication trees for demonstration purposes. The trees are provided as JSON files and can be imported into an AM deployment using Amster. Find information on importing files using Amster in Importing Configuration Data in the Amster 8.0.0 User Guide. |
||
|
A utility to help with creating a trust store for use with web authentication. Find more information in the |
(1) AM also provides REST-based STS endpoints that you can use directly on the AM server.
Customize the AM .war file
For basic AM installations you don’t need to customize the AM .war file before deploying it.
If you need to customize any AM extension points, add the new classes to the .war file before deploying it.
|
Find information about customizing the secure cookie filter in Secure cookie filter. |
You can also customize the AM user pages and package them into the .war file.
Learn more about customizing the .war file in Customize before upgrading.
Prepare the environment
Perform the following tasks to prepare your environment for AM:
|
Find details of supported operating systems and Java requirements in Requirements in the Release notes. |
Prepare an FQDN
AM requires that you provide an FQDN when you configure it.
Before you set up AM, be sure that your system has an FQDN, such as am.example.com.
For evaluation purposes, you can give your system an alias using the /etc/hosts file on UNIX systems
or %SystemRoot%\system32\drivers\etc\hosts on Windows.
For production deployments, make sure the FQDN is properly assigned using DNS.
Do not use the hostname localhost for AM, not even for testing purposes.
AM relies on browser cookies, which are returned based on the domain name.
You can set the cookie domain name value to an empty string for host-only cookies or to any non-top level domain.
For example, if you install AM and use am.example.com as the host,
you can set the cookie domain name as example.com.
|
Do not configure a top-level domain as your cookie domain as browsers will reject them. Top-level domains are browser-specific. Some browsers, like Firefox, also consider special domains like Amazon’s web service (for example, ap-southeast-2.compute.amazonaws.com) to be a top-level domain. Check the effective top-level domain list at https://publicsuffix.org/list/effective_tld_names.dat to ensure that you do not set your cookie to a domain in the list. |
Prepare the Java environment
AM software depends on a Java runtime environment.
Check the output of the java -version command to make sure your version is supported
according to the Java requirements.
|
Keep your Java software up-to-date with the latest supported version.
Make sure your |
The following table summarizes the high-level tasks required to configure your Java environment:
| Task | Resources |
|---|---|
Prepare your JDK The suggestions in these sections apply to AM deployments with the following characteristics:
|
|
Tune the JVM for AM This document provides guidance on tuning the JVM for production, but you must also tune it for garbage collection based on your environment. |
|
You can find information on configuring JVM properties for proxy support in Configuring AM for Outbound Communication. |
Settings for Oracle Java environments
When using an Oracle Java environment, set at least the following options:
-Xmx1g(minimum)-
AM requires at least a 1 GB heap. Higher volume and higher performance deployments require additional heap space.
-XX:MetaspaceSize=256m-
Set the metaspace memory size to 256 MB.
-XX:MaxMetaspaceSize=256m-
Set the maximum metaspace memory size to 256 MB.
You can find additional JVM tuning and security recommendations in Tune JVM settings.
Settings for OpenJDK Java environments
When using an OpenJDK Java environment, set at least the following options.
-Xmx1024m(minimum)-
AM requires at least a 1 GB heap. Higher volume and higher performance deployments require additional heap space.
Recommended:
-Xmx2048m. -XX:MetaspaceSize=256m-
Set the initial metadata space size to 256 MB.
Tune JVM settings
This section gives some initial guidance on configuring the JVM for running AM when the deployment has a dedicated CTS token store, and AM is configured to use server-side sessions.
These settings provide a strong foundation to the JVM before a more detailed garbage collection tuning exercise, or as best practice configuration for production:
| JVM parameters | Suggested value | Description |
|---|---|---|
|
At least 1 GB. In production environments, at least 2 to 3 GB. This setting depends on the available physical memory and whether a 32- or 64-bit JVM is used. |
|
|
Set both to 256 MB |
Controls the size of the metaspace in the JVM. |
|
60000 |
Controls the read timeout in the Java HTTP client implementation. This applies only to the Sun/Oracle HotSpot JVM. |
|
High setting: 30000 (30 seconds) |
Controls the connect timeout in the Java HTTP client implementation. When you have hundreds of incoming requests per second, reduce this value to avoid a huge connection queue. This applies only to the Sun/Oracle HotSpot JVM. |
| JVM parameters | Suggested value | Description |
|---|---|---|
|
|
Controls the protocols used for outbound HTTPS connections from AM. Specify one or more of the following values, separated by commas:
This setting applies only to Sun/Oracle Java environments. |
|
|
Controls the protocol AM uses to connect to affected external resources. Specify one or more of the following values, separated by commas:
This setting overrides the default server value. Learn more in advanced properties. |
| JVM parameters | Suggested value | Description |
|---|---|---|
|
Verbose garbage collection reporting. |
|
|
|
Logs detailed information about garbage collection.
When using the |
|
Out of Memory errors generate a heap dump automatically. |
|
|
|
Location of the heap dump. |
|
Prints a heap histogram when the JVM receives a SIGTERM signal. |
| Module flag | Suggested value | Description |
|---|---|---|
|
|
When running AM, SAML Artifact flows (or any flows that use Xerces SOAP libraries) can fail with the following error:
Set this module flag to avoid this error. |
Tune the underlying datastores
AM is not file-descriptor intensive, but you may need to tune each DS instance in your environment to handle multiple client connections.
Learn more about tuning DS in the DS performance tuning documentation.
Prepare a web application container
As a Java application, AM must be deployed in a Java container. Refer to Application containers for the list of supported containers.
The following table summarizes the high-level tasks required to prepare your container:
| Task | Resources |
|---|---|
Prepare the container for AM Follow the instructions for your container. |
|
Secure the container There are many ways to deploy and configure your environment for AM. Enforce HTTPS connections to AM where possible. If a Java Security Manager is enabled for your web application container, add permissions before installing AM. |
Apache Tomcat
AM examples often use Apache Tomcat (Tomcat) as the deployment container.
In these examples, Tomcat is installed on am.example.com and listens on the default ports without a Java
Security Manager enabled.
JVM startup
AM core services require a minimum JVM heap size of 1 GB, and a metadata space size of up to 256 MB.
Set a CATALINA_OPTS environment variable with the appropriate tuning for your environment.
For example, add the following in your setenv file:
-
Linux
-
Windows
In $CATALINA_BASE/bin/setenv.sh:
export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m"In $CATALINA_BASE/bin/setenv.bat:
set "CATALINA_OPTS=%CATALINA_OPTS% -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m"Some versions of Microsoft Edge support the Expires header attribute
instead of the Max-Age header attribute, which may cause SAML 2.0 and agent logout sequences to fail.
If you have set the org.apache.catalina.STRICT_SERVLET_COMPLIANCE Tomcat property to true, add the
org.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRE property in the setenv file, to add the Expires
attribute to the headers:
-
Linux
-
Windows
In $CATALINA_BASE/bin/setenv.sh:
export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \
-Dorg.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRES=true"In $CATALINA_BASE/bin/setenv.bat:
set "CATALINA_OPTS=%CATALINA_OPTS% -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m -
-Dorg.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRES=true"Slashes in resource names
Some AM resources have names that can contain slash characters (/), for example, in policy names, application names, and SAML v2.0 entities. These slash characters can cause unexpected behavior when running AM on Tomcat.
Avoid resource names that contain forward slashes.
Cookie domains
Set the cookie domain name value to an empty string (for host-only cookies) or to any non-top level domain (for domain cookies).
For example, if you install AM on am.example.com, you can set the cookie domain name to example.com.
| Because host-only cookies are more secure than domain cookies, you should use host-only cookies unless you have a good business case for using domain cookies. |
You can find information on configuring the cookie domain during installation in Install an instance.
Log request times
Tomcat provides components called valves that can be configured to track access to resources. The Access Log Valve outputs information about request activity to log files for you to analyze or use when troubleshooting.
To record request times in the Access Log Valve log, configure the pattern attribute to include the following values:
-
%D: The time taken to send an entire request in milliseconds. This is the total processing time and may be affected by network conditions. -
%F: The time taken to commit the response in milliseconds.
Example Valve element in server.xml:
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
prefix="localhost_access_log" suffix=".txt"
pattern="%h %l %u %t "%r" %s %b %D %F" />You can find information about the Access Log Valve configuration in the
Tomcat
documentation, including the %F value.
Encoding and security
You should edit the Tomcat <Connector> configuration to set URIEncoding="UTF-8".
UTF-8 URI encoding means the container can correctly decode URL-encoded characters in URI paths.
This is particularly useful if your applications use the AM REST APIs and some identifiers,
such as usernames, contain special characters.
You should also set the protocols property appropriately to define which protocols are supported.
Make sure you don’t support any unsafe protocols such as the SSL v3.0 protocol (SSLv3).
<Connector> configuration elements are found in the configuration file, /path/to/tomcat/conf/server.xml.
The following excerpt shows an example <Connector> with the URIEncoding and protocols
attributes set appropriately:
<Connector port="8443" protocol="HTTP/1.1"
SSLEnabled="true"
protocols="TLSv1.2,TLSv1.3"
maxThreads="150"
scheme="https"
secure="true"
clientAuth="false"
URIEncoding="UTF-8" />When you have finished setting up Apache Tomcat, you should enforce HTTPS connections to AM. Learn more in Secure connections to the AM container.
JBoss and WildFly
You can deploy AM on JBoss AS, JBoss EAP, and WildFly. The procedures listed here provide steps for configuring JBoss AS, JBoss EAP, and WildFly for AM.
After configuring JBoss or WildFly, you then prepare AM for deployment
by making changes to the contents of the AM .war archive.
Prepare JBoss or WildFly
-
Stop JBoss or WildFly.
-
The default JVM settings don’t allocate enough memory to AM. This step shows one method you can use to modify the JVM settings. You can find other methods in JBoss Configuring JVM Settings or WildFly JVM Settings.
-
Open the
standalone.conffile in the/path/to/jboss/bindirectory for JBoss or WildFly in standalone mode. -
Check the JVM settings associated with
JAVA_OPTS.Change the JVM heap size to
-Xmx1g. The default JVM heap size for some versions of JBoss might already exceed the recommended value.Change the metaspace size to
-XX:MaxMetaspaceSize=256mif the default size doesn’t exceed this amount. -
Set the following JVM
JAVA_OPTSsetting in the same file:-Dorg.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRES=trueMake sure the headers include the
Expiresattribute in addition toMax-Agebecause some versions of Microsoft Edge don’t supportMax-Age.
-
-
Edit the WildFly configuration to allow HTTP connections from any IP address.
In the
/path/to/wildfly/standalone/configuration/standalone.xmlfile, locate the<interface name="public">interface (around line 512 of the file) and change the value to<any-address/>:<interface name="public"> <any-address/> </interface> -
Set up WildFly for Social Authentication by performing the following steps:
-
Ensure the WildFly server is running.
-
Go to the WildFly Path.
-
In the
$JBOSS_HOME/bindirectory, run thejboss-cli.shscript file:$ ./bin/jboss-cli.sh -
Type "connect" to connect to the server.
-
Enable use of the equals (=) symbol in cookies by running the following command:
For example:
[standalone@localhost:9990 /] /subsystem=undertow/server=default-server/ http-listener=default:write-attribute(name=allow-equals-in-cookie-value, value=true) { "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } } -
Restart WildFly.
-
-
Deploy the
am.warfile into the appropriate deployment directory. The directory varies depending on whether you’re running in standalone or domain mode.
Prepare AM for JBoss and WildFly
To prepare AM to run with JBoss or WildFly, you must change the default AM war file.
JBoss and WildFly deploy applications from different temporary directories every time you restart the container,
which would require reconfiguring AM. To avoid problems, change the AM war file as follows:
-
If you haven’t already done so, create a temporary directory and expand the
AM-8.0.1.warfile. For example:$ cd /tmp $ mkdir /tmp/am && cd /tmp/am $ jar xvf ~/Downloads/AM-8.0.1.war -
Locate the
bootstrap.propertiesfile in theWEB-INF/classesdirectory of the expandedwararchive. Update the# configuration.dir=line in this file to specify a path with read and write permissions, then save the change.# This property should also be used when the system user that # is running the web/application server process does not have # a home directory. i.e. System.getProperty("user.home") returns # null. configuration.dir=/my/readwrite/config/dir -
If you are deploying AM on JBoss AS or JBoss EAP, remove the
jboss-all.xmlfile from theWEB-INFdirectory of the expandedwararchive.Don’t remove this file if you are deploying AM on WildFly.
-
Rebuild the
am.warfile.$ jar cvf ../am.war *
IBM WebSphere Liberty
To deploy AM in IBM WebSphere Liberty, perform the following steps:
-
Update the JVM options as described in Prepare the Java environment.
-
Customize the
AM-8.0.1.warfile as described in Prepare AM for WebSphere. -
After deploying AM, configure WebSphere as described in Prepare WebSphere.
Prepare AM for WebSphere
To prepare AM to run in WebSphere, change the AM .war file to ensure that the AM upgrade process
is able to find the AM configuration files.
You must make this change whenever you deploy a new .war file as part of an AM upgrade.
If you are installing on Windows, use slashes (/) in the paths listed here, and not backslashes (\).
|
-
Create a temporary directory and expand the
AM-8.0.1.warfile. For example:$ cd /tmp $ mkdir /tmp/am && cd /tmp/am $ jar xvf ~/Downloads/AM-8.0.1.war -
Locate the
bootstrap.propertiesfile in theWEB-INF/classesdirectory of the expandedwarfile.Update the
# configuration.dir=line in thebootstrap.propertiesfile to specify a path with read and write permissions. For example:# This property should also be used when the system user that # is running the web/application server process does not have # a home directory. i.e. System.getProperty("user.home") returns # null. configuration.dir=/my/readwrite/config/dir -
Rebuild the
AM-8.0.1.warfile:$ jar cvf ../AM-8.0.1.war *
Prepare WebSphere
In addition to preparing the AM .war file, follow these steps to configure WebSphere for AM after you
deploy AM into WebSphere:
-
Load classes from AM bundled libraries before loading classes from libraries delivered with Liberty:
-
In the WebSphere Liberty administration console, go to Explore > Configure > server.xml.
-
Select the
amweb application, click Add Child, and select Classloader from the list. -
In the Delegation field, select parentLast.
-
Save your work.
-
-
If your environment uses SOAP, add the SOAP-related properties to the JVM.
In the
AM-config-dir, create a file namedjvm.options, and add the following properties:-Djavax.xml.soap.MessageFactory=com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl -Djavax.xml.soap.SOAPFactory=com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPFactory1_1Impl -Djavax.xml.soap.SOAPConnectionFactory=com.sun.xml.internal.messaging.saaj.client.p2p.HttpSOAPConnectionFactory -Djavax.xml.soap.MetaFactory=com.sun.xml.internal.messaging.saaj.soap.SAAJMetaFactoryImpl -Dcom.ibm.websphere.webservices.DisableIBMJAXWSEngine=true
Secure connections to the AM container
There are many ways to deploy and configure your environment for AM, but we recommend that you enforce HTTPS connections to AM. For more information about securing AM, see Security.
The container where AM runs requires a certificate to set up secure connections. You can install either CA-signed or self-signed certificates in the container where AM runs, although you should have in mind that you will need to configure your applications to trust your self-signed certificates.
The following is an example about how to configure Apache Tomcat for HTTPS:
Configure Apache Tomcat for HTTPS
There are several ways of completing the tasks ahead, and it is beyond the scope of this document to explore them all.
If this procedure does not suit your environment, refer to your CA vendor documentation,
the keytool command documentation, or Java container documentation for more information.
-
Stop Apache Tomcat.
-
Ensure you have a keystore containing the appropriate certificates:
-
If you have CA certificates, import them in a new keystore using the
keytoolcommand. For example, if you have root, intermediate, and primary certificates, import them in the same keystore you used when generating your certificate signing request (CSR):$ keytool -importcert -alias root -file myrootCA.cert \ -keystore /path/to/tomcat_keystore.pfx -storetype PKCS12 $ keytool -importcert -alias intermediate -file myintCA.cert \ -keystore /path/to/tomcat_keystore.pfx -storetype PKCS12 $ keytool -importcert -alias mysite.example.com -file mypriCA.cert \ -keystore /path/to/tomcat_keystore.pfx -storetype PKCS12
-
If you need a self-signed certificate, create a new self-signed key pair with the
keytoolcommand.For example:
$ cd /path/to/tomcat/conf/ $ keytool -genkey -alias am.example.com -storetype PKCS12 -keyalg RSA -validity 730 \ -keysize 2048 -keystore tomcat_keystore.pfx -dname 'CN=am.example.com' -ext 'san=dns:am.example.com'
-
-
Create an SSL connector configuration in Apache Tomcat’s
conf/server.xmlconfiguration file, and specify your keystore file, type, and password.Note that there are different types of SSL connectors, and that implementation details may change across Tomcat versions. This example creates a JSSE connector in Tomcat as provided as part of the Java runtime:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="200" SSLEnabled="true" scheme="https" secure="true" keystoreFile="/path/to/tomcat_keystore.pfx" keystoreType="PKCS12" keystorePass="keystore_password" clientAuth="false" sslProtocol="TLS" />You may need different settings depending on your configuration and version of Apache Tomcat. See the documentation for your version for more information.
-
Start Tomcat.
-
Verify that you can connect to Apache Tomcat on port 8443 over HTTPS.
If you used self-signed certificates, your browser would not trust the certificate, because the certificate is self-signed and not signed by any of the CAs stored in your browser.
Figure 1. Unknown CertificateIf you recognize the subject and issuer of your certificate, and so can choose to trust the certificate, save it into your browser’s trust store.
-
Deploy and configure AM.
-
To share the self-signed certificate in your container with other applications or servers, see Share self-signed certificates.
Share self-signed certificates
How you configure the containers where AM and your applications run to use self-signed certificates depends on your web application server or web server software. The following basic principles apply:
-
First, your container requires its own certificate for setting up secure connections.
-
Second, the clients connecting must be able to trust the container’s certificate. Generally, this means that clients recognize the container’s certificate because they have a copy of the public certificate stored somewhere the client trusts.
-
Third, if you use certificate authentication in AM, AM must also be able to find a copy of the client’s public certificate to trust the client, most likely by finding a match with the certificate stored in the client profile from the identity repository. How you include client certificates in their identity repository entries depends on your identity repository more than it depends on AM.
Some client applications let you trust certificates blindly. This can be helpful when working in your lab or test environment with self-signed certificates. For example, you might want to use HTTPS with the AM RESTful API without having the client recognize the self-signed server certificate:
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate'
{
curl: (60) Peer certificate cannot be authenticated with known CA certificates
}The curl command performs SSL certificate verification by default,
using a "bundle" of CA-signed public keys.
If the default bundle file is not adequate, you can specify an alternate file using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in the bundle,
the certificate verification probably failed due to a problem with the certificate
(it might be expired, or the name might not match the domain name in the URL).
If you would like to turn off curl’s verification of the certificate for test purposes only,
use the --insecure option.
$ curl \
--request POST \
--insecure \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate'
{
"tokenId":"rMLhJjWVo…MAAlMxAAA.*",
"successUrl":"/am/console",
"realm":"/alpha"
}When you use a self-signed certificate for your container, clients connecting must be able to trust the container certificate. Your browser makes this an easy, but manual process. For other client applications, you must import the certificate into the truststore used by the client. By default, Java applications can use the $JAVA_HOME/lib/security/cacerts
store. The default password is changeit.(1)
The following steps demonstrate how to import a self-signed certificate into the Java cacerts store:
-
Export the certificate from the keystore:
$ cd /path/to/tomcat/conf/ $ keytool \ -exportcert \ -alias am.example.com \ -file am.crt \ -storetype JCEKS -keystore keystore.jceks Enter keystore password: Certificate stored in file <am.crt>; -
Import the certificate into the trust store:
$ keytool \ -importcert \ -alias am.example.com \ -file am.crt -trustcacerts \ -keystore $JAVA_HOME/lib/security/cacerts Enter keystore password: Owner: CN=am.example.com, OU=Admin, O=example.com Issuer: CN=am.example.com, OU=Admin, O=example.com Serial number: 4e789e40 Valid from: Tue Sep 20 16:08:00 CEST 2011 until: Mon Dec 19 15:08:00 CET 2011 Certificate fingerprints: MD5: 31:08:11:3B:15:75:87:C2:12:08:E9:66:00:81:61:8D SHA1: AA:90:2F:42:0A:F4:A9:A5:0C:90:A9:FC:69:FD:64:65:D9:78:BA:1D Signature algorithm name: SHA1withRSA Version: 3 Trust this certificate? [no]: yes Certificate was added to keystore
(1) Alternatively, you can specify the trust store for a Java application,
such as -Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit.
Use stronger encryption algorithms
AM encrypts and decrypts system passwords and the keys used in the configuration, and by components such as agents. The default encryption algorithm is Java Cryptography Extension (JCE) PBEWithMD5AndDES.
If you need a more secure encryption algorithm, use the Advanced Encryption Standard (AES) Key Wrap algorithm (RFC3394). AM’s implementation of AES Key Wrap uses the Password-Based Key Derivation Function 2 (PBKDF2) (RFC2898) with HMAC-SHA1. This lets you choose key size hash algorithms, such as SHA256, SHA384, or SHA512.
|
The AES Key Wrap encryption algorithm is only enabled when installing AM. There is no current upgrade path for existing installations. You must also Configure |
Configure AES Key Wrap encryption for Tomcat
-
Edit your container startup scripts, for example
setenv.sh, to set the following JVM system properties in Tomcat:JAVA_OPTS="$JAVA_OPTS -Dcom.iplanet.security.encryptor=org.forgerock.openam.shared.security.crypto.AESWrapEncryption"(1) JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.iterations=10000"(2) JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.useextractandexpand=true"(3) JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.size=256"(4) JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.digest=SHA512"(5)1 Enables use of AES Key Wrap encryption. 2 Specifies the iteration count of the encryption key. Large iteration counts, for example, of 20,000, slow down brute-force attacks when passwords are of low quality (less than 20 characters and easy to predict). AM does not have an iteration count requirement. However, it will log a warning if both of the following conditions are true: -
The number of iterations is less than 10,000.
-
The AM encryption key is less than 20 characters long.
3 Enables the algorithm to reduce the performance cost of AES Key Wrap encryption even when high-iteration counts are used. If this property is unset, and you configured a large iteration count, AM startup times may see a performance impact if there are many agents in your deployment. Determine the optimal iteration count based on the security and performance requirements of your deployment. 4 Specifies the size of the encryption key. Configure the key size to meet the needs of your deployment. 5 Specifies the digest algorithm. Possible values are SHA1,SHA256,SHA384, orSHA512. Configure the digest algorithm to meet the needs of your deployment.You cannot change these configuration parameters once AM has been installed. -
Configure ssoadm for AES Key Wrap encryption
After you enable AES key wrap encryption, update the ssoadm command for it to work with the new encryption settings.
Add the following properties to the /path/to/ssoadm/setup and /path/to/ssoadm/bin/ssoadm commands:
-Dcom.iplanet.security.encryptor=org.forgerock.openam.shared.security.crypto.AESWrapEncryption
-Dorg.forgerock.openam.encryption.key.iterations=10000
-Dorg.forgerock.openam.encryption.key.size=256
-Dorg.forgerock.openam.encryption.key.digest=SHA512Deploy AM
After you have downloaded AM software, deploy it to your installed application container.
Deploying AM only extracts the files into the application container, prior to installation and configuration. Deploying AM also makes LDIF files available, which can be used to prepare datastores for use with AM.
|
After deploying AM, but before installation, your application container serves AM’s installer (or upgrader, if performing an upgrade) user interfaces. We recommend that any external network access to the application container is suspended until the install, or upgrade, is complete. When complete, AM prevents access to the installer, or upgrader UI itself. |
The AM-8.0.1.war file contains the AM server.
How you deploy the .war file depends on your web application container.
-
Deploy the
.warfile on your container.For example, copy the file to deploy on Apache Tomcat.
$ cp AM-8.0.1.war /path/to/tomcat/webapps/am.war
In development or demonstration deployments, change the
.warfile name toam.warwhen deploying in Tomcat, so that the deployment URI is/am.-
Change the file name to something other than
am.warwhen deploying to a production environment so the deployment URI isn’t/am. Your deployment URI in production shouldn’t disclose the kind of software it is hosting. -
AM requires a deployment URI with a non-empty string after
/. Don’t deploy AM in the root context. For example, don’t rename the.warfile toROOT.warbefore deploying on Tomcat.
It can take several seconds for AM to be deployed in your container.
-
-
Go to the initial configuration page. For example,
https://am.example.com:8443/am.
AM is now ready for installation.
-
You can now configure datastores using the files created during deployment. Learn more in Prepare datastores.
Prepare datastores
AM stores different types of information. At a high-level, you can divide information into the following types:
- Configuration
-
Relatively static information that doesn’t change frequently after initial setup. Only administrative users can change it.
- Runtime data
-
Dynamic information that changes at runtime, often due to end user action. Examples of runtime data are identities, CTS tokens, policies, sessions, and applications.
Apart from identity data, AM stores all data after the installation process in its configuration store. This keeps basic deployments simple.
For advanced and high-load deployments, you can configure different sets of replicated DS servers to keep distinct data types separate and to tune DS for different requirements.
AM supports the following datastores:
| Store name | Type of data | Required during installation? |
|---|---|---|
Configuration store (PingDS or FBC) |
Static configuration (properties and settings used by the AM instance). |
Yes |
Identity or user store |
Stores identity profiles; that is, information about the users, devices, or things that authenticate to your systems. You can also configure AM to access existing directory servers to get identity profiles. |
No, but you can configure one during the installation process. |
Policy store |
Stores policy-related data, such as policies, policy sets, and resource types. |
No |
Application store |
Stores application-related data, such as web and Java agent configurations, federation entities and configuration, and OAuth 2.0 client definitions. |
No |
CTS token store |
Stores information about sessions, SAML v2.0 assertions, OAuth 2.0 tokens, and session denylists and allowlists. |
No |
UMA store |
Stores information about UMA resources, labels, audit messages, and pending requests. |
No |
LDAP datastores
The following table lists the supported directory servers for storing different data types:
| Directory server | Versions | Configuration | Apps / policies | CTS | Identities | UMA |
|---|---|---|---|---|---|---|
PingDS |
7.3 and later |
✔ |
✔ |
✔ |
✔ |
✔ |
Oracle Unified Directory |
12c |
✔ |
||||
Microsoft Active Directory |
2019, 2022, 2025 |
✔ |
The procedure for preparing directory servers for AM to use is similar for each data type and includes the following steps:
-
If you don’t have an existing directory server, install the directory server software; for example, PingDS.
-
As the directory administrator, you may need to perform the following steps:
-
Apply the relevant schema to the directory.
-
Create indexes to optimize data retrieval from the directory server.
-
Create a user account with the minimum required privileges for AM to bind to the directory server and access necessary data.
-
To prepare the datastores AM needs during installation, read the following pages:
Where do I find more information about the other datastores?
You can configure all datastores except the configuration store after you install AM:
File-based configuration store
File-based configuration (FBC) is best-suited to a DevOps-style deployment, with the associated tools and practices of that approach.
Static FBC data is written to configuration files in the file system and checked into a source control system, such as Git.
AM instances are created as Docker images, with the FBC incorporated into the image.
You can insert variables into these configuration files before you check them into source control. The variables are substituted with the appropriate values at runtime when you start the Docker container. Using variables lets you reuse the same base configuration files for multiple instances, and different staging environments. For example, development, QA, or pre-production, which are then promoted to production.
Learn more about FBC in Store configuration data in JSON files.
Learn more about installing AM instances with Kubernetes in the ForgeOps documentation.
Prepare the truststore
PingDS requires secure connections using LDAPS. To connect to a DS server securely, AM needs access to DS’s CA certificate. AM also needs access to CA certificates for making secure connections to other sites; for example, connections to social providers using HTTPS.
To give AM access to these certificates, you create a truststore that contains the certificates, and configure AM’s web application container to use that truststore when starting up.
AM uses a single truststore for LDAPS and outbound HTTPS connections. This truststore must contain the CA certificates of the sites with which AM communicates securely.
By default, Apache Tomcat loads the truststore configured for its JVM (for example, $JAVA_HOME/JRE/lib/security/cacerts).
The default JVM truststore contains multiple CA certificates. Its password, by default, is changeit.
As a best practice, create a new truststore with the certificates required for your AM deployment, then configure
your container to use it. Don’t add the DS CA certificate to the JVM’s truststore because JVM updates are likely
to overwrite the cacerts file.
To keep all existing CA certificates, you can copy the cacerts keystore file, change its password to a secure one,
and import the DS CA certificate into it. Then, configure your web application container, for
example, Apache Tomcat, to load that file as its truststore.
|
Using a separate truststore for AM means updates to the JVM truststore in patch releases aren’t taken into account. This can cause operational issues, for example, when distrusted root CA certificates are removed, or when new root CA certificates are added. To mitigate this risk, update the AM truststore periodically to reflect the latest JVM truststore settings. |
Create a truststore for AM
These steps create a copy of the default JVM truststore, and configure the AM web application container to use the new truststore:
-
Copy the default truststore. For example,
$JAVA_HOME/lib/security/cacerts, name ittruststore, and place it in a directory of your choice:$ cp $JAVA_HOME/lib/security/cacerts /path/to/truststoreIf you place the truststore in the
/path/to/amdirectory before you install AM, the installation process detects the directory isn’t empty and the installation fails.After AM is installed, you can move the truststore to a different directory. For example, the
/path/to/am/security/keystoresdirectory. -
For improved security, change the default password for the truststore.
The default password of the $JAVA_HOME/lib/security/cacertstruststore ischangeit.Use the
keytool -storepasswdoption to change the default password:$ keytool -storepasswd -keystore /path/to/truststore Enter keystore password: changeit New keystore password: new-password Re-enter new keystore password: new-password -
Export the DS certificate.
-
On the DS host, export the DS CA certificate.
DS uses a deployment ID and password to generate a CA key pair. Learn more in Deployment IDs.
Use the
dskeymgrcommand to export the CA certificate:$ /path/to/opendj/bin/dskeymgr \ export-ca-cert \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --outputFile /path/to/ca-cert.pem -
Copy the
ca-cert.pemfile to an accessible location on the AM host.
-
-
Import the DS CA certificate into the new truststore:
$ keytool \ -importcert \ -file /path/to/ca-cert.pem \ -keystore /path/to/truststoreEnter the keystore password when prompted and confirm you trust this certificate.
-
To configure the truststore in Apache Tomcat so that AM can access it, append the truststore settings to the
CATALINA_OPTSvariable in thesetenvfile.For example:
-
Linux
-
Windows
In
$CATALINA_BASE/bin/setenv.sh:export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \ -Djavax.net.ssl.trustStore=/path/to/truststore \ -Djavax.net.ssl.trustStorePassword=new-password \ -Djavax.net.ssl.trustStoreType=jks"In
$CATALINA_BASE/bin/setenv.bat:set "CATALINA_OPTS=%CATALINA_OPTS% -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m - -Djavax.net.ssl.trustStore=/path/to/truststore - -Djavax.net.ssl.trustStorePassword=new-password - -Djavax.net.ssl.trustStoreType=jks"Read your specific container’s documentation for information on configuring truststores.
After AM is installed, you can move the truststore to a different location. For example, the
/path/to/am/security/keystores/. If you do, remember to update the truststore path in the container configuration. -
Prepare a configuration store
This page explains how to prepare a single DS server as a configuration datastore. Make sure DS replicas use the same configuration.
Installing DS with a setup profile creates the required backend, schema, bind user, and indexes:
-
Follow the steps in Install DS for AM configuration in the PingDS documentation.
-
Install AM to use the prepared DS directory server as a configuration store.
The default bind DN of the service account to connect to the configuration store is:
uid=am-config,ou=admins,ou=am-config
-
Share the configuration store certificate with the AM container to prepare for TLS/LDAPS.
Communication with the configuration store must use a secure connection.
-
On the DS host, export the DS CA certificate.
DS uses a deployment ID and password to generate a CA key pair. Learn more in Deployment IDs.
Use the
dskeymgrcommand to export the CA certificate:$ /path/to/opendj/bin/dskeymgr \ export-ca-cert \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --outputFile /path/to/ca-cert.pem -
Copy the
ca-cert.pemfile to an accessible location on the AM host.
-
Import the DS certificate into the AM truststore:
$ keytool \ -importcert \ -file /path/to/ca-cert.pem \ -keystore /path/to/am/security/keystores/truststore
Learn more about configuring AM’s truststore in Prepare the truststore.
-
-
When the certificate is in place, continue installing AM.
| After setting up the configuration store, you can enhance security by configuring mTLS authentication to that store and rotating the mTLS certificates periodically. Learn more in mTLS for configuration stores. |
Store configuration data in JSON files
AM can read its configuration from JSON files instead of directory servers. Configuration stored in JSON files is called file-based configuration (FBC).
File-based configuration (FBC) is best-suited to a DevOps-style deployment, with the associated tools and practices of that approach.
Static FBC data is written to configuration files in the file system and checked into a source control system, such as Git.
AM instances are created as Docker images, with the FBC incorporated into the image.
You can insert variables into these configuration files before you check them into source control. The variables are substituted with the appropriate values at runtime when you start the Docker container. Using variables lets you reuse the same base configuration files for multiple instances, and different staging environments. For example, development, QA, or pre-production, which are then promoted to production.
In an existing deployment, you can migrate to FBC after you’ve upgraded to AM 8.
If you’re setting up an AM deployment from scratch, read Passive install with FBC to create a file-based configuration store.
How AM reads FBC
An initial startup with FBC enabled writes configuration files with the following structure:
- noninteractive-install.properties
-
You specify a limited set of environment variables on startup. AM writes these environment variables to a configuration properties file,
/path/to/am/config/config/services/noninteractive-install.properties, when the server starts.The values in the
noninteractive-install.propertiesfile are used on subsequent startups, unless you set these properties in the deployment configuration layer. - Baseline configuration layer
-
The baseline configuration files are read-only and are located under
/path/to/am/config/baseline/config/services.These files include placeholders that are resolved with values of environment variables. The baseline layer lets you define a configuration that works across different environments, with a few distinct parameters that are specific to each server instance.
For example, three instances might have the same configuration but different keystore locations and URLs. Those differences are resolved with environment variables at startup.
- Deployment configuration layer
-
The deployment configuration files are read/write and are located under
/path/to/am/config/config/services.Changes made through the AM admin UI and REST API are written to the deployment configuration layer.
This layer overrides the baseline configuration on a file-by-file basis. In other words, AM reads its configuration from the baseline configuration until you add corresponding files to the deployment configuration layer.
In summary, AM looks for its configuration in the following order:
-
Deployment configuration layer
-
Baseline configuration layer
-
noninteractive-install.properties
FBC and AM sites
A site refers to multiple AM servers that share a single configuration store.
When your configuration is stored in files, you don’t need to group AM servers into sites because each AM server has its configuration stored locally.
Instead of pointing at a shared configuration store, servers using FBC are exact copies of each other. Each server is assumed to be in its own discrete site, along with its configuration.
The following diagram illustrates the difference between configuration stored in an LDAP store and configuration stored in files on the file system:
If you migrate to FBC from an LDAP configuration store, the migration utility enforces a single site and a single server instance. If your deployment has more than one server or more than one site, the migration retains the first site and uses this site in the resulting output configuration. If your deployment has no sites configured, a single site is added.
Prepare identity repositories
AM accesses user identity data from one or more identity repositories.
In most deployments, AM connects to existing LDAP directory servers for user identity data, because it shares data in an identity repository with other applications.
|
You shouldn’t configure more than one writable identity repository in a single realm. AM tries 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 PingIDM. |
To prepare identity repositories, read the following sections:
-
If you’re installing a new PingDS instance for identity data, read Install and configure PingDS for identity data.
-
If you’re connecting AM to an existing identity repository, read Configure existing directory servers for identity data.
Install and configure PingDS for identity data
This section shows how to install and set up a new DS server for identity data. Make sure DS replicas use the same configuration.
Installing DS with a setup profile creates the required backend, schema, bind user, and indexes.
| The bind account for the identity store is fetched when AM starts up. If you change the account (DN or password) while AM is running, you must restart AM to take account of the changes. Otherwise, you’ll encounter bind failures with persistent searches. |
-
Follow the steps in Install DS for AM identities in the PingDS documentation.
-
Share the identity store certificate with the AM container to prepare for TLS/LDAPS. Communication with the identity store must use a secure connection.
-
On the DS host, export the DS CA certificate.
DS uses a deployment ID and password to generate a CA key pair. Learn more in Deployment IDs.
Use the
dskeymgrcommand to export the CA certificate:$ /path/to/opendj/bin/dskeymgr \ export-ca-cert \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --outputFile /path/to/ca-cert.pem -
Copy the
ca-cert.pemfile to an accessible location on the AM host.
-
Import the DS certificate into the AM truststore:
$ keytool \ -importcert \ -file /path/to/ca-cert.pem \ -keystore /path/to/am/security/keystores/truststore
Learn more about configuring AM’s truststore, in Prepare the truststore.
-
-
If you didn’t install DS using a setup profile, perform the following steps to update the permissions in a PingDS identity repository.
If you are using a directory server other than PingDS, apply the relevant LDIF files using the appropriate tools.
-
Edit the
opendj_userinit.ldifLDIF file in the/path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendjdirectory, replacing all variables that are surrounded by at (@ ) symbols with a value specific to your directory server.For example, in the
opendj_userinit.ldifLDIF file you must replace all instances of @userStoreRootSuffix@ with the root suffix you specified when configuring the DS identity store. The default isou=identities. -
Use the
ldapmodifycommand to add the updated LDIF data to the DS instance.For example:
$ /path/to/opendj/bin/ldapmodify \ --hostname 'ds.example.com' \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --truststorepassword:file /path/to/opendj/config/keystore.pin \ --continueOnError \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ /path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_userinit.ldifYou can find more information on this LDIF file, and equivalent files for supported directory servers, in Set up directory schemas with LDIF.
-
If you intend to use web authentication, or perform device profiling with the Ping SDKs, you might need to update the directory server schema. For a PingDS repository, you can update the schema by applying the following LDIF files:
-
/path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif -
/path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldifFor example:
$ /path/to/opendj/bin/ldapmodify \ --hostname 'ds.example.com' \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --truststorepassword:file /path/to/opendj/config/keystore.pin \ --continueOnError \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ /path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif\ /path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldifYou can find more information on these LDIF files in Set up directory schemas with LDIF. For directory servers other than PingDS, adapt the
opendj_*.ldiffiles accordingly.
-
-
-
Proceed to configure the identity store in AM.
The bind DN of the service account to use when configuring the identity store in AM is
uid=am-identity-bind-account,ou=admins,ou=identities.
Configure existing directory servers for identity data
It is common for AM to access identity data from an existing directory server. AM requires a user account to connect to the directory server, and AM LDAP schema to update entries with AM-related identity data.
You can find a list of supported directory servers in Directory servers.
The following sections show you how to prepare an existing identity repository for use in AM:
Create a directory server user for AM connections
AM connects to a directory server with a service account that you specify in the AM identity repository configuration. This service account is known as the AM bind account.
Specifying the directory administrator as the AM bind account isn’t recommended for production deployments as it would give AM directory administrator privileges to the identity repository.
Instead, create a separate AM bind account with fewer access privileges than the directory administrator so that you can assign the appropriate level of privileges for the AM bind account.
You need to consider two areas of permission for the AM bind account:
- Schema Update Privileges
-
AM needs to update the directory schema when you configure a new identity repository and when you upgrade AM software. If the AM bind account has schema update privileges, AM can update the schema dynamically during identity repository configuration and during AM upgrades. If the AM bind account doesn’t have schema update privileges, you must update the schema manually before configuring a new identity repository and before upgrading AM.
- Directory Read and Write Access Privileges
-
If you want AM to create, update, and delete user entries, then the AM bind account must have full read and write access to the identity data in the directory. If you are using an identity repository as a read-only user directory, then the AM bind account needs read privileges only.
The level of access privileges you give the AM bind account is specific to each AM deployment. Work with your directory server administrator to determine the appropriate level of privileges as part of the process of preparing your identity repositories.
Create a bind account in Active Directory for AM connections
The following procedure gives an example of creating a bind account in Active Directory:
Perform these steps to create a user that AM can use to connect to Active Directory. These steps are one example, consult with your Active Directory administrator on how best to create an account.
-
Create a new user account in the Active Directory domain. For example, in Windows 2019:
-
In the Active Directory Users and Computers tool, right-click Users in the domain, and select New > User.
-
Provide descriptive values for the new user, and a logon name such as
AM-Bind-Account. -
Click Next.
-
Enter a strong password for the bind account, disable the User must change password at next logon option, and click Next.
-
Review the details of the new account, and click Finish.
-
-
Give the new bind account access to the directory data:
-
In the Active Directory Users and Computers tool, right-click the domain that contains your users, and select Delegate Control.
-
Add the bind account you created in the previous step, and click Next.
-
Select the tasks you want to allow the AM bind account to perform from the list.
For example, to allow read and write access to users, enable the
Create, delete, and manage inetOrgPerson accountstask. -
After assigning the tasks you want to allow the AM bind account to perform, click Finish.
You can now set up the necessary schema in the directory server.
The bind account to use when configuring the identity store in AM is the full DN of the user, for example
uid=AM-Bind-Account,ou=Users,dc=example,dc=org. -
Update the schema in an identity repository
AM can add the necessary LDAP schema definitions itself, if it has sufficient privileges to do so, or you can apply the LDAP schema definition LDIF files manually if required. Read the following procedures:
Prepare an identity repository with manual schema updates
If the AM bind account doesn’t have permission to update schema then you must configure existing datastores using manual schema updates. To do this, you must update the directory server schema of the existing identity repository manually at the following times:
-
Before you configure the identity repository as part of initial AM configuration.
-
Before you configure an identity repository after initial AM configuration.
-
Whenever you upgrade AM.
A number of LDIF files are provided in the AM .war file for supported identity directory servers.
The path is /path/to/tomcat/webapps/am/WEB-INF/template/ldif/directory-type, where directory-type is one of the following:
-
adfor Microsoft Active Directory -
adamfor Microsoft Active Directory Lightweight Directory Services -
opendjfor PingDS and Oracle Unified Directory
You can find more information on the LDIF files in Set up directory schemas with LDIF.
The following steps update the schema in an Active Directory identity repository. For other directory servers, apply the relevant LDIF files using the appropriate tools.
-
Edit the LDIF files in the
/path/to/tomcat/webapps/am/WEB-INF/template/ldif/addirectory, replacing any variables that are surrounded by at (@ ) symbols with a value specific to your directory server.For the Active Directory LDIF files you must replace all instances of @userStoreRootSuffix@ with the root suffix used by your Active Directory identity store, for example
DC=example,DC=org. -
Using an Active Directory administrator account, add the required AM schema extensions to your identity repository.
For example, in PowerShell, run the
ldifdecommand to import the user, device print, and dashboard schema extensions:PS C:\Users\Administrator> cd \path\to\am\WEB-INF\template\ldif\ad PS C:\path\to\am\WEB-INF\template\ldif\ad> ldifde -i -f .\ad_user_schema.ldif Connecting to "domain.example.org" Logging in as current user using SSPI Importing directory from file ".\ad_user_schema.ldif" Loading entries................................................................. 64 entries modified successfully. The command has completed successfully PS C:\path\to\am\WEB-INF\template\ldif\ad> ldifde -i -f .\ad_deviceprint.ldif Connecting to "domain.example.org" Logging in as current user using SSPI Importing directory from file ".\ad_deviceprint.ldif" Loading entries................................................................. 6 entries modified successfully. The command has completed successfully PS C:\path\to\am\WEB-INF\template\ldif\ad> ldifde -i -f .\ad_dashboard.ldif Connecting to "domain.example.org" Logging in as current user using SSPI Importing directory from file ".\ad_dashboard.ldif" Loading entries................................................................. 6 entries modified successfully. The command has completed successfully -
If you intend to use push or web authentication, apply the following LDIF files:
-
/path/to/tomcat/webapps/am/WEB-INF/template/ldif/ad/ad_pushdevices.ldif -
/path/to/tomcat/webapps/am/WEB-INF/template/ldif/ad/ad_webauthndevices.ldif
You can find more information on these LDIF files, and the equivalent files for supported directory servers, in Set up directory schemas with LDIF.
-
-
Proceed to configure the identity store in AM.
If you updated the schema to use web authentication, you must add webauthnDeviceProfilesContainerto the LDAP User Object Class property when configuring the identity store in a realm. This property is located on the User Configuration tab.
Prepare an identity repository with automatic schema updates
If the bind account has permission to update schema then you can allow AM to update the schema automatically.
To allow AM to update the schema, you must first configure AM to be able to access the directory server, and enable the Load Schema option, by performing the following steps:
-
Configure the directory server in AM by following the instructions in Configure an identity store.
Enable the Load Schema option before saving your changes, and AM will apply the necessary schema to the directory server. The schema is loaded as part of configuring the identity store in AM. No further configuration is required.
-
Verify that the new identity repository is correctly configured in AM by following the instructions in Test identity repository access.
Set up directory schemas with LDIF
AM installation deploys several LDIF files that can be used to create the schemas required by AM. LDIF files are available for Microsoft Active Directory, Microsoft Active Directory Lightweight Directory Services, PingDS and Oracle Unified Directory.
The following tables provide descriptions for each LDIF file:
| LDIF File | Description |
|---|---|
ad_config_schema.ldif |
Obsolete. Active Directory isn’t supported as a configuration store. |
ad_dashboard.ldif |
LDIF to support the dashboard service. |
ad_deviceprint.ldif |
LDIF to support the device print service. |
ad_kba.ldif |
LDIF to support the User Self-Service’s knowledge-based questions and answers service. |
ad_oathdevices.ldif |
LDIF to support registered devices for the OATH authentication service. |
ad_pushdevices.ldif |
LDIF to support registered devices for the PUSH notification service. |
ad_user_schema.ldif |
LDIF for the user schema. |
ad_webauthndevices.ldif |
LDIF to support registered devices for the Web Authentication (WebAuthn) authentication service. |
| LDIF file | Description |
|---|---|
adam_dashboard.ldif |
LDIF to support the dashboard service. |
adam_deviceprint.ldif |
LDIF to support the device print service. |
adam_kba.ldif |
LDIF to support the User Self-Service’s knowledge-based questions and answers. |
adam_oathdevices.ldif |
LDIF to support registered devices for the OATH authentication service. |
adam_pushdevices.ldif |
LDIF to support registered devices for the PUSH notification service. |
adam_user_schema.ldif |
LDIF for the user schema. |
adam_webauthndevices.ldif |
LDIF to support registered devices for the Web Authentication (WebAuthn) authentication service. |
| LDIF file | Description |
|---|---|
opendj_bounddevices.ldif |
LDIF to support bound devices. |
opendj_dashboard.ldif |
LDIF to support the dashboard service. |
opendj_deviceprint.ldif |
LDIF to support the device print service. |
opendj_deviceprofiles.ldif |
LDIF to support storage of device information, collected by the SDK device authentication nodes. Apply this LDIF if you intend to use the Ping SDKs for device profiling. |
opendj_kba.ldif |
LDIF to support the User Self-Service’s knowledge-based questions and answers. |
opendj_oathdevices.ldif |
LDIF to support registered devices for the OATH authentication service. |
opendj_pushdevices.ldif |
LDIF to support registered devices for the PUSH notification service. |
opendj_user_index.ldif |
LDIF for the user repository indexes. |
opendj_user_schema.ldif |
LDIF for the user repository schema. |
opendj_userinit.ldif |
LDIF to set up user session initialization. |
opendj_webauthndevices.ldif |
LDIF to support registered devices for the Web Authentication (WebAuthn) authentication service. |
|
The |
Install AM
Production or production-like environments require a separate configuration store and CTS token store.
You can store the configuration in a DS server or in JSON files. File-based configuration (FBC) is best-suited to a DevOps-style deployment, with the associated tools and practices of that approach.
The CTS token store must be a DS server. If you store configuration in a DS server, AM stores CTS tokens there until you configure a separate LDAP store for them.
Learn more in Prepare datastores.
The following table provides information to help you install AM instances:
| Task or requirement | Resources |
|---|---|
Configure an instance interactively in a production or pre-production environment This can be the first instance of a site deployment. Interactive installation assumes a DS configuration store. |
|
Configure an instance without user interaction You can install an instance passively with either a DS configuration or file-based configuration. |
|
Configure an AM site and add an instance to the site A site lets you group multiple AM servers. |
Install multiple instances for high availability
Install multiple instances to maintain service availability. If one instance is down for any reason, another instance can respond instead. This means you need some type of component, such as a load balancer or a proxy server, between incoming traffic and AM to route around instances that are down.
AM uses a site for this purpose. In an AM site, multiple AM instances are configured in the same way, and accessed through a load balancer layer.
The load balancer can be implemented in hardware or software, but it is separate and independent from AM. When installed properly, a site configuration improves service availability, because the load balancer routes around AM instances that are down, sending traffic to other servers in the site.
You can find high-level deployment information in Deployment planning.
|
If you need to delete your AM configuration entirely and start again, you can find information in Delete and redeploy AM. |
Interactive install
During interactive installation, you customize the parameters of the AM deployment, such as the cookie domain and the settings of the configuration and datastores.
-
Installing the first instance creates the required configuration that the site will share.
You can specify the site configuration when you install the first instance or configure the site when the first instance is running.
-
By default, the cookie domain is set to the full URL of the first instance; for example,
server.west.example.com.You can change the cookie domain when you’re installing the first instance or later.
-
You can use a load balancer layer to protect AM services. The load balancer can restrict access to AM services, throttle traffic, offload HTTPS encryption, and so forth.
As an alternative, or in addition, you can use a separate reverse proxy.
-
When you are protecting AM with a load balancer or proxy service, configure your container so that AM can trust the load balancer or proxy service.
-
The container for each instance in the site must trust any certificate authorities (CA) used to sign certificates used by other instances in the site to communicate using SSL.
-
Successful authentication can depend on information about the authenticating user, such as the IP address where the request originated. When AM is accessed through a load balancer or proxy layer, pass this information along using request headers. Also, configure AM to consume and to forward the headers as necessary. Learn more in Handle HTTP request headers.
Follow these steps to install a single AM instance, or to install the first instance on a site.
-
Go to your deployment URL. For example,
https://am.example.com:8443/am. -
On the initial configuration page, click Create New Configuration.
-
Read the license agreement. Agree to the license agreement and click Continue.
-
On the Default User Password page, provide a password with at least eight characters for the AM Administrator,
amAdmin. -
Verify that the server settings are valid for your configuration.
- Server URL
-
Provide a valid URL to the base of your AM web container, including an FQDN.
In a test or QA environment, you can simulate the FQDN by adding it to your
/etc/hostsas an alias. The following example shows lines from the/etc/hostsfile on a Linux system where AM is installed:127.0.0.1 localhost.localdomain localhost ::1 localhost6.localdomain6 localhost6 127.0.1.1 am am.example.com - Cookie Domain
-
The domain for which created cookies will be valid. For example
example.com. - Platform Locale
-
The platform locale of your server. Supported locales include en_US (English), de (German), es (Spanish), fr (French), ja (Japanese), ko (Korean), zh_CN (Simplified Chinese), and zh_TW (Traditional Chinese).
- Configuration Directory
-
The directory to use for configuration files. AM must be able to write to this directory.
By default, the configuration directory is located in
$HOME/am, where $HOME corresponds to the user who runs the web container.
-
On the Configuration Data Store page, you can configure options related to AM configuration data.
The installation process stores AM configuration data in an existing DS server. You must have prepared the server as explained in Prepare a configuration store.
- SSL/TLS Enabled
-
Select this option to use LDAPS to communicate with the configuration store. DS is configured for LDAPS by default.
Before proceeding, make sure you have shared the DS certificate with the container where AM is running. Learn more in Prepare the truststore.
- Host Name
-
The FQDN of the DS server.
- Port
-
The LDAPS port of the DS server.
- Encryption Key
-
A randomly generated key that AM uses for different purposes. All the servers in the site must have the same encryption key.
The installer creates a random key automatically, which you can use.
- Root Suffix
-
The root suffix of the DS store.
The default base DN of a DS store when you configure it with the
am_configprofile isou=am-config. - Login ID
-
The bind DN to use to connect to the DS store.
The default bind DN of a DS store when you configure it with the
am_configprofile isuid=am-config,ou=admins,ou=am-config.Don’t use
cn=adminas the bind account. - Password
-
The password for the bind DN.
- Server configuration
-
-
New deployment
The installation is a new deployment, with its own configuration and identity stores.
If you choose this option, the next step is to configure the identity store.
-
Additional server for existing deployment
The installation is an additional server for an existing deployment, which uses the existing configuration and identity stores.
If you choose this option, you don’t need to configure the identity store. The installation uses the same stores as those of the existing deployment.
Learn more in Add a server to a site.
-
-
If you specified New deployment in the previous step, the User Data Store page appears as the next step. Use this page to configure where AM looks for identities.
AM must have write access to the directory service you choose, because it adds to the directory schema needed to allow AM to manage identity profiles in the identity store.
- User Data Store Type
-
If you have already provisioned a directory service with identities in a supported identity store, then select that type of directory from the options available.
- SSL/TLS Enabled
-
Select this option to use a secure connection. When using this option, make sure the trust store used by the JVM running AM has the necessary certificates installed. Learn more in Prepare the truststore.
- Directory Name
-
The FQDN of the identity store.
- Port
-
The LDAPS port of the identity store. Make sure the port you define corresponds to the port the directory server listens to for StartTLS or SSL connections.
- Root Suffix
-
The base DN of the identity store.
If you installed PingDS with the
am-identity-storeprofile, the base DN isou=identities. - Login ID
-
The directory administrator user DN. The administrator must be able to update the schema and identity profiles.
If you installed PingDS with the
am-identity-storeprofile, the bind DN to use here isuid=am-identity-bind-account,ou=admins,ou=identities. - Password
-
The password for the directory administrator user.
If you installed PingDS with the
am-identity-storeprofile, this password is the one you set witham-identity-store/amIdentityStoreAdminPassword.
-
On the Site Configuration page, you can set up AM as part of a site where the load is balanced across multiple AM servers.
When you deploy multiple servers, AM automatically enables session high availability.(1) AM stores session data in a directory service that is shared by multiple AM servers. The shared storage means that if an AM server fails, other AM servers in the deployment have access to the user’s session data and can serve requests about that user. As a result, the user doesn’t have to log in again.
You can also set up a site after initial installation and configuration. Learn more in Configure a site with the first server.
-
Check the details on the Configurator Summary page.
-
If anything needs changing, click Previous to return to earlier pages and update as needed.
-
If everything is correct, click Create Configuration to proceed. The configuration progress is shown in the browser and also output to the installation log.
-
-
When the configuration process completes, click Proceed to Login, and log in as the
amAdminadministrator.After logging in, the Realms page is displayed.
-
Restrict permissions to the configuration directory to prevent other users accessing configuration files.
-
The AM install wizard uses three libraries that should be removed after installation for security reasons.
When your installation is complete, remove the following .jar files from the
WEB-INF/libdirectory:-
click-extras-2.3.0.jar -
click-nodeps-2.3.0.jar -
velocity-1.7.jarThese files are used only by the install and upgrade wizards. Removing them will have no effect on your installed instance.
You must also remove the references to
click-servletfrom the deployment descriptor file. Edit/path/to/tomcat/webapps/am/WEB-INF/web.xmlto remove the following mappings:<servlet> <servlet-name>click-servlet</servlet-name> <servlet-class>org.apache.click.ClickServlet</servlet-class> </servlet> ... <servlet-mapping> <servlet-name>click-servlet</servlet-name> <url-pattern>*.htm</url-pattern> </servlet-mapping> -
-
Review the suggested next steps after installing AM.
(1) You can configure AM to store sessions in the Core Token Service (CTS) token store or on the client. Because client-side sessions reside in HTTP cookies, they don’t need to be retrieved from a persistent datastore. In the event of a server failure, they can be retrieved from the cookies. AM doesn’t store client-side sessions in the CTS token store. You can find details about sessions in Introduction to sessions.
Passive install
Passive installation, also called non-interactive or silent installation, lets you set up AM with minimal user intervention.
There are two methods of installing AM passively:
File-based configuration (FBC) is best-suited to a DevOps-style deployment, with the associated tools and practices of that approach.
Learn more in Deployment configuration locations.
Passive install with FBC
If you store your configuration in JSON files (file-based configuration) you can set up AM with no user interaction when you start the web application container.
The following sections describe the process to install an AM server with (file-based configuration) (FBC).
| Before you start, read How AM reads FBC to understand the FBC layers. |
These topics assume you have a DS instance up and running, and that the instance has been installed as an identity store, CTS store, and policy and application store.
| You can find information on setting up an evaluation DS server that stores all three data types in Step 2. Prepare your datastore. |
FBC initial startup
A passive FBC installation requires a few mandatory configuration properties set as environment variables on initial startup. These properties specify that it’s a file-based configuration, set the AM server host and port, and set the connection details to the identity and policy stores.
If you don’t explicitly set a mandatory configuration property, its default value is used, as listed in the tables in this section. This lets you get started with FBC with minimal configuration upfront and add the required configuration after startup.
FBC installation writes files to the location specified by the value of com.sun.identity.configuration.directory. If you don’t set a value for this property, AM uses the location of the application container (for example, /path/to/tomcat/webapps/am) and the application context (for example, /am) to create a file in ~/openamcfg with the derived name. That file contains the path to the configuration folder.
Mandatory startup properties
This table lists the minimum environment variables required to install a server with FBC. If you don’t specify a variable listed here, its default value is used on startup.
| Environment variable | Description | Valid values | Default |
|---|---|---|---|
|
Whether FBC is enabled. |
true, false |
false |
|
Path to the folder that holds the configuration files |
Any writeable folder on the file system |
|
|
The server protocol used for the AM server instance configuration. |
https, http |
http |
|
The fully qualified domain name that will be used for the AM server instance configuration |
Any valid FQDN |
|
|
The port on which this server instance will be available. |
Any valid port number |
8080 |
|
The web application context on which this server instance will be available. |
/web application context |
|
|
The encryption key value that will be used to encrypt passwords and other sensitive FBC configuration. |
An alphanumeric string |
A random secret is generated if not provided |
|
Connection string for the user store in the format host:port. |
A valid server connection string |
|
|
Bind DN to connect to the user store. |
Valid bind DN |
|
|
Bind password for the user store |
Alphanumeric value |
|
|
Connection string for the application and policy stores in the format host:port. |
A valid server connection string |
|
|
Bind password for the user store |
Alphanumeric value |
|
|
You can’t specify the password of the In production deployments, you must set up a secret store to store the Learn more in Store the amAdmin password in a secret store. |
Additional startup properties
These tables list all the properties you can set as environment variables on startup.
The properties listed in these tables aren’t written to the noninteractive-install.properties file. After an initial startup, you must specify these values in the deployment configuration layer. Otherwise, you’ll need to include them as environment variables for each subsequent startup.
|
General startup properties
| Environment variable | Description | Valid values | Default |
|---|---|---|---|
|
The location of the debug logs. |
A writeable location on the file system |
|
Startup properties for the identity store
| Environment variable | Description | Valid values | Default |
|---|---|---|---|
|
Whether AM connects to the identity store over SSL |
true, false |
true |
|
Whether mTLS is enabled for the identity store(1). |
true, false |
false |
(1) This property requires you to configure secrets so you can’t set it on an initial install.
The root suffix for the identity store defaults to ou=identities.
Startup properties for the CTS store
| Environment variable | Description | Valid values | Default |
|---|---|---|---|
|
Connection string for the CTS store in the format host:port |
A valid server connection string |
The value of |
|
Bind DN to connect to the CTS store |
Valid bind DN |
|
|
Bind password for the CTS store |
Alphanumeric value |
The value of |
|
Whether AM connects to the CTS store over SSL |
true, false |
The value |
|
Whether mTLS is enabled for the CTS store |
true, false |
false |
The base DN for the CTS store defaults to ou=famrecords,ou=openam-session,ou=tokens.
Startup properties for the application store
| Environment variable | Description | Valid values | Default |
|---|---|---|---|
|
Connection string for the application store in the format host:port |
A valid server connection string |
The value of |
|
Bind DN to connect to the application store |
Valid bind DN |
|
|
Bind password for the application store |
Alphanumeric value |
The value of |
|
Whether AM connects to the application store over SSL |
true, false |
The value |
|
Not used for the application store |
– |
– |
The base DN for the application store defaults to ou=services,ou=am-config.
Startup properties for the policy store
| Environment variable | Description | Valid values | Default |
|---|---|---|---|
|
Connection string for the policy store in the format host:port |
A valid server connection string |
The value of |
|
Bind DN to connect to the policy store |
Valid bind DN |
|
|
Bind password for the policy store |
Alphanumeric value |
The value of |
|
Whether AM connects to the policy store over SSL |
true, false |
The value |
The base DN for the policy store defaults to ou=services,ou=am-config.
Startup properties for UMA stores
| Environment variable | Description | Valid values | Default |
|---|---|---|---|
|
Connection string for the UMA store in the format host:port |
A valid server connection string |
The value of |
|
Bind DN to connect to the UMA store |
Valid bind DN |
|
|
Bind password for the UMA store |
Alphanumeric value |
The value of |
|
Whether AM connects to the UMA store over SSL |
true, false |
The value |
|
Whether mTLS is enabled for the UMA store(1). |
true, false |
The value |
(1) This property requires you to configure secrets so you can’t set it on an initial install.
The root suffix for the UMA store defaults to ou=am-config.
Start the server with the mandatory FBC properties
The following command assumes you’re running AM in Apache Tomcat. It adds the required settings to the CATALINA_OPTS variable in the setenv file. You can also set these properties as JAVA_OPTS environment variables before you start the application container.
This command sets the following properties:
-
FBC to
true -
Location of configuration files to
/path/to/am-config -
Identity and application stores to
ds.example.com:1636 -
Identity and application store connection details to the values set if you install your /pingds/8 servers with the corresponding setup profiles.
-
Location of truststore to
/path/to/truststore. Learn more in Prepare the truststore. -
Truststore password to
new-password -
Truststore type to
jks
-
Linux
-
Windows
In $CATALINA_BASE/bin/setenv.sh:
export CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.identity.sm.sms_object_filebased_enabled=true \
-Dcom.sun.identity.configuration.directory=/path/to/am-config \
-Dam.server.fqdn=am.example.com \
-Dam.stores.user.servers=ds.example.com:1636 \
-Dam.stores.user.username=uid=am-identity-bind-account,ou=admins,ou=identities \
-Dam.stores.user.password=5up35tr0ng \
-Dam.stores.application.servers=ds.example.com:1636 \
-Dam.stores.application.password=5up35tr0ng \
-Djavax.net.ssl.trustStore=/path/to/truststore \
-Djavax.net.ssl.trustStorePassword=new-password \
-Djavax.net.ssl.trustStoreType=jks -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m"In $CATALINA_BASE/bin/setenv.bat:
set "CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.identity.sm.sms_object_filebased_enabled=true -
-Dcom.sun.identity.configuration.directory=/path/to/am-config -
-Dam.server.fqdn=am.example.com -
-Dam.stores.user.servers=ds.example.com:1636 -
-Dam.stores.user.username=uid=am-identity-bind-account,ou=admins,ou=identities -
-Dam.stores.user.password=5up35tr0ng -
-Dam.stores.application.servers=ds.example.com:1636 -
-Dam.stores.application.password=5up35tr0ng -
-Djavax.net.ssl.trustStore=/path/to/truststore -
-Djavax.net.ssl.trustStorePassword=new-password -
-Djavax.net.ssl.trustStoreType=jks -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m"-
Start the web application container where AM runs. For example:
$ bin/startup.sh Using CATALINA_BASE: /path/to/tomcat10 Using CATALINA_HOME: /path/to/tomcat10 Using CATALINA_TMPDIR: /path/to/tomcat10/temp Using JRE_HOME: /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home Using CLASSPATH: /path/to/tomcat10/bin/bootstrap.jar:/path/to/tomcat10/bin/tomcat-juli.jar Using CATALINA_OPTS: -Dcom.sun.identity.sm.sms_object_filebased_enabled=true -Dcom.sun.identity.configuration.directory=/path/to/am-config -Dam.server.fqdn=am.example.com -Dam.stores.user.servers=ds.example.com:1636 -Dam.stores.user.username=uid=am-identity-bind-account,ou=admins,ou=identities -Dam.stores.user.password=5up35tr0ng -Dam.stores.application.servers=ds.example.com:1636 -Dam.stores.application.password=5up35tr0ng -Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=new-password -Djavax.net.ssl.trustStoreType=jks -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m Tomcat started. -
In the configuration file directory, locate the
noninteractive-install.propertiesfile for the FBC installation.This file reflects the environment variables you provided at startup:
$ more am-config/config/services/noninteractive-install.properties am.server.fqdn=am.example.com am.passwords.dsameuser.encrypted=AQICpxyEaXv0vc5cFxQttsDWoYfqmCqV9Kljs4rByHQ2hHzOTjiF3MdTrUfKNKKyg5ie7FujAhPxWY6unMOpxn8Tj9CJXJ/289YxL04q6pMkxqX9K2tGh55F/um4tv7sqYybySDeAP7UW9X3PpeMB8Ye6e+reEdH9dAmjGcf8gh8rvnZw29hPo0/EA== am.server.protocol=http am.stores.user.password=5up35tr0ng am.server.port=8080 am.stores.application.servers=ds.example.com:1636 am.server.context=/am am.encryption.key=PL2EdksXsEyCh0xrEwgLdRXwXPzCqf36 am.stores.user.username=uid=am-identity-bind-account,ou=admins,ou=identities am.stores.user.servers=ds.example.com:1636 am.stores.application.password=5up35tr0ngIf you don’t explicitly set a variable on startup, the FBC install uses the defaults listed in Mandatory startup properties.
-
Navigate to the AM admin UI at your deployment URL:
am.server.protocol://am.server.fqdn:am.server.port/am.server.contextFor example,
http://am.example.com:8080/am. -
Log in as
amAdminwith the default password (password). -
Set up a secret store to store the
amAdminpassword.Learn more in Store the amAdmin password in a secret store.
-
Review and edit the configuration for the following datastores, as required:
-
Configure any required secret stores.
-
Make any additional configuration changes.
|
Any configuration you update in the AM admin UI is written to the deployment configuration layer (under Any configuration you don’t update uses the baseline layer and requires the relevant environment variables to be set on subsequent startups. |
Passive install with the configurator
The configurator, openam-configurator-tool-14.1.3.29.jar, lets you install AM based on settings in a property file.
To use the configurator, the AM server must be deployed and running but not yet configured.
| This command-line utility is deprecated and will be removed in a future AM release. |
Follow these steps to install AM with the configurator:
Set up the configuration tools
-
Make sure the
JAVA_HOMEenvironment variable is correctly set:$ echo $JAVA_HOME /path/to/jdk -
Create a file system directory to unpack the tools:
$ mkdir -p /path/to/am-tools/config -
Unpack the tools from where you unzipped AM:
$ cd /path/to/am-tools/config $ unzip ~/Downloads/am/AM-SSOConfiguratorTools-5.1.3.29.zip Archive: ~/Downloads/am/AM-SSOConfiguratorTools-5.1.3.29.zip creating: legal-notices/ inflating: legal-notices/LICENSE.DOM-software.html inflating: legal-notices/NOTICE.resolver.txt inflating: legal-notices/LICENSE.DOM-documentation.html … (more output) … extracting: lib/xml-apis-2.11.0.jar extracting: openam-configurator-tool-14.1.3.29.jar extracting: lib/servlet-api-2.5.jar
Install AM with the configurator
-
Make sure the
JAVA_HOMEenvironment variable is correctly set:$ echo $JAVA_HOME /path/to/jdk -
The configurator tool needs a property file to specify the AM configuration. You can find property file options in configurator.jar.
Copy the sample configuration property file provided with AM, and modify properties as needed:
$ cd /path/to/am-tools/config $ cp sampleconfiguration config.properties $ grep -v "^#" config.properties \| grep -v "^$" SERVER_URL=https://am.example.com:8443 DEPLOYMENT_URI=/am BASE_DIR=/home/am/ locale=en_US PLATFORM_LOCALE=en_US AM_ENC_KEY= ADMIN_PWD=password COOKIE_DOMAIN=example.com ACCEPT_LICENSES=true DATA_STORE=dirServer DIRECTORY_SSL=SSL DIRECTORY_SERVER=ds.example.com DIRECTORY_PORT=1636 DIRECTORY_ADMIN_PORT=4444 ROOT_SUFFIX=ou=am-config DS_DIRMGRDN=uid=am-config,ou=admins,ou=am-config DS_DIRMGRPASSWD=passwordWhen setting options in the property file, note the following:
-
If you include the
ACCEPT_LICENSES=trueproperty, AM automatically accepts the software license agreement and suppresses the display of the license acceptance page during silent installation. -
When installing AM to support HTTPS, make sure the
SERVER_URLproperty specifies a URL with HTTPS. -
You must use an external directory server for the configuration store. If you try to install AM with the
DATA_STORE=embeddedproperty, the installation fails with the following exceptionFrom AM 8, embedded DS configuration is not supported.
-
-
Run the AM configurator tool,
openam-configurator-tool-14.1.3.29.jar:$ java -jar openam-configurator-tool-14.1.3.29.jar --file config.propertiesYou can specify additional runtime options on the command line:
-
With the
--acceptLicenseoption, the installer auto-accepts the software licensing agreement and suppresses the display of the license acceptance page, resulting in the same behavior as settingACCEPT_LICENSES=truein the configuration property file. -
The
-Djavax.net.ssl.trustStore=PATH_TO_JKS_TRUSTSTOREoption is required when installing AM to support HTTPS. Specify the AM web container’s trust store forPATH_TO_JKS_TRUSTSTORE.
The installer displays output similar to the following:
$ java -jar openam-configurator-tool-14.1.3.29.jar --file config.properties Checking license acceptance….License terms accepted. Checking configuration directory /home/openam…. Success. Installing OpenAM configuration store…Success RSA/ECB/OAEPWithSHA1AndMGF1… … Configuration complete! -
Configure sites and add servers
Sites group multiple AM servers together to provide services.
To configure a site, follow these high-level steps:
-
Install the first server in the site. This creates the configuration that the site will share.
Learn more in Interactive install.
-
Add the first server to a site if you didn’t do this already during the installation.
Learn more in Configure a site with the first server.
-
Add more servers to the site.
Learn more in Add a server to a site.
Configure a site with the first server
The following steps show how to set up a site when AM is running:
-
Review AM’s load balancing requirements in Load balancing.
-
In the AM admin UI, go to Deployment > Sites.
-
Click Add a Site to start configuring the new site.
-
On the New Site page, enter the site name without any spaces. For example, the site name must be in the format
ExampleSite, rather thanExample Site.Set the Primary URL to the load balancer URL that’s the entry point for the site, such as
https://lb.example.com/am.The site URL is the URL to the load balancer in front of the AM servers in the site. For example, if your load balancer listens for HTTPS on host
lb.example.comand port443with AM under/am, then your site URL ishttps://lb.example.com/am.Client applications and web or Java agents access the servers in the site through the site URL.
-
Click Save to keep the site configuration.
-
Configure the cookie domain of your site as required. Learn more in Change the cookie domain.
-
Go to Deployment > Servers > Server Name > General.
-
Set the Parent Site drop-down menu to the name of the site you just created, and save your changes.
At this point, the first server is part of the new site you have configured.
For all additional servers in the AM site, add them to the site at configuration time as described in Add a server to a site.
Add a server to a site
High availability requires redundant servers in case of failure. With AM, you configure an AM site with multiple servers in a pool behind a load balancing service that exposes a single URL as an entry point to the site.
Follow these steps to configure a server to an existing site:
-
Go to the deployment URL of the new instance to display the AM configurator page.
-
On the initial configuration page, click Create New Configuration.
-
Read the license agreement. Agree to the license agreement and click Continue.
-
On the Default User Password page, enter the same password you entered for the
amAdminadministrator when you configured the first server in the site. -
Configure server settings as required.
The cookie domain must be identical to that of the first server in the site.
You’ll get a warning if the Configuration Directory isn’t empty. If this happens, check that the directory you’re trying to use doesn’t contain any data you need to preserve. -
On the Configuration Data Store page, configure the same DS instance that is already used as the configuration store for the rest of the instances in the site, including the same encryption key.
Make sure you also select the Additional server for existing deployment option.
-
On the Site Configuration page, select Yes, and enter the same Site Name and Load Balancer URL values as the existing servers in the site.
Spaces aren’t allowed in the site name. -
Check the details on the Configurator Summary page.
-
If anything needs changing, click Previous to return to earlier pages and update as needed.
-
If everything is correct, click Create Configuration to proceed.
-
-
When the configuration process completes, stop the newly-installed AM instance or the container where it runs, and don’t try to access it.
-
Compare the
/path/to/am/config/boot.jsonbootstrap file with that of a running instance. Make sure the newly installed instance’s bootstrap file is appropriate for your environment.The
boot.jsonfile doesn’t exist in the new instanceDepending on the configuration of the AM keystore in the site, the installation process might not create the bootstrap file.
If not, copy the bootstrap file from another instance and continue with the procedure.
Unless your environment has a requirement to configure the AM keystore in a different location on each instance, it’s likely the bootstrap file will be the same across the site.
If you are overriding the start up settings:
-
Make sure you have copied the customized bootstrap file from another instance in the site.
-
Make sure you are overwriting the existing bootstrap file with your modified file prior to every AM restart.
-
-
Make the existing AM keystore infrastructure available to the new instance:
-
Back up the new instance’s default keystore and password files in the following locations:
-
/path/to/am/security/keystores/ -
/path/to/am/security/secrets/default/
-
-
Make sure the existing keystores in the site are available in the same location to the new instance. You might need to make changes, such as copying the keystores and their password files or mounting a volume.
-
Make sure the keystore files configured in the
/path/to/am/config/boot.jsonfile are available to the instance.
-
-
Make the existing secret store infrastructure in the site available to the new instance:
-
In the AM admin UI of an existing instance in the site, go to Configure > Secret Stores.
-
Review the list of secret stores configured globally and provide the relevant stores to the new instance. For example:
-
For keystore-type secret stores, copy the keystores to the same path on the new instance.
-
For filesystem-type secret stores, copy the contents of the directories to the same path or make the filesystem available on the same mount point on the new instance.
-
For HSM-type stores, make sure the new instance can access it.
-
For secrets configured as environment variables accessible by the container where AM runs, make sure they’re also accessible by the container of the new instance.
-
-
Go to Realms > Realm Name > Secret Stores.
-
Review the list of secret stores configured per realm and make sure to provide the relevant stores to the new instance.
-
-
Restart the new instance.
The instance is now configured for the site.
-
Review AM’s load balancing requirements in Load balancing.
-
Make sure the cookie domain configuration is appropriate for your site. Learn more in Change the cookie domain.
Delete and redeploy AM
If you need to delete your configuration and start the process from the beginning, follow these steps:
-
Stop the AM web application to clear the configuration held in memory.
The following example shuts down Apache Tomcat:
$ /path/to/tomcat/bin/shutdown.sh Password: Using CATALINA_BASE: /path/to/tomcat Using CATALINA_HOME: /path/to/tomcat Using CATALINA_TMPDIR: /path/to/tomcat/temp Using JRE_HOME: /path/to/jdk/jre Using CLASSPATH: /path/to/tomcat/bin/bootstrap.jar:/path/to/tomcat/bin/tomcat-juli.jar -
Delete the AM configuration files, by default under the
$HOMEof the user running the web application container:$ rm -rf $HOME/am $HOME/.openamcfg -
When installing or reinstalling a standalone AM instance, you must ensure the configuration store used does not contain previous configuration data.
You should either install a new, clean instance of DS, or delete the entries under the configured AM suffix (by default
ou=am-config) of an existing instance.Note that when adding a server to an existing deployment, you must not delete the configuration from DS, as it is shared by all servers in the deployment. See Add a server to a site.
-
Delete any cached files from the container.
For example, on Tomcat, files are cached in a folder named after the deployment path, such as
/path/to/tomcat/work/Catalina/localhost/deployment path. Use a command such as the following to delete these cached files:$ rm -rf /path/to/tomcat/work/Catalina/localhost/am -
Restart the AM web application.
The following example starts the Tomcat container:
$ /path/to/tomcat/bin/startup.sh Password: Using CATALINA_BASE: /path/to/tomcat Using CATALINA_HOME: /path/to/tomcat Using CATALINA_TMPDIR: /path/to/tomcat/temp Using JRE_HOME: /path/to/jdk/jre Using CLASSPATH: /path/to/tomcat/bin/bootstrap.jar:/path/to/tomcat/bin/tomcat-juli.jar
Start AM
AM is a web application installed in a web container, such as Apache Tomcat. Starting the web container starts the AM application.
At the beginning of its startup process, AM performs an operation called bootstrapping,
during which AM obtains startup settings from a bootstrap file in its configuration directory,
then uses those settings to initiate its operation.
AM creates the bootstrap file, boot.json, during installation.
How is the bootstrap file created?
The installation or upgrade process creates the file after configuring the instance, provided it can find the AM keystore and its password files in either of the following locations:
-
Configure > Server Defaults > Security > Key Store
-
Deployment > Servers > Server Name > Security > Key Store
Change the AM default keystore configuration at Server Default level so the environment is homogeneous.
When is the bootstrap file updated?
After every successful startup, AM rewrites the bootstrap file using the current information for the AM keystore.
If you change the configuration of the AM keystore, for example, the path to its files, AM will save the changes to the bootstrap file the next time it starts successfully.
This is why, if you want to override AM’s startup settings, you need to replace the bootstrap file manually before AM starts.
Override startup settings
Users who deploy AM with DevOps tooling, such as Docker and Kubernetes, might want to launch multiple AM instances from a single image, providing startup settings dynamically when AM starts up instead of reading the settings from the bootstrap file created during AM installation.
You can replace the bootstrap file and provide your own static and dynamic startup settings. The following sections describe how to override the bootstrap file created during AM installation:
-
Replace the bootstrap File covers how to specify a custom bootstrap file, and describes all the startup settings in the bootstrap file.
-
Override startup settings using environment variables covers how to dynamically override startup settings in the bootstrap file with environment variables.
-
Override startup settings using Java properties covers how to dynamically override startup settings in the bootstrap file with Java properties.
Replace the bootstrap File
AM’s bootstrap file is located at the path /path/to/am/config/boot.json,
where /path/to/am/config is the AM configuration directory.
How is the AM configuration directory specified?
You specify it during AM installation, as follows:
-
In the Configuration Directory field on the Server Settings page when using GUI installation. You can find details in Interactive install.
-
In the
BASE_DIRproperty in the installation configuration file when using command-line installation. Learn more in the API documentation.
To override AM’s startup configuration, modify the boot.json bootstrap file then overwrite the existing bootstrap
file with your modified file before every AM restart.
You must overwrite the file each time you start AM because after startup, AM overwrites the bootstrap file with the initial startup settings created during AM installation, removing any modifications you might have made to startup settings in the bootstrap file.
Make changes to supporting files and passwords before changing bootstrap file properties—AM will
fail to start up when bootstrap file properties do not correspond to actual configuration.
For example, if you change the value of the keyStorePasswordFile property to a file that does not exist,
AM will not be able to start up.
Bootstrap file example, with properties
{
"instance": "https://am.example.com:8443/am",
"dsameUser": "cn=dsameuser,ou=DSAME Users,dc=am,dc=example,dc=com",
"keystores": {
"default": {
"keyStorePasswordFile": "/path/to/am/security/secrets/default/.storepass",
"keyPasswordFile": "/path/to/am/security/secrets/default/.keypass",
"keyStoreType": "JCEKS",
"keyStoreFile": "/path/to/am/security/keystores/keystore.jceks"
}
},
"configStoreList": [
{
"baseDN": "ou=am-config",
"dirManagerDN": "uid=am-config,ou=admins,ou=am-config",
"ldapHost": "ds.example.com",
"ldapPort": 1636,
"ldapProtocol": "ldap"
}
]
}| Property | Description and Derivation |
|---|---|
|
AM server URL. Defaults to the Server URL field on the Server Settings page (GUI configurator)
or the This property’s value is the URL for directly accessing an AM instance, not an AM site using a load balancer URL. Do not modify this bootstrap file property. If you need to change the AM instance URL, reinstall AM. |
|
An internal account that AM uses to connect to the configuration store. AM generates the password for this account on startup and you can’t read or change it. The first part of the user’s DN is always created initially as |
|
The AM keystore. Currently, no other keystores are referenced in the bootstrap file. |
|
Path to the file that contains the password required to open the AM keystore.
Always created initially as When creating a new |
|
Path to the file that contains the password used to encrypt individual keystore entries.
Always created initially as When creating a new |
|
AM key store type. Currently, the only valid value is |
|
Path to the AM keystore. Always created initially as The AM keystore is required for startup because it contains the password of the directory manager user of the AM configuration store. |
|
Array of one or more objects that describe AM configuration stores. The initial object in the array is mandatory and defines the primary configuration store. Additional objects are optional and define failover configuration stores. |
|
Root suffix of the AM configuration store. Defaults to the Root Suffix field on the Configuration Data Store Settings page (GUI configurator) or the |
|
DN of the configuration store directory manager user. Defaults to |
|
fully qualified domain name (FQDN) of the configuration store’s host. Defaults to the Host Name field on the Configuration Data Store Settings page (GUI configurator) or the |
|
LDAP or LDAPS port number on which to access the configuration store. Defaults to the Port field on the Configuration Data Store Settings page (GUI configurator) or the |
|
Protocol with which to access the directory service running the configuration store.
The value can be Defaults to the SSL/TLS Enabled field on the Configuration Data Store Settings page (GUI configurator)
or the |
Override startup settings using environment variables
You can dynamically override startup settings in the bootstrap file by defining environment variables in the shell that starts AM and referencing the variables in a modified version of the bootstrap file.
Specify JSON properties that reference environment variables in a modified bootstrap file
that uses the notation ${env.MY_ENVIRONMENT_VARIABLE}.
For example, you could dynamically change the AM instance URL as follows:
-
Set an environment variable named
MY_INSTANCEin the shell that starts AM. -
Create a modified version of the bootstrap file with the following line:
"instance" : "${env.MY_INSTANCE}", -
Overwrite the initial bootstrap file with the modified bootstrap file.
-
Start AM.
Override startup settings using Java properties
You can dynamically override startup settings in the bootstrap file by referencing Java system properties
in a modified version of the bootstrap file.
You can reference both built-in Java system properties and properties specified with the -D option
in the web container that runs AM.
Specify JSON properties that reference Java properties in a modified bootstrap file that uses the notation
${MY_JAVA_PROPERTY}.
For example, you could dynamically change the AM keystore’s path to the user’s home directory as follows:
-
Create a modified version of the bootstrap file, specifying the default AM keystore as follows:
"keystores" : { "default" : { "keyStorePasswordFile" : "/home/jenkins/.storepass", "keyPasswordFile" : "/home/jenkins/.keypass", "keyStoreType" : "JCEKS", "keyStoreFile" : "/home/jenkins/keystore.jceks" } }, -
Overwrite the initial bootstrap file with the modified bootstrap file.
-
Start AM.
Run AM as a service
AM can run as a service on a standard systemd-based Linux distribution. Once you have configured AM as a service, you can stop and start AM using systemd.
These instructions assume you have deployed AM on Apache Tomcat.
|
A service file (called You can enable this service to run on startup and manage the Tomcat service using |
Configure AM as a service
-
Create a service file using your preferred text editor:
$ sudo vim /etc/systemd/system/am.service -
Add the following content to this file, update all the values as needed, and save:
[Unit] Description=AM (Apache Tomcat) After=network.target [Service] Type=forking Environment=JAVA_HOME=/path/to/jdk Environment=CATALINA_PID=/path/to/tomcat/temp/tomcat.pid Environment=CATALINA_HOME=/path/to/tomcat Environment=CATALINA_BASE=/path/to/tomcat Environment='CATALINA_OPTS=-Xmx2048m -server -XX:+UseParallelGC' Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom' ExecStart=/path/to/tomcat/bin/startup.sh ExecStop=/path/to/tomcat/bin/shutdown.sh User=tomcat_user Group=tomcat_user [Install] WantedBy=multi-user.target -
Reload the daemon:
$ sudo systemctl daemon-reload -
Make the new service launch on startup:
$ sudo systemctl enable am.service -
Check the service is enabled:
$ systemctl is-enabled am.serviceThis command returns
enabledordisabledas appropriate.
Use systemctl commands to manage the AM service
Once you’ve configured AM as a service and checked it’s enabled, use systemctl commands to manage the AM service:
-
Start the service:
$ sudo systemctl start am.service -
Stop the service:
$ sudo systemctl stop am.service -
Restart the service:
$ sudo systemctl restart am.service -
Check the service status:
$ sudo systemctl status am.serviceThis command returns the service state (whether the service has started or stopped as expected) and the first few entries of the AM log file.
Set up administration tools
AM provides a set of administration tools that are now deprecated in favor of Amster. They are part of the AM distributable file.
The ssoadm tool requires access to the AM configuration files
and therefore must be installed on the same host as AM.
-
Verify that AM is installed and running before proceeding.
-
Verify that the
JAVA_HOMEenvironment variable is set properly:$ echo $JAVA_HOME /path/to/jdk
-
Create a file system directory to unpack the tools:
$ mkdir -p /path/to/am-tools/admin
-
Unpack the tools:
$ cd /path/to/am-tools/admin $ unzip ~/Downloads/am/AM-SSOAdminTools-5.1.3.29.zip
-
Run the
setuputility (setup.baton Windows) providing the location, password, and type of the truststore containing the public certificate of the DS configuration store.Optionally, include the
--acceptLicenseoption if you want to auto-accept the license agreement and suppress the display of the license acceptance page.How do I create the truststore?
Even though you may have other truststores containing the public certificate of the configuration store, you should use a truststore specifically for the
ssoadmcommand.To create it, follow the steps in Prepare the truststore, but do not configure the new truststore in the container. You will configure it in the
ssoadmcommand script later.If the container where AM runs is configured for secure connections and is using self-signed certificates, import that public certificate into the new truststore, too. For more information, see To Share Self-Signed Certificates.
When using self-signed certificates, for example, in non-production environments, you can configure the ssoadmcommand to trust all server certificates. Learn more in How do I configure ssoadm to trust all certificates? in the Knowledge Base.You will also need to provide the paths to the directories where AM configuration files are located, and where the
ssoadmdebug and log information will be located.For example:
$ ./setup --truststore-path /my/ssoadm/truststore --truststore-password changeit \ --truststore-type JKS --acceptLicense Path to config files of OpenAM server [/home/user/am]: Debug Directory [/path/to/am-tools/admin/debug]: Log Directory [/path/to/am-tools/admin/log]: The scripts are properly setup under directory: /path/to/am-tools/admin/am Debug directory is /path/to/am-tools/admin/debug. Log directory is /path/to/am-tools/admin/log. The version of this tools.zip is: version and date The version of your server instance is: ForgeRock Access Management version, Build, and date
If the
setuputility cannot connect to the configuration store, it will show a message similar to the following:Connect Error: No operational connection factories available
If you see this message, check that the truststore exists in the specified location, that it contains the configuration store certificate, and that the user running the
setuputility can change directories to the specified location and open/read the file.After setup, the tools are located under a directory named after the instance of AM:
$ ls am/bin/ ampassword amverifyarchive ssoadm
On Windows, these files are
.batscripts. -
Edit the
ssoadmscript and configure the truststore containing the certificate of the configuration store. This truststore may also contain the certificate to connect to AM using SSL, if needed.-
In the script, look for the following lines:
.... TRUSTSTORE="-Djavax.net.ssl.trustStore=$truststore_path" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStorePassword=$truststore_password" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStoreType=$truststore_type" .... -
Add the
truststore_path,truststore_password, andtruststore_typevariables above the lines you found:truststore_path=/my/ssoadm/truststore truststore_password=changeit truststore_type=JKS TRUSTSTORE="-Djavax.net.ssl.trustStore=$truststore_path" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStorePassword=$truststore_password" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStoreType=$truststore_type" ....
-
-
Check that the
ssoadmcommand works properly:-
Create a text file, for example
$HOME/.pwd.txt, containing the AM administrative user’s password string in cleartext on a single line. -
Make the text file read-only:
$ chmod 400 $HOME/.pwd.txt
-
Run the
ssoadmcommand to list the configured servers:$ cd /path/to/am-tools/admin/am/bin/ $ ./ssoadm list-servers --adminid uid=amAdmin,ou=People,dc=am,dc=example,dc=com --password-file $HOME/.pwd.txt https://am.example.com:8443/amThe value for the
--adminidparameter is the universal ID of an administrative user.Administrative users are listed in the
com.sun.identity.authentication.super.userorcom.sun.identity.authentication.special.usersadvanced properties, under Configure > Server Defaults > Advanced.The default super-user account is
uid=amAdmin,ou=People,%ROOT_SUFFIX%. To check your %ROOT_SUFFIX% value, go to the/path/to/am/config/boot.jsonfile, and find the value for theconfigStoreList/baseDNproperty.
-
-
If you have deployed AM in a site configuration, edit the
ssoadm(ssoadm.baton Windows) script to map the site URL to the AM server URL.To do this, set the
com.iplanet.am.naming.map.site.to.serversystem property as ajavacommand option in the script. The option takes the following form:-D"com.iplanet.am.naming.map.site.to.server=lb-url=openam-url[,other-lb-url=openam-url…]"
The property maps each lb-url key to an openam-url value, where lb-url is the URL to a site load balancer, and openam-url is the URL to the AM server against which you set up the
ssoadmcommand.The
ssoadmcommand is dependent on the AM server against which you set it up, so always map site load balancer URLs to that server’s openam-url.For example, if your site is behind
https://lb.example.com:443/am, and the AM server against which you set up thessoadmcommand is athttps://am.example.com:8443/am, then add the following property to thejavacommand (all on one line without spaces):-D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/am=https://am.example.com/am"Repeat this step for each AM server in your site configuration. You can install all your instances of
ssoadmon the same host, but in each case the command should manage only one AM server.
Next steps
Congratulations on installing AM!
The following list shows you different tasks you should consider after installing AM:
- Core administrative tasks
-
-
Learn about realms, configure them, and connect them to identity stores.
-
Configure AM’s cookie domain.
-
Learn about other types of configuration stores and decide if your environment would benefit from having dedicated application stores.
For more information, see the Setup.
-
- Core Token Service tasks
-
-
Learn about the Core Token Service and decide if your environment would benefit from having dedicated CTS token stores.
For more information, see the Core Token Service (CTS).
-
- Access Management-related tasks
-
-
Learn about authentication trees and nodes and configure them to let your users log in to AM.
-
Learn about sessions in AM and configure them for your environment.
For more information, see the Authentication and SSO
-
- Security-related tasks
-
-
Secure your core AM environment against different threats.
-
Configure keys and keystores used for different AM features.
-
Change the
amAdminuser password. -
Learn about delegated privileges and configure delegated realm administrators.
-
Configure audit logging services.
For more information, see the Security.
-
- Maintenance-related tasks
-
-
Learn how to back up and restore your environment.
-
Learn how to monitor your AM instances.
-
Learn how to enable debug logging and how to record troubleshooting information.
-
Tune AM.
For more information, see the Maintenance.
-
AM offers authentication and authorization functionality, which you can expand with Internet specifications and drafts, such as OAuth 2.0, and SAML v2.0.
Once you are confident about your base AM configuration, move on to more advanced features, such as protecting web applications, configuring single sign-on (SSO), federating access across applications, and others.
Uninstall AM
This page describes how to remove AM software.
To remove a single server from a multi-server deployment, select Deployment > Servers > Server Name then click and Delete.
You can find instructions on removing agents in the Web Agents Installation Guide and the Java Agents Installation Guide.
After you have deployed and configured AM, you might have as many as four locations where AM files are stored on your system.
The following steps remove the AM software. After removing all the software, remove the AM configuration data.
-
Shut down the web application container where you deployed AM.
$ /etc/init.d/tomcat stop Password: Using CATALINA_BASE: /path/to/tomcat Using CATALINA_HOME: /path/to/tomcat Using CATALINA_TMPDIR: /path/to/tomcat/temp Using JRE_HOME: /path/to/jdk/jre Using CLASSPATH: /path/to/tomcat/bin/bootstrap.jar: /path/to/tomcat/bin/tomcat-juli.jar
-
Unconfigure AM by removing the configuration files in the $HOME directory of the user running the web application container.
For example:
$ rm -rf $HOME/am $HOME/.openamcfgTo uninstall AM and its associated configuration files, delete the following directories:
-
The configuration directory.
If you didn’t use the default configuration location (
$HOME/am), check the value of theBase installation directoryproperty under Deployment > Servers > Server Name > General > System. -
The hidden directory that holds a file pointing to the configuration directory.
For example, if you are using Apache Tomcat as the web container, this file could be
$HOME/.openamcfg/AMConfig_path_to_tomcat_webapps_am_.
-
-
Remove the configuration manually from your directory server. The default base DN for AM configuration data is
ou=am-config.At this point, you can restart the web container and reconfigure AM if you only want to start over with a clean configuration rather than removing AM completely. -
Undeploy the AM web application.
For example, if you are using Apache Tomcat as the web container, remove the
.warfile and expanded web application from the container:$ cd /path/to/tomcat/webapps/ $ rm -rf am.war am/
Troubleshoot installations
AM can capture information in debug log files that are useful when troubleshooting AM problems. Debug logging describes how to enable debug logging after AM has been started.
It is also possible to capture debug logs while installing AM. This can be useful if you need to troubleshoot an installation problem.
Follow these steps to capture debug logs while installing AM on Tomcat:
-
If Tomcat is already started, stop it.
-
Specify the
-Dcom.iplanet.services.debug.level=messageoption in theCATALINA_OPTSenvironment variable:$ export CATALINA_OPTS=-Dcom.iplanet.services.debug.level=message
There are several ways that you can specify the
CATALINA_OPTSenvironment variable. You can set the variable:-
In the
/path/to/tomcat/bin/setenv.shfile -
In the login shell of the user who runs Tomcat
-
-
Run the AM installation. Debug log files containing troubleshooting information appear in the
/path/to/am/var/debugdirectory. -
When you have completed AM installation and no longer need to capture debug logs, stop Tomcat, revert the debug logging options, and restart Tomcat.