Using ssoadm in AM/OpenAM

This book provides information on using ssoadm in AM/OpenAM to make configuration changes as well as tips to help you get the most from ssoadm.


FAQ: Installing and using ssoadm in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing and using ssoadm in AM/OpenAM.

Frequently asked questions

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

A. If you access the configuration store and/or AM/OpenAM 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/OpenAM 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/OpenAM 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/OpenAM 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. 

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:

  • load balancer: 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 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 Installation Guide › Installing and Starting Servers › 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 by adding the following JVM options to the ssoadm or ssoadm.bat script:

-D"opensso.protocol.handler.pkgs=com.sun.identity.protocol" \
-D"com.iplanet.am.jssproxy.trustAllServerCerts=true" \

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.

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

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/OpenAM and must be done separately.

See Upgrade Guide › Upgrading Components › Upgrading 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:

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

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:

$ ./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/OpenAM 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/OpenAM 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/OpenAM 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/OpenAM 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 Reference › Command Line Tools › 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/OpenAM (All versions)?

ssoadm fails in AM/OpenAM (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/OpenAM (All versions)

Subsequent attempts to use ssoadm fail in AM/OpenAM (All versions)

Using ssoadm in AM/OpenAM

FAQ: Installing AM/OpenAM

FAQ: Configuring AM/OpenAM

FAQ: General AM/OpenAM

Installation Guide › Installing and Starting Servers › Setting Up Administration Tools

Reference › Command Line Tools › ssoadm

Related Training

ForgeRock Access Management Core Concepts (AM-400)


How do I export and import Service configurations for AM/OpenAM (All versions)?

The purpose of this article is to provide steps on using ssoadm to export and import your Service configuration for AM/OpenAM. These commands are used when making edits to your service configuration file. Additionally, exporting the service configuration is commonly used by Administrators and Support to validate configuration settings. You can also use Amster to export and import configurations in AM 5 and later.

Amster (AM 5 and later)

In AM 5 and later, you can also use Amster to export and import configurations as detailed in:

With Amster, it is also possible to import a Service configuration that was created in a different version of AM/OpenAM. For example, you can export a configuration from AM 5 and import it into AM 5.5.

Note

If you have custom modules, you must ensure you have installed and registered the custom module first as detailed in How do I import Service configurations in AM (All versions) using Amster when there are custom modules?

Exporting Service configurations using ssoadm

You can export your Service configurations using the following ssoadm command:

$ ./ssoadm export-svc-cfg -u [adminID] -f [passwordfile] -e [secretkey] -o [outputfile]

replacing [adminID], [passwordfile], [secretkey] and [outputfile] with appropriate values.

Note

The secret key can be any value and is used to encrypt passwords from the configuration; the same key must be used again when importing the configuration through ssoadm import-svc-cfg.

Known issues

The following known issues may prevent you from exporting Service configurations using ssoadm:

Importing Service configurations using ssoadm

Caution

You cannot import a Service configuration that was created in a different version of AM/OpenAM using ssoadm. 

You can import your Service configurations using the following ssoadm command:

$ ./ssoadm import-svc-cfg -u [adminID] -f [passwordfile] -e [secretkey] -X [XMLfile]

replacing [adminID], [passwordfile], [secretkey] and [XMLfile] with appropriate values.

Restart the web application container in which AM/OpenAM runs to update the configuration.

Known issues

The following known issues may prevent you from importing Service configurations using ssoadm:

Back up and Restore

In testing environments, you can use the ssoadm import and export commands to back up and restore your service configuration. In production environments, you should back up the service configuration using file system utilities or the export-ldif command. The export-ldif  and import-ldif commands must be on the same deployment as the one where the encryption keys are located. 

See To Back Up All Server Configuration DataFAQ: Backing up AM/OpenAM and How do I make a backup of configuration data in AM/OpenAM (All versions)? for further information.

See Also

How do I import Service configurations in AM (All versions) using Amster when there are custom modules?

Guice creation errors when importing service configurations using ssoadm in AM (All versions) and OpenAM 13.5.1 

How do I enable Message level debugging in AM/OpenAM (All versions) debug files?

How do I collect all the data required for troubleshooting AM/OpenAM and Policy Agents (All versions)?

Troubleshooting AM/OpenAM and Policy Agents

Reference › Command Line Tools › ssoadm

User Guide › Using the Amster Command-line Interface › Exporting Configuration Data

User Guide › Using the Amster Command-line Interface › Importing Configuration Data

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-12123 (ssoadm import-svc-cfg cannot work on 5.5.x)

OPENAM-12122 (NPE during export-svc-cfg)

OPENAM-12089 (13.5.1 ssoadm import-svc-cfg fails with "An registered exception occurred." error exception )

OPENAM-11607 (ssoadm import-svc-cfg fails with Guice errors)

OPENAM-8265 (Cannot import service configuration via ssoadm)

OPENAM-8169 (OpenAM Policies not shown after importing service configuration xml via ssoadm)

OPENAM-7928 (ssoadm export-svc-cfg / import-svc-cfg should mention that 'ldif-export / ldif-import' can only be used on the same deployment)

OPENAM-3793 (import-svc-cfg overrides serverconfigxml from import)  


How do I make a backup of configuration data in AM/OpenAM (All versions)?

The purpose of this article is to provide information on backing up configuration data in AM/OpenAM, using DS/OpenDJ tools to provide a more reliable and comprehensive backup than using ssoadm.

Background information

The Configuration directory ($HOME/[am_instance]) contains files created during the install process. Some of these files contain critical information that is required when AM/OpenAM initializes; AM/OpenAM cannot start if these files become corrupt or are missing. For this reason, it is essential to back up the Configuration directory to enable you to recover AM/OpenAM to its original state if needed. The files used when AM/OpenAM initializes includes all the files in the /opends directory and the following files:

  • bootstrap or boot.json depending on your version of AM/OpenAM.
  • keystore.jceks or keystore.jks depending on which keystore you are using.
  • certificate stores
  • openam_mon_auth (used in web based monitoring). This file is not required in AM 5 and later.
  • .version
Note

Although you can use the How do I export and import Service configurations for AM/OpenAM (All versions)? command to back up configuration data, there are some known issues with this approach that are included in the Related Issue Tracker IDs section below; in production environments, it is recommended that you use DS/OpenDJ tools to back up your configuration data if you use DS/OpenDJ as your configuration store.

There are two options available for using DS/OpenDJ tools to back up your configuration directory: 

  • DS/OpenDJ backup and restore - this option is the preferred approach; it should be used when you want to back up configuration data with the intention that you can restore it at a later date, if needed, and it would be replicated to other servers.
  • Export-ldif and import-ldif commands - this option is only required if you may need to revert changes from all replicating servers in the future. Typically this isn't required for configuration data, as you can simply reverse a change if it is no longer required. For example, if you change a configuration setting to TRUE, you can change it back to FALSE to revert the change.

In a replicated environment, the replication changelog has a purge delay of 3 days (by default). With either of these backup options, If you restore a backup taken within this period, the restored server will be able to re-sync with the other DS/OpenDJ servers; if you have an older backup, it will never be able to re-sync. It is therefore important to take periodic backups. 

Caution

It is also recommended that you take a file system backup of the directories for each AM/OpenAM server in your deployment as described in Upgrade Guide › About Upgrading › Back Up the Deployment. If you ever need to restore a corrupted AM/OpenAM server, it is essential to have a backup of your configuration store and the file system backup. Additionally, you should back up the $HOME/.openamcfg/ directory; the file used to bootstrap (the bootstrap locator file) is located in this directory.

Using DS/OpenDJ backup and restore

You can use a backup command such as the following to back up your configuration directory:

$ ./backup --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backUpAll --backupDirectory /path/to/ds/bak --start 0
Note

You only need to specify a start time if you are scheduling the backup; you can use --start 0 to perform the backup immediately.

You can tell that the backup command was successful by checking the error log (located in the $HOME/[am_instance]/opends/logs directory). If the backup was successful, you should see messages similar to this:

[30/Oct/2016:10:49:19 +0000] category=BACKEND severity=NOTICE msgID=9896349 msg=Backup task 20131030104919093 started execution
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend schema
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend tasks
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend userRoot
[30/Oct/2016:10:49:19 +0000] category=JEB severity=NOTICE msgID=8847446 msg=Archived: 00000000.jdb
[30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944795 msg=The backup process completed successfully
[30/Oct/2016:10:49:19 +0000] category=BACKEND severity=NOTICE msgID=9896350 msg=Backup task 20131030104919093 finished execution

You can restore changes using the restore command as follows:

$ ./restore --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backupDirectory /path/to/ds/bak

Using export-ldif and import-ldif

Note

The export-ldif  and import-ldif commands must be on the same deployment as the one where the encryption keys are located.

You can back up and restore the configuration directory using export-ldif and import-ldif as follows:

  1. Back up the configuration directory using an export-ldif command such as:
    $ ./export-ldif --hostname ds1.example.com --port 4444 --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/backupfile.ldif
  2. Prepare the replicated domain prior to importing the ldif data: You must specify the baseDN of the data you are going to be changing (that is, the one for which you exported ldif data), for example:
    $ ./dsreplication pre-external-initialization --hostname ds1.forgerock.com --port 4444 --baseDN dc=example,dc=com --adminUID admin --adminPassword password --trustAll --no-prompt
    
  3. Restore the configuration on all servers using an import-ldif command such as:
    $ ./import-ldif --hostname ds1.example.com --port 4444 --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/backupfile.ldif
  4. Enter the following command on one of the servers to set the new generation ID for the entire domain:
    $ ./dsreplication post-external-initialization --hostname ds1.forgerock.com --port 4444 --baseDN dc=example,dc=com --adminUID admin --adminPassword password --trustAll --no-prompt 

The above steps alter the generation ID of the replicated domain. "Old" changes will not get replayed because they were targeting the data using the previous generation ID. The final step calculates a new generation ID for the domain and broadcasts it to all the servers, which allows them to replicate again.

Replication will now proceed as normal, but from the restored point in time.

See Also

FAQ: Backing up AM/OpenAM

How do I export and import Service configurations for AM/OpenAM (All versions)?

Installing and configuring AM/OpenAM

Setup and Maintenance Guide › Maintaining an Instance › Backing Up and Restoring Configurations

Administration Guide › Backing Up and Restoring Data

Administration Guide › Managing Directory Data

Reference › Tools Reference

Related Training

N/A

Related Issue Tracker IDs

OPENAM-718 (Agent group membership lost after backup/restore)

OPENAM-3165 (NPE during export-svc-cfg)

OPENAM-3793 (import-svc-cfg overrides serverconfigxml from import)

OPENAM-7928 (ssoadm export-svc-cfg / import-svc-cfg should mention that 'ldif-export / ldif-import' can only be used on the same deployment)


How do I add a second configuration store or edit an existing configuration store in AM/OpenAM (All versions)?

The purpose of this article is to provide information on adding a second configuration store to AM/OpenAM. You may want to do this in a high availability (HA) environment where you have multiple servers in a site. This information can also be used to update an existing directory configuration and includes a way of doing it via ssoadm.

Maintaining configuration store details

Note

In OpenAM 11.x and 12.x, you can only have two configuration stores as they use the legacy Netscape® LDAP SDK. If you have more than two configuration stores listed, OpenAM will only use the first two in the list.

You can add a second configuration store or update details for an existing configuration store using either the console or ssoadm:

Console

  1. Navigate as follows:
    • AM / OpenAM 13.5 console: navigate to: Deployment > Servers > [Server Name] > Directory Configuration > Server, and add a new server or edit the existing server details as needed.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > [Server Name] > Directory Configuration > Server, and add a new server or edit the existing server details as needed.
  2. Restart the web application container in which AM/OpenAM runs.

ssoadm 

  1. Output the current server configuration details to an XML file using the following command:
    $ ./ssoadm get-svrcfg-xml -u [adminID] -f [passwordfile] -s [serverName] -o [XMLfile]
    
    replacing [adminID], [passwordfile], [serverName] and [XMLfile] with appropriate values.
  2. Locate the following section in the XML file you output in step 1 (ServerGroup name="sms"):
    <ServerGroup name="sms" minConnPool="1" maxConnPool="10">
        <Server name="Server1" host="localhost" port="18080" type="SIMPLE" />
    
  3. Update these server details if you want to make amendments; otherwise add a new line if you want to add a second configuration store. For example:
    <ServerGroup name="sms" minConnPool="1" maxConnPool="10">
        <Server name="Server1" host="localhost" port="18080" type="SIMPLE" />
        <Server name="Server2" host="localhost" port="28080" type="SIMPLE" />
    
  4. Upload the updated server configuration XML file to AM/OpenAM using the following command:
    $ ./ssoadm set-svrcfg-xml -u [adminID] -f [passwordfile] -s [serverName] -X [XMLfile]
    replacing [adminID], [passwordfile], [serverName] and [XMLfile] with appropriate values.
  5. Restart the web application container in which AM/OpenAM runs.

See Also

How do I change the password for the configuration store in AM/OpenAM (All versions)?

How do I migrate from an embedded to external DS/OpenDJ in AM/OpenAM (All versions)?

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8738 (Need more scriptable method to change Config Stores "Directory Configuration" than xml files)


How do I create a user data store in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on creating a user data store in AM/OpenAM using ssoadm. This is an external identity repository that contains user profiles or identity data (attributes) for users who have authenticated to AM/OpenAM.

Creating a data store

The properties you can set when creating a data store depend on the data store type you are creating. You can find the equivalent ssoadm attribute names by looking in the Admin guide for the appropriate data store type: Setup and Maintenance Guide › Setting Up Identity Data Stores.

Note

You cannot change the Load Schema or Load schema when saved option via ssoadm when creating a data store, as AM/OpenAM should not amend the directory schema. This is discussed in OPENAM-1853 (Add ssoadm flag to load schema while creating datastore).

You can create a data store via ssoadm as follows:

  1. Create a data file (called DATA_FILE to match the next command) and populate it with the required properties. The attached DATASTORE_DATA_FILE provides all the properties for the DS/OpenDJ data store in OpenAM 13 (in order, with default values); you can use this as a template to create a DS/OpenDJ data store.
  2. Enter the following command to create the data store with these settings: 
    $ ./ssoadm create-datastore -e [realmname] -u [adminID] -f [passwordfile] -m [datastoreName] -t [datastoreType] -D DATA_FILE
    
    replacing [realmname], [adminID], [passwordfile], [datastoreName] and [datastoreType] with appropriate values, where [datastoreType] is one of the following values (which correspond to supported data store types):
    datastoreType Description
    LDAPv3ForAD Active Directory
    LDAPv3ForTivoli Tivoli Directory Server
    LDAPv3ForAMDS Sun DS with AM/OpenAM schema
    LDAPv3ForOpenDS DS/OpenDJ

Refer to the release notes for a list of supported data stores. For example: Release Notes › Before You Install › Data Store Requirements

See Also

How do I understand what the user data store is used for in AM/OpenAM (All versions)?

How do I make a whole user data store read-only to users in AM/OpenAM (All versions)?

How do I change the data store minimum password length in AM/OpenAM (All versions)?

Data stores in AM/OpenAM

Setup and Maintenance Guide › Setting Up Identity Data Stores

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-1853 (Add ssoadm flag to load schema while creating datastore)

OPENAM-3762 (sun-idrepo-ldapv3-config-memberurl doesn't exist for LDAPv3ForOpenDS )


How do I configure an external CTS token store in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on configuring an external Core Token Service (CTS) token store in AM/OpenAM using ssoadm.

Prerequisites

The external CTS token store must already exist (and you just want to modify its configuration using ssoadm) or you must take steps to prepare the external OpenDJ instance for CTS first if you want to automate the entire process.

The Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)  article guides you through all the steps needed to configure an external OpenDJ instance for CTS. In summary, these steps are:

  1. OpenDJ base build and CTS data (container and schema) import.
  2. Non-admin user creation and ACI import.
  3. CTS index import and rebuild.
  4. AM/OpenAM console configuration.
  5. Testing session failover.

You must complete steps 1 to 3 prior to configuring an external CTS token store in AM/OpenAM. You can then use these instructions to complete step 4 using ssoadm instead of using the console if you wish.

See Installation Guide › Implementing the Core Token Service for further information.

Configuring an external CTS token store

You can configure an external CTS token store using ssoadm as follows:

  1. Create a data file (called DATA_FILE to match the next command) and include the following properties with appropriate values (example values are shown): 
    ​org.forgerock.services.cts.store.directory.name=host.domain:60589
    org.forgerock.services.cts.store.heartbeat=10
    org.forgerock.services.cts.store.location=external
    org.forgerock.services.cts.store.loginid=uid=user
    org.forgerock.services.cts.store.max.connections=10
    org.forgerock.services.cts.store.password=password
    org.forgerock.services.cts.store.root.suffix=dc=example,dc=com
    org.forgerock.services.cts.store.ssl.enabled=false
  2. Enter the following command:
    $ ./ssoadm update-server-cfg -s [serverName] -u [adminID] -f [passwordfile] -D DATA_FILE
    
    replacing [serverName], [adminID] and [passwordfile] with appropriate values. You can use default for [serverName] if you want to change the Default Server Settings.
  3. Restart the web application container in which AM/OpenAM runs.

If you only want to update some of the configuration settings, you can specify just the attributes you want to change. For example, to change the maximum number of connections, you could use the following ssoadm command:

$ ./ssoadm update-server-cfg -s default -u amadmin -f pwd.txt -a org.forgerock.services.cts.store.max.connections=17

See Also

Best practice for configuring an external DS/OpenDJ instance for the Core Token Service (CTS) in AM/OpenAM (All versions)

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

FAQ: Installing and using ssoadm in AM/OpenAM

Installation Guide › Implementing the Core Token Service › CTS Configuration

Installation Guide › Implementing the Core Token Service

Setup and Maintenance Guide › Maintaining an Instance › Tuning LDAP CTS and Configuration Store Settings

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4673 (External CTS Root DN is hardcoded)


How do I tune LDAP connection pool settings in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide assistance with tuning LDAP connection pool settings in AM/OpenAM using ssoadm. These connection pool settings apply to your LDAP data stores and LDAP authentication modules.

Tuning LDAP connection pool settings

LDAP data store settings

You can configure the LDAP data store connection pool sizes as follows using ssoadm:

  • LDAP Connection Pool Minimum Size: enter the following command:
    $ ./ssoadm update-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] -a sun-idrepo-ldapv3-config-connection_pool_min_size=[size]
    replacing [realmname], [datastorename], [adminID], [passwordfile] and [size] with appropriate values.
  • LDAP Connection Pool Maximum Size: enter the following command:
    $ ./ssoadm update-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] -a sun-idrepo-ldapv3-config-connection_pool_max_size=[size]
    replacing [realmname], [datastorename], [adminID], [passwordfile] and [size] with appropriate values.

