• Amster 5.5.2 is the latest release targeted for Amster 5.5 deployments and can be downloaded from the ForgeRock Backstage website. To view the list of fixes in this release, see Key Fixes in Amster 5.5.2.

• Improved Error Messages for the install-openam Command

  Amster 5.5.2 improves the error messages showing when installing AM is unsuccessful.

  For more information, see "Troubleshooting Access Management Installations" in the User Guide

• Support for AM 5.5 or Newer Only

  Amster 5.5.2 supports exporting and importing configuration from AM 5.5 or newer.

  If you have a previous version of Amster:

  1. Perform a fresh installation of Amster 5.5.2. For more information, see "Installing Amster" in the User Guide.

  2. Migrate any Amster Groovy scripts from the previous Amster installation. Take into account these Release Notes for possible changes in functionality.

  3. Migrate any JSON configuration files that were exported from the following versions of AM:

     • AM 5

     • AM 5.1.0

     • AM 5.1.1

     A configuration file upgrade tool is provided in the AM 5.5.2 ZIP file. For more information on converting configuration files for import into AM 5.5, see the README.md file in the Config-Upgrader-5.5.2.zip file.

  4. Test the new Amster installation

  5. Delete the previous amster installation. For example:

     $ rm -rf /path/to/amster_5.0

• Support for Installing Access Management With an External Configuration and User Store

  Amster 5.5 supports installing AM with an external configuration store. When you install AM with an external configuration store, you must also use an external user store. By default, the external user store is the same directory server instance as the external configuration store. You can, however, specify a different user store.

  For more information about installing AM with an external configuration store, see Installing AM With an External Configuration Store in the User Guide.

  For more information about supported user stores, see the ForgeRock Access Management Release Notes.

  For more information about the configuration options supported by Amster, see "Command-Line Reference" in the User Guide.

• There are no important changes in functionality in this release, only bug fixes.

• There are no important changes in functionality in this release, only bug fixes.

• No functionality has been deprecated in this release.

• No functionality has been deprecated in this release.

• No features were removed in this release.

• PolicyAgentPwd Option Removed

  The PolicyAgentPwd option has been removed from the install-openam option, since it is no longer required by AM.

The following important issues were fixed in this release:

• OPENAM-10667: Amster should be able to add second instance of AM to existing one

• OPENAM-11159: OpenAM Amster export/import for Site have import errors

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

• OPENAM-12168: Amster tries to load custom service subconfiguration before loading realm level configurations

• OPENAM-12912: Upgrade 5.5.x --> 6.x fails if Amster has been used at some point to export/import

• OPENAM-12923: Amster import bug with chain ("Unable to update SMS config")

• OPENAM-13084: Entity Import ordering in amster

• OPENAM-13590: Document or Improve Amster for org.forgerock.amster.com.iplanet.am.lbcookie.value

• OPENAM-15510: Generic amster error message "No Base Entity dc=config,dc=forgerock,dc=com found" needs to detail the actual ldap error - during install-openam

• OPENAM-15687: Session endpoint is searching for a long value in CTS that is stored as a string

The following important issues were fixed in this release:

• OPENAM-11307: Amster import should not set the com.iplanet.am.version property

• OPENAM-10689: Installing AM using Amster failed when using an external data store

• OPENAM-10664: Amster does not support configuration of an external user store

• There are no limitations in functionality in this release.

• Private Key Connections to Access Management Can Fail

  Installing or upgrading AM appends the contents of the /path/to/openam/amster_rsa.pub file to the /path/to/openam/authorized_keys file. The contents of the authorized_keys file resemble the following:

  from="127.0.0.0/24,::1" ssh-rsa AAAAB3NzaC1y...

  The from attribute restricts the communication between AM and Amster clients that communicate using the 127.0.0.0/24 network. If your AM server is not configured in the loopback interface, Amster connections may fail with an error resembling the following:

  am> connect  --private-key /home/fr/openam/amster_rsa https://openam.example.com:8443/openam
     Unexpected response from OpenAM
      [code:401, reason:Unauthorized, message:Authentication Failed]

  To work around this problem, remove or update the from attribute to suit your environment as follows:

  • Remove the from attribute, leaving only the key. For example:

    ssh-rsa AAAAB3NzaC1y...

    In this example, the Amster client holding the appropriate private key can communicate with AM regardless of their IP address or DNS domain.

  • Update the loopback network specified in the from attribute with the DNS domain configured for AM. For example:

    $ cat /etc/hosts | grep -i openam
         192.168.1.94  openam.example.com
    
          $ vi /path/to/openam/authorized_keys
         from="*.example.com" ssh-rsa AAAAB3NzaC1y...

    In this example, the Amster client holding the appropriate private key can communicate with AM if they are part of the .example.com DNS domain.

    Refer to the Linux documentation for more information about patterns supported by the from attribute.

• Amster Installs Single-server Instances of Access Management

  To create instances and add them to a multi-server site deployment, see the ForgeRock Access Management Install Guide.

• Importing Resources Containing Slash Characters Can Fail

  Some Access Management resources have names that can contain slash characters (/), for example policy names, application names, and SAML v2.0 entities. These slash characters can cause unexpected behavior and failures in Amster when importing into Access Management instances running on Apache Tomcat.

  To workaround this issue, configure Apache Tomcat to allow encoded slash characters by updating the CATALINA_OPTS environment variable. For example:

  On Unix/Linux systems:

  $ export CATALINA_OPTS= \
     "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
     $ startup.sh

  On Windows systems:

  C:\> set CATALINA_OPTS= ^
     "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
     C:\> startup.bat

  Warning

  It is strongly recommended that you do not enable org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH when running AM in production as it introduces a security risk on Apache Tomcat.

  For more information, see How do I safely enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM/OpenAM (All Versions)? in the ForgeRock Knowledge Base.

• [INFO] Messages Showing On SuSE On Amster Start Up

  Running Amster on SuSE may produce [INFO] messages, for example:

  # ./amster
     [INFO] Unable to bind key for unsupported operation: up-history
      [INFO] Unable to bind key for unsupported operation: down-history
      [INFO] Unable to bind key for unsupported operation: up-history
      [INFO] Unable to bind key for unsupported operation: down-history
      OpenAM Shell (5.5.2 build c9ca9450a9, JVM: 1.8.0_65)
      Type ':help' or ':h' for help.
      -----------------------------------------------------
      am>

  These messages are caused by the keyboard mappings configured in the /etc/inputrc file and can safely be ignored, as they do not affect functionality.

• No issues remained open when Amster 5.5.2 became available.

• No issues remained open when Amster 5.5.0 became available.