Just a modest list of ssoadm (the command line tool for OpenAM administration). Note: As with other cheat sheets, this one remains a perpetual work in progress.
The ssoadm command is extremely useful. It should be installed with every OpenAM depoyment.
The utility has its own help function:
Installing the SSO Admin Tools
See my article on the OpenAM Tools for how I do it.
Getting and Setting Attribute Values
See Attributes and the ssoadm command, for important tips on how to get and set attribute values with ssoadm.
List the servers in an OpenAM environment
ssoadm list-servers -u amadmin -f $HOME/etc/pwd.txt
In this and the examples to follow “-u” is the ID of the admin user and “-f” in the full path to the pwd.txt file you created above.
List all Web Agents for a realm
ssoadm list-agents -u amadmin -f $HOME/etc/pwd.txt -t WebAgent -e testrealm
Here “-t” is for the type of agent, and “-e” is the name of the realm. The output will show the actual configuration directory dn of the realm.
List the configuration of a server
ssoadm list-server-cfg -u amadmin -f $HOME/etc/pwd.txt -s http://test1.example.com:8081/openam
Here the “-s” stands for “server”, the value being the base url where your OpenAM node can be accessed.
List cookie domains
ssoadm get-attr-defs -u amadmin -f $HOME/etc/pwd.txt -s iPlanetAMPlatformService -t global -a "iplanet-am-platform-cookie-domains"
How I got here: The OpenAM Reference says that the cookie domain list is stored in the iplanet-am-platform-cookie-domains attribute. That attribute is defined in the amPlatform.xml schema file as part of the iPlanetAMPlatformService. Because cookie domains are configured under the “Configure” tab in the gui console, it is a global attribute.
Change the default cookie domain
ssoadm set-attr-defs -u amadmin -f $HOME/etc/pwd.txt -s iPlanetAMPlatformService -t global -a "iplanet-am-platform-cookie-domains=.newdom.com"
List the user datastores in a realm
ssoadm list-datastores -u amadmin -f $HOME/etc/pwd.txt -e /tesrealm
The “-e” parameter specifies the realm. The default “root” realm is “/”. Example uses the “/testrealm” sub-realm.
Get the config for a datastore
ssoadm show-datastore -u amadmin -f $HOME/etc/pwd.txt -e /testrealm -m OpenDS >/tmp/opends-cfg.txt
Here “-m” is the name of the datastore as returned by the “list-datastores” command,
Update a datastore config
ssoadm update-datastore -u amadmin -f $HOME/etc/pwd.txt -e /testrealm -m OpenDS -D $HOME/data/additional-cfg.txt
“-D” points to a text file containing parameters to add or overwrite a datastore’s configuration. For example, to add the attributes “departmentnumber”, “o” and “ou” to the list of user attributes a datastore is configured for, you will need to create a text file that includes all of the values currently existing for:
and then add those new values thus:
sun-idrepo-ldapv3-config-user-attributes=departmentnumber sun-idrepo-ldapv3-config-user-attributes=o sun-idrepo-ldapv3-config-user-attributes=ou
Note that when updating an existing datastore configuration you should not include the
attribute unless you really want to change that password value (used to bind with the target directory server). By default this attribute is included in any config dump and is set to asterisks (“*****”) for security — which will result in your password being reset to all asterisks if you don’t remove the line.
Create a datastore
This is most useful for when you want to “clone” a datastore configuration from one OpenAM server to another or even between realms.
ssoadm create-datastore -u amadmin -f $HOME/etc/pwd.txt -e /testrealm -m OpenDS -t LDAPv3ForOpenDS -D $HOME/data/ldap1-cfg.txt
The “-t” or “–datatype” parameter is mandatory in creating datastores.
You can get the types supported by the server with:
ssoadm list-datastore-types -u amadmin -f $HOME/etc/pwd.txt
Output will look something like this:
Supported Datastore Types: Description Type ---------------------------------------- --------------- Database Repository (Early Access) Database Active Directory LDAPv3ForAD Tivoli Directory Server LDAPv3ForTivoli Sun DS with OpenAM schema LDAPv3ForAMDS OpenDS LDAPv3ForOpenDS Active Directory Application Mode (ADAM) LDAPv3ForADAM
If you use the output of the “show-datastore” command for an existing datastore as input for a new one, you’ll want to change the value for:
… to the password of the admin user entry that will bind to the directory server for OpenAM. By default this is represented by a line of asterisks, which will definitely cause a bind failure. The value can be clear text. It will get encoded SHA when committed to the server configuration.
List Web Agents in a realm
Example given is for Web Agents in the /testrealm realm.
ssoadm list-agents -e /testrealm -t WebAgent -u amadmin -f $HOME/etc/pwd.txt
Show a Web Agent config
ssoadm show-agent -e /testrealm -b testagent-01 -u amadmin -f $HOME/etc/pwd.txt >/tmp/testagent-cfg-01
Here “-b” is where you specify the name of the agent as shown by the list-agents command. There is an “-o” parameter for output files but I usually just use a redirect.
Create a Web Agent
Best done using an input file, usually from an existing agent configuration.
Be sure to add this attribute/value pair to the end of your input file — it is required for creating an agent object:
The “agentpassword” string being the password used to authorize the remote agent’s registration with the server. This parameter is left out of the output from the “show-agent” command.
ssoadm create-agent -e /testrealm -t WebAgent -b testagent-02 -u amadmin -f $HOME/etc/pwd.txt -D /tmp/testagent-cfg-01
Notice I’ve used the output of an existing agent config for my input here (after inserting the userpassword attribute and value).
Update a Web Agent
Making changes to agent configurations using ssoadm can reduce errors commonly committed when using a gui. It can also come in handy when syncing agent configurations in a multi-agent environment.
Begin by exporting the existing agent configuration (or configuration for the agent you want to sync with) using the “ssoadm show-agent” command as described above.
ssoadm update-agent -e /testrealm -b testagent-02 -u amadmin -f $HOME/etc/pwd.txt -D /tmp/testagent-cfg-02
Check the resulting configuration in both the gui and at the command line (by doing another “ssoadm show-agent”) to make sure none of the attribute values were munged, and correct as necessary. Pay particular attention to those attributes having multiple values.
Comparing Agent Configurations
In comparing web agent configurations it is always a good idea to first sort the results from the show-agent command, since attributes and their values are normally ordered randomly. You can do that like this:
sort testagent-cfg-01.txt >testagent-cfg-01.txt~ sort testagent-cfg-02.txt >testagent-cfg-02.txt~
Having sorted the files you want to compare, you can then use diff or your differencing tool of choice on them.
diff testagent-cfg-01.txt~ testagent-cfg-02.txt~