LDAP authentication modules 

You can configure the LDAP authentication module connection pool sizes (Default LDAP Connection Pool Size) as follows using ssoadm:

$ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t global -u [adminID] -f [passwordfile] -a iplanet-am-auth-ldap-connection-pool-default-size=[minSize:maxSize]

replacing [adminID], [passwordfile] and [minSize:maxSize] with appropriate values.

For example, if you wanted to tune this to the recommended production settings: 10 (minimum connection pool size) and 65 (maximum connection pool size), you would use an ssoadm command such as:

$ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t global -u amadmin -f pwd.txt -a iplanet-am-auth-ldap-connection-pool-default-size=10:65

See Also

How do I understand what the user data store is used for in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

Setup and Maintenance Guide › Maintaining an Instance › Tuning LDAP Data Store Settings

Setup and Maintenance Guide › Maintaining an Instance › Tuning LDAP Authentication Module Settings

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I update Authentication modules in an authentication chain in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on updating Authentication modules in an authentication chain in AM/OpenAM using ssoadm. This also includes removing existing Authentication modules. This article assumes the authentication chain already exists.

Updating the authentication chain

You can update the Authentication modules in an existing authentication chain using the following ssoadm command:

$ ./ssoadm update-auth-cfg-entr -u [adminID] -f [passwordfile] -e [realmname] -m [authchain] -a "[module1|criteria|options]" "[module2|criteria|options]"

replacing [adminID], [passwordfile], [realmname], [authchain] and "[module|criteria|options]" with appropriate values. You should include "[module|criteria|options]" for each module you want included in the chain (in the required order) where:

  • module is the module name, for example, LDAP.
  • criteria is REQUIRED, OPTIONAL, SUFFICIENT or REQUISITE.
  • options are any additional options and values you want to specify. This is optional and each option=value should be separated with a space.

Alternatively, you can use a data file to specify these values using the ssoadm -D option instead of -a. 

Note

The update-auth-cfg-entr command overwrites the Authentication modules included in the chain with the ones specified. Therefore you must always specify all the modules you want included. For example, if you already have two modules in a chain and want to add a new one, you must specify all three. Similarly, if you already have three modules in a chain and want to remove one, you must specify the two remaining ones.

Example - add a module

To add a second module (LDAP) to the testChain that already includes the DataStore module (no options):

$ ./ssoadm update-auth-cfg-entr -u amadmin -f pwd.txt -e / -m testChain -a "DataStore|REQUIRED" "LDAP|SUFFICIENT"

Example - update modules

To update these modules in the testChain to share credentials by adding options and to make the LDAP module REQUIRED:

$ ./ssoadm update-auth-cfg-entr -u amadmin -f pwd.txt -e / -m testChain -a "DataStore|REQUIRED|iplanet-am-auth-store-shared-state-enabled=true" "LDAP|REQUIRED| iplanet-am-auth-shared-state-enabled=true iplanet-am-auth-shared-state-behavior-pattern=useFirstPass"

Example - remove a module

To remove the LDAP module (and the shared credential options) from the testChain:

$ ./ssoadm update-auth-cfg-entr -u amadmin -f pwd.txt -e / -m testChain -a "DataStore|REQUIRED"

Example - using a data file

To add two new modules (LDAP and HOTP) to the testChain that replace the DataStore module (no options):

  1. Create a data file (called DATA_FILE to match the next command) with the following contents:
    LDAP|REQUIRED
    HOTP|REQUIRED
    
  2. Run the following command:
    $ ./ssoadm update-auth-cfg-entr -u amadmin -f pwd.txt -e / -m testChain -D DATA_FILE
Note

There is a known issue in OpenAM 13.0, which prevents added options being seen in the console and further options being added: OPENAM-8727 (Module options in authentication chain are not displayed or editable). This is a UI issue only; the options are stored correctly in the configuration store and can be viewed using the ssoadm get-auth-cfg-entr command. This is fixed in OpenAM 13.5.

See Also

FAQ: Installing and using ssoadm in AM/OpenAM

Reference › Command Line Tools › ssoadm

Authentication and Single Sign-On Guide › Implementing Authentication › Configuring Authentication Chains

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8727 (Module options in authentication chain are not displayed or editable)


How do I create a policy agent that inherits group settings using ssoadm in AM/OpenAM (All versions)?

The purpose of this article is to provide information on creating a policy agent that inherits group settings using ssoadm in AM/OpenAM.

Overview

Using Agent groups in AM/OpenAM is recommended when you have multiple policy agents behind a load balancer as it ensures all policy agents have the same updated configuration. Consider the following flow:

  1. AM/OpenAM sends a notification to the load balancer.
  2. The load balancer sends it on to one of the policy agents.
  3. The policy agent receiving the notification updates its configuration; this means the other policy agents now have out-of-date configurations.

Where an agent group is used instead in the above flow, the load balancer sends the notification to the agent group. This means the policy agents within this group will inherit the updated settings.

Creating a policy agent that inherits group settings

You can use ssoadm to create a policy agent that inherits group settings as follows:

  1. Create the agent group using the following ssoadm command:
    $ ./ssoadm create-agent-grp -u [adminID] -f [passwordFile] -t [agentType] -e [realmName] -b [agentGroupName]
    replacing [adminID], [passwordFile], [agentType], [realmName] and [agentGroupName] with appropriate values.
  2. Create the policy agent using the following ssoadm command:
    $ ./ssoadm create-agent -u [adminID] -f [passwordFile] -t [agentType] -e [realmName] -b [agentName] -g [agentURL] -s [serverURL] -a [agentProperties]
    
    replacing [adminID], [passwordFile], [agentType], [realmName], [agentName], [agentURL], [serverURL] and [agentProperties] with appropriate values.
  3. Assign the policy agent you created in step 2 to the group you created in step 1 using the following ssoadm command:
    $ ./ssoadm add-agent-to-grp -u [adminID] -f [passwordFile] -e [realmName] -b [agentGroupName] -s [agentName]
    replacing [adminID], [passwordFile], [realmName], [agentGroupName] and [agentName] with appropriate values.
  4. Remove any properties from the agent's configuration that you want to be inherited from the agent group using the following ssoadm command:
    $ ./ssoadm agent-remove-props -u [adminID] -f [passwordFile] -e [realmName] -b [agentName] -a [agentProperties]
    replacing [adminID], [passwordFile], [realmName], [agentName] and [agentProperties] with appropriate values.
Note

The agent-remove-props command does not support the use of a data file; if you have lots of properties to remove, you may consider using the do-batch command as detailed in How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

Example

The following example demonstrates an agent group being created, a new web policy agent being created, that web policy agent being assigned to the group and finally two properties being removed that should be inherited from the agent group.

$ ./ssoadm create-agent-grp -u amadmin -f pwd.txt -t WebAgent -e / -b agentGroup1

Agent group was created.


$ ./ssoadm create-agent -u amadmin -f pwd.txt -t WebAgent -e / -b agent1 -g http://agent.example.com:80 -s http://host1.example.com:8080/openam -a userpassword=password

Agent configuration was created.


$ ./ssoadm add-agent-to-grp -u amadmin -f pwd.txt -e / -b agentGroup1 -s agent1

Agent was added to group.


$ ./ssoadm agent-remove-props -u amadmin -f pwd.txt -e / -b agent1 -a com.sun.identity.agents.config.sso.only com.sun.identity.agents.config.sso.cache.polling.interval

Properties were removed.

See Also

How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

FAQ: Configuring Policy Agents in AM/OpenAM

Using ssoadm in AM/OpenAM

Reference › Command Line Tools › ssoadm

Web Policy Agent Guide › Implementing Web Policy Agents › Creating Agent Profiles

OpenAM JEE Policy Agent User's Guide › Configuring Java EE Policy Agents › Creating Agent Profiles

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3937 (inheritance does not work with ssoadm update-agent-grp --set)

OPENAM-5466 (Agent does not automatically inherit group settings)


How do I create a hosted IdP or SP in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on creating a hosted IdP or SP in AM/OpenAM using ssoadm. Using ssoadm allows you to automate the entire entity provider creation process, including adding attribute mapping.

Creating a hosted IdP or SP

