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.
1.1. Maintenance Releases
ForgeRock maintenance releases contain a collection of fixes and minor RFEs that have been grouped together and released as part of our commitment to support our customers. For general information on ForgeRock's maintenance and patch releases, see Maintenance and Patch Availability Policy.
Amster 6.5.5 is the latest release targeted for Amster 6.5.x deployments and can be downloaded from the ForgeRock Backstage website. To view the list of fixes in this release, see Key Fixes in Amster 6.5.5.
1.2. New Features
There are no new features in Amster 6.5.5, other than those identified in Amster 6.5.
There are no new features in Amster 6.5.4, other than those identified in Amster 6.5.
There are no new features in Amster 6.5.3, other than those identified in Amster 6.5.
There are no new features in Amster 6.5.2.3, other than those identified in Amster 6.5.
There are no new features in Amster 6.5.2.2, other than those identified in Amster 6.5.
There are no new features in Amster 6.5.2.1, other than those identified in Amster 6.5.
There are no new features in Amster 6.5.2, other than those identified in Amster 6.5.
There are no new features in Amster 6.5.1, other than those identified in Amster 6.5.
There are no new features in Amster 6.5.0.1, other than those identified in Amster 6.5.
Support for AM 6.5.5 or Newer Only
Amster 6.5.5 supports exporting and importing configuration from AM 6.5.5 or newer.
Support for Multi-Server Deployment Installations
Amster 6.5 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.
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:
| Operating System | Versions |
|---|---|
| Red Hat Enterprise Linux, Centos | 6, 7 |
| Amazon Linux | Amazon Linux 2 Amazon Linux 2017.09 Amazon Linux 2018.03 |
| SuSE | 12 |
| Ubuntu | 14.04 LTS 16.04 LTS 18.04 LTS |
| Solaris x64 | 10, 11 |
| Solaris Sparc | 10, 11 |
| Windows Server | 2012 R2 2016 |
2.2. Java Requirements
The following table lists supported Java versions:
| Vendor | Versions |
|---|---|
| Oracle JDK | 8, 11 [a] |
| IBM SDK, Java Technology Edition (WebSphere only) | 8 |
| OpenJDK | 8, 11 [a] |
[a] Federation-related pages do not display when using Java 11. For more information, see the Knowledge Base. | |
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.
There are no important changes in Amster 6.5.3, other than those identified in Amster 6.5.
There are no important changes in Amster 6.5.2.3, other than those identified in Amster 6.5.
There are no important changes in Amster 6.5.2.2, other than those identified in Amster 6.5.
There are no important changes in Amster 6.5.2.1, other than those identified in Amster 6.5.
There are no important changes in Amster 6.5.2, other than those identified in Amster 6.5.
There are no important changes in Amster 6.5.1, other than those identified in Amster 6.5.
There are no important changes in Amster 6.5.0.1, other than those identified in Amster 6.5.
The Amster Configuration Upgrader Utility is not Included in the AM 6.5 Release
The tool could be used to upgrade configuration files exported by Amster for use in later versions.
Follow the procedures in the AM Upgrade Guide to upgrade from previous versions to AM 6.5. Then, use Amster to export configuration files that are compatible with AM 6.5.
3.2. Removed Functionality
No features or functionality have been removed in this release.
No features or functionality have been removed in this release.
No features or functionality have been removed in this release.
No features or functionality have been removed in this release.
No features or functionality have been removed in this release.
No features or functionality have been removed in this release.
No features or functionality have been removed in this release.
No features or functionality have been removed in this release.
Chapter 4. Key Fixes, Limitations, and Known Issues
4.1. Key Fixes
The following issues are fixed in this release. For details, see the OpenAM issue tracker.
OPENAM-13510: Amster does not allow to connect to load balancer URL
OPENAM-14818: Amster clean import removes current server when AM is deployed to root context
OPENAM-17020: Amster import fails after removing identity store and setting User Profile to ignore
OPENAM-17072: eval(String) function in amster shell results in MissingMethodException
OPENAM-17977: Amster connect command ignores connection-timeout
OPENAM-18027: Amster import clean fails intermittently with 500 - authentication instance x does not exist
OPENAM-11159: OpenAM Amster export/import for Site have import errors
OPENAM-14265: Amster Import with --clean doesn't delete the secrets store and mappings
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-15574: Amster Import - updating com.iplanet.am.lbcookie.value to a different value to server ID
OPENAM-15687: Session endpoint is searching for a long value in CTS that is stored as a string
OPENAM-15880: Lack of documentation of what kind of amster variable substitution is supported
No fixes were made in this release. Only the version number was updated to match the AM version.
No fixes were made in this release. Only the version number was updated to match the AM version.
No fixes were made in this release. Only the version number was updated to match the AM version.
OPENAM-10958: Amster cannot import configuration with containing sub realms with --clean if the instance already contains sub realms
OPENAM-13896: Comparison method violates its general contract! seen during amster import
OPENAM-14049: Amster export failure
OPENAM-14172: Amster Export - Persistent cookie Keystore Mapping inconsistency after upgrade to 6.5.0
OPENAM-14222: Amster fails exporting Secret Store Mappings in sub-realms
OPENAM-14049: Amster export failure
OPENAM-13590: Document or Improve Amster for org.forgerock.amster.com.iplanet.am.lbcookie.value
OPENAM-12912: Upgrade 5.5.x --> 6.x fails if Amster has been used at some point to export/import
OPENAM-10667: Amster should be able to add second instance of AM to existing one
4.2. Limitations
The following important issues remained open at the time release 6.5.5 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.pubfile to the/path/to/openam/authorized_keysfile. The contents of theauthorized_keysfile resemble the following:from="127.0.0.0/24,::1" ssh-rsa AAAAB3NzaC1y...
The
fromattribute restricts the communication between AM and Amster clients that communicate using the127.0.0.0/24network. 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
fromattribute to suit your environment as follows:Remove the
fromattribute, 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
fromattribute 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.comDNS domain.Refer to the Linux documentation for more information about patterns supported by the
fromattribute.
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_OPTSenvironment 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_SLASHwhen 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 (${amster.software.vers} 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/inputrcfile and can safely be ignored, as they do not affect functionality.
4.3. Known Issues
There are no known issues in Amster 6.5.5, other than those identified in Amster 6.5.
OPENAM-19529: amster does not export non-global service schema defaults
There are no known issues in Amster 6.5.3, other than those identified in Amster 6.5.
There are no known issues in Amster 6.5.2.3, other than those identified in Amster 6.5.
There are no known issues in Amster 6.5.2.2, other than those identified in Amster 6.5.
There are no known issues in Amster 6.5.2.1, other than those identified in Amster 6.5.
There are no known issues in Amster 6.5.2, other than those identified in Amster 6.5.
There are no known issues in Amster 6.5.1, other than those identified in Amster 6.5.
There are no known issues in Amster 6.5.0.1, other than those identified in Amster 6.5.
OPENAM-13896: Comparison method violates its general contract! seen during amster import
Chapter 5. Documentation Updates
The following table tracks changes to the documentation set following the release of Amster 6.5.5:
| Date | Description |
|---|---|
| 2022-01-20 | Highlighted the limitation regarding load balanced deployments. |
| 2020-09-14 | Initial release of 6.5.3. |
| 2020-02-17 | Initial release of 6.5.2.3. |
| 2019-10-31 | Initial release of 6.5.2.2. |
| 2019-08-27 | Initial release of 6.5.2.1. The Following documentation changes were made: Added missing --connection-timeout option. |
| 2019-06-14 | Initial release of 6.5.2. |
| 2019-04-11 | Initial release of 6.5.1. |
| 2019-01-17 | Initial release of 6.5.0.1. |
| 2018-11-13 | Initial release of 6.5. |
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, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.