Notes covering new features, fixes and known issues for the ForgeRock® Access Management command-line interface, Amster.

Preface

Amster is a lightweight command-line interface, ideal for use in DevOps processes, such as continuous integration and deployment.

Read these release notes before you install Amster. The information contained in these release notes cover prerequisites for installation, known issues and improvements to the software, changes and deprecated functionality, and other important information.

About ForgeRock Identity Platform™ Software

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Chapter 1. What's New

This chapter covers new features and improvements in Amster.

Amster 6

  • Support for AM 6 or Newer Only

    Amster 6 supports exporting and importing configuration from AM 6 or newer.

    If you have a previous version of Amster:

    1. Perform a fresh installation of Amster 6. 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

      • AM 5.5

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

    4. Test the new Amster installation.

    5. Delete the previous Amster installation. For example: 

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

  • ForgeRock Identity Platform Common Configuration Expressions

    Since its inception, Amster has supported using variables in exported configuration files in the format AMSTER{myVariableName}.

    ForgeRock Identity Platform 6 introduces expressions, a way to support property value substitution on configuration files using the same rules across the Platform.

    Amster variables in configuration files are deprecated in favor of expressions.

    For more information, see "Using Configuration Expressions in Exported Configuration Files" in the User Guide.

Amster 6.0.1

  • Support for Multi-Server Deployment Installations

    Amster 6.0.1 can now configure deployed AM instances as part of a multi-server deployment.

    To support these deployments, the following options have been added to the install-openam command:

    • dsEmbReplReplPort1

    • dsEmbReplReplPort2

    • dsEmbReplFlag

    • dsEmbReplHost2

    • dsEmbReplAdminPort2

    • existingServerId

    For more information about the options, see "Command-Line Reference" in the User Guide. For examples, see "Installing Access Management with Amster" in the User Guide.

  • Improved Error Messages for the install-openam Command

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

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

  • The Value of the com.iplanet.am.lbcookie.value Property Can Be Overridden

    By default, Amster configures the value of the com.iplanet.am.lbcookie.value property as the value of the server ID. This could not be changed in earlier versions of Amster.

    To override the default during import in Amster 6.0.1, prefix the new value with override-server-id: in the configuration files. For example: 

    "com.iplanet.am.lbcookie.value" : "override-server-id:myLBCookieValue"

Chapter 2. Before You Install

This section covers software and hardware prerequisites for installing and running Amster.

ForgeRock supports customers using the versions specified here. Other versions and alternative environments might work as well. When opening a support ticket for an issue, however, make sure you can also reproduce the problem on a combination covered here.

2.1. Operating System Requirements

ForgeRock supports customers using ForgeRock Access Management server software on the following operating system versions:

Supported Operating Systems
Operating SystemVersion
Red Hat Enterprise Linux, Centos, Amazon Linux6, 7
Amazon LinuxAmazon Linux AMI 2017.09, Amazon Linux 2
SuSE12
Ubuntu14.04 LTS, 16.04 LTS
Solaris x6410, 11
Solaris Sparc10, 11
Windows Server2012 R2, 2016

2.2. Java Requirements

JDK Requirements
VendorVersion
Oracle JDK8
IBM SDK, Java Technology Edition (Websphere only)8
OpenJDK8

2.3. Special Requests

If you have a special request regarding support for a combination not listed here, contact ForgeRock at info@forgerock.com.

Chapter 3. Changes and Deprecated Functionality

This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.

3.1. Important Changes to Existing Functionality

This section lists changes made to existing functionality in Amster.

Amster 6

  • Changes to the install-openam Command

    Amster 5.5 supports fallback to external configuration store properties for the user store during AM installation. Amster 6 requires that you specify the properties for both the external user store and external configuration store, even if they will use the same DS server.

    For more information about installing AM using Amster, see install-openam in the User Guide and "Installing Access Management With Amster Examples" in the User Guide.

Chapter 4. Limitations and Known Issues

4.1. Key Fixes

The following issues are fixed in this release. For details, see the OpenAM issue tracker.

Amster 6

4.2. Limitations

The following important issues remained open at the time release 6 became available:

  • No Support for Load Balanced Deployments

    Amster cannot connect to a load balancer URL. You must connect Amster directly to a single AM instance. Using a load balancer could send sequential commands to different AM instances, and could result in concurrency issues when writing to the underlying configuration store.

  • 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 (6 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.

4.3. Known Issues

Amster 6

  • No issues remained open when Amster 6 became available.

Chapter 5. Documentation Updates

The following table tracks changes to the documentation set following the release of Amster 6:

Documentation Change Log
DateDescription
2022-01-20

Highlighted the limitation regarding load balanced deployments.

2019-07-16

Added missing --connection-timeout option.

2018-06-04

Added a warning admonition about enabling -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH in production. For more information, see "Limitations".

2018-05-04

Initial release


Appendix A. Getting Support

For more information or resources about OpenAM and ForgeRock Support, see the following sections:

A.1. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

A.2. Using the ForgeRock.org Site

The ForgeRock.org site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.

If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.

A.3. Getting Support and Contacting ForgeRock

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details on ForgeRock's support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.

Read a different version of :