You can create a hosted IdP or SP using ssoadm as follows: 

  1. Create the Circle of Trust (COT) unless it already exists:
    $ ./ssoadm create-cot -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT]
    replacing [adminID], [passwordfile], [realmname], [entityCOT] with appropriate values. You will see the following response if this was successful:
    Circle of trust, [entityCOT] was created.
  2. Create the metadata template XML files unless they already exist:
    $ ./ssoadm create-metadata-templ -u [adminID] -f [passwordfile] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile] [metaAlias] 
    
    replacing [adminID], [passwordfile], [entityID], [metadataXMLfile], [extendedXMLfile] and [metaAlias] with appropriate values, where [metaAlias] is one of the following options and values depending on the type of entity provider you are creating:
    • IdP - this should be option -i with a value equal to the metaAlias for the hosted identity provider and should be in the format: [realm name]/[metaAlias], for example: -i /idp for a metaAlias of idp in the top level realm.
    • SP - this should be option -s with a value equal to the metaAlias for the hosted service provider and should be in the same format as detailed above for the IdP.
    For example, if you wanted to create metadata template XML files for your IdP (with an ID of EmployeeIdP and a metaAlias of idp in realm employees), your command would look similar to this:
    $ ./ssoadm create-metadata-templ -u amadmin -f pwd.txt -y EmployeeIdP -c saml2 -m standard.xml -x extended.xml -i employees/idp
    You will see the following response if this was successful:
    Hosted entity configuration was written to extended.xml. 
    Hosted entity descriptor was written to standard.xml.
Note

This simple example create-metadata-templ command creates basic template files, which you can use as a start point for your rmetadata files. However, you can create more comprehensive template files, if required, by specifying other properties as detailed in Reference › Command Line Tools › ssoadm create-metadata-templ.

  1. Update your metadata files as necessary and include any additional details needed. If you want to map attributes, you can add attribute mapping to the extended metadata file using the following format:
    <Attribute name="attributeMap">
         <Value>EmailAddress=mail</Value>
         <Value>username=uid</Value>
    </Attribute>
    
    Where the first attribute listed (EmailAddress and username in this example) are the attributes used by the entity provider you are creating.
  2. Import the metadata files to create the entity provider in AM/OpenAM:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You will see the following response if this was successful:
    Import file, [metadataXMLfile].
    Import file, [extendedXMLfile].
Note

You could script these changes to fully automate updating your entity providers. See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information on scripting ssoadm commands.

See Also

How do I export and import SAML metadata in AM/OpenAM (All versions)?

How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3172 (ssoadm create-metadata-templ fails with Exception)


How do I register a remote IdP or SP in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on registering a remote IdP or SP in AM/OpenAM using ssoadm. Using ssoadm allows you to automate the entire entity provider creation process, including adding attribute mapping.

Registering a remote IdP or SP

You can register a remote IdP or SP using ssoadm as follows: 

  1. Create the Circle of Trust (COT) unless it already exists:
    $ ./ssoadm create-cot -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT]
    replacing [adminID], [passwordfile], [realmname], [entityCOT] with appropriate values. You will see the following response if this was successful:
    Circle of trust, [entityCOT] was created.
  2. Create the metadata template XML files unless they already exist:
    $ ./ssoadm create-metadata-templ -u [adminID] -f [passwordfile] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile] [metaAlias] 
    
    replacing [adminID], [passwordfile], [entityID], [metadataXMLfile], [extendedXMLfile] and [metaAlias] with appropriate values, where [metaAlias] is one of the following options and values depending on the type of entity provider you are creating:
    • IdP - this should be option -i with a value equal to the metaAlias for the remote identity provider and should be in the format: [realm name]/[metaAlias].
    • SP - this should be option -s with a value equal to the metaAlias for the remote service provider and should be in the same format as detailed above for the IdP.
    For example, if you wanted to create metadata template XML files for your IdP (with an ID of EmployeeIdP and a metaAlias of idp in realm employees), your command would look similar to this:
    $ ./ssoadm create-metadata-templ -u amadmin -f pwd.txt -y EmployeeIdP -c saml2 -m standard.xml -x extended.xml -i employees/idp
    You will see the following response if this was successful:
    Remote entity configuration was written to extended.xml. 
    Remote entity descriptor was written to standard.xml.
Note

This simple example create-metadata-templ command creates basic template files, which you can use as a start point for your metadata files. However, you can create more comprehensive template files, if required, by specifying other properties as detailed in Reference › Command Line Tools › ssoadm create-metadata-templ.

  1. Update the extended metadata file to indicate it is a remote entity provider you want to create. Change the following hosted="true" value:
    <EntityConfig xmlns="urn:sun:fm:SAML:2.0:entityconfig"
        xmlns:fm="urn:sun:fm:SAML:2.0:entityconfig"
        hosted="true"
    
    
    to hosted="false":
    <EntityConfig xmlns="urn:sun:fm:SAML:2.0:entityconfig"
        xmlns:fm="urn:sun:fm:SAML:2.0:entityconfig"
        hosted="false"
    
    
  2. Update your metadata files as necessary and include any additional details needed. If you want to map attributes, you can add attribute mapping to the extended metadata file using the following format:
    <Attribute name="attributeMap">
         <Value>EmailAddress=mail</Value>
         <Value>username=uid</Value>
    </Attribute>
    
    Where the first attribute listed (EmailAddress and username in this example) are the attributes used by the entity provider you are creating.
  3. Import the metadata files to create the entity provider in AM/OpenAM:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You will see the following response if this was successful:
    Import file, [metadataXMLfile].
    Import file, [extendedXMLfile].
Note

You can script these changes to fully automate creating entity providers. See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information on scripting ssoadm commands.

See Also

How do I export and import SAML metadata in AM/OpenAM (All versions)?

How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

How do I create a hosted IdP or SP in AM/OpenAM (All versions) using ssoadm?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3172 (ssoadm create-metadata-templ fails with Exception)


How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on updating metadata for an IdP or SP in AM/OpenAM using ssoadm. Using ssoadm allows you to automate the entire entity provider update process, including adding attribute mapping, if required.

Updating metadata

Standard metadata is the information necessary to transmit an agreement between Identity and Service providers on how they want to set up the federation (through NameID) and where to reach the various services. As such, you should only change this for remote entities if the change has been requested by the remote entity itself. Similarly, if you make changes to the standard metadata for the hosted entity, you must communicate these changes to all the remote entities. You can make any changes required to the extended metadata as this is not part of the standard and is not shared.

You can update metadata for an IdP or SP using ssoadm as follows: 

  1. Back up the entity data in case you need to revert your changes. You can do this by exporting the IdP's or SP's standard and extended metadata files using the following ssoadm command:
    $ ./ssoadm export-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityID], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You will see the following response if this was successful:
    Entity descriptor was exported to file, [metadataXMLfile].
    Entity configuration was exported to file, [extendedXMLfile].
  2. Update your metadata files as necessary and include any additional details needed. If you want to map attributes, you can add attribute mapping to the extended metadata file using the following format:
    <Attribute name="attributeMap">
         <Value>EmailAddress=mail</Value>
         <Value>username=uid</Value>
    </Attribute>
    
    Where the first attribute listed (EmailAddress and username in this example) are the attributes used by the entity provider you are updating.
Note

If you have only changed the extended metadata file, you can include the -x option in the following delete-entity command to only delete the extended metadata rather than the entire entity provider. If you do this, you only need to import the extended metadata in the subsequent step.

  1. Delete the IdP or SP as follows, depending on which metadata files you updated:
    • extended metadata file only - you can use the following ssoadm command:
      $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -x
      replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values. You will see the following response if this was successful:
      Configuration was deleted for entity, [entityID].
    • standard metadata file only or both -  you can use the following ssoadm command:
      $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2
      replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values. You will see the following response if this was successful:
      Descriptor was deleted for entity, [entityID].
  2. Import the metadata file(s) to re-create or update the entity provider in OpenAM:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You will see the following response if this was successful:
    Import file, [metadataXMLfile].
    Import file, [extendedXMLfile].
Note

You could script these changes to fully automate updating your entity providers. See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information on scripting ssoadm commands.

See Also

How do I export and import SAML metadata in AM/OpenAM (All versions)?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

How do I change the hostname for a remote IdP or SP entity in AM/OpenAM (All versions)?

How do I create a hosted IdP or SP in AM/OpenAM (All versions) using ssoadm?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2350 (Implement ssoadm command to update portions of standard/extended SAML metadata)


How do I add and configure a REST STS instance in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide assistance with adding and configuring a REST STS (Secure Token Service) instance in AM/OpenAM using ssoadm.

Overview

The ssoadm command used to add a REST STS instance differs between versions. In summary, the -b and -g options have swapped round as of OpenAM 13.x and you no longer need to escape the forward slash in the REST STS instance name. However, the ssoadm command to configure a REST STS instance is unchanged.

Adding a REST STS instance (AM and OpenAM 13.x)

Firstly you should create a data file (in this example, DATA_FILE) and populate it with the required attribute values for the new REST STS instance. You can use the attached DATA_FILE to get started.

You can then add a REST STS instance using ssoadm as follows:

$ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e [realmname] -b [subconfigname] -g [parentconfigID] -u [adminID] -f [passwordfile] -D DATA_FILE

replacing [realmname], [subconfigname], [parentconfigID], [adminID] and [passwordfile] with appropriate values, where:

  • [subconfigname] is the REST STS instance name. If you want to have a REST STS instance name that follows the same convention used when creating a REST STS instance via the console (that is, realm/deployment-url), you can set this to: "realm/deployment-uri".
  • [parentconfigID] is the ID of the parent configuration (SubSchema name), as defined in restSTS.xml (located in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where AM/OpenAM is deployed). The SubSchema name is serverconfig by default.

Example

To create a REST STS instance called testSTS in the employees realm, you would use the following command:

$ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e employees -b "employees/testSTS" -g serverconfig -u amadmin -f pwd.txt -D DATA_FILE

Adding a REST STS instance (OpenAM 12.x)

Firstly you should create a data file (in this example, DATA_FILE) and populate it with the required attribute values for the new REST STS instance. You can use the attached DATA_FILE to get started.

You can then add a REST STS instance using ssoadm as follows

$ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e [realmname] -g [subconfigname] -b [parentconfigID] -u [adminID] -f [passwordfile] -D DATA_FILE

replacing [realmname], [subconfigname], [parentconfigID], [adminID] and [passwordfile] with appropriate values, where:

  • [subconfigname] is the REST STS instance name. If you want to have a REST STS instance name that follows the same convention used when creating a REST STS instance via the console (that is, realm/deployment-url), you should set this to: "realm&#47;deployment-uri" where &#47; escapes the forward slash.
  • [parentconfigID] is the ID of the parent configuration (SubSchema name), as defined in restSTS.xml (located in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where OpenAM is deployed). The SubSchema name is serverconfig by default.

Example

To create a REST STS instance called testSTS in the employees realm, you would use the following command:

$ ./ssoadm create-sub-cfg -s RestSecurityTokenService -e employees -g "employees&#47;testSTS" -b serverconfig -u amadmin -f pwd.txt -D DATA_FILE

Configuring a REST STS instance

You can use the ssoadm get-sub-cfg command to check what attributes are available and then update them using set-sub-cfg.

Example

  1. Run the ssoadm get-sub-cfg command to check which attributes are available:
    $ ./ssoadm get-sub-cfg -s RestSecurityTokenService -e employees -g "employees&#47;testSTS" -u amadmin -f pwd.txt
    Example output (where only saml2-token-lifetime-seconds has been set to the default value of 600):
    saml2-custom-attribute-statements-provider-class-name=
    saml2-attribute-map=
    supported-token-transforms=OPENAM|SAML2|false
    supported-token-transforms=OPENIDCONNECT|SAML2|true
    supported-token-transforms=USERNAME|SAML2|true
    supported-token-transforms=X509|SAML2|true
    saml2-sign-assertion=
    saml2-name-id-format=
    issuer-name=
    deployment-realm=
    saml2-encryption-key-alias=
    saml2-custom-subject-provider-class-name=
    saml2-encrypt-nameid=
    saml2-keystore-filename=
    saml2-signature-key-password=
    deployment-auth-target-mappings=X509|module|cert_module|x509_token_token_auth_target_header_key=client_cert
    deployment-auth-target-mappings=OPENIDCONNECT|module|oidc|oidc_id_token_auth_target_header_key=oidc_id_token
    deployment-auth-target-mappings=USERNAME|service|ldapService
    deployment-tls-offload-engine-hosts=
    saml2-encryption-algorithm=http://www.w3.org/2001/04/xmlenc#aes128-cbc
    saml2-custom-attribute-mapper-class-name=
    saml2-encryption-algorithm-strength=
    saml2-custom-authz-decision-statements-provider-class-name=
    saml2-custom-conditions-provider-class-name=
    saml2-token-lifetime-seconds=600
    saml2-encrypt-assertion=
    saml2-sp-entity-id=
    saml2-custom-authn-context-mapper-class-name=
    deployment-url-element=
    saml2-sp-acs-url=
    saml2-signature-key-alias=
    saml2-encrypt-attributes=
    deployment-offloaded-two-way-tls-header-key=
    saml2-keystore-password=
    saml2-custom-authentication-statements-provider-class-name=
    
    Sub Configuration emp&#47;testSTS was retrieved from realm employees
  2. Change the lifetime of the SAML2 token that is created by REST STS to 5 minutes (instead of the default 10 minutes) using the following command: 
    $ ./ssoadm set-sub-cfg -s RestSecurityTokenService -e employees -g "employees&#47;testSTS" -u amadmin -f pwd.txt -o set -a saml2-token-lifetime-seconds=300

See Also

Using the REST STS in AM/OpenAM

Security Token Service Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6532 (Unable to add a Rest STS instance with a value of "/" in the --subconfigname/-g option using ssoadm - NullPointerException - needs to be URL encoded)

OPENAM-6811 (Support consumption of rest endpoints from ssoadm)


How do I configure audit logging via ssoadm in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on configuring audit logging via ssoadm in AM/OpenAM. This also includes information on adding, deleting and modifying audit event handlers.

Configuring audit logging

You can configure audit logging at either a global or realm level as required. The global and realm configuration options are described in Reference › Configuration Reference › Audit Logging with the equivalent ssoadm attribute names. Alternatively, you can return all the current settings to get you started using the ssoadm get-attr-defs command (global) or the ssoadm get-realm-svc-attrs command (realm). For example:

