Using Amster in AM

This book provides information on using Amster in AM to make configuration changes as well as detailing known issues (with solutions).


FAQ: Installing and using Amster in AM

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

Frequently asked questions

Q. Do I need to upgrade Amster when I upgrade AM?

A. Yes, you should always upgrade Amster to the corresponding version when you upgrade AM. This is stated in the release notes: Amster Release Notes › What's New.

Q. Are there any known issues with installing Amster?

A. No, there are no known issues to be aware of when installing Amster. See User Guide › Getting Started with the Amster Command-line Interface for further information.

Q. Are there any known issues with installing AM using Amster?

A. Yes, you should be aware of the following known install issues:

You should also refer to User Guide › Installing ForgeRock Access Management with Amster for further information.

Q. How do I connect to Amster?

A. You can either connect interactively or by using a private key pair (RSA or ECDSA key files) as described in the User Guide › Connecting to ForgeRock Access Management.

Interactive connections

If you choose to use the interactive connection, you should be aware of the following:

Private key connections

If you choose to use the private key connection (non-interactive), you should be aware of the following:

  • You should use self-signed certificates and have either imported them into the JVM's cacerts keystore on the Amster client or run the amster command specifying the truststore containing the certificate and its type.
  • If you use the default RSA key, you must delete the following from authorized_keys to connect locally if AM is not listening on localhost:
    from="127.0.0.0/24,::1"
    
    This is a known issue: OPENAM-11134 (Amster: Remove the 'from' option in authorized_keys).

Q. How can I troubleshoot my SSL connection if it fails?

A. If you experience an issue connecting to the AM instance over HTTPS, you can use one of the following options to help you troubleshoot:

  • Run Amster with the following debug options:
    $ ./amster -d -Djavax.net.debug=all
  • Use the following openssl command to provide information about the SSL connection as well as attempt a SSL handshake:
    $ openssl s_client -connect [hostname:port] -showcerts

Q. How do I view and set AM server defaults using Amster?

A. You should use the DefaultXX entities to view and set server defaults. For example, if you want to read the default server advanced properties, you would use the following command:

am> read DefaultAdvancedProperties --global

See How do I update property values in AM (All versions) using Amster? for a worked example on setting default server security properties.

If you want to configure settings for specific servers, you should use the corresponding entity without the Default prefix. For example, the AdvancedProperties entity is the equivalent of the DefaultAdvancedProperties entity for specific servers. See Entity Reference for further information.

Q. Is there any best practice advice for exporting and importing via Amster?

A. The Amster User Guide provides information on exporting and importing via Amster. Additionally, you should follow these guidelines to avoid common issues:

 Known issues

Q. Can I import encrypted passwords?

A. No, you should import passwords in plain text. Providing AM is correctly configured and you have the required transport key installed, the password will then be encrypted. Subsequent exports will include the encrypted password.

See User Guide › Creating Transport Keys for further information.

Q. How do I use variables with Amster?

A. You can use the following types of variables with Amster:

  • Amster expressions or variables
  • Shell variables
  • Groovy variables

Amster expressions or variables

Depending on what version of Amster you are using, you can use expressions (Amster 6 and later) or variables (Amster 5.x):

Shell variables

Shell variables can be made available as Java® system properties by using the -D parameter as demonstrated in User Guide › Scripting.

Amster also supports shell redirection, which allows you to use here documents. For example:

#!/bin/sh

export_path=/tmp/export

amster <<-EOF

        connect -k amster_rsa  http://host1.example.com:8080/openam
        export-config --path $export_path

EOF

Groovy variables

The Amster shell provides support for Groovy variable assignment. See groovysh — the Groovy command -like shell - variables for further information.

Q. Are variables preserved as placeholders when you do an export?

A. No. Any variables in your configuration are output as values in the export. If you update the exported configuration to include variables, they will be overwritten on the next export.

Q. How do I prevent variable values (such as credentials) being output to the command line?

A. The underlying Groovy shell (groovysh) used by Amster provides support for quiet mode. You can suppress the output of variable values by adding -q to your command. This will not suppress the output of useful information.

Q. Can I execute Amster via a shell script without user intervention?

A. Yes, you can call a script directly from the command line by running Amster followed by the script you want Amster to load, for example:

$ ./amster myScript.amster

Where myScript.amster is the script that contains the Amster commands.

Example

Here is an example of a simple script that installs AM and then quits once complete (no user interaction):

install-openam --serverUrl http://host1.example.com:8080/openam --adminPwd password --policyAgentPwd agentPassword --cookieDomain .example.com --cfgDir /home/openam --acceptLicense
:exit

Q. Can I use Amster commands within Groovy functions or inside a loop context?

A. You can as of Amster 5.5 by using the eval(String) function. See User Guide › Scripting for example uses.

Resolved RFE: OPENAM-11197 (Amster not usable inside groovy functions or not scriptable with loops ).

See Also

How do I enable debug mode for troubleshooting Amster (All versions)?

502 Bad Gateway error when an Amster (All versions) command fails

Using Amster in AM

User Guide

Entity Reference

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12398 (Memory leak in Amster Web Agent Administration)

OPENAM-12334 (Unable to create Saml2Entity using Amster)

OPENAM-11807 (Amster - Delegated administration for Subrealm Configuration)

OPENAM-11773 (amster throws missleading error '502 bad gateway')

OPENAM-11457 (When importing session.json with amster --clean a failure occurs and sesson.json is not imported)

OPENAM-11379 (Have the amster exported JSON ordered)

OPENAM-11197 (Amster not usable inside groovy functions or not scriptable with loops )

OPENAM-10816 (Amster - SAML2 Entity fails to import)


How do I upgrade Amster configuration files when upgrading to AM 6.5?

The purpose of this article is to provide information on upgrading to AM 6.5 if you have Amster configuration files.

Background information

The Amster Configuration Upgrader tool is not included in AM 6.5 as noted in the release notes: Release Notes › Important Changes to Existing Functionality.

Additionally, there is a known issue in AM 6.5 (fixed in AM 6.5.0.1), where an export using the --failOnError true option fails with the following error:

ERROR java.lang.IllegalArgumentException:
Illegal character in path at index 11: json/users/{user}/devices/2fa/webauthn?_queryFilter=true
   at org.forgerock.amster.org.forgerock.openam.sdk.http.HttpSessionImpl.createRequest (HttpSessionImpl.java:244)
   at org.forgerock.amster.org.forgerock.openam.sdk.http.HttpSessionImpl.createRequest (HttpSessionImpl.java:251)
   at org.forgerock.amster.org.forgerock.openam.sdk.http.HttpSessionImpl.request (HttpSessionImpl.java:202)
   at org.forgerock.amster.org.forgerock.openam.sdk.crest.CrestResourceProviderAsync.queryCollectionWithFilter (CrestResourceProviderAsync.java:412)
   at org.forgerock.amster.org.forgerock.openam.sdk.crest.HttpCrestResourceProvider.queryCollectionWithFilter (HttpCrestResourceProvider.java:357)
   at org.forgerock.amster.org.forgerock.openam.sdk.operations.CrestOperations.queryWithFilter (CrestOperations.java:490)
   at org.forgerock.amster.org.forgerock.openam.sdk.operations.CrestOperations.queryWithFilter (CrestOperations.java:475)
   at org.forgerock.openam.amster.loadster.exporter.EntityWriter.writeCollection (EntityWriter.groovy:85)
   at org.forgerock.openam.amster.loadster.exporter.GenericExporter.exportEntity (GenericExporter.groovy:29)

You can either exclude the --failOnError option or set it to false as a workaround; the export will then proceed and just log an error about the endpoint it does not need to query.

See OPENAM-14049 (Amster export failure ) for further information. This issue is fixed in AM 6.5.0.1.

Upgrading Amster configuration files

You can upgrade Amster configuration files as follows:

  1. Perform a standard upgrade by following the steps in Upgrade Guide › To Upgrade From a Supported Version.
  2. Export the configuration from the upgraded server using Amster (either using the --failOnError false option or excluding the --failOnError option). For example:
    am> export-config --path /path/to/export --failOnError false
    The exported configuration is now up-to-date with AM 6.5 and can be used as required.

