FAQ: Installing and using ssoadm in AM

Frequently asked questions

• Q. How do I install the ssoadm administration tool if I am using SSL?
• Q. How do I install the ssoadm administration tool if I have a Site configuration?
• Q. How do I configure ssoadm to trust all certificates?
• Q. Do I need to upgrade the ssoadm administration tool when I upgrade AM?
• Q. Can I make batch changes using ssoadm to improve performance?
• Q. How can I set a property to blank or null using ssoadm?
• Q. How do I know which ssoadm command to use for changing service attributes?
• Q. Can I change the Load schema option via ssoadm when creating a data store?
• Q. What are some useful ssoadm commands that I can use?
• Q. How do I find the correct sub-command to use for an attribute?
• Q. Can I still use ssoadm.jsp?

Q. How do I install the ssoadm administration tool if I am using SSL?

A. For AM 7 and later, you should follow the install steps in Setting Up Administration Tools, which includes the necessary steps for specifying the truststore that contains the required certificates. 

Pre-AM 7

If you access the configuration store and/or AM instance using a SSL/TLS secured connection, you need to update the setup or setup.bat script before installing ssoadm to include details of the truststore that contains the required certificates. Otherwise, the ssoadm tool cannot trust AM and cannot complete the handshake phase of setting up a secure connection. Once setup has completed successfully, you need to update the ssoadm or ssoadm.bat script prior to using ssoadm.

The following examples assume AM is deployed on an Apache Tomcat™ web container, where /path/to/truststore is the truststore that contains all the SSL certificate chain and server certificates that are used for the SSL/TLS secured connection. For example, this would be $JAVA_HOME/jre/lib/security/cacerts if you are using the AM default truststore.

setup or setup.bat script changes

1. Add the following to the setup or setup.bat script depending on which keystore type you are using:
   • JCEKS keystore: KEYSTORE=" -Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.trustStoreType=JCEKS "
   • JKS keystore: KEYSTORE=" -Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=changeit "
2. Add $KEYSTORE to the $JAVA_HOME line in the the setup or setup.bat script, for example, change it as follows: $JAVA_HOME/bin/java $KEYSTORE -D"load.config=yes" -D"help.print=$help_print" \

ssoadm or ssoadm.bat script changes

Add the following to the ssoadm or ssoadm.bat script depending on which keystore type you are using:

• JCEKS keystore: -D"javax.net.ssl.trustStore=/path/to/truststore" -D"javax.net.ssl.trustStoreType=JCEKS"
• JKS keystore: -D"javax.net.ssl.trustStore=/path/to/truststore"

Q. How do I install the ssoadm administration tool if I have a Site configuration?

A. When used in a Site configuration, the ssoadm administration tool accesses the configuration via the load balancer; therefore, you need to map the load balancer to the server within your site that is being used for ssoadm. This is done by adding site-to-server-mapping to the ssoadm or ssoadm.bat script.

For example, if you have:

• primary site URL : https://lb.example.com:443/openam
• first server within your site configuration (used for ssoadm): http://host1.example.com:8080/openam
• second server within your site configuration (also used for ssoadm): http://host2.example.com:8080/openam

You would add the following to the ssoadm script running on the http://host1.example.com:8080/openam (first) server:

and the following to the ssoadm script running on the http://host2.example.com:8080/openam (second) server:

See Setting Up Administration Tools for further information.

Q. How do I configure ssoadm to trust all certificates?

A. You can configure ssoadm to trust all certificates if you are using Java 8 for ssoadm by adding the following JVM options to the ssoadm or ssoadm.bat script. These settings disable SSL certificate checking; although helpful to get ssoadm working for troubleshooting purposes (for example, to determine if certificates are causing your issues or to export your configuration), you should avoid using these settings on a permanent basis in production.

You cannot configure the JVM to trust all certificates in Java 11.

Q. Do I need to upgrade the ssoadm administration tool when I upgrade AM?

A. Yes you do; you must ensure you are running the equivalent version of the ssoadm administration tool. The ssoadm administration tool is not automatically upgraded when you upgrade AM and must be done separately.

See Setting Up Administration Tools for further information.

Q. Can I make batch changes using ssoadm to improve performance?

A. Yes you can. Refer to the following articles for further information:

• How do I add multiple attributes with a single ssoadm command in AM (All versions)? - this article provides information on setting multiple attributes with a single ssoadm command in AM. This is useful when you want to add multiple attributes for a single sub-command, for example, set-identity-attrs or set-attr-defs.
• How do I make batch changes using ssoadm in AM (All versions)? - this article provides information on making batch changes using ssoadm in AM. You can make multiple changes to AM using ssoadm commands, which makes scripted installs or upgrades possible.

See How do I improve the performance of ssoadm in AM (All versions)? for additional options to improve the performance of ssoadm.

Q. How can I set a property to blank or null using ssoadm?

A. You can simply specify the ssoadm command with the attribute=

For example:

• AM 7 and later: $ ./ssoadm update-server-cfg -s default -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a org.forgerock.services.cts.store.root.suffix=
• Pre-AM 7: $ ./ssoadm update-server-cfg -s default -u amadmin -f pwd.txt -a org.forgerock.services.cts.store.root.suffix=

This command would remove any existing value from the org.forgerock.services.cts.store.root.suffix property (CTS Root Suffix) and set it to blank.

Q. How do I know which ssoadm command to use for changing service attributes?