$ ./ssoadm get-attr-defs -s AuditService -t global -u amadmin -f pwd.txt

auditEnabled=true
fieldFilterPolicy=/access/http/request/queryParameters/tokenId
fieldFilterPolicy=/access/http/request/headers/cache-control
fieldFilterPolicy=/access/http/request/queryParameters/redirect_uri
fieldFilterPolicy=/access/http/request/queryParameters/Login.Token1
fieldFilterPolicy=/access/http/request/headers/accept-language
fieldFilterPolicy=/config/before
fieldFilterPolicy=/access/http/request/headers/%AM_AUTH_COOKIE_NAME%
fieldFilterPolicy=/config/after
fieldFilterPolicy=/access/http/request/queryParameters/access_token
fieldFilterPolicy=/access/http/request/headers/X-OpenAM-Password
fieldFilterPolicy=/access/http/request/queryParameters/id_token_hint
fieldFilterPolicy=/access/http/request/headers/proxy-authorization
fieldFilterPolicy=/access/http/request/queryParameters/IDToken1
fieldFilterPolicy=/access/http/request/queryParameters/requester
fieldFilterPolicy=/access/http/request/headers/connection
fieldFilterPolicy=/access/http/request/queryParameters/sessionUpgradeSSOTokenId
fieldFilterPolicy=/access/http/request/headers/content-type
fieldFilterPolicy=/access/http/request/cookies/%AM_COOKIE_NAME%
fieldFilterPolicy=/access/http/request/headers/accept-encoding
fieldFilterPolicy=/access/http/request/headers/authorization
fieldFilterPolicy=/access/http/request/headers/content-length
fieldFilterPolicy=/access/http/request/headers/%AM_COOKIE_NAME%

Schema attribute defaults were returned.

Global

You can set global properties using the following ssoadm command:

$ ./ssoadm set-attr-defs -s AuditService -t global -u [adminID] -f [passwordfile] -a [attributes]

replacing [adminID], [passwordfile] and [attributes] with appropriate values.

Realm level

You can set realm level properties using the following ssoadm command:

$ ./ssoadm set-realm-svc-attrs -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -a [attributes]

replacing [realmname], [adminID], [passwordfile] and [attributes] with appropriate values.

Configuring audit event handlers

The following audit event handlers are available depending on your version of AM/OpenAM:

Audit event handler type AM 6.x AM 5.x OpenAM 13.5 OpenAM 13
JSON Yes Yes -- --
CSV Yes Yes Yes Yes
Syslog Yes Yes Yes Yes
JDBC Yes Yes Yes Yes
Elasticsearch Yes Yes Yes --
JMS Yes Yes Yes --
Splunk Yes Yes -- --

You can configure audit event handlers at a global level or realm level (secondary configurations) as required. The following commands show the realm parameter included; if you want to configure them at the global level instead, just exclude the realm parameter. The properties you can set are described in Reference › Audit Logging with the corresponding ssoadm attribute name. Alternatively, you can return all the current settings for an existing audit event handler using the ssoadm get-sub-cfg command. For example, to return the settings for the global JSON handler (default handler in AM 5 and later) with no realm parameter:

$ ./ssoadm get-sub-cfg -s AuditService -u amadmin -f pwd.txt -g "Global JSON Handler"

rotationInterval=-1
rotationTimes=
bufferingMaxSize=100000
topics=access
topics=activity
topics=config
topics=authentication
rotationEnabled=true
retentionMinFreeSpaceRequired=-1
enabled=true
handlerFactory=org.forgerock.openam.audit.events.handlers.JsonAuditEventHandlerFactory
retentionMaxNumberOfHistoryFiles=1
retentionMaxDiskSpaceToUse=-1
rotationFileSuffix=-yyyy.MM.dd-HH.mm.ss
bufferingWriteInterval=5
rotationMaxFileSize=100000000
location=%BASE_DIR%/%SERVER_URI%/log/
rotationFilePrefix=
elasticsearchCompatible=false
rotationRetentionCheckInterval=5

Sub Configuration, Global JSON Handler was retrieved.

Add a new audit event handler

You can add an audit event handler using the following ssoadm command:

$ ./ssoadm create-sub-cfg -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -g [eventHandlerType] -b [eventHandlerName] -a [attributes]

replacing [realmname], [adminID], [passwordfile], [eventHandlerType], [eventHandlerName] and [attributes] with appropriate values, where [eventHandlerType] should equal one of the types in the above table.

Modify an existing audit event handler

You can modify an existing audit event handler using the following ssoadm command:

$ ./ssoadm set-sub-cfg -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -g [eventHandlerName] -o set -a [attributes]

replacing [realmname], [adminID], [passwordfile], [eventHandlerName] and [attributes] with appropriate values. 

For example, to configure the file to rotate once a day (86400 seconds) for an existing audit event handler (called Daily CSV File in this example), you would use an ssoadm command such as:

$ ./ssoadm set-sub-cfg -s AuditService -e / -u amadmin -f pwd.txt -g "Daily CSV File" -o set -a rotationEnabled=true rotationInterval=86400 rotationFileSuffix=-yy.MM.dd-HH.mm
Note

There is a known issue in OpenAM 13.0 that can make the set-sub-cfg command run very slowly when updating audit event handlers via ssoadm: OPENAM-8441 (Deleting an audit service using the REST SMS takes a long time). This is fixed in OpenAM 13.5. 

Delete an audit event handler

You can delete an audit event handler using the following ssoadm command:

$ ./ssoadm delete-sub-cfg -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -g [eventHandlerName]

replacing [realmname], [adminID], [passwordfile] and [eventHandlerName] with appropriate values. 

See Also

How do I log audit events to a database in OpenAM 12.x and 13.x?

Error when flushing the writer message when AM (All versions) and OpenAM 13.x is under high load with audit logging enabled

How do I improve the performance of ssoadm in AM/OpenAM (All versions)?

How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

Authentication and Single Sign-On Guide › Configuring Audit Event Handlers

Reference › Configuration Reference › Audit Logging

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8441 (Deleting an audit service using the REST SMS takes a long time)

OPENAM-8389 (Audit Event Handler ignores realm-based log configurations)


How do I add and update applications in the AM/OpenAM (All versions) Dashboard Service using ssoadm?

The purpose of this article is to provide information on adding and updating applications in the AM/OpenAM Dashboard Service using ssoadm. The default applications are Google®, SalesForce® and Zendesk®. This article also includes information on assigning applications to realms and users using ssoadm.

Updating existing applications

You can check the configuration for an existing application using the ssoadm get-sub-cfg command. For example, to check the configuration for the default Google application:

$ ./ssoadm get-sub-cfg -s dashboardService -g Google -u amadmin -f pwd.txt

dashboardLogin=http://www.google.com
dashboardIcon=images/logos/googleplus.png
dashboardClassName=SAML2ApplicationClass
ICFIdentifier=idm magic 34
dashboardDisplayName=Google
dashboardName=Google

Sub Configuration DashboardService was retrieved.

Once you know what the current configuration is, you can update the application's configuration using the ssoadm set-sub-cfg command. For example, to change the name displayed on the dashboard for the Google application:

$ ./ssoadm set-sub-cfg -s dashboardService -g Google -u amadmin -f pwd.txt -o set -a dashboardDisplayName="Google Apps"

See Reference › Configuration Reference › Dashboard for further information on the available options.

Adding new applications

You can create new applications using the ssoadm create-sub-cfg command. You can exclude the ICFIdentifier attribute as it is not required (although it gets added by default if you add the application via the console). The command varies slightly between versions; in summary, the difference is that the -b and -g options have swapped round in AM / OpenAM 13.x. 

Example 

This example demonstrates creating an application for Google Mail; you should ensure the logo you want to use exists in the directory specified (dashboardIcon):

  1. Create a data file (called DATA_FILE to match the next command) with the following contents:
    dashboardLogin=https://mail.google.com/mail
    dashboardIcon=images/logos/googlemail.png
    dashboardClassName=SAML2ApplicationClass
    dashboardDisplayName="Google Mail"
    dashboardName=GoogleMail
  2. Enter the following command depending on which version of AM/OpenAM you are using:
    • AM / OpenAM 13.x:
      $ ./ssoadm create-sub-cfg -s dashboardService -g dashboardApp -b GoogleMail -u amadmin -f pwd.txt -D DATA_FILE
    • Pre-OpenAM 13.x:
      $ ./ssoadm create-sub-cfg -s dashboardService -g GoogleMail -b dashboardApp -u amadmin -f pwd.txt -D DATA_FILE

Assigning applications to realms and users

Once you have configured your applications, you need to make them available in selected realms and/or to selected users.

Realms

For example, to make the Google and Zendesk applications available in the top level realm:

$ ./ssoadm set-svc-attrs -s dashboardService -e / -u amadmin -f pwd.txt -a assignedDashboard=Google assignedDashboard=Zendesk

This command overwrites any existing applications that are available in the realm; if you already have applications available in the realm, you must include both the new and existing applications in this command.

Note

You may need to add the dashboardService if it is not assigned to the realm. You can do this by replacing set-svc-attrs in the above ssoadm command with add-svc-realm.

Users

For example, to make the Google application available to the demo user:

$ ./ssoadm set-identity-svc-attrs -s dashboardService -e / -t User -i demo -u amadmin -f pwd.txt -a assignedDashboard=Google

This command overwrites any existing applications that are available to the user; if you already have applications available to the user, you must include both the new and existing applications in this command.

Note

You may need to add the dashboardService if it is not assigned to the user. You can do this by replacing set-identity-svc-attrs in the above ssoadm command with add-svc-identity

See Also

FAQ: Installing and using ssoadm in AM/OpenAM

Setup and Maintenance Guide › Setting Up the Dashboard Service

Reference › Configuration Reference › Dashboard

Setup and Maintenance Guide › Setting Up the Dashboard Service › Displaying Dashboard Applications

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5610 (Remove ICF Identifier field from the Dashboard Service configuration)


Tips


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

The purpose of this article is to provide information on enabling message level debugging for ssoadm in AM/OpenAM. Message level debugging can be useful when troubleshooting ssoadm issues. Additionally, you can enable SSL debug logging if you access the configuration store and/or AM/OpenAM instance using a SSL/TLS secured connection.

Enabling message level debugging

You can enable message level debugging in ssoadm as follows:

  1. Add the following JVM option to the ssoadm or ssoadm.bat script:
    -D"com.iplanet.services.debug.level=message" \
  2. Delete the contents of the /debug directory; the /debug directory is specified during the installation of the ssoadm administration tool. You can confirm which directory this is by checking the value of the following JVM option in the ssoadm or ssoadm.bat script:
    -D"com.iplanet.services.debug.directory=YOUR_DEBUG_FOLDER_PATH" \
  3. Re-attempt the ssoadm command that was causing issues to obtain more detailed debug information; this is logged to the /debug directory. 

Enabling SSL debug logging

You can enable SSL debug logging by adding the following JVM option to the ssoadm or ssoadm.bat script:

-D"javax.net.debug=SSL" \

SSL debugging information is output to the command line providing you access the configuration store and/or AM/OpenAM instance using a SSL/TLS secured connection.

See Also

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

FAQ: Installing and using ssoadm in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

The purpose of this article is to provide information on setting multiple attributes with a single ssoadm command in AM/OpenAM. This is useful when you want to add multiple attributes for a single sub-command, for example, set-identity-attrs or set-attr-defs.

Adding multiple attributes

You can add multiple attributes using a single ssoadm command either by using a data file or by specifying multiple attributes against the -a parameter with a space as the separator.

For example, if you want to run the following ssoadm commands to make session related changes:

$ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u amadmin -f pwd.txt -a iplanet-am-session-max-session-time=150

$ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u amadmin -f pwd.txt -a iplanet-am-session-max-idle-time=15

$ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u amadmin -f pwd.txt -a iplanet-am-session-max-caching-time=5

You could use one of the following approaches instead of running them separately:

Data file

  1. Create a data file (called DATA_FILE to match the next command) with the following contents:
    iplanet-am-session-max-session-time=150
    iplanet-am-session-max-idle-time=15
    iplanet-am-session-max-caching-time=5
  2. Run the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u [adminID] -f [passwordfile] -D DATA_FILE
    replacing [adminID] and [passwordfile] with appropriate values.

Multiple attributes in one command

Run the following command to change all the attributes at the same time:

$ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u [adminID] -f [passwordfile] -a iplanet-am-session-max-session-time=150 iplanet-am-session-max-idle-time=15 iplanet-am-session-max-caching-time=5

replacing [adminID] and [passwordfile] with appropriate values.

Note

If you want to change multiple attributes for multiple sub-commands, you will need to use the ssoadm do-batch command or a script. This is detailed in: How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

See Also

How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5505 (Setting openam-session-timeout-handler-list= in ssoadm set-attr-defs ends up creating a list with one empty item)


How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

The purpose of this article is to provide information on making batch changes using ssoadm in AM/OpenAM. You can make multiple changes to AM/OpenAM using ssoadm commands, which makes scripted installs or upgrades possible.

Overview

There are two approaches you can take to making batch changes, both of which utilize ssoadm commands. You can:

  • use the ssoadm do-batch command.
  • use a bash or bat script (depending on your operating system).

Using the ssoadm do-batch command means multiple ssoadm commands are executed together in a single JVM call. This can be much quicker than using a bash or bat script (depending on the number of changes) where ssoadm commands are executed consecutively as individual JVM calls. However, if you use a bash or bat script, you can make use of variables, which may be advantageous depending on your setup.

The following sections give examples of these two approaches based on running the following ssoadm commands as a batch to make some service related changes:

$ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u amadmin -f pwd.txt -a iplanet-am-session-max-session-time=150

$ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u amadmin -f pwd.txt -a iplanet-am-session-max-idle-time=15

$ ./ssoadm set-attr-defs -s iPlanetAMSessionService -t dynamic -u amadmin -f pwd.txt -a iplanet-am-session-max-caching-time=5

$ ./ssoadm set-realm-svc-attrs -s MailServer -e /employees -u amadmin -f pwd.txt -a forgerockEmailServiceSMTPSSLEnabled="Non SSL"
Note

If you only want to change multiple attributes related to the same ssoadm sub-command (for example, set-attr-defs), there are simpler options available as described in How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

Using do-batch commands

Firstly you need to create a batch file containing all the ssoadm commands you want to run. The ssoadm commands you include in the batch file take the same format as the ones you would normally run individually but with the ./ssoadm part, and the -u and -p parameters removed. The only exception to this is when attribute values are surrounded in quotes; in this situation, you should surround the attribute name and value in quotes. This is a known issue: OPENAM-8234 (ssoadm batch fails when attribute values are surrounded by quotes).

For example:

  1. Create a batch file (called services.batch to match the next command) containing the following:
    # Update service properties
    set-attr-defs -s iPlanetAMSessionService -t dynamic -a iplanet-am-session-max-session-time=150
    set-attr-defs -s iPlanetAMSessionService -t dynamic -a iplanet-am-session-max-idle-time=15
    set-attr-defs -s iPlanetAMSessionService -t dynamic -a iplanet-am-session-max-caching-time=5
    set-realm-svc-attrs -s MailServer -e /employees -a "forgerockEmailServiceSMTPSSLEnabled=Non SSL"
  2. Execute the commands in the batch file using the following ssoadm command:
    $ ./ssoadm do-batch -u [adminID] -f [passwordfile] -Z services.batch
    replacing [adminID] and [passwordfile] with appropriate values.
Note

You can still include data files or multiple attributes in the ssoadm commands within the batch file as described in How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

Using bash or bat scripts

Firstly you need to create a bash or bat script containing all the ssoadm commands you want to run and any variables you want to use. Obviously you can extend this script to perform other tasks as applicable, but for the purposes of this example, it will just be used for simple ssoadm updates.

For example:

  1. Create a data file (called DATA_FILE to match the next command) with the following contents:
    iplanet-am-session-max-session-time=150
    iplanet-am-session-max-idle-time=15
    iplanet-am-session-max-caching-time=5
  2. Create a bash or bat script (called services.bash to match the next command) containing the following:
    # !/bin/bash
    #
    # Example bash script
    #
    # Define variables
    SSOADM=/opt/tools/openam/bin/ssoadm
    PWORD=/opt/tools/openam/pwd.txt
    #
    # Update service properties
    #
    ${SSOADM} set-attr-defs -s iPlanetAMSessionService -t dynamic -u amadmin -f ${PWORD} -D DATA_FILE
    ${SSOADM} set-realm-svc-attrs -s MailServer -e /employees -u amadmin -f ${PWORD} -a forgerockEmailServiceSMTPSSLEnabled="Non SSL"
    
    Making sure you update the variables to match your environment.
  3. Execute the bash script using the following command:
    $ bash services.bash

See Also

How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

How do I improve the performance of ssoadm in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8234 (ssoadm batch fails when attribute values are surrounded by quotes)

OPENAM-5505 (Setting openam-session-timeout-handler-list= in ssoadm set-attr-defs ends up creating a list with one empty item)

OPENAM-5677 (ssoadm batch: create-auth-instance fails if run after update-auth-cfg-entr)

OPENAM-294 (ssoadm: create and update )


How do I improve the performance of ssoadm in AM/OpenAM (All versions)?

The purpose of this article is to provide information on improving the performance of ssoadm in AM/OpenAM.

Improving the performance of ssoadm

There are five things you can try to improve the performance of ssoadm:

Establishing a baseline

You can add time before the ssoadm command to output the execution time of the ssoadm command, which will help you assess the effect of any changes you make. It is recommended you run a simple command, such as the following, prior to making any changes to give you a baseline:

$ time ./ssoadm list-servers -u amadmin -f pwd.txt

You can then repeat this command after making changes to assess the impact.

Using the do-batch command

You can use the ssoadm do-batch command to run multiple ssoadm commands; using this command means multiple ssoadm commands are executed together in a single JVM call, rather than as individual JVM calls, which speeds up processing time.

See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information.

Increasing the ssoadm heap size

The default ssoadm heap size settings are:

-Xms256m -Xmx512m

You can increase these values (providing you have enough physical memory) to improve ssoadm performance. Initially, you should try setting both Xms and Xmx to 1024m; Xms and Xmx should be the same for the best performance.

You can increase the ssoadm heap size values as follows:

  1. Edit the ssoadm or ssoadm.bat script and update the following line:
    $JAVA_HOME/bin/java -Xms1024m -Xmx1024m -cp "$CLASSPATH" \
  2. Save your changes.
Note

You can update the ssoadm.template or ssoadm.bat.template file (located in the /path/to/ssoadm/tools/template/unix/bin or /path/to/ssoadm/tools/template/windows/bin directory respectively) prior to installation instead; this means ssoadm will be installed with these default values. This approach is useful if you have multiple installations or do automated installs.

Use a client VM

The JDK offers both a client VM and a server VM; the client VM is tuned for reduced startup times and memory footprint, but typically the server VM is used by default. See Java Virtual Machine Technology for further information.

You can force ssoadm to use the client VM as follows:

  1. Edit the ssoadm or ssoadm.bat script and update the following line:
    $JAVA_HOME/bin/java -Xms1024m -Xmx1024m -client -cp "$CLASSPATH" \
  2. Save your changes.
Note

You can update the ssoadm.template or ssoadm.bat.template file (located in the /path/to/ssoadm/tools/template/unix/bin or /path/to/ssoadm/tools/template/windows/bin directory respectively) prior to installation instead; this means ssoadm will be installed with these default values. This approach is useful if you have multiple installations or do automated installs.

Adding the --nolog option to the ssoadm command

There is a known issue in OpenAM 13.0 and 13.5: OPENAM-9685 (SSOAdmin is slow with a site configured), where ssoadm is slow in a site configuration. This issue is resolved in OpenAM 13.5.1.