See Also

Only url, secondaryURLs and _id are valid in write error when importing configuration data via Amster in AM (All versions)

Upgrading AM/OpenAM

Using Amster in AM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14049 (Amster export failure )

OPENAM-12233 (Amster doesn't export custom authentication node configuration)

OPENAM-11906 (Amster import using --clean true and site url hangs)


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

The purpose of this article is to provide information on using Amster to update property values in AM. You can also use these concepts to help you get started with creating resources via Amster.

Overview

This article provides a summary of the steps involved in updating property values using Amster and also provides worked examples to help guide you through the process.

The high level steps for updating a property value are:

  1. Determine the entity to which the property you want to update belongs. All the available entities are listed in the Entity Reference. See Tips for finding which entity to update for further information.
  2. Connect to AM using Amster per User Guide › Connecting to ForgeRock Access Management.
  3. Run the read command against the entity you are interested in to return the entity details in JSON format.
  4. Copy the outputted JSON response and make the following changes:
    • Amster 5.5 only: Remove the line breaks (for example, using sed or an online tool). 
    • Edit the value of the property you want to update.
    • Remove the end of the response starting with ,"_rev" (leaving the closing curly bracket). The string to remove includes the _id field and possibly others such as _type.
  5. Run the corresponding update command against the entity, passing the edited JSON response in the body. You must enclose the JSON response in single quotes.
Note

You can also use a JSON parsing library, which allows you to do a read, update the required property and then send the update. Using a JSON parsing library is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

The following sections show worked examples to help you get started:

Note

You can use similar principles to create resources via Amster; it is often best to initially create the resource via the console and then do a read so you know which fields are required for future creates. Alternatively, you can do a read on a similar resource (for example, an existing realm if you want to create another realm) and then use that output as the basis of your create.

Updating a default server setting

This worked example demonstrates updating the session cookie name. From the Reference guide, we can see it is a Security property: Reference › Configuration Reference > Cookie and the corresponding property name is: com.iplanet.am.cookie.name. The corresponding entity is DefaultSecurityProperties: Entity Reference › DefaultSecurityProperties.

You can update this property as follows:

  1. Connect to AM using Amster, for example:
    $ ./amster
    
    am> connect --interactive http://host1.example.com:8080/openam
    Sign in to top level realm
    User Name: amadmin
    Password: **********
  2. Run the read command against the DefaultSecurityProperties entity, for example (exclude the --prettyPrint option in Amster 5.x):
    am> read DefaultSecurityProperties --global --prettyPrint false
    Example response:
    ===> {"amconfig.header.encryption":{"am.encryption.pwd":"@AM_ENC_PWD@","com.iplanet.security.encryptor":"com.iplanet.services.util.JCEEncryption","com.iplanet.security.SecureRandomFactoryImpl":"com.iplanet.am.util.SecureRandomFactoryImpl"},"amconfig.header.validation":{"com.iplanet.services.comm.server.pllrequest.maxContentLength":"16384","com.iplanet.am.clientIPCheckEnabled":false},"amconfig.header.cookie":{"com.iplanet.am.cookie.name":"iPlanetDirectoryPro","com.iplanet.am.cookie.encode":false,"com.iplanet.am.cookie.secure":false},"amconfig.header.securitykey":{"com.sun.identity.saml.xmlsig.keystore":"%BASE_DIR%/%SERVER_URI%/keystore.jceks","com.sun.identity.saml.xmlsig.storetype":"JCEKS","com.sun.identity.saml.xmlsig.keypass":"%BASE_DIR%/%SERVER_URI%/.keypass","com.sun.identity.saml.xmlsig.certalias":"test","com.sun.identity.saml.xmlsig.storepass":"%BASE_DIR%/%SERVER_URI%/.storepass"},"amconfig.header.crlcache":{"com.sun.identity.crl.cache.directory.searchlocs":"","com.sun.identity.crl.cache.directory.password":null,"com.sun.identity.crl.cache.directory.ssl":false,"com.sun.identity.crl.cache.directory.user":"","com.sun.identity.crl.cache.directory.searchattr":"","com.sun.identity.crl.cache.directory.host":"","com.sun.identity.crl.cache.directory.port":""},"amconfig.header.ocsp.check":{"com.sun.identity.authentication.ocsp.responder.nickname":"","com.sun.identity.authentication.ocspCheck":false,"com.sun.identity.authentication.ocsp.responder.url":""},"amconfig.header.deserialisationwhitelist":{"openam.deserialisation.classes.whitelist":"com.iplanet.dpro.session.DNOrIPAddressListTokenRestriction,com.sun.identity.common.CaseInsensitiveHashMap,com.sun.identity.common.CaseInsensitiveHashSet,com.sun.identity.common.CaseInsensitiveKey,com.sun.identity.common.configuration.ServerConfigXML,com.sun.identity.common.configuration.ServerConfigXML$DirUserObject,com.sun.identity.common.configuration.ServerConfigXML$ServerGroup,com.sun.identity.common.configuration.ServerConfigXML$ServerObject,com.sun.identity.console.base.model.SMSubConfig,com.sun.identity.console.service.model.SMDescriptionData,com.sun.identity.console.service.model.SMDiscoEntryData,com.sun.identity.console.session.model.SMSessionData,com.sun.identity.console.user.model.UMUserPasswordResetOptionsData,com.sun.identity.shared.datastruct.OrderedSet,com.sun.xml.bind.util.ListImpl,com.sun.xml.bind.util.ProxyListImpl,java.lang.Boolean,java.lang.Integer,java.lang.Number,java.lang.StringBuffer,java.net.InetAddress,java.security.cert.Certificate,java.security.cert.Certificate$CertificateRep,java.util.ArrayList,java.util.Collections$EmptyMap,java.util.Collections$EmptySet,java.util.Collections$SingletonList,java.util.HashMap,java.util.HashSet,java.util.LinkedHashSet,java.util.Locale,org.forgerock.openam.authentication.service.protocol.RemoteCookie,org.forgerock.openam.authentication.service.protocol.RemoteHttpServletRequest,org.forgerock.openam.authentication.service.protocol.RemoteHttpServletResponse,org.forgerock.openam.authentication.service.protocol.RemoteServletRequest,org.forgerock.openam.authentication.service.protocol.RemoteServletResponse,org.forgerock.openam.authentication.service.protocol.RemoteSession,org.forgerock.openam.dpro.session.NoOpTokenRestriction,org.forgerock.openam.dpro.session.ProofOfPossessionTokenRestriction"},"_rev":"570060492","_id":"null/properties/security"}
    
  3. Copy the outputted JSON response and make the following changes:
    • Amster 5.5 only: Remove the line breaks (for example, using sed or an online tool). 
    • Edit the value of the property you want to update (com.iplanet.am.cookie.name).
    • Remove the end of the response starting with ,"_rev" (leaving the closing curly bracket). The string to remove includes the _id field and possibly others such as _type. You would remove the following from the end of the response in this example:
      ,"_rev":"570060492","_id":"null/properties/security"
  4. Run the corresponding update command against the DefaultSecurityProperties entity, passing the edited JSON response in the body. You must enclose the JSON response in single quotes. For example (with the updated property highlighted in bold for reference):
    am> update DefaultSecurityProperties --global --body '{"amconfig.header.encryption":{"am.encryption.pwd":"@AM_ENC_PWD@","com.iplanet.security.encryptor":"com.iplanet.services.util.JCEEncryption","com.iplanet.security.SecureRandomFactoryImpl":"com.iplanet.am.util.SecureRandomFactoryImpl"},"amconfig.header.validation":{"com.iplanet.services.comm.server.pllrequest.maxContentLength":"16384","com.iplanet.am.clientIPCheckEnabled":false},"amconfig.header.cookie":{"com.iplanet.am.cookie.name":"NewCookie","com.iplanet.am.cookie.encode":false,"com.iplanet.am.cookie.secure":false},"amconfig.header.securitykey":{"com.sun.identity.saml.xmlsig.keystore":"%BASE_DIR%/%SERVER_URI%/keystore.jceks","com.sun.identity.saml.xmlsig.storetype":"JCEKS","com.sun.identity.saml.xmlsig.storepass":"%BASE_DIR%/%SERVER_URI%/.storepass","com.sun.identity.saml.xmlsig.keypass":"%BASE_DIR%/%SERVER_URI%/.keypass","com.sun.identity.saml.xmlsig.certalias":"test"},"amconfig.header.crlcache":{"com.sun.identity.crl.cache.directory.host":"","com.sun.identity.crl.cache.directory.ssl":false,"com.sun.identity.crl.cache.directory.user":"","com.sun.identity.crl.cache.directory.searchlocs":"","com.sun.identity.crl.cache.directory.searchattr":""},"amconfig.header.ocsp.check":{"com.sun.identity.authentication.ocspCheck":false,"com.sun.identity.authentication.ocsp.responder.url":"","com.sun.identity.authentication.ocsp.responder.nickname":""},"amconfig.header.deserialisationwhitelist":{"openam.deserialisation.classes.whitelist":"com.iplanet.dpro.session.DNOrIPAddressListTokenRestriction,com.sun.identity.common.CaseInsensitiveHashMap,com.sun.identity.common.CaseInsensitiveHashSet,com.sun.identity.common.CaseInsensitiveKey,com.sun.identity.common.configuration.ServerConfigXML,com.sun.identity.common.configuration.ServerConfigXML$DirUserObject,com.sun.identity.common.configuration.ServerConfigXML$ServerGroup,com.sun.identity.common.configuration.ServerConfigXML$ServerObject,com.sun.identity.console.base.model.SMSubConfig,com.sun.identity.console.service.model.SMDescriptionData,com.sun.identity.console.service.model.SMDiscoEntryData,com.sun.identity.console.session.model.SMSessionData,com.sun.identity.console.user.model.UMUserPasswordResetOptionsData,com.sun.identity.shared.datastruct.OrderedSet,com.sun.xml.bind.util.ListImpl,com.sun.xml.bind.util.ProxyListImpl,java.lang.Boolean,java.lang.Integer,java.lang.Number,java.lang.StringBuffer,java.net.InetAddress,java.security.cert.Certificate,java.security.cert.Certificate$CertificateRep,java.util.ArrayList,java.util.Collections$EmptyMap,java.util.Collections$EmptySet,java.util.Collections$SingletonList,java.util.HashMap,java.util.HashSet,java.util.LinkedHashSet,java.util.Locale,org.forgerock.openam.authentication.service.protocol.RemoteCookie,org.forgerock.openam.authentication.service.protocol.RemoteHttpServletRequest,org.forgerock.openam.authentication.service.protocol.RemoteHttpServletResponse,org.forgerock.openam.authentication.service.protocol.RemoteServletRequest,org.forgerock.openam.authentication.service.protocol.RemoteServletResponse,org.forgerock.openam.authentication.service.protocol.RemoteSession,org.forgerock.openam.dpro.session.NoOpTokenRestriction"}}'
  5. Restart the web application container in which AM runs to update the configuration.

Updating realm level authentication settings

This worked example demonstrates enabling client-based sessions in a realm. From the Authentication and Single Sign-On Guide, we can see it is an authentication setting: Authentication and Single Sign-On Guide › Reference › General called Use Client-based Sessions (Use Stateless Sessions in AM 5.x). The corresponding entity is Authentication: Entity Reference › Authentication and the property name is: statelessSessionsEnabled (this was found by searching the Entity Reference for 'Use Client-based Sessions' ('Use Stateless Sessions in AM 5.x')).

You can update this property as follows:

  1. Connect to AM using Amster, for example:
    $ ./amster
    
    am> connect --interactive http://host1.example.com:8080/openam
    Sign in to top level realm
    User Name: amadmin
    Password: **********
  2. Run the read command against the Authentication entity, for example (exclude the --prettyPrint option in Amster 5.x):
    am> read Authentication --realm / --prettyPrint false
    Example response:
    ===> {"core":{"adminAuthModule":"ldapService","orgConfig":"ldapService"},"userprofile":{"dynamicProfileCreation":"false","defaultRole":[],"aliasAttributeName":["uid"]},"accountlockout":{"loginFailureLockoutMode":false,"loginFailureCount":5,"loginFailureDuration":300,"lockoutWarnUserCount":0,"lockoutDuration":0,"lockoutDurationMultiplier":1,"storeInvalidAttemptsInDataStore":true},"general":{"locale":"en_US","identityType":["agent","user"],"userStatusCallbackPlugins":[],"statelessSessionsEnabled":false,"twoFactorRequired":false,"defaultAuthLevel":0},"trees":{"authenticationSessionsStateManagement":"JWT","authenticationSessionsWhitelist":false,"authenticationSessionsMaxDuration":5},"security":{"moduleBasedAuthEnabled":true,"keyAlias":"test","zeroPageLoginEnabled":false,"zeroPageLoginReferrerWhiteList":[],"zeroPageLoginAllowedWithoutReferrer":true},"postauthprocess":{"loginSuccessUrl":["/openam/console"],"loginFailureUrl":[""],"loginPostProcessClass":[],"usernameGeneratorEnabled":true,"usernameGeneratorClass":"com.sun.identity.authentication.spi.DefaultUserIDGenerator","userAttributeSessionMapping":[]},"_rev":"-1312682552","_type":{"_id":"EMPTY","name":"Core","collection":false},"_id":""}
    
  3. Copy the outputted JSON response and make the following changes:
    • Amster 5.5 only: Remove the line breaks (for example, using sed or an online tool). 
    • Edit the value of the property you want to update (statelessSessionsEnabled).
    • Remove the end of the response starting with ,"_rev" (leaving the closing curly bracket). The string to remove includes the _id field and possibly others such as _type. You would remove the following from the end of the response in this example:
      ,"_rev":"-1312682552","_type":{"_id":"EMPTY","name":"Core","collection":false},"_id":""
  4. Run the corresponding update command against the Authentication entity, passing the edited JSON response in the body. You must enclose the JSON response in single quotes. For example (with the updated property highlighted in bold):
    am> update Authentication --realm / --body '{"core":{"adminAuthModule":"ldapService","orgConfig":"ldapService"},"userprofile":{"dynamicProfileCreation":"false","defaultRole":[],"aliasAttributeName":["uid"]},"accountlockout":{"loginFailureLockoutMode":true,"loginFailureCount":5,"loginFailureDuration":300,"lockoutWarnUserCount":0,"lockoutDuration":0,"lockoutDurationMultiplier":1,"storeInvalidAttemptsInDataStore":true},"general":{"locale":"en_US","identityType":["agent","user"],"userStatusCallbackPlugins":[],"statelessSessionsEnabled":true,"twoFactorRequired":false,"defaultAuthLevel":0},"security":{"moduleBasedAuthEnabled":true,"keyAlias":"test","zeroPageLoginEnabled":false,"zeroPageLoginReferrerWhiteList":[],"zeroPageLoginAllowedWithoutReferrer":true},"postauthprocess":{"loginSuccessUrl":["/openam/console"],"loginFailureUrl":[],"loginPostProcessClass":[],"usernameGeneratorEnabled":true,"usernameGeneratorClass":"com.sun.identity.authentication.spi.DefaultUserIDGenerator","userAttributeSessionMapping":[]}}'

Tips for finding which entity to update

The Entity Reference has a full list of entities you can update and includes the JSON schema, which details the properties. In order to update a property, you need to know the property name and the corresponding entity. The following tips should help you find this information:

See Also

How do I enable debug mode for troubleshooting Amster (All versions)?

FAQ: Installing and using Amster in AM

Using Amster in AM

User Guide

Entity Reference

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12092 (Prettyprint for Amster should be a switch)

OPENAM-11813 (Amster documentation needs improving)

OPENAM-10641 (Prettyprint for responses would be great for Amster output)


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

The purpose of this article is to provide information on importing Service configurations in AM using Amster when you have custom authentication modules. You must install and register the custom module before you can import a service configuration.

Overview

This article assumes you have working AM and Amster installations, and you have already created a custom authentication module. See Authentication and Single Sign-On Guide › Creating a Custom Authentication Module for further information on creating custom modules.

Prior to importing service configurations that contain custom authentication modules, you must install and register the custom module. The way in which this is done varies between AM versions as detailed in this article:

This change is detailed in the AM 5.5 Release Notes: Release Notes › Important Changes to Existing Functionality.

Import Error

Failing to install and register the custom module first will cause the import to fail with the following error (where custom-authentication-module is the example custom module name):

Failed to import /path/to/config/global/custom-authentication-module.json : Unrecognised entity type: custom-authentication-module
Failed to import /path/to/config/realms/realmName/custom-authentication-module/custom-authentication-module.json : Unrecognised entity type: custom-authentication-module

AM 5.5 and later

You can import service configurations that contain custom authentication modules in AM 5.5 and later as follows:

  1. Copy the custom authentication module jar file to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory, for example:
    $ cp custom-authentication-module-5.5.0.jar /path/to/tomcat/webapps/openam/WEB-INF/lib
    
  2. Restart the web application container in which AM runs to complete the registration of the custom module.
  3. You can now import your service configurations using the Amster import-config command, for example:
    am> import-config --path /path/to/config

AM 5 and 5.1.x

You can import service configurations that contain custom authentication modules in AM 5 and 5.1.x as follows:

  1. Copy the custom authentication module jar file to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory, for example:
    $ cp custom-authentication-module-14.0.0.jar /path/to/tomcat/webapps/openam/WEB-INF/lib
    
  2. Install the custom authentication module using ssoadm:
    $ ./ssoadm create-svc -u [adminID] -f [passwordfile] -X [xmlfile]
    replacing [adminID], [passwordfile] and [xmlfile] with appropriate values, where [xmlfile] is the service configuration file for the auth module (e.g., amAuthSampleAuth.xml)  
  3. Register the custom authentication module using ssoadm:
    $ ./ssoadm register-auth-module -u [adminID] -f [passwordfile] -a [javaClass]
    replacing [adminID], [passwordfile] and [javaClass] with appropriate values, where [javaClass] is the Java class name of the custom authentication module.
  4. Restart the web application container in which AM runs to complete the registration of the custom module.
  5. You can now import your service configurations using the Amster import-config command, for example:
    am> import-config --path /path/to/config

See Also

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

How do I customize authentication modules using source code in AM/OpenAM (All versions)?

How do I access and build the sample code provided for AM/OpenAM (All versions)?

Authentication and Single Sign-On Guide › Creating a Custom Authentication Module

Amster User Guide > Importing Configuration Data

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11947 (Not able to import AM configs with custom authentication module)


How do I enable debug mode for troubleshooting Amster (All versions)?

The purpose of this article is to provide information on enabling debug mode to troubleshoot Amster. It also includes additional debugging options that you can use to increase debug levels and debug SSL issues.

Enabling debug mode

You can enable debug mode when you start Amster by using the -d option, for example:

$ cd /path/to/amster
$ ./amster -d 

This option outputs debug information to the command line while Amster starts and also when you run any Amster commands within the current session (that is, up until you exit Amster). This output can be quite verbose, so this option should only be used if you are experiencing issues.

Increasing debug output

There are other options you can add when starting Amster to capture additional troubleshooting data. The following options increase the logging level to TRACE to generate more detailed error messages than debug level, adds additional log details such as timestamps and thread names and also redirects the output to a log file (ensure you replace /path/to/logfile.log using the full path to the log file location) :

$ cd /path/to/amster
$ ./amster -d -Dorg.slf4j.simpleLogger.log.org.apache.http=TRACE -Dorg.slf4j.simpleLogger.log.org.forgerock.http=TRACE -Dorg.slf4j.simpleLogger.showThreadName=true -Dorg.slf4j.simpleLogger.showDateTime=true -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE -Dorg.slf4j.simpleLogger.dateTimeFormat="yyyy-MM-dd'T'HH:mm:ss.SSS" -Dorg.slf4j.simpleLogger.logFile=/path/to/logfile.log

The output in the console is even more verbose than the normal debug output, so should only be used when experiencing issues.

Debug level

The debug level (org.slf4j.simpleLogger.defaultLogLevel) is set to DEBUG by default in the Amster script. If you always want the debug level to be TRACE, you can change this option in the script:

  1. Change DEBUG to TRACE for the org.slf4j.simpleLogger.defaultLogLevel option in the Amster script, for example:
    • amster script:
      debug="-agentlib:jdwp=transport=dt_socket,server=y,suspend=$debug_suspend,address=$debug_port -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE"
      
    • amster.bat script:
      debug="-agentlib:jdwp=transport=dt_socket,server=y,suspend=%debug_suspend%,address=%debug_port% -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE"
      

Now when you start Amster with the -d option, TRACE will be used as the default debug level. 

Enabling SSL debug logging

You can also troubleshoot SSL issues by adding the following line to the Amster script:

SSL="-Djavax.net.debug=all -verbose:class -Djavax.net.ssl.trustStore=/path/to/truststore"

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 default JVM truststore and AM is deployed on Apache Tomcat™ web container.

This line should be added immediately before the final line in the script, for example:

  • amster script:
    SSL="-Djavax.net.debug=all -verbose:class -Djavax.net.ssl.trustStore=/path/to/truststore"
    $JAVA_HOME/bin/java $debug -Djava.awt.headless=true -jar ${DIR}/amster-*.jar $*
    
  • amster.bat script:
    SSL="-Djavax.net.debug=all -verbose:class -Djavax.net.ssl.trustStore=/path/to/truststore"
    "!JAVA_HOME!\bin\java.exe" %debug% -Djava.awt.headless=true -jar %amster_jar% %*
    

Now when you start Amster with the -d option, the debug output will also include SSL debug information. 

Note

You can also use the -Djavax.net.debug=all option when you start Amster if you are experiencing connection issues. See FAQ: Installing and using Amster in AM (Q. How can I troubleshoot my SSL connection if it fails?) for further information.

See Also

FAQ: Installing and using Amster in AM

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

How do I record troubleshooting information in AM/OpenAM (All versions)?

Troubleshooting AM/OpenAM and Policy Agents

Using Amster in AM

Amster User Guide

Class SimpleLogger

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I automate the creation of a SAML2 entity provider in AM/OpenAM (All versions)?

The purpose of this article is to provide information on creating an IdP or SP (hosted or remote) using either the REST API in AM/OpenAM or Amster in AM.

Overview

When creating SAML2 entity providers using either the REST API or Amster, you should be aware of the following key points:

  • The entity ID must not contain slashes else creation will fail with a 400 response as detailed in 400 response when adding or updating resources via REST or Amster when the resource name contains forward slashes in AM/OpenAM (All versions).
  • You must pass the metadata and extended metadata XML documents in the body/payload of the request.
  • Characters in the XML documents must be escaped correctly. In particular, you must escape double quotes (") as follows:
    • REST - escaped with a single backslash, for example \"
    • Amster - escaped with a double backslash, for example \\"
  • Hosted and remote entity providers are identified in the entityConfig field of the body/payload by the value of the hosted element (true or false), for example:
    • REST:
      • Hosted identity providers:
        "entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><EntityConfig entityID=\"hostedEntityProviderID\" hosted=\"true\" ...
        
      • Remote entity providers:
        "entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><EntityConfig entityID=\"remoteEntityProviderID\" hosted=\"false\" ...
        
    • Amster:
      • Hosted identity providers:
        "entityConfig": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" standalone=\\"yes\\"?><EntityConfig entityID=\\"hostedEntityProviderID\\" hosted=\\"true\\" ...
        
      • Remote entity providers:
        "entityConfig": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" standalone=\\"yes\\"?><EntityConfig entityID=\\"remoteEntityProviderID\\" hosted=\\"false\\" ...
        

This article details the automation options available for creating entity providers:

Creating an entity provider using the REST API

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

You can create an entity provider using the REST API as follows:

  1. Ensure you have the metadata and extended metadata XML documents; either generated yourself if you are the hosted entity provider or received from the remote entity provider.
  2. Ensure any characters in the XML documents are escaped correctly, for example, escaping " with a single backslash (\").
  3. Authenticate as an admin user. 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.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
    
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  4. Create the SAML2 entity provider using the following curl command, where entityID in the URL is replaced with the name of your entity provider:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" -H "If-None-Match: *" -d '{"metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ","entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... "}' 
    'http://host1.example.com:8080/openam/json/realms/root/realm-config/federation/entityproviders/saml2/entityID'
    
    Example response (this has been abbreviated due to the size of response):
    {
      "_id": "entityID",
      "_rev": "1045663808",
      "metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ",
      "entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ",
      "_type": {
        "_id": "saml2",
        "name": "Entity Descriptor ",
        "collection": true
      }
    }
    
Note

You can put the data payload in a file and then pass the file instead of the raw data using the following format:

-d "@/path/to/filename"

See curl -d, --data <data> for further information.

Creating an entity provider using Amster

You can create an entity provider using Amster as follows:

  1. Ensure you have the metadata and extended metadata XML documents; either generated yourself if you are the hosted entity provider or received from the remote entity provider.
  2. Ensure any characters in the XML documents are escaped correctly, for example, escaping " with a double backslash (\\").
  3. Create the SAML2 entity provider:
    $ create Saml2Entity --realm / --id entityProviderID --body '{"metadata": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" ... ","entityConfig": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" ... "}'
    
    Example response (this has been abbreviated due to the size of response):
    ===> {
        "metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ",
        "entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ",
        "_rev": "772106341",
        "_type": {
            "_id": "saml2",
            "name": "Entity Descriptor ",
            "collection": true
        },
        "_id": "entityProviderID"
    }
    

See Also

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Using the REST API in AM/OpenAM

Using Amster in AM

Entity Reference › Saml2Entity

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12334 (Unable to create Saml2Entity using Amster)


How do I automate the creation of an authentication tree in AM 5.5.x and 6.x?

The purpose of this article is to provide information on creating an authentication tree using either the REST API or Amster in AM.

Overview

When creating authentication trees using either the REST API or Amster, you should be aware of the following key points:

  • You must re-create each node in order to create a new authentication tree.
  • Each node must have a valid UUID as its identifier; you can generate UUIDs online, for example: Online UUID Generator. If you don't use a valid UUID, authentication will fail and you will see an error similar to the following in the Authentication debug log:
    ERROR: Could not get SMS service: authenticationTreesService
    java.lang.IllegalArgumentException: Invalid UUID string: 12345
  • The entryNodeId field specified when creating the authentication tree is the UUID of the first node in the tree.
  • The outcome field specified when creating the authentication tree is the UUID of the next node; in this way you can move between the nodes.
  • The Success/Failure nodes have static UUIDs that remain constant across all authentication trees and AM versions. These UUIDs are as follows:
    • Success node:
      70e691a5-1e33-4ac3-a356-e7b6d60d92e0
    • Failure node:
      e301438c-0bd0-429c-ab0c-66126501069a
Note

There are known issues that prevent custom nodes being created via Amster: OPENAM-13157 (Custom Authentication Nodes not being exported correctly) and OPENAM-14008 (creating custom auth node fails with amster). As a result, you should create custom nodes via REST instead. 

The following sections provide examples for creating a simple tree that consists of three nodes (UsernameCollectorNode, PasswordCollectorNode and DataStoreDecisionNode):

The resulting tree created from these examples looks like this:

 

Creating a tree using the REST API

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

The following example demonstrates creating the authentication tree using the REST API: 

  1. Generate UUIDs for each of the nodes you want to create. For example:
    • UsernameCollectorNode: 8f9d2280-caa7-433f-93a9-1f64f4cae60a
    • PasswordCollectorNode: 54f14341-d1b7-436f-b159-d1f9b6c626eb
    • DataStoreDecisionNode: 3fc7ce22-fc79-4131-85f2-f1844709d042
  2. Authenticate as an admin user. 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.1"  http://host1.example.com:8080/openam/json/realms/root/authenticate
    
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  3. Create the UsernameCollector node using the following curl command, where the UUID is the one you generated:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" -H "If-None-Match: *" -d '{"_id":"8f9d2280-caa7-433f-93a9-1f64f4cae60a","_type":{"_id":"UsernameCollectorNode","name":"Username Collector"}}' 'http://host1.example.com:8080/openam/json/realms/root/realms/employees/realm-config/authentication/authenticationtrees/nodes/UsernameCollectorNode/8f9d2280-caa7-433f-93a9-1f64f4cae60a'
    
    Example response:
    {"_id":"8f9d2280-caa7-433f-93a9-1f64f4cae60a","_type":{"_id":"UsernameCollectorNode","name":"Username Collector","collection":true}}
    
  4. Create the PasswordCollector node using the following curl command, where the UUID is the one you generated:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" -H "If-None-Match: *" -d '{"_id":"54f14341-d1b7-436f-b159-d1f9b6c626eb","_type":{"_id":"PasswordCollectorNode","name":"Password Collector"}}' 'http://host1.example.com:8080/openam/json/realms/root/realms/employees/realm-config/authentication/authenticationtrees/nodes/PasswordCollectorNode/54f14341-d1b7-436f-b159-d1f9b6c626eb'
    
    Example response:
    {"_id":"54f14341-d1b7-436f-b159-d1f9b6c626eb","_type":{"_id":"PasswordCollectorNode","name":"Password Collector","collection":true}}
    
  5. Create the DataStoreDecision node using the following curl command, where the UUID is the one you generated:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" -H "If-None-Match: *" -d '{"_id":"3fc7ce22-fc79-4131-85f2-f1844709d042","_type":{"_id":"DataStoreDecisionNode","name":"Data Store Decision"}}' 'http://host1.example.com:8080/openam/json/realms/root/realms/employees/realm-config/authentication/authenticationtrees/nodes/DataStoreDecisionNode/3fc7ce22-fc79-4131-85f2-f1844709d042'
    
    Example response:
    {"_id":"3fc7ce22-fc79-4131-85f2-f1844709d042","_type":{"_id":"DataStoreDecisionNode","name":"Data Store Decision","collection":true}}
    
  6. Create the authentication tree with these three nodes, where the UUIDs are the ones you used to create the nodes. Ensure you set entryNodeId to the UUID of the first node and set the outcome of each node to the UUID of the next node. For example:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" -H "If-None-Match: *" -d '{"entryNodeId":"8f9d2280-caa7-433f-93a9-1f64f4cae60a","nodes":{"8f9d2280-caa7-433f-93a9-1f64f4cae60a":{"displayName":"Username Collector","nodeType":"UsernameCollectorNode","connections":{"outcome":"54f14341-d1b7-436f-b159-d1f9b6c626eb"}},"54f14341-d1b7-436f-b159-d1f9b6c626eb":{"displayName":"Password Collector","nodeType":"PasswordCollectorNode","connections":{"outcome":"3fc7ce22-fc79-4131-85f2-f1844709d042"}},"3fc7ce22-fc79-4131-85f2-f1844709d042":{"displayName":"Data Store Decision","nodeType":"DataStoreDecisionNode","connections":{"false":"e301438c-0bd0-429c-ab0c-66126501069a","true":"70e691a5-1e33-4ac3-a356-e7b6d60d92e0"}}}}' 'http://host1.example.com:8080/openam/json/realms/root/realms/employees/realm-config/authentication/authenticationtrees/trees/MyNewAuthTree'
    
    Example response:
    {"entryNodeId":"8f9d2280-caa7-433f-93a9-1f64f4cae60a","nodes":{"8f9d2280-caa7-433f-93a9-1f64f4cae60a":{"nodeType":"UsernameCollectorNode","displayName":"Username Collector","connections":{"outcome":"54f14341-d1b7-436f-b159-d1f9b6c626eb"}},"54f14341-d1b7-436f-b159-d1f9b6c626eb":{"nodeType":"PasswordCollectorNode","displayName":"Password Collector","connections":{"outcome":"3fc7ce22-fc79-4131-85f2-f1844709d042"}},"3fc7ce22-fc79-4131-85f2-f1844709d042":{"nodeType":"DataStoreDecisionNode","displayName":"Data Store Decision","connections":{"false":"e301438c-0bd0-429c-ab0c-66126501069a","true":"70e691a5-1e33-4ac3-a356-e7b6d60d92e0"}}},"_id":"MyNewAuthTree"}
    

Creating a tree using Amster

The following example demonstrates creating the authentication tree using Amster:

  1. Generate UUIDs for each of the nodes you want to create. For example:
    • UsernameCollectorNode: 8f9d2280-caa7-433f-93a9-1f64f4cae60a
    • PasswordCollectorNode: 54f14341-d1b7-436f-b159-d1f9b6c626eb
    • DataStoreDecisionNode: 3fc7ce22-fc79-4131-85f2-f1844709d042
  2. Create the UsernameCollector node:
    $ create UsernameCollector --realm employees --id 8f9d2280-caa7-433f-93a9-1f64f4cae60a --body '{"_id":"8f9d2280-caa7-433f-93a9-1f64f4cae60a","_type":{"_id":"UsernameCollectorNode","name":"Username Collector"}}'
    
    ===> {
     "_rev": "1086377982",
     "_type": {
     "_id": "UsernameCollectorNode",
     "name": "Username Collector",
     "collection": true
     },
     "_id": "8f9d2280-caa7-433f-93a9-1f64f4cae60a"
    }
    
  3. Create the PasswordCollector node:
    $ create PasswordCollector --realm employees --id 54f14341-d1b7-436f-b159-d1f9b6c626eb --body '{"_id":"54f14341-d1b7-436f-b159-d1f9b6c626eb","_type":{"_id":"PasswordCollectorNode","name":"Password Collector"}}'
    
    ===> {
     "_rev": "-747204328",
     "_type": {
     "_id": "PasswordCollectorNode",
     "name": "Password Collector",
     "collection": true
     },
     "_id": "54f14341-d1b7-436f-b159-d1f9b6c626eb"
    }
    
  4. Create the DataStoreDecision node:
    $ create DataStoreDecision --realm employees --id 3fc7ce22-fc79-4131-85f2-f1844709d042 --body '{"_id":"3fc7ce22-fc79-4131-85f2-f1844709d042","_type":{"_id":"DataStoreDecisionNode","name":"Data Store Decision"}}'
    
    ===> {
     "_rev": "756753534",
     "_type": {
     "_id": "DataStoreDecisionNode",
     "name": "Data Store Decision",
     "collection": true
     },
     "_id": "3fc7ce22-fc79-4131-85f2-f1844709d042"
    }
    
  5. Create the authentication tree with these three nodes, where the UUIDs are the ones you used to create the nodes. Ensure you set entryNodeId to the UUID of the first node and set the outcome of each node to the UUID of the next node. For example:
    $ create AuthTree --realm employees --id MyNewAuthTree --body '{"entryNodeId":"8f9d2280-caa7-433f-93a9-1f64f4cae60a","nodes":{"8f9d2280-caa7-433f-93a9-1f64f4cae60a":{"displayName":"Username Collector","nodeType":"UsernameCollectorNode","connections":{"outcome":"54f14341-d1b7-436f-b159-d1f9b6c626eb"}},"54f14341-d1b7-436f-b159-d1f9b6c626eb":{"displayName":"Password Collector","nodeType":"PasswordCollectorNode","connections":{"outcome":"3fc7ce22-fc79-4131-85f2-f1844709d042"}},"3fc7ce22-fc79-4131-85f2-f1844709d042":{"displayName":"Data Store Decision","nodeType":"DataStoreDecisionNode","connections":{"false":"e301438c-0bd0-429c-ab0c-66126501069a","true":"70e691a5-1e33-4ac3-a356-e7b6d60d92e0"}}}}'
    
    ===> 
    { 
     "entryNodeId":"8f9d2280-caa7-433f-93a9-1f64f4cae60a",
     "nodes":{ 
      "54f14341-d1b7-436f-b159-d1f9b6c626eb":{ 
       "nodeType":"PasswordCollectorNode",
       "displayName":"Password Collector",
       "connections":{ 
        "outcome":"3fc7ce22-fc79-4131-85f2-f1844709d042"
       }
      },
      "3fc7ce22-fc79-4131-85f2-f1844709d042":{ 
       "nodeType":"DataStoreDecisionNode",
       "displayName":"Data Store Decision",
       "connections":{ 
        "false":"e301438c-0bd0-429c-ab0c-66126501069a",
        "true":"70e691a5-1e33-4ac3-a356-e7b6d60d92e0"
       }
      },
      "8f9d2280-caa7-433f-93a9-1f64f4cae60a":{ 
       "nodeType":"UsernameCollectorNode",
       "displayName":"Username Collector",
       "connections":{ 
        "outcome":"54f14341-d1b7-436f-b159-d1f9b6c626eb"
       }
      }
     },
     "_rev":"1365759445",
     "_id":"MyNewAuthTree"
    }

See Also

Best practice for migrating Authentication Chains to Trees in AM 6.x

How do I modify the prompt text shown when authenticating to a tree in AM 5.5.x and 6.x?

Authentication and Single Sign-On Guide › Configuring Authentication Trees

Entity Reference › UsernameCollector

Entity Reference › PasswordCollector

Entity Reference › DataStoreDecision

Entity Reference › AuthTree

Related Training

N/A

Related Issue Tracker IDs

N/A


Known Issues


Issues with upgrades, Amster exports and registering clients (OAuth2, OIDC and RADIUS) or agents with reference to sunserviceID in AM (All versions)

The purpose of this article is to provide assistance if you experience issues with upgrades failing, Amster export failures and problems registering large numbers of clients or agents in AM. You will see "The search results cannot be sorted because the given search request is not indexed" messages when this happens with reference to the sunserviceID attribute. This issue only occurs if you are using an external DS for your configuration store.

Symptoms

You will encounter errors relating to the sunserviceID attribute in a number of situations, including (but not limited to):

  • Upgrading AM.
  • Exporting Amster configurations.
  • Registering large numbers of clients (OAuth2, OIDC or RADIUS clients).
  • Creating large numbers of agents.

Errors similar to the following are shown in AM CoreSystem debug log when this happens:

  • Upgrade example:
    ERROR: An error occurred while trying to look for WebAgents to upgrade
    SMSException Exception Code:5
    Message:Unexpected LDAP exception occurred.
    --------------------------------------------------
    The lower level exception message
    Unavailable Critical Extension: The search results cannot be sorted because the given search request is not indexed
    
  • Registering large numbers of clients and exporting Amster example:
    WARNING: ::SmsCollectionProvider:: SMSException on query
    SMSException Exception Code:5
    Message:Unexpected LDAP exception occurred.
    --------------------------------------------------
    The lower level exception message
    Unavailable Critical Extension: The search results cannot be sorted because the given search request is not indexed
    The lower level exception:
    Unavailable Critical Extension: The search results cannot be sorted because the given search request is not indexed
    

You will find a corresponding error in the DS logs, which provides more insight. For example, one referencing sunserviceID=WebAgent which may be seen on upgrade:

{"eventName":"DJ-LDAP","client":{"ip":"	192.0.2.0","port":8080},"server":{"ip":"192.0.2.10","port":1636},"request":{"protocol":"LDAPS","operation":"SEARCH","connId":67,"msgId":22107,"dn":"ou=default,ou= OrganizationConfig,ou=1.0,ou=AgentService,ou=services,dc=openam,dc=forgerock,dc=com","scope":"one","filter":"(&(&(objectclass=top)(ou=*))(&(objectclass=top)(sunserviceID= WebAgent)))","attrs":["o"]},"transactionId":"d1e21e68-8f64-fa1e-4fbd-16e77cc475ef-62545461","response":{"status":"FAILED","statusCode":"12","elapsedTime":13,"elapsedTimeUnits":"MILLISECONDS","detail":"The search results cannot be sorted because the given search request is not indexed","additionalItems":"unindexed","nentries":0},"timestamp":"2019-10-24T04:15:11.424Z","_id":"d1e21e68-8f64-fa1e-4fbd-16e77cc475ef-62545464"}

When an Amster export fails (with the --failOnError flag set), you will get the following response, which corresponds to the above log snippets:

500 Internal Server Error: Unable to query SMS config: Unexpected LDAP exception occurred.

Recent Changes

Created a large number of clients (OAuth2, OIDC or RADIUS).

Created a large number of agents.

Created a large number of SAML2 entities.

Causes

sunserviceID is the attribute type that stores AM configuration data. By default, it is not indexed.

Each time AM performs a search against things like OAuth2 clients, agents or SAML2 entities, DS tries to do a server-side sort and fails because sunserviceID is not indexed. AM performs searches in various situations, for example, when registering an OAuth2 client, AM will perform a search against existing clients, or when upgrading, AM will perform a search against existing clients, agents and SAML2 entities. If you have a large number of clients, agents or SAML2 entities (for example, running into the thousands), this unindexed attribute will cause the errors seen in the Symptoms section.

Solution

You can workaround this issue by indexing sunserviceID and increasing the search limit as follows:

  1. Create an index for sunserviceID using dsconfig, for example:
    $ ./dsconfig create-backend-index --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --backend-name userRoot --index-name sunserviceID --set index-type:equality --trustAll --no-prompt
  2. Increase the search limit for this index using dsconfig. It is suggested you start with a limit of 10000, but you may need to increase this further. Do not set the index-entry-limit to the total size of the backend. For example:
    $ ./dsconfig set-backend-index-prop --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --backend-name userRoot --index-name sunserviceID --set index-entry-limit:10000 --no-prompt --trustAll
  3. Rebuild the index using the rebuild-index command. For example:
    $ ./rebuild-index --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --baseDN dc=openam,dc=forgerock,dc=org --index sunserviceID --start 0 --trustAll

Important Considerations

Indexing sunserviceID and increasing the index-entry-limit is effectively a workaround for having a large number of clients, agents or entities. Ideally, you should avoid having large numbers of clients/agents. For OAuth2 clients, it is recommended that you have a one-to-many mapping of clients, where one client is associated with many devices/users rather than one client per device/user, which is also best practice advice for keeping clients manageable and easier to administrate.

If you have a large number of clients/agents/entities, it is likely you will hit other scaling and performance issues. You should consider the following, and ensure you performance test and tune your intended setup (AM and DS) before going into production:

  • Index entry limits are set to 4000 by default. Increasing this limit beyond the default (as suggested here) is likely to impact performance as DS will need to maintain entries for very large indexes. There is a blog that explains this setting in more detail: Explaining index-entry-limit in ForgeRock Directory Services.
  • The cursor-entry-limit advanced property (default 100000) specifies the maximum number of entry IDs that can be retrieved by cursoring through an index during a search. Depending on the number of entries, you may need to increase this limit as well. Do not set the cursor-entry-limit to the total size of the backend. See Configuration Reference › cursor-entry-limit for further information.  
  • DS must be tuned for search performance as there are default limits on search operations. You may need to increase these limits (ds-rlim-size-limit and ds-rlim-lookthrough-limit) to allow more search results to be returned. See Administration Guide › Limiting Search Resources for further information on these settings. Additionally, increasing these settings will require more heap, so you will need to ensure your DS heap is tuned appropriately.
  • Clients and agents are stored in in-memory caches, which can lead to heap sizing issues as the number of clients/agents increase. You should ensure your AM heap is tuned appropriately.
  • The AM console cannot cope with large numbers of clients/agents/entities and will hang, respond very slowly or the server will crash with OutOfMemory errors as numbers increase. You should avoid administering clients/agents/entities through the console if this happens.
  • RADIUS clients only: you can change the maximum number of RADIUS clients that can be cached concurrently on an AM server (default 5000) by configuring the org.forgerock.openam.radius.server.context.cache.size advanced server property. See RADIUS Server Guide › RADIUS Server Limitations for further information.
Note

Performance tuning recommendations are outside the scope of ForgeRock support. if you want more tailored advice, consider engaging Deployment Support Services.

See Also

Unindexed searches causing slow searches and poor performance on DS/OpenDJ (All versions) server

Best practice for JVM Tuning

Performance tuning and monitoring ForgeRock products

Administration Guide › Indexing Attribute Values

Related Training

N/A

Related Issue Tracker IDs

OPENAM-15572 (Document sunserviceID index needs to be created under certain case)

OPENAM-15406 (Improve performance for registering and maintaining OAuth2 Clients)

OPENAM-14825 (OAuth2 Dynamic Registration with Software Statement triggers objectClass=* search)

OPENAM-14271 (sunserviceID index is not created and it needs to be indexed )

OPENAM-3996 (AgentsRepo search is suboptimal)


502 Bad Gateway error when an Amster (All versions) command fails

The purpose of this article is to provide assistance if an Amster command fails and you see an "Unhandled server error: [Status: 502 Bad Gateway]".

Symptoms

Amster connects successfully, but subsequent commands (for example, export-config) fail.

One of the following 502 Bad Gateway responses is shown when an Amster command fails:

  • ERROR org.forgerock.openam.sdk.http.ServerErrorException:
    [main] ERROR org.forgerock.openam.sdk.http.DefaultErrorHandler - Unhandled server error: [Status: 502 Bad Gateway]
    ERROR org.forgerock.openam.sdk.http.ServerErrorException:
    502 Bad Gateway
       at org.forgerock.openam.sdk.http.DefaultErrorHandler.onServerError (DefaultErrorHandler.java:62)
       at org.forgerock.openam.sdk.http.HttpSessionImpl.handleUnsuccessfulResponse (HttpSessionImpl.java:273)
       at org.forgerock.openam.sdk.http.HttpSessionImpl.send (HttpSessionImpl.java:169)
       at org.forgerock.openam.sdk.http.RequestBuilder.post (RequestBuilder.java:205)
       at org.forgerock.openam.sdk.crest.CrestResourceProviderAsync.actionCollection (CrestResourceProviderAsync.java:334)
       at org.forgerock.openam.sdk.crest.HttpCrestResourceProvider.actionCollection (HttpCrestResourceProvider.java:296)
       at org.forgerock.openam.sdk.operations.CrestOperations.action (CrestOperations.java:427)
       at org.forgerock.openam.sdk.operations.CrestOperations.action (CrestOperations.java:409)
       at org.forgerock.openam.amster.loadster.EntityTypeProvider.getCustomSubEntityTypes (EntityTypeProvider.groovy:168)
       at org.forgerock.openam.amster.loadster.EntityTypeProvider.getCustomEntityTypes (EntityTypeProvider.groovy:157)
       at org.forgerock.openam.amster.loadster.EntityTypeProvider.getEntityTypes (EntityTypeProvider.groovy:102)
       at org.forgerock.openam.amster.loadster.EntityTypeProvider.getGlobalEntityTypes (EntityTypeProvider.groovy:84)
       at org.forgerock.openam.amster.loadster.importer.Importer.<init> (Importer.groovy:72)
    
  • ERROR org.forgerock.sdk.com.google.inject.ProvisionException:
    [main] ERROR org.forgerock.amster.org.forgerock.openam.sdk.http.DefaultErrorHandler - Unhandled server error: [Status: 502 Bad Gateway]
    ERROR org.forgerock.sdk.com.google.inject.ProvisionException: 
    Unable to provision, see the following errors:
    1) Error in custom provider, org.forgerock.amster.org.forgerock.openam.sdk.http.ServerErrorException: 502 Bad Gateway
       at org.forgerock.amster.org.forgerock.openam.sdk.controller.SDKGuiceModule.getHttpSession(Unknown Source)
       at org.forgerock.amster.org.forgerock.openam.sdk.controller.SDKGuiceModule.getHttpSession(Unknown Source) while locating org.forgerock.amster.org.forgerock.openam.sdk.http.HttpSession for parameter 0 
      at org.forgerock.amster.org.forgerock.openam.sdk.controller.SDKGuiceModule.getCrestResourceProviderForPolicy(Unknown Source)
       at org.forgerock.amster.org.forgerock.openam.sdk.controller.SDKGuiceModule.getCrestResourceProviderForPolicy(Unknown Source) while locating org.forgerock.amster.org.forgerock.openam.sdk.crest.CrestResourceProvider<org.forgerock.amster.org.forgerock.openam.sdk.domain.model.Policy> annotated with @org.forgerock.sdk.com.google.inject.name.Named(value=policyProvider) for parameter 0 
       at org.forgerock.amster.org.forgerock.openam.sdk.policy.operations.PolicyOperationsProvider.<init>(Unknown Source) while locating org.forgerock.amster.org.forgerock.openam.sdk.policy.operations.PolicyOperationsProvider
    1 error
       at org.forgerock.sdk.com.google.inject.internal.InjectorImpl$2.get (InjectorImpl.java:1025)
       at org.forgerock.sdk.com.google.inject.internal.InjectorImpl.getInstance (InjectorImpl.java:1051)
       at org.forgerock.amster.org.forgerock.openam.sdk.controller.AbstractRealm.<init> (AbstractRealm.java:44)
       at org.forgerock.amster.org.forgerock.openam.sdk.controller.Realm.<init> (Realm.java:759)
       at org.forgerock.amster.org.forgerock.openam.sdk.controller.SDK.getTopLevelRealm (SDK.java:67)
       at org.forgerock.openam.amster.loadster.EntityTypeProvider.<init> (EntityTypeProvider.groovy:50)
       at org.forgerock.openam.amster.loadster.exporter.EntityExporter.<init> (EntityExporter.groovy:47)
       at org.forgerock.openam.amster.commands.ExportCommand.execute (ExportCommand.groovy:61)
       at org.forgerock.openam.amster.Main$_addCommandLineWrapping_closure2.doCall (Main.groovy:90)
       at java_lang_Runnable$run.call (Unknown Source)
       at org.forgerock.openam.amster.Main.main (Main.groovy:60)
    
  • ERROR org.forgerock.sdk.com.google.inject.ProvisionException: Guice provision errors: 
    [main] ERROR org.forgerock.openam.sdk.http.DefaultErrorHandler - Unhandled server error: [Status: 502 Bad Gateway] 
    ERROR org.forgerock.sdk.com.google.inject.ProvisionException: 
    Guice provision errors: 
    
    1) Error in custom provider, org.forgerock.openam.sdk.http.ServerErrorException: 502 Bad Gateway 
       at org.forgerock.openam.sdk.controller.SDKGuiceModule.getHttpSession(Unknown Source) 
       at org.forgerock.openam.sdk.controller.SDKGuiceModule.getHttpSession(Unknown Source) 
       while locating org.forgerock.openam.sdk.http.HttpSession 
       at org.forgerock.openam.sdk.controller.SDKGuiceModule.getCrestResourceProviderForPolicy(Unknown Source) 
       while locating org.forgerock.openam.sdk.crest.CrestResourceProvider<org.forgerock.openam.sdk.domain.model.Policy> annotated with @org.forgerock.sdk.com 
    .google.inject.name.Named(value=policyProvider) 
       for parameter 0 at org.forgerock.openam.sdk.policy.operations.PolicyOperationsProvider.<init>(Unknown Source) 
       while locating org.forgerock.openam.sdk.policy.operations.PolicyOperationsProvider 
    