A. You can use services.jsp (for example, URL: http://host1.example.com:8080/openam/services.jsp) to help you work out the ssoadm command to use to change service attributes. You can search this page for the field name displayed in console or the ssoadm attribute if known, for example, sun-am-policy-config-org-alias-mapped-resources-enabled. This will then give you the ssoadm attribute if not previously known, the service name (in this example, iPlanetAMPolicyConfigService) and the schema type, which can be Dynamic, Global or Organization (in this case Global).

You can then construct the ssoadm command as follows:

For example:

• AM 7 and later: $ ./ssoadm set-attr-defs -s iPlanetAMPolicyConfigService -t global -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a sun-am-policy-config-org-alias-mapped-resources-enabled=true
• Pre-AM 7: $ ./ssoadm set-attr-defs -s iPlanetAMPolicyConfigService -t global -u amadmin -f pwd.txt -a sun-am-policy-config-org-alias-mapped-resources-enabled=true

Q. Can I change the Load schema option via ssoadm when creating a data store?

A. No you cannot, as AM should not amend the directory schema. This is discussed in OPENAM-1853 (Add ssoadm flag to load schema while creating datastore).

Q. What are some useful ssoadm commands that I can use?

A. There are many ssoadm commands available; all AM articles give instructions using either the console or the equivalent ssoadm command where applicable.

The following provides some ssoadm commands for common tasks to get you started:

Servers

• Check ssoadm is working by listing the servers in an AM environment: $ ./ssoadm list-servers -u [adminID] -f [passwordfile] replacing [adminID] and [passwordfile] with appropriate values.
• Check the server configuration: $ ./ssoadm list-server-cfg -u [adminID] -f [passwordfile] -s [serverURL] replacing [adminID], [passwordfile] and [serverURL] with appropriate values.

Sessions

• List active sessions from command line using the list-sessions sub-command $ ./ssoadm list-sessions -u [adminID] -f [passwordfile] -t [hostname] replacing [adminID], [passwordfile] and [hostname] with appropriate values. You can also filter the list of sessions using the -x option. A filter -x "sally*" would return all the sessions which start with the string sally.

Cookie Domains

• Change the default cookie domain: $ ./ssoadm set-attr-defs -s iPlanetAMPlatformService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-platform-cookie-domains=[domain] replacing [adminID], [passwordfile] and [domain] with appropriate values.
• Change the cookie domain for SAML2 IdP Discovery Service: $ ./ssoadm set-attr-defs -s sunFAMSAML2Configuration -t Global -u [adminID] -f [passwordfile] -a IDPDiscoveryCookieDomain=[domain] replacing [adminID], [passwordfile] and [domain] with appropriate values.

Authentication modules

• List authentication modules in a realm: $ ./ssoadm list-auth-instances -u [adminID] -f [passwordfile] -e [realmname] replacing [adminID], [passwordfile] and [realmname] with appropriate values.
• List the values for a specific authentication module, as demonstrated in the example below using the HOTP module: $ ./ssoadm get-auth-instance -u [adminID] -f [passwordfile] -e [realmname] -m HOTP replacing [adminID], [passwordfile] and [realmname] with appropriate values.
• List the available authentication configurations in a realm: $ ./ssoadm list-auth-cfgs -u [adminID] -f [passwordfile] -e [realmname] replacing [adminID] and [passwordfile] with appropriate values.
• Update an authentication instance, as demonstrated in the example below using the LDAP module and setting the minimum password length to 12: $ ./ssoadm update-auth-instance -u [adminID] -f [passwordfile] -e [realmname] -m LDAP -a iplanet-am-auth-ldap-min-password-length=12 replacing [adminID], [passwordfile] and [realmname] with appropriate values.

Users

• Confirm that AM to LDAP communication is configured correctly and can query userids etc: $ ./ssoadm list-identities -u [adminID] -f [passwordfile] -e / -t User -x "*" replacing [adminID] and [passwordfile] with appropriate values.
• Create a user with a password: $ ./ssoadm create-identity -u [adminID] -f [passwordfile] -e [realmname] -i [username] -t User -a "userpassword=[password]" replacing [adminID], [passwordfile], [realmname], [username] and [password] with appropriate values.
• Add a privilege to a user: $ ./ssoadm add-privileges -u [adminID] -f [passwordfile] -e [realmname] -t Role -i [username] -g [privilegename] replacing [adminID], [passwordfile], [realmname], [username] and [privilegename] with appropriate values.
• Remove a privilege from all authenticated users: $ ./ssoadm remove-privileges -u [adminID] -f [passwordfile] -e [realmname] -t Role -i "All Authenticated Users" -g [privilegename] replacing [adminID], [passwordfile], [realmname] and [privilegename] with appropriate values.

Agents

• List all agents of a specific type (for example, J2EEAgent or WebAgent.): $ ./ssoadm list-agents -u [adminID] -f [passwordfile] -e [realmname] -t[agenttype] replacing [adminID] and [passwordfile] with appropriate values.

Q. How do I find the correct sub-command to use for an attribute?

A. All the sub-commands that can be used in ssoadm commands are listed in ssoadm.

If you are unsure which sub-command you should use to change an attribute, you can use the get, list or show equivalent of the one you think is right to check (without including the attribute value). The get, list and show sub-commands display all the applicable attributes and their current values.

The following table shows the sub-commands for viewing the attributes with the equivalent sub-command for changing the attributes:

Q. Can I still use ssoadm.jsp?

A. No, you should not use ssoadm.jsp. It has been removed in AM 5.5 and was deprecated in AM 5. Prior to this, it was deactivated by default to prevent potential misuse; however, you could re-activate it by changing a property in the console.

See Also

How do I enable message level debugging for ssoadm in AM (All versions)?

ssoadm fails in AM (All versions) with FATAL ERROR: Cannot obtain Application SSO token

Some ssoadm commands fail with Service URL not found:session error when module based authentication is disabled in AM (All versions)

Subsequent attempts to use ssoadm fail in AM 5.x and 6.x

Using ssoadm in AM

FAQ: Installing AM

FAQ: Configuring AM

FAQ: General AM