There is also a known issue in OpenAM 13.5 (resolved in OpenAM 13.5.1): OPENAM-9749 (Resource leak in ssoadm's audit logging), where batch ssoadm commands fail with the following error in the ssoadm IdRepo debug log:

ERROR: IdRemoteServicesImpl.processException(): caught remote/un-known exception -
java.net.SocketException: Too many open files

You can mitigate these issues by adding the --nolog option to your ssoadm command to disable audit logging for that command, for example:

$ ./ssoadm list-servers -u amadmin -f pwd.txt --nolog

Adding a Java option to change how random bits are generated

In some situations, running ssoadm on Linux systems can result in performance issues; this is particularly true if you are using a virtual machine. When this happens, you will see a stack trace similar to the following when generating the SSOToken ID:

"main" prio=10 tid=0x00007f806400c000 nid=0x7e3f runnable [0x00007f8068918000]
   java.lang.Thread.State: RUNNABLE
      at java.io.FileInputStream.readBytes(Native Method)
      at java.io.FileInputStream.read(FileInputStream.java:272)
      at sun.security.provider.SeedGenerator$URLSeedGenerator.getSeedBytes(SeedGenerator.java:526)
      at sun.security.provider.SeedGenerator.generateSeed(SeedGenerator.java:139) 
      at sun.security.provider.SecureRandom$SeederHolder.(SecureRandom.java:186) 
      at sun.security.provider.SecureRandom.engineNextBytes(SecureRandom.java:203) 
      - locked <0x00000000ed1684f0> (a sun.security.provider.SecureRandom) 
      at java.security.SecureRandom.nextBytes(SecureRandom.java:455) 
      - locked <0x00000000ed168790> (a java.security.SecureRandom) 
      at java.security.SecureRandom.next(SecureRandom.java:477) 
      at java.util.Random.nextLong(Random.java:334) 
      at com.sun.identity.authentication.internal.AuthContext.getSSOToken(AuthContext.java:842) 
      at com.sun.identity.setup.Bootstrap.getSSOToken(Bootstrap.java:289) 
      at com.sun.identity.setup.Bootstrap.getConfiguration(Bootstrap.java:203) 
      at com.sun.identity.setup.Bootstrap.load(Bootstrap.java:135) 
      at com.sun.identity.setup.Bootstrap.load(Bootstrap.java:92) 
      - locked <0x00000000eb0536e0> (a java.lang.Class for com.sun.identity.setup.Bootstrap) 
      at com.sun.identity.cli.CommandManager.main(CommandManager.java:113)

To improve the performance in this situation, you can add the following JVM option to the ssoadm script:

-D"java.security.egd=file:/dev/./urandom" \

See Also

How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

Using ssoadm in AM/OpenAM

Best practice for JVM Tuning

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9749 (Resource leak in ssoadm's audit logging)

OPENAM-9685 (SSOAdmin is slow with a site configured)

OPENAM-8441 (Deleting an audit service using the REST SMS takes a long time)

OPENAM-2283 (Document a workaround for ssoadm slowness on virtual machines)


Known Issues


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

The purpose of this article is to provide assistance if you receive the "com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction: FATAL ERROR: Cannot obtain Application SSO token" response when attempting to use ssoadm in AM/OpenAM.

Symptoms

One of the following responses is received when attempting to use ssoadm depending on your AM/OpenAM version:

OpenAM 13.x; AM 5 and later

Logging configuration class "com.sun.identity.log.s1is.LogConfigReader" failed
com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction:  FATAL ERROR: Cannot obtain Application SSO token.

Pre-OpenAM 13

Logging configuration class "com.sun.identity.log.s1is.LogConfigReader" failed
com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction:  FATAL ERROR: Cannot obtain Application SSO token.
Check AMConfig.properties for the following properties
	com.sun.identity.agents.app.username
	com.iplanet.am.service.password

Recent Changes

Recent changes that could result in this issue include the following:

  • Enabled SSL.
  • Configured AM/OpenAM sites.
  • Added a new server to your site configuration in pre-OpenAM 13.0.
  • Changed the dsameuser password.
  • Upgraded AM/OpenAM without upgrading the ssoadm administration tool to the same version.
  • Upgraded to Apache Tomcat™ 8.5 or 9.

Causes

This error can be caused by a number of different issues; the most common of which are:

  • Accessing the configuration store and/or AM/OpenAM instance using a SSL/TLS secured connection but failing to include details of the truststore in the necessary scripts.
  • Having a site configuration but failing to include site-to-server-mapping in the ssoadm or ssoadm.bat script.
  • Adding a new server to your site configuration but not restarting all servers within the site. This is a known issue in OpenAM 13.5.1 and earlier: OPENAM-480 (Adding a server to a site requires restart of OpenAM) and OPENAM-10874 (Adding a new server (site) requires a Restart on all the old servers), which is resolved in OpenAM 13.5.2 and later. This can also cause the following error to be shown immediately before the response detailed in the Symptoms section:
    [Fatal Error] :1:1: Content is not allowed in prolog.
  • Having different dsameuser passwords in your global and local configurations, which means the first ssoadm attempt will succeed, whereas subsequent attempts will fail.
  • Having issues with ssoadm connecting to your AM/OpenAM server, as indicated by the following error in the ssoadm CoreSystem debug file:
    ERROR: Naming service connection failed for http://host1.example.com:8080/openam/namingservice
    com.iplanet.services.comm.client.SendRequestException: Connection refused
  • Having an invalid domain specified for the cookie; this causes issues on Tomcat 8.5 and later since Tomcat now enforces stricter checking for valid cookie domain values per RFC 1034 and RFC 6265.

Solution

The solution depends on the cause; you should check and rectify the following if they apply to your setup:

SSL

If you access the configuration store and/or AM/OpenAM instance using a SSL/TLS secured connection, you should add a JVM parameter to specify the truststore that contains the required certificates to the setup or setup.bat script prior to installing ssoadm and to the ssoadm or ssoadm.bat script once it is installed.

This is described in FAQ: Installing and using ssoadm in AM/OpenAM (Q. How do I install the ssoadm administration tool if I am using SSL?).

Site configuration

If you have a site configuration, 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 JVM parameters in the ssoadm or ssoadm.bat script. 

This is described in FAQ: Installing and using ssoadm in AM/OpenAM (Q. How do I install the ssoadm administration tool if I have a Site configuration?).

New Server in Site configuration

If you have added a new server to your site configuration in pre-AM 5, you must restart all servers in the site configuration, including existing ones, to complete the setup.

dsameuser passwords

If you have changed the dsameuser password recently and can access ssoadm on the first attempt but not subsequent attempts, you need to ensure your dsameuser has the same password in your global and local configurations.

This is described in How do I change the dsameuser password in AM/OpenAM (All versions)? and more detail can be found on this particular issue in Subsequent attempts to use ssoadm fail in AM/OpenAM (All versions).

Connection issues

If you are having issues with ssoadm connecting to your AM/OpenAM server, you will need to investigate this further as this issue will be specific to your configuration.

Possible configuration issues to look out for include:

  • Server is not reachable over the network.
  • Server causes naming service to return a site URL that is not reachable.
  • Connection to server or site is refused due to certificate issues.
  • Supplied credentials are incorrect.

Cookie domains and Tomcat

If you have upgraded to Tomcat 8.5 or later, you need to change the cookie domain to remove the leading dot.

This is described in Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

See Also

Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

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

FAQ: Installing and using ssoadm in AM/OpenAM

Subsequent attempts to use ssoadm fail in AM/OpenAM (All versions)

How do I change the dsameuser password in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-10874 (Adding a new server (site) requires a Restart on all the old servers)

OPENAM-8668 (Fresh install of OpenAM doesn't load the login page on some Tomcat versions)

OPENAM-4292 (dsameuser authentication on /authservice differs at startup)

OPENAM-1110 (ssoadm fails with NullPointerException and does not terminate)

OPENAM-480 (Adding a server to a site requires restart of OpenAM)


Subsequent attempts to use ssoadm fail in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if the first use of ssoadm in AM/OpenAM is successful but subsequent attempts fail with a "FATAL ERROR: Cannot obtain Application SSO token".

Symptoms

The first attempt to use ssoadm is successful, whereas subsequent attempts give the following response:

Logging configuration class "com.sun.identity.log.s1is.LogConfigReader" failed
com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction:  FATAL ERROR: Cannot obtain Application SSO token.
Check AMConfig.properties for the following properties
	com.sun.identity.agents.app.username
	com.iplanet.am.service.password

Restarting the web application container in which AM/OpenAM runs allows you to successfully use ssoadm once more before getting the above response.

Recent Changes

Changed the dsameuser password.

Causes

The dsameuser is used by ssoadm to authenticate with AM/OpenAM. The first authentication attempt to ssoadm uses the dsameuser password from the bootstrap file (local configuration) and subsequent authentication attempts use the dsameuser password from the SpecialRepo userstore (global configuration). This is a known issue:  OPENAM-4292 (dsameuser authentication on /authservice differs at startup). Therefore, if your dsameuser passwords are different in your global and local configurations, subsequent authentications to ssoadm will fail. 

Solution

This issue can be resolved by ensuring your dsameuser has the same password in your global and local configurations.

See How do I change the dsameuser password in AM/OpenAM (All versions)? for further information on changing your dsameuser password.

See Also

How do I change the dsameuser password in AM/OpenAM (All versions)?

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

FAQ: Installing and using ssoadm in AM/OpenAM

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

Using ssoadm in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4292 (dsameuser authentication on /authservice differs at startup)


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

The purpose of this article is to provide assistance if you encounter a "Service URL not found:session" error or a "java.lang.NullPointerException" error when running some ssoadm commands in AM/OpenAM. You may also encounter a 401 Unauthorized: Access denied response when running the ssoadm start-recording command. These issues occur when module based authentication is disabled.

Symptoms

When module based authentication is disabled in the top level realm, many ssoadm functions will fail with one of the following errors in response to the ssoadm command:

Service URL not found:session
java.lang.NullPointerException
com.sun.identity.cli.CLIException: Message:New Generic Exception

The following response is shown when you run the ssoadm start-recording command:

{"code":401,"reason":"Unauthorized","message":"Access Denied"}

An error similar to the following is shown in the CoreSystem debug log when the ssoadm command fails:

amXMLHandler:12/07/2015 02:52:34:165 PM EST: Thread[WebContainer : 7,5,main]
ERROR: Exception during LoginIndex
com.sun.identity.authentication.spi.AuthLoginException: Module Based Authentication is not allowed.
   at com.sun.identity.authentication.service.AMLoginContext.executeLogin(AMLoginContext.java:297)
   at com.sun.identity.authentication.server.AuthContextLocal.login(AuthContextLocal.java:544)
   at com.sun.identity.authentication.server.AuthContextLocal.login(AuthContextLocal.java:419)
...

ssoadm commands that do not include the realm parameter are successful, whereas ones that include the realm parameter, such as agent related ones (show-agent, list-agents, create-agent and update-agent) fail.

Recent Changes

Disabled module based authentication (sunEnableModuleBasedAuth=false) in the top level realm. Module based authentication can be checked via the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > Top Level Realm / > Authentication > Settings > Security and check if Module Based Authentication is enabled.
  • Pre-OpenAM 13 console: navigate to: Access Control > (Top Level Realm) > Authentication > All Core Settings > Security and check if the Module Based Authentication option is enabled.
  • ssoadm: enter the following command and check the value of the sunEnableModuleBasedAuth property:
    $ ./ssoadm get-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile]
    replacing [adminID] and [passwordfile] with appropriate values.

Causes

The ssoadm command fails during the authentication process, as successful admin authentication relies on module based authentication being enabled (sunEnableModuleBasedAuth=true) in AM/OpenAM. Admin privileges are needed for some ssoadm commands.

Solution

You can re-enable module based authentication if this is viable. If you do re-enable module based authentication, you can secure your environment by defining policies to have a condition that enforces authentication against a given authentication module/chain. In this scenario, the agent will ensure that the user is authenticated by the configured authentication module/chain; this means it would not be possible to access the application using different authentication mechanisms.

Alternatively, this issue can be resolved as follows depending on your version of AM/OpenAM:

AM 5 and later; OpenAM 12.0.1 and later

This issue is fixed in OpenAM 12.0.1 onwards and two additional JVM options have been introduced to identify which authentication service/module should be used for authenticating as an administrator.

Add the following JVM options to the ssoadm or ssoadm.bat script and set appropriately:

  • org.forgerock.openam.ssoadm.auth.indexType - specify the type of authentication mechanism that should be used for authenticating the administrator in the top level realm; this can be one of the following values:
    • module_instance (this value can only be used if module based authentication is enabled)
    • service
    • user
    • role
    • level
    • composite_advice
    • resource
  • org.forgerock.openam.ssoadm.auth.indexName - enter the name of the actual authentication mechanism that should be used. This must be consistent with the indexType specified. For example, if you set indexType to module_instance, indexName would be the name of the actual authentication module to use, such as LDAP. 

If these JVM options are missing, authentication will continue to rely on module based authentication being enabled.

Caution

Do not use module_instance as your IndexType if module based authentication is disabled as ssoadm will still fail. For a default configuration, you can set the following JVM options to provide an alternative authentication mechanism: org.forgerock.openam.ssoadm.auth.indexType=service | org.forgerock.openam.ssoadm.auth.indexName=ldapService 

OpenAM 12.0.0

This issue can be resolved by upgrading to OpenAM 12.0.1 and later, and setting the JVM options as described above; you can download this from BackStage.

Alternatively, you can use the console to make changes as a workaround.

See Also

Authentication and Single Sign-On Guide › Reference › Security

Related Training

N/A

Related Issue Tracker IDs

OPENAM-816 (ssoadm authentication depends on the sunEnableModuleBasedAuth=true)

OPENAM-5898 (ssoadm get-realm-svc-attrs fails with Nullpointer when module based authentication is disabled)

OPENAM-6211 (Document new JVM properties for ssoadm)


Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

The purpose of this article is to provide assistance if the login page does not load or ssoadm fails in AM running on Apache Tomcat™ 8.5 or 9. The following error is shown when this happens: "An invalid domain [.example.com] was specified for this cookie".

Symptoms

Note

OpenAM 12.x and 13.x support Tomcat 8.0.x, but not 8.5.x; Tomcat 8.5.x is supported in AM 5 and later; Tomcat 9 is supported in AM 6 and later.

Login page

The browser shows a Loading... message; no errors are logged when trying to accessing the login page in AM. 

ssoadm

The following response is shown when ssoadm fails:

Logging configuration class "com.sun.identity.log.s1is.LogConfigReader" failed
com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction:  FATAL ERROR: Cannot obtain Application SSO token.

 The corresponding error is shown in the CoreSystem log when this happens:

ERROR: Exception during LoginIndex
java.lang.IllegalArgumentException: An invalid domain [.example.com] was specified for this cookie
        at org.apache.tomcat.util.http.Rfc6265CookieProcessor.validateDomain(Rfc6265CookieProcessor.java:183)
        at org.apache.tomcat.util.http.Rfc6265CookieProcessor.generateHeader(Rfc6265CookieProcessor.java:125)
        at org.apache.catalina.connector.Response.generateCookieString(Response.java:989)
        at org.apache.catalina.connector.Response.addCookie(Response.java:937)

Recent Changes

Upgraded Tomcat to 8.5 or 9.

Installed AM 5 or later in a new environment that is running Tomcat 8.5 or 9.

Causes

Tomcat enforces stricter checking for valid cookie domain values per RFC 1034 and RFC 6265. In Tomcat 8.0.x, a leading dot was required for cookie domains, whereas this is no longer permitted in 8.5 and later.

Solution

This issue can be resolved by correcting your cookie domain name as follows:

  1. Revert Tomcat to use the legacy cookie processor in order to get your system back up and running. Add the following line to the context.xml file (you should create this file in the /path/to/tomcat/webapps/openam/META-INF directory if it does not already exist):
    <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />
    
    A default context.xml file exists in the /path/to/tomcat/conf directory; this applies to all web applications, but it is preferable to create separate contexts for individual web applications as needed. See Apache Tomcat 8.5 Configuration Reference - Defining a context for further information on contexts.
  2. Modify the cookie domain name to remove the leading dot. You can remove the leading dot from your cookie domain name (for example, example.com rather than .example.com) using either the console or ssoadm:
    • Console: navigate to: Configure > Global Services > Platform > Cookie Domains and modify the cookie domain.
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s iPlanetAMPlatformService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-platform-cookie-domains=["domainname"]
      
      replacing [adminID], [passwordfile] and ["domainname"] with appropriate values.
  3. Reinstate the default cookie processor in Tomcat by removing the line you added in step 1.

See Also

Apache Tomcat 8.5 Configuration Reference - The Cookie Processor Component

Apache Tomcat 8.5 Configuration Reference - Defining a context

FAQ: Cookies in AM/OpenAM

AM/OpenAM (All versions) fail to start due to SEVERE: ContainerBase.addChild: start: error on Apache Tomcat

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

OpenAM 13.5 Release Notes › OpenAM Web Application Container Requirements

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8668 (Fresh install of OpenAM doesn't load the login page on some Tomcat versions)

OPENAM-1983 (Configuration fail with second level FQDN like "example.com")


Creating authentication module via ssoadm causes Not found error in AM 5, 5.1.x and OpenAM 13.0, 13.5

The purpose of this article is to provide assistance if you create an authentication module via ssoadm and get a "Not found error" when trying to open the new module in the AM/OpenAM console.

Symptoms

When you create an authentication module via ssoadm with a command such as the following, where the module name and type match:

$ ./ssoadm create-auth-instance -u amadmin -f pwd.txt -e / -m HOTP -t HOTP 

the module appears to be created but when you try to open it in the console, you will see the following message:

Not found error.

Please note: 

  • You can create authentication modules with the same module name and type via the console. 
  • This issue affects all authentication modules, including custom ones.
  • This issue also affects authentication modules that were created in earlier versions of AM/OpenAM, where the module name and type match. If you upgrade to an affected version and then try to open an authentication module that was created in an earlier version of OpenAM with the same module name and type, you will see the "Not found error."

Recent Changes

Upgraded to, or installed AM 5 or 5.1.x.

Upgraded to, or installed OpenAM 13.0 or 13.5.

Causes

The sub-configuration is not created if the name of the authentication module is the same as the auth type when the module is created using ssoadm.

Solution

This issue can be resolved by upgrading to AM 5.5 and later, or OpenAM 13.5.1; you can download this from BackStage.

Workaround

You can workaround this issue by using a different module name and type when creating the authentication module via ssoadm. For example:

$ ./ssoadm create-auth-instance -u amadmin -f pwd.txt -e / -m HOTPmodule -t HOTP

Alternatively, you can create the authentication module via the console, which allows you to use the same module name and type if required.

See Also

N/A

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9156 ('Not Found' error in UI when opening a custom auth module created with ssoadm with the name the same as type)

OPENAM-8574 (The OpenAM CREST processing chain doesn't contain a RuntimeException handler)


java.lang.ExceptionInInitializerError when using ssoadm commands in AM 5, 5.1 and OpenAM 13, 13.5, 13.5.1

The purpose of this article is to provide assistance if you receive an "Exception in thread "SystemTimer" java.lang.Error: java.lang.ExceptionInInitializerError" error when using ssoadm commands in AM/OpenAM. This error occurs even though the ssoadm response indicates the operation was successful and shows as "caused by: java.lang.IllegalStateException: CachedConnectionPool is already closed".

Symptoms

The following error is sporadically shown when some ssoadm commands are run, even though you will see a positive response (for example, Schema attribute defaults were set).

Exception in thread "SystemTimer" java.lang.Error: java.lang.ExceptionInInitializerError 
   at com.sun.identity.common.TimerPool$WorkerThread.run(TimerPool.java:542) 
Caused by: java.lang.ExceptionInInitializerError 
   at com.sun.identity.idm.IdRepoListener.getChangedIds(IdRepoListener.java:278) 
   at com.sun.identity.idm.IdRepoListener.objectChanged(IdRepoListener.java:174) 
   at com.sun.identity.idm.remote.IdRemoteEventListener.sendIdRepoNotification(IdRemoteEventListener.java:315) 
   at com.sun.identity.idm.remote.IdRemoteEventListener$NotificationRunnable.run(IdRemoteEventListener.java:398) 
   at com.sun.identity.common.TimerPool$WorkerThread.run(TimerPool.java:434) 
Caused by: java.lang.IllegalStateException: CachedConnectionPool is already closed

Recent Changes

Upgraded to, or installed AM 5 or 5.1.

Upgraded to, or installed OpenAM 13, 13.5 or 13.5.1.

Causes

When the ssoadm command is executed, the polling thread tries to retrieve the changes from the server, but ssoadm starts to shut the process down before the changes are retrieved. This timing issue causes the error but the ssoadm operation itself completes successfully.

Solution

Firstly, these errors can be safely ignored since the operation performed by ssoadm still completes successfully.

However, this issue can be resolved by upgrading to AM 5.1.1 or later, or OpenAM 13.5.2; you can download this from BackStage.

See Also

Policy import fails in OpenAM 13.0 with Invalid resource type null message

FAQ: Installing and using ssoadm in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6252 (Sporadic error on ssoadm commands)

OPENAM-7852 (Various list-xxx ssoadm commands fail)


Guice creation errors when importing service configurations using ssoadm in AM (All versions) and OpenAM 13.5.1

The purpose of this article is to provide assistance if you receive a "com.google.inject.CreationException: Guice creation errors" response when using the import-svc-cfg ssoadm command in AM/OpenAM. Alternatively, you may see "An registered exception occurred. Please see log for further details." response instead.

Symptoms

Using the import-svc-cfg ssoadm command fails with one of the following responses:

  • com.google.inject.CreationException: Guice creation errors:
    com.google.inject.CreationException: Guice creation errors:
    
    1) No implementation for javax.servlet.ServletContext annotated with @com.google.inject.name.Named(value=servletContext) was bound.
      while locating javax.servlet.ServletContext annotated with @com.google.inject.name.Named(value=servletContext)
        for parameter 0 at org.forgerock.openam.services.baseurl.BaseURLProviderFactory.<init>(Unknown Source)
      while locating org.forgerock.openam.services.baseurl.BaseURLProviderFactory
        for parameter 1 at org.forgerock.openam.http.OpenAMHttpApplication.<init>(Unknown Source)
      at org.forgerock.openam.http.HttpGuiceModule.configure(HttpGuiceModule.java:35)
    
    1 error
       at com.google.inject.internal.Errors.throwCreationExceptionIfErrorsExist(Errors.java:435)
       at com.google.inject.internal.InternalInjectorCreator.initializeStatically(InternalInjectorCreator.java:154)
       at com.google.inject.internal.InternalInjectorCreator.build(InternalInjectorCreator.java:106)
       at com.google.inject.Guice.createInjector(Guice.java:95)
       at org.forgerock.guice.core.GuiceInjectorCreator.createInjector(GuiceInjectorCreator.java:33)
       at org.forgerock.guice.core.InjectorFactory.createInjector(InjectorFactory.java:63)
       at org.forgerock.guice.core.InjectorHolder.<init>(InjectorHolder.java:49)
       at org.forgerock.guice.core.InjectorHolder.<clinit>(InjectorHolder.java:37)
       at com.sun.identity.cli.SubCommand.execute(SubCommand.java:295)
       at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:217)
       at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:139)
       at com.sun.identity.cli.CommandManager.serviceRequestQueue(CommandManager.java:583)
       at com.sun.identity.cli.CommandManager.<init>(CommandManager.java:180)
       at com.sun.identity.cli.CommandManager.main(CommandManager.java:157)
    
  • An registered exception occurred.  Please see log for further details:
    Process Request ...
    Constructing Request Context...
    Validating mandatory options...
    Processing Sub Command ...
    
    Executing class, com.sun.identity.cli.schema.ImportServiceConfiguration.
    Connecting to directory server.
    Connected to directory server.
    com.sun.identity.cli.CLIException: An registered exception occurred.  Please see log for further details.
       at com.sun.identity.cli.schema.ImportServiceConfiguration.handleRequest(ImportServiceConfiguration.java:153)
       at com.sun.identity.cli.SubCommand.execute(SubCommand.java:296)
       at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:217)
       at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:139)
       at com.sun.identity.cli.CommandManager.serviceRequestQueue(CommandManager.java:578)
       at com.sun.identity.cli.CommandManager.<init>(CommandManager.java:175)
       at com.sun.identity.cli.CommandManager.main(CommandManager.java:152)
    An registered exception occurred.  Please see log for further details.
    

