FAQ: Installing and using ssoadm in AM
The purpose of this FAQ is to provide answers to commonly asked questions regarding installing and using ssoadm in AM.
3 readers recommend this article
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
- 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 "
- 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.
Note
If you have multiple servers running ssoadm, you need to modify the ssoadm script for each server, ensuring the mapping is specific to the server on which you are setting up the ssoadm tools.
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:
-D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=http://host1.example.com:8080/openam"and the following to the ssoadm script running on the http://host2.example.com:8080/openam (second) server:
-D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=http://host2.example.com:8080/openam"See Setting Up Administration Tools for further information.
Q. How do I configure ssoadm to trust all certificates?
A.
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:
$ ./ssoadm set-attr-defs -s [servicename] -t [schematype] -u [adminID] -f [passwordfile] -a [ssoadmattribute]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
Note
You can use the same principles as above to change the equivalent service attribute in a realm (providing the service has already been added to the realm) but substitute set-svc-attrs for set-attr-defs and replace -t [schematype] with -e [realmname].
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:
Viewing attributes sub-command | Changing attributes sub-command |
---|---|
show-agent | update-agent |
show-agent-grp | update-agent-grp |
get-auth-cfg-entr | update-auth-cfg-entr |
get-auth-instance | update-auth-instance |
show-datastore | update-datastore |
show-app-priv | update-app-priv |
show-appl | set-appl |
show-entitlement-conf | set-entitlement-conf |
get-identity | set-identity-attrs |
show-identity-svc-attrs | set-identity-svc-attrs |
list-xacml | create-xacml |
get-realm | set-realm-attrs |
get-realm-svc-attrs | set-realm-svc-attrs |
list-server-cfg | update-server-cfg |
get-sub-cfg | set-sub-cfg |
get-attr-defs | set-attr-defs |
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.
Note
Not all of the sub-commands available through the ssoadm command are available on the ssoadm.jsp page.
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