PingAM 8.0.0

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

com.sun.identity.sm.sms_object_filebased_enabled

Whether FBC is enabled.

true, false

false

com.sun.identity.configuration.directory

Path to the folder that holds the configuration files

Any writeable folder on the file system

$HOME/application-context

am.server.protocol

The server protocol used for the AM server instance configuration.

https, http

http

am.server.fqdn

The fully qualified domain name that will be used for the AM server instance configuration

Any valid FQDN

am.localtest.me

am.server.port

The port on which this server instance will be available.

Any valid port number

8080

am.server.context

The web application context on which this server instance will be available.

/web application context

/am

am.encryption.key

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

am.stores.user.servers

Connection string for the user store in the format host:port.

A valid server connection string

ds.localtest.me:1636

am.stores.user.username

Bind DN to connect to the user store.

Valid bind DN

uid=admin

am.stores.user.password

Bind password for the user store

Alphanumeric value

password

am.stores.application.servers

Connection string for the application and policy stores in the format host:port.

A valid server connection string

ds.localtest.me:1636

am.stores.application.password

Bind password for the user store

Alphanumeric value

password

You can’t specify the password of the amAdmin user during a passive FBC install. The default amAdmin password is password. You can use this password to log in to the AM admin UI after the initial install.

In production deployments, you must set up a secret store to store the amAdmin password.

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

com.iplanet.services.debug.directory

The location of the debug logs.

A writeable location on the file system

am-config-path/var/debug
Startup properties for the identity store
Environment variable Description Valid values Default

am.stores.user.ssl.enabled

Whether AM connects to the identity store over SSL

true, false

true

am.stores.user.mtls.enabled

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

am.stores.cts.servers

Connection string for the CTS store in the format host:port

A valid server connection string

The value of am.stores.user.servers

am.stores.cts.username

Bind DN to connect to the CTS store

Valid bind DN

uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens

am.stores.cts.password

Bind password for the CTS store

Alphanumeric value

The value of am.stores.user.password

am.stores.cts.ssl.enabled

Whether AM connects to the CTS store over SSL

true, false

The value am.stores.user.ssl.enabled, if set, otherwise true

am.stores.cts.mtls.enabled

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

am.stores.application.servers

Connection string for the application store in the format host:port

A valid server connection string

The value of am.stores.user.servers

am.stores.application.username

Bind DN to connect to the application store

Valid bind DN

uid=am-config,ou=admins,ou=am-config

am.stores.application.password

Bind password for the application store

Alphanumeric value

The value of am.stores.user.password

am.stores.application.ssl.enabled

Whether AM connects to the application store over SSL

true, false

The value am.stores.user.ssl.enabled, if set, otherwise true

am.stores.application.mtls.enabled

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

am.stores.policy.servers

Connection string for the policy store in the format host:port

A valid server connection string

The value of am.stores.application.servers

am.stores.policy.username

Bind DN to connect to the policy store

Valid bind DN

uid=am-config,ou=admins,ou=am-config

am.stores.policy.password

Bind password for the policy store

Alphanumeric value

The value of am.stores.application.password

am.stores.policy.ssl.enabled

Whether AM connects to the policy store over SSL

true, false

The value am.stores.user.application.enabled, if set, otherwise true

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

am.stores.uma.servers

Connection string for the UMA store in the format host:port

A valid server connection string

The value of am.stores.application.servers

am.stores.uma.username

Bind DN to connect to the UMA store

Valid bind DN

uid=am-config,ou=admins,ou=am-config

am.stores.uma.password

Bind password for the UMA store

Alphanumeric value

The value of am.stores.application.password

am.stores.uma.ssl.enabled

Whether AM connects to the UMA store over SSL

true, false

The value am.stores.user.application.enabled, if set, otherwise true

am.stores.uma.mtls.enabled

Whether mTLS is enabled for the UMA store(1).

true, false

The value am.stores.application.mtls.enabled, if set, otherwise false

(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"

  1. 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.

  2. In the configuration file directory, locate the noninteractive-install.properties file 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=5up35tr0ng

    If you don’t explicitly set a variable on startup, the FBC install uses the defaults listed in Mandatory startup properties.

  3. Navigate to the AM admin UI at your deployment URL:

    am.server.protocol://am.server.fqdn:am.server.port/am.server.context

    For example, http://am.example.com:8080/am.

  4. Log in as amAdmin with the default password (password).

  5. Set up a secret store to store the amAdmin password.

    Learn more in Store the amAdmin password in a secret store.

  6. Review and edit the configuration for the following datastores, as required:

  7. Configure any required secret stores.

  8. Make any additional configuration changes.

Any configuration you update in the AM admin UI is written to the deployment configuration layer (under /path/to/am/config/config/services).

Any configuration you don’t update uses the baseline layer and requires the relevant environment variables to be set on subsequent startups.