This occurs when you use a command such as the following:

$ ./ssoadm import-svc-cfg -u amadmin -f pwd.txt -e secretkey -X Config.xml

Recent Changes

Upgraded to, or installed AM 5 or later.

Upgraded to, or installed OpenAM 13.5.1.

Causes

Recent changes to resolve OPENAM-10562 (Audit log 'Configuration' entries are not written when using external configuration store) introduced a reliance on Guice to get the Auditor module. ssoadm has not been updated to use this code, which prevents service configurations being imported.

Solution

This issue can be resolved by upgrading to OpenAM 13.5.2; you can download this from BackStage.

Workaround

You can workaround this issue as follows depending on your version:

AM 5 or later

Note

You cannot use Amster to import the XML that was exported using the ssoadm command. The service configuration in AM 5.x is stored in JSON format and unfortunately, they are not interchangeable.

You can use the following Amster commands to export and then import your service configuration:

For example, you would use the following command to export with Amster:

am> export-config --path /path/to/exportedFiles

See Exporting Configuration Data and Importing Configuration Data for a complete list of options. 

OpenAM 13.5.1

You can install and use the ssoadm tool from OpenAM 13.5.0 to import service configurations.

See Also

How do I export and import Service configurations for AM/OpenAM (All versions)?

Guice configuration errors when importing or exporting policies using ssoadm in AM (All versions) and OpenAM 13.5.1

create-realm ssoadm command fails in AM 5 with Guice configuration errors

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12089 (13.5.1 ssoadm import-svc-cfg fails with "An registered exception occurred." error exception )

OPENAM-11607 (ssoadm import-svc-cfg fails with Guice errors)


Guice configuration errors when importing or exporting policies using ssoadm in AM (All versions) and OpenAM 13.5.1

The purpose of this article is to provide assistance if you receive an "Exception in thread "main" com.google.inject.ConfigurationException: Guice configuration errors" response when using the export-policy or import-policy ssoadm commands in AM/OpenAM.

Symptoms

Using the export-policy or import-policy ssoadm command fails with the following exception:

Exception in thread "main" com.google.inject.ConfigurationException: Guice configuration errors:

1) Could not find a suitable constructor in org.forgerock.http.Client. Classes must have either one (and only one) constructor annotated with @Inject or a zero-argument constructor that is not private.
   at org.forgerock.http.Client.class(Unknown Source)
   while locating org.forgerock.http.Client
     for parameter 0 at org.forgerock.openam.cli.entitlement.PolicyExport.<init>(Unknown Source)
   while locating org.forgerock.openam.cli.entitlement.PolicyExport

1 error
   at com.google.inject.internal.InjectorImpl.getProvider(InjectorImpl.java:1004)
   at com.google.inject.internal.InjectorImpl.getProvider(InjectorImpl.java:961)
   at com.google.inject.internal.InjectorImpl.getInstance(InjectorImpl.java:  
   at org.forgerock.guice.core.InjectorHolder.getInstance(InjectorHolder.java:72)
   at com.sun.identity.cli.SubCommand.execute(SubCommand.java:295)
   at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:217)
   at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:139)
   at com.sun.identity.cli.CommandManager.serviceRequestQueue(CommandManager.java:581)
   at com.sun.identity.cli.CommandManager.<init>(CommandManager.java:178)
   at com.sun.identity.cli.CommandManager.main(CommandManager.java:155)

This occurs when you use a command such as the following:

$ ./ssoadm policy-export -e / -u amadmin -f pwd.txt -s "http://host1.example.com:8080/openam" -J policy.json

Recent Changes

Upgraded to, or installed AM 5 or later.

Upgraded to, or installed OpenAM 13.5.1.

Causes