Recent Changes

N/A

Causes

The cause depends on the error seen:

ERROR org.forgerock.openam.sdk.http.ServerErrorException

A REST call to the AM server is not serviced within the 10 second read-timeout. This is a hard-coded timeout that is not configurable since 10 seconds is sufficient in a working environment; this error usually indicates an unresponsive AM server.

ERROR org.forgerock.sdk.com.google.inject.ProvisionException

This error (with or without the Guice provision errors) indicates an underlying issue with the SSL connection and certificate.

Solution

This issue can be resolved as follows depending on the error seen:

ERROR org.forgerock.openam.sdk.http.ServerErrorException

Address the reason(s) why the AM server is unresponsive. If the unresponsiveness is associated with high CPU, see How do I collect data for troubleshooting high CPU utilization on AM/OpenAM (All versions) servers? for further information.

Other possible reasons include network and storage bottlenecks on the AM server, which you should investigate and resolve as needed.

ERROR org.forgerock.sdk.com.google.inject.ProvisionException

Enable SSL debugging and set the debug level to TRACE to identify the specific cause of your SSL connection issue and resolve accordingly. See How do I enable debug mode for troubleshooting Amster (All versions)? for information on enabling SSL debug logging and increasing the debug level.

Some possible errors that you might encounter include:

Error Resolution
javax.net.ssl.SSLException: Certificate for <host> doesn't match any of the subject alternative names: [SAN]
Ensure the hostname is specified in the CN or SAN of the server certificate. 
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: Certificate chaining error
Ensure the client or server is sending a valid certificate chain with the certificates in the correct order. See SSL client certificate is failing with "ValidatorException: Certificate chaining error" for further information.

