Notes covering new features, fixes and known issues for the ForgeRock® Access Management command-line interface, Amster.
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™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.
The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:
ForgeRock Access Management (AM)
ForgeRock Identity Management (IDM)
ForgeRock Directory Services (DS)
ForgeRock Identity Gateway (IG)
ForgeRock Identity Message Broker (IMB)
Chapter 1. What's New
This chapter covers the new features and improvements done in Amster 5.
1.1. New Features in Amster 5
Amster 5 is the first release, and includes the following features:
Scripted, Deterministic Deployments. Script AM deployments by using the Groovy scripting support within Amster.
See Section 3.5, "Scripting" in the User Guide.
Import and Export Configuration. Amster can export all the configuration settings related to an AM instance and import it back to the same or a different instance.
See Section 3.2, "Exporting Configuration Data" in the User Guide.
Configuration Stored in JSON. Amster exports all configuration settings as a hierarchy of JSON format text files on the local filesystem. Store these files in a version control system to manage and maintain AM configurations.
See Chapter 1, "Introducing the Amster Command-line Interface" in the User Guide.
Encryption of Sensitive Data. Amster can export encrypted password and sensitive data to the configuration files. Amster is not able to decrypt the values itself, only a correctly configured AM instance with the appropriate transport key installed is able to decrypt the values.
See Section 3.1, "Creating Transport Keys" 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:
|Red Hat Enterprise Linux, Centos, Amazon Linux||6, 7|
|Amazon Linux||Amazon Linux 2016.09|
|Ubuntu||14.04 LTS, 16.04 LTS|
|Solaris x64||10, 11|
|Solaris Sparc||10, 11|
|Windows Server||2012, 2012 R2, 2016|
2.2. Java Requirements
|Oracle JDK||7, 8|
|IBM SDK, Java Technology Edition (Websphere only)||7|
Support for Oracle JDK 7 and IBM SDK 7 will be removed in a future version.
2.3. Special Requests
If you have a special request regarding support for a combination not listed here, contact ForgeRock at firstname.lastname@example.org.
Chapter 3. Limitations and Known Issues
The following important issues remained open when Amster 5 became available:
Amster Imports and Exports Configuration From Access Management 5 or Newer
Upgrade to Access Management 5 or newer to import or export the configuration using Amster.
For more information on upgrades, see the Upgrade Guide.
Amster Installs Single-server Instances of Access Management
To create instances and add them to a multi-server site deployment, see the 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_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
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 (14.0.0 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.
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 the
authorized_keysfile resemble the following:
from="127.0.0.0/24,::1" ssh-rsa AAAAB3NzaC1y...
fromattribute restricts the communication between AM and Amster clients that communicate using the
127.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:
fromattribute, leaving only the key. For example:
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
Refer to the Linux documentation for more information about patterns supported by the
3.2. Known Issues
3.2.1. Known Issues in Amster 5
The following important issues remained open when Amster 5 became available:
OPENAM-10664: Amster does not support configuration of an external user store
OPENAM-10667: Amster should be able to add second instance of AM to existing one
OPENAM-10735: Amster script does not work on Solaris SPARC 10
OPENAM-10920: Amster: Multiple " Unhandled server error: [Status: 501 Not Implemented]" for --listPasswords
Chapter 4. Documentation Updates
The following table tracks changes to the documentation set following the release of Amster 5:
Added a warning admonition about enabling
Added a brief paragraph on how to pass variables into an Amster script. See Section 3.5, "Scripting" in the User Guide
Added a brief paragraph on how to invoke a script directly in Amster. See Section 3.5, "Scripting" in the User Guide
Added documentation about starting the amster
command in debug with the
Added a limitation to the Release Notes related to private key connections to AM. For more information, see Section 3.1, "Limitations".
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, classes 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.