Recent changes to resolve OPENAM-9749 (Resource leak in ssoadm's audit logging) have caused this issue with exporting and importing policies via ssoadm.

Solution

This issue can be resolved by upgrading to OpenAM 13.5.2; you can download this from BackStage.

Workaround

You can workaround this issue as follows depending on your version:

AM 5 and later

You can use Amster or REST to export and import policies. For example, you would use the following command to export with Amster:

$ export-config --path /path/to/export --realm / --realmEntities 'Policies'

See Authorization Guide › Importing and Exporting XACML 3.0 for further information on using REST.

OpenAM 13.5.1

You can install and use the ssoadm tool from OpenAM 13.5 or you can use REST to export and import policies.

See Developer's Guide › Importing and Exporting XACML 3.0 for further information on using REST.

See Also

How do I export and import policies in AM/OpenAM (All versions)?

create-realm ssoadm command fails in AM 5 with Guice configuration errors

Amster User Guide > Exporting Configuration Data

Amster User Guide > Importing Configuration Data

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11584 (Ssoadm policy-import throws Guice error)

OPENAM-9749 (Resource leak in ssoadm's audit logging)


Creating OAuth2 Provider in AM 5.5.x and 6 fails with a Could not initialise script configurations for realm error when using ssoadm

The purpose of this article is to provide assistance if you encounter a "Could not initialise script configurations for realm" error when trying to create an OAuth2 Provider in AM using ssoadm.

Symptoms

A blank response is shown when using a command such as the following to create the OAuth2 Provider:

$ ./ssoadm add-svc-realm -s OAuth2Provider -e / -u amadmin -f pwd.txt -D oauth2providerconfig.txt

Where the oauth2providerconfig.txt file contains the forgerock-oauth2-provider-oidc-claims-extension-script attribute. 

The AM console does not show the creation of the OAuth2Provider.

Debug log

You will see the following error in the ssoadm Configuration debug log when this happens:

amCLI:02/08/2018 09:27:45:487 PM GMT: Thread[main,5,main]: TransactionId[unknown]
ERROR: An unexpected error occurred in thread 'Thread[main,5,main]'
java.lang.IllegalStateException: Could not initialise script configurations for realm /
   at org.forgerock.openam.scripting.service.ScriptConfigurationService.reload(ScriptConfigurationService.java:130)
   at org.forgerock.openam.scripting.service.ScriptConfigurationService.init(ScriptConfigurationService.java:115)
   at org.forgerock.openam.scripting.service.ScriptConfigurationService.<init>(ScriptConfigurationService.java:111)
   at org.forgerock.openam.scripting.service.ScriptChoiceValues.getScriptingService(ScriptChoiceValues.java:116)
   at org.forgerock.openam.scripting.service.ScriptChoiceValues.getChoiceValues(ScriptChoiceValues.java:88)
   at com.sun.identity.sm.AttributeSchemaImpl$AttributeSchemaState.getChoiceValuesMap(AttributeSchemaImpl.
...
Caused by: org.forgerock.openam.scripting.ScriptException: Script type not recognised: AUTHENTICATION_TREE_DECISION_NODE

Recent Changes

Upgraded to, or installed AM 5.5 or later.

Causes

The introduction of authentication tree nodes in AM 5.5 has caused an issue with modifying the script configuration in the OAuth2 provider service. The presence of the forgerock-oauth2-provider-oidc-claims-extension-script attribute prevents the OAuth2 provider being created or the custom script being updated for existing providers.

Solution

This issue can be resolved using one of the following approaches:

  • Use Amster to create the OAuth2 provider
  • Use the REST API to create the OAuth2 provider
  • Exclude the problematic attribute and create the OAuth2 provider using ssoadm
Note

Since ssoadm is deprecated as of AM 5, this known issue will not be resolved.

Use Amster to create the OAuth2 provider

Create the OAuth provider as described in: Entity Reference › OAuth2Provider › create.

Use the REST API to create the OAuth2 provider

You can create the OAuth2 provider using the /realm-config/services/oauth-oidc REST endpoint​. You can use the API Explorer to try out this endpoint as detailed in Development Guide › Introducing the API Explorer, which will provide the OAuth2 provider data you should include in the REST call or you can query the OAuth2 provider service first as demonstrated in the following example:

  1. Authenticate to obtain a SSOToken; you must use the actual AM server URL (not lb). For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0"  http://host1.example.com:8080/openam/json/realms/root/authenticate
    
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
    
  2. Retrieve the OAuth2Provider service details using the following curl command against the actual AM server URL (not lb), where the iPlanetDirectoryPro header (default AM session cookie name) is set to the token returned when you authenticated:
    $ curl -X GET -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/realms/root/realm-config/services/oauth-oidc 
    
    Example response (this has been truncated due to the size of response):
    {
        "_id": "",
        "_rev": "-2046488110",
        "coreOAuth2Config": {
            "refreshTokenLifetime": 604800,
    ...
    ...
      "_type": {
        "_id": "oauth-oidc",
        "name": "OAuth2 Provider",
        "collection": false
      }
    }
    
    
  3. Create the OAuth2 provider using the following curl command against the actual AM server URL (not lb), where the iPlanetDirectoryPro header (default AM session cookie name) is set to the token returned when you authenticated; the data option should include the response from step 2 with the configuration updated for the new provider, and the first _id and _rev fields removed, for example:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0, protocol=1.0" -d '{
        "coreOAuth2Config": {
            "refreshTokenLifetime": 604800,
    ...
    ...
      "_type": {
        "_id": "oauth-oidc",
        "name": "OAuth2 Provider",
        "collection": false
      }
    }' http://host1.example.com:8080/openam/json/realms/root/realm-config/services/oauth-oidc
    
    Example response (this has been truncated due to the size of response):
    {
        "_id": "",
        "_rev": "-870213730",
        "coreOAuth2Config": {
            "refreshTokenLifetime": 604800,
    .........
        "_type": {
            "_id": "oauth-oidc",
            "name": "OAuth2 Provider",
            "collection": false
        }
    }
    

Exclude the problematic attribute and create the OAuth2 provider using ssoadm

  1. Remove the following attribute from your OAuth2 provider configuration file:
    forgerock-oauth2-provider-oidc-claims-extension-script
  2. Re-run the ssoadm command to create the OAuth2 provider, for example:
    $ ./ssoadm add-svc-realm -s OAuth2Provider -e / -u amadmin -f pwd.txt -D oauth2providerconfig.txt
  3. Add the custom claims script in the AM console by navigating to: Realms > [Realm Name] > Services > OAuth2 Provider > OpenID Connect > OIDC Claims Script and adding your custom claims script.

See Also

OAuth 2.0 in AM/OpenAM

Using Amster in AM

Using the REST API in AM/OpenAM

Reference › OAuth2 Provider

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12305 (ssoadm does not create OAuth2Provider service)


ssoadm command fails to run with null pointer exception in AM 5 and 5.1.x

The purpose of this article is to provide assistance if you encounter an "Exception in thread "main" java.lang.NullPointerException" at com.sun.identity.tools.bundles.VersionCheck.isVersionValid(VersionCheck.java:73) when running an ssoadm command in AM 5 or 5.1.x after importing and exporting a service configuration using Amster.

Symptoms

The following error is shown when running a ssoadm command:

Exception in thread "main" java.lang.NullPointerException
 at com.sun.identity.tools.bundles.VersionCheck.isVersionValid(VersionCheck.java:73)
 at com.sun.identity.cli.CommandManager.main(CommandManager.java:145)

If you try to reinstall the ssoadm tools after receiving this error, you will see a message similar to the following after running the setup command (although the tools will install successfully):

The version of this tools.zip is: OpenAM 14.0.0
The version of your server instance is: null

Recent Changes

Exported and then imported a service configuration using Amster.

Causes

The com.iplanet.am.version property value is missing from the Amster export, which causes ssoadm to fail.

Note

The com.iplanet.am.version property is also used to determine when the upgrade process should be started; future upgrades will fail if this property is missing or set incorrectly.

Solution

This issue can be resolved by upgrading to AM 5.5 or later; you can download this from BackStage.

Workaround

You can workaround this issue using either of the following approaches:

  • Add the missing property in the console.
  • Add the missing property to the Amster export and re-import.

Add the missing property in the console

You can add the missing property in the console as follows:

  1. Navigate to: Configure > Server Defaults > Advanced and add the com.iplanet.am.version property and appropriate value, depending on which version of AM you are using:
    AM version Valid com.iplanet.am.version values
    AM 5.1.1 OpenAM 14.1.1 Build 2de1c7b98b (2017-August-09 12:33)
    AM 5.1 OpenAM 14.1.0 Build 0d174ec57d (2017-June-06 09:33)
    AM 5 OpenAM 14.0.0 Build 2db9af6287 (2017-March-29 05:21)
    For example, if you are using AM 5.1, you would add the following:
    com.iplanet.am.version = OpenAM 14.1.0 Build 0d174ec57d (2017-June-06 09:33)
  2. Click + to add followed by Save Changes.

Add the missing property to the Amster export and re-import

You can add the missing property to the Amster export as follows:

  1. Add the com.iplanet.am.version property and appropriate value (per the table above depending on which version of AM you are using) to the data section in the DefaultAdvancedProperties.json file (located in the /path/to/amster/export_dir/global directory). For example, if you are using AM 5, you would add:
    "com.iplanet.am.version" : "OpenAM 14.0.0 Build 2db9af6287 (2017-March-29 05:21)",
    
  2. Re-import the service configuration using Amster.

See Also

FAQ: Installing and using ssoadm in AM/OpenAM

Using ssoadm in AM/OpenAM

Using Amster in AM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11307 (Amster export should include the com.iplanet.am.version property)

OPENAM-11159 (OpenAM Amster export/import for Site have import errors)


create-realm ssoadm command fails in AM 5 with Guice configuration errors

The purpose of this article is to provide assistance if you encounter "Exception in thread "main" com.google.inject.ConfigurationException: Guice configuration errors" when trying to create a new realm in AM 5 using the ssoadm create-realm command.

Symptoms

Using the create-realm ssoadm command fails with the following exception:

Exception in thread "main" com.google.inject.ConfigurationException: Guice configuration errors:

1) No implementation for org.forgerock.openam.notifications.NotificationBroker annotated with interface org.forgerock.openam.notifications.LocalOnly was bound.
  while locating org.forgerock.openam.notifications.NotificationBroker annotated with interface org.forgerock.openam.notifications.LocalOnly

1 error
   at com.google.inject.internal.InjectorImpl.getProvider(InjectorImpl.java:1004)
   at com.google.inject.internal.InjectorImpl.getInstance(InjectorImpl.java:1009)
   at org.forgerock.guice.core.InjectorHolder.getInstance(InjectorHolder.java:85)
   at com.sun.identity.idm.plugins.internal.AgentsRepo.<init>(AgentsRepo.java:183)
   at com.sun.identity.sm.OrganizationConfigManager.createSubOrganization(OrganizationConfigManager.java:344)
   at com.sun.identity.cli.realm.CreateRealm.handleRequest(CreateRealm.java:86)
   at com.sun.identity.cli.SubCommand.execute(SubCommand.java:296)
   at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:217)
   at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:139)
   at com.sun.identity.cli.CommandManager.serviceRequestQueue(CommandManager.java:581)
   at com.sun.identity.cli.CommandManager.<init>(CommandManager.java:178)
   at com.sun.identity.cli.CommandManager.main(CommandManager.java:155

This occurs when you use a command such as the following:

$ ./ssoadm create-realm -e /newRealm -u amadmin -f pwd.txt

The realm is partially created and can be seen in the console, but critical elements such as the data store, services and authentication modules do not exist, so the realm is not fully functional.

Recent Changes

Upgraded to, or installed AM 5.

Causes

There is a missing guice dependency; ssoadm needs its own guice mappings (dependencies) that are separate to the core server ones. In this instance, core classes were changed and new guice dependencies added, but they were not added to ssoadm as well.

Solution

This issue can be resolved by upgrading to AM 5.1 or later; you can download this from BackStage.

Workaround

A suggested workaround for this issue is to use Amster instead to automate realm creation as detailed in Entity Reference › Amster Entity Reference › Realms.

Amster was introduced in AM 5 as a new command-line interface built upon the AM REST interface. Amster will replace ssoadm in a future release.

See Also

How do I update property values in AM (All versions) using Amster?

Using Amster in AM

Entity Reference › Amster Entity Reference › Realms

Amster User Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11034 (OpenAM 14.0.0 (AM5) ssoadm create-realm error)


Policy import fails in OpenAM 13.0 with Invalid resource type null message

The purpose of this article is to provide assistance if you receive an "Invalid resource type null, must be one from the set defined against the containing application" message when trying to import a policy in OpenAM 13.0 via REST or ssoadm. The policy import fails in the OpenAM console without a message.

Symptoms

The following error is shown when attempting to import a policy in XACML format using ssoadm:

com.sun.identity.entitlement.EntitlementException: Invalid resource type null, must be one from the set defined against the containing application.

The following response is received when attempting to import a policy in XACML format using the REST API:

{"code":400,"reason":"Bad Request","message":"Invalid resource type null, must be one from the set defined against the containing application."}

If you try to import a policy via the OpenAM console, the policy is not imported but you do not get a message saying it failed. 

Recent Changes

Installed, or upgraded to OpenAM 13.0.

Causes

OpenAM 13 introduced a new concept - Resource Types which form part of describing policies in OpenAM 13. The resource types are missing from the xml file for the exported policy. The existing resource type is not associated with the imported policy and as such the policy fails validation

Solution

This issue can be resolved by upgrading to OpenAM 13.5 or later; you can download this version from BackStage.

Workaround

Alternatively, this issue can be resolved by manually re-creating the policy using either the OpenAM console or the REST API.

If you want to use the REST API, see How do I create a policy in AM/OpenAM (All versions) using the REST API? for details on successfully creating a policy, including retrieving the missing resource types. This article also provides a Postman collection  to make it easier to create policies.

See Also

How do I export and import policies in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6013 (Resource types are missing in XACML exported policy and it is not possible to import it)

OPENAM-8495 (XACML Import - Existing resource type not being associated with the imported policy)


Updating or creating the WindowsDesktopSSO authentication module via the configurator tool or ssoadm fails in OpenAM 12.0.0, 12.0.1 and 12.0.2

The purpose of this article is to provide assistance if you receive a "iplanet-am-auth-windowsdesktopsso-keytab does not match the service schema" error when updating or creating the Windows Desktop SSO (WDSSO) authentication module via the configurator tool in OpenAM 12.0.0, 12.0.1 and 12.0.2. Similarly, if you use ssoadm to configure the Windows Desktop SSO authentication module, you see a "File [path_to_keytab] did not exist" error.

Symptoms

An error similar to the following is shown in the ssoadm Configuration debug log if you use the configurator tool to configure the Windows Desktop SSO authentication module in OpenAM and include the iplanet-am-auth-windowsdesktopsso-keytab-file property:

amCLI:06/14/2015 10:17:25:789 AM PDT: Thread[main,5,main]
ERROR: UpdateAuthInstance.handleRequest
Message:The attribute name iplanet-am-auth-windowsdesktopsso-keytab does not match the service schema

                at com.sun.identity.sm.ServiceSchemaImpl.validateAttrValues(ServiceSchemaImpl.java:471)
                at com.sun.identity.sm.ServiceSchemaImpl.validateAttributes(ServiceSchemaImpl.java:291)
                at com.sun.identity.sm.ServiceConfig.setAttributes(ServiceConfig.java:536)
                at com.sun.identity.authentication.config.AMAuthenticationInstance.setAttributeValues(AMAuthenticationInstance.java:155)
                at com.sun.identity.cli.authentication.UpdateAuthInstance.handleRequest(UpdateAuthInstance.java:98)
                at com.sun.identity.cli.SubCommand.execute(SubCommand.java:291)
                at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:212)
                at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:134)
                at com.sun.identity.cli.CommandManager.serviceRequestQueue(CommandManager.java:573)
                at com.sun.identity.cli.CommandManager.<init>(CommandManager.java:170)
                at com.sun.identity.cli.CommandManager.main(CommandManager.java:147)

The following response is shown if you use a ssoadm command to add or update the iplanet-am-auth-windowsdesktopsso-keytab-file property:

File [path_to_keytab] did not exist. 

Recent Changes

Upgraded to OpenAM 12.0.0, 12.0.1 or 12.0.2

Created or updated the Windows Desktop SSO authentication module via the configurator tool or ssoadm; specifically setting the iplanet-am-auth-windowsdesktopsso-keytab-file property.

Causes

The UpdateAuthInstance class assumes that all properties ending with -file refer to a file rather than a value as is the case with the iplanet-am-auth-windowsdesktopsso-keytab-file property. Since it cannot locate a file when this property is set, it fails.

Solution

This issue can be resolved by upgrading to OpenAM 12.0.3 or later; you can download this version from BackStage.

Workaround

You can workaround this issue by creating a file that contains the required value for the iplanet-am-auth-windowsdesktopsso-keytab-file property and use the iplanet-am-auth-windowsdesktopsso-keytab-file-file property to reference this file instead.

For example, to update the property via ssoadm you would:

  1. Create a data file (called DATA_FILE to match the next command) that contains the required value for the iplanet-am-auth-windowsdesktopsso-keytab-file property (rather than the actual location of the keytab file itself), for example: 
    /etc/krb5.keytab
  2. Enter the following command to update the Windows Desktop SSO authentication module:
    $ ./ssoadm update-auth-instance -e [realmname] -m [moduleinstancename] -u [adminID] -f [passwordfile] -a iplanet-am-auth-windowsdesktopsso-keytab-file-file=DATA_FILE
    replacing [realmname], [moduleinstancename], [adminID] and [passwordfile] with appropriate values.

See Also

OpenAM Reference › OpenAM Command Line Tools › ssoadm

OpenAM Reference › OpenAM Command Line Tools › configurator.jar

OpenAM Administration Guide › Defining Authentication Services › Hints for the Windows Desktop SSO Authentication Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5894 (Can't update WindowsDesktopSSO module with ssoadm)


Not a supported type: realm error with ssoadm in OpenAM 11.0.0, 11.0.1, 11.0.2 and 12.0.0

The purpose of this article is to provide assistance if you receive a "Not a supported type: realm" error when using ssoadm in OpenAM 11.0.0, 11.0.1, 11.0.2 and 12.0.0. This error is seen when using one of the following ssoadm commands to change realm settings: get-realm-svc-attrs, set-realm-svc-attrs, add-svc-attrs or set-svc-attrs.

Symptoms

An error similar to the following is given in response to the ssoadm command when the -v (verbose) option is used:

Process Request ...
Constructing Request Context...
Validating mandatory options...
Processing Sub Command ...

Executing class, com.sun.identity.cli.realm.RealmSetServiceAttributeValues.
Authenticating...
Authenticated.
com.sun.identity.cli.CLIException: Not a supported type: realm.
        at
com.sun.identity.cli.realm.RealmSetServiceAttributeValues.handleRequest(RealmSetServiceAttributeValues.java:106)
        at com.sun.identity.cli.SubCommand.execute(SubCommand.java:291)
        at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:212)
        at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:134)
        at
com.sun.identity.cli.CommandManager.serviceRequestQueue(CommandManager.java:573)
        at
com.sun.identity.cli.CommandManager.<init>(CommandManager.java:171)
        at com.sun.identity.cli.CommandManager.main(CommandManager.java:148)
Not a supported type: realm.

Attempting to change the Realm specific settings can be set successfully using the OpenAM admin console. 

Recent Changes

Exported / imported service configurations using export-svc-cfg and import-svc-cfg ssoadm commands, and restarted the web application container in which OpenAM runs.

Causes

The Realm configuration object is incorrectly lost when the server is restarted following the export / import process, which causes the realm related sub-commands to fail.

Solution

This issue can be resolved by upgrading to OpenAM 11.0.3, or OpenAM 12.0.1 or later; you can download this from BackStage.

Alternatively, you can work around the lost Realm configuration object using the following ssoadm command:

$ ./ssoadm create-sub-cfg -u [adminID] -f [passwordfile] -s sunIdentityRepositoryService -g realm -b SupportedIdentities -D attrs.txt

replacing [adminID] and [passwordfile] with appropriate values. The attrs.txt file should be empty because the Realm object does not contain any attributes by default.

See Also

OpenAM Reference › OpenAM Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2348 (set-realm-svc-attrs: "Not a supported type: realm")


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...