See Also

FAQ: Installing and using Amster in AM

How do I enable debug mode for troubleshooting Amster (All versions)?

How do I diagnose a hung AM/OpenAM (All versions) server?

How do I use the msnapshots script to capture information for troubleshooting AM/OpenAM (All versions)?

Troubleshooting AM/OpenAM and Policy Agents

Using Amster in AM

User Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11876 (Amster has a timeout limit of 10 second and it is not configurable )

OPENAM-11773 (amster throws missleading error '502 bad gateway')


Only url, secondaryURLs and _id are valid in write error when importing configuration data via Amster in AM (All versions)

The purpose of this article is to provide assistance if you encounter a "400 Bad Request: Only url, secondaryURLs and _id are valid in write" error when importing the service configuration using Amster in AM. This error only happens when you have a site configured.

Symptoms

One of the following errors is shown when importing a service configuration using Amster depending on whether your deployment has a load balancer or not:

Failed to import /path/to/amster/export_dir/global/Sites/Main.json  : 400 Bad Request: Only url, secondaryURLs and _id are valid in write

Failed to import /path/to/amster/export_dir/global/Sites/lb.json  : 400 Bad Request: Only url, secondaryURLs and _id are valid in write

Recent Changes

Configured a site.

Causes

The exported Main.json or lb.json file has an extra id property.

Solution

You can workaround this issue by removing the extra id property form the exported Main.json or lb.json file:

  1. Locate the Main.json or lb.json file that it is indicated in the error. For example, an exported lb.json file looks similar to this:
    {
      "metadata" : {
        "realm" : null,
        "amsterVersion" : "14.0.0",
        "entityType" : "Sites",
        "entityId" : "lb",
        "pathParams" : { }
      },
      "data" : {
        "_id" : "lb",
        "id" : "02",
        "url" : "http://host1.example.com:8080/openam",
        "secondaryURLs" : [ ]
      }
    
  2. Remove the id property ("id" : "02") from this file to leave the following valid file:
    {
      "metadata" : {
        "realm" : null,
        "amsterVersion" : "14.0.0",
        "entityType" : "Sites",
        "entityId" : "lb",
        "pathParams" : { }
      },
      "data" : {
        "_id" : "lb",
        "url" : "http://host1.example.com:8080/openam",
        "secondaryURLs" : [ ]
      }
    
  3. Save this file and re-attempt the import.

See Also

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

FAQ: Installing and using Amster in AM

Using Amster in AM

Related Training

N/A

Related Issue Tracker IDs

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


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)


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...