Amster

Connect to AM

Amster can connect to an AM instance using interactive login or using RSA or ECDSA key files, either over HTTP or HTTPS protocols. If you use self-signed certificates for AM, you must either:

  • Import the certificates into the JVM cacerts keystore on the Amster client.

  • Run the amster command, specifying the truststore containing the certificates and its type. For example:

    $ ./amster \
 -D javax.net.ssl.trustStore=/path/to/keystore.jceks \
 -D javax.net.ssl.trustStoreType=jceks

Interactive login connections

To establish an interactive connection with AM, Amster uses the default authentication chain for administrator users, configured in the AM instance. To locate this property, log in to the AM admin UI and navigate to Realms > Top Level Realm > Authentication > Settings > Core.

The ldapService authentication chain, configured by default after AM installation, requires a valid user in AM. Log in as an administrative user, for example amadmin, to perform operations such as export and import of the configuration.

Connect with interactive login

This procedure assumes the use of the ldapService chain. Perform the following steps to connect to a local or remote AM instance using interactive login:

  1. Start the Amster command-line interface.

  2. Run the connect command with the --interactive or the -i options:

    am> connect --interactive https://openam.example.com:8443/openam

    When using the amster command to import or export a significant amount of data, the default timeout of 10 seconds may be insufficient.

    To increase the default timeout, add the --connection-timeout seconds option. For example:

    am> connect --connection-timeout 45 \
 --interactive https://openam.example.com:8443/openam

  3. Specify the username and password to authenticate to PingAM:

    Sign in to OpenAM
User Name: amadmin
Password: *************
amster openam.example.com:8443>

Private key connections

Amster can connect to an AM instance by using a private key pair, and an authentication module and chain in AM. The private key must be available to the Amster client, and the AM instance must trust the client IP address and have the public key in its authorized_keys file. Successful connections create an amAdmin session in AM.

An installation, or an upgrade of AM creates the following infrastructure for Amster:

  • The Forgerock Amster authentication module in the Top Level Realm. The module is enabled by default in new AM installations and disabled by default when upgrading an existing AM.

    For information on how to configure this module, see Amster Authentication Module Properties in the Authentication and single sign-on guide.

  • The amsterService authentication chain in the Top Level Realm. Changing or removing this chain may result into not being able to connect with Amster.

  • The following RSA key pair files, in PKCS#1 PEM format:

    Default private keypair files
    File name Description

    /path/to/openam/security/keys/amster/authorized_keys

    Holds the public keys of trusted Amster clients. AM checks incoming Amster connections against these trusted keys. By default, contains a copy of the public key of a generated key pair that Amster can use.

    If this file exists in the configuration directory before a new installation is performed, the file is not overwritten; the contents of the newly-created amster_rsa.pub file are appended to it instead.

    /path/to/openam/security/keys/amster/amster_rsa

    Contains the private key of a generated key pair that Amster can use.

    /path/to/openam/security/keys/amster/amster_rsa.pub

    Contains the public key of a generated key pair that Amster can use.

Connect locally with default private key files

An Amster installation local to a new AM instance can connect without further configuration.

  1. Start the Amster command-line interface.

  2. Run the connect command with the --private-key, or the -k options:

    am> connect --private-key /path/to/openam/security/keys/amster/amster_rsa \
 https://openam.example.com:8443/openam
amster openam.example.com:8443>

Connect to a remote AM instance

To connect to a remote AM instance, create a private key pair for Amster, and append the contents of the public key to the authorized_keys file of the instance.

Create and configure a private key pair

Create a new key pair and append the public key to the AM instance:

  1. Login to the Amster server.

  2. Create a directory for the keys, for example, /path/to/.ssh .

  3. Run the ssh-keygen command to generate a key pair without passphrase. You can create RSA or ECDSA key pairs:

    • To create an RSA key pair, run the ssh-keygen command with the -t rsa option:

      $ ssh-keygen -t rsa -N "" -f /path/to/.ssh/id_rsa -b 2048
Generating public/private rsa key pair.
Your identification has been saved in id_rsa.
Your public key has been saved in id_rsa.pub.
The key fingerprint is:
78:ca:43:bc:0a:84:b0:ab:ac:40:96:49:48:84:80:63 root@amster_server

    • To create an ECDSA keypair, run the ssh-keygen command with the -t ecdsa option. You can create key pairs of 256, 384, or 521 curve sizes.

      For example:

      $ ssh-keygen -t ecdsa -N "" -f /path/to/.ssh/id_ecdsa -b 521
Generating public/private ecdsa key pair.
Your identification has been saved in id_ecdsa.
Your public key has been saved in id_ecdsa.pub.
The key fingerprint is:
6b:b9:75:cb:42:07:91:25:a7:bf:d6:d0:bc:6f:5a:d7 root@amster_server

      AM requires the private key to be in PKCS#1 PEM format. Recent versions of the OpenSSH ssh-keygen tool creates keys in its own format, which AM cannot process.

      If your generated private key (id_ras) begins with -----BEGIN OPENSSH PRIVATE KEY-----, you will need to recreate your keypair in PKCS#1 PEM format.

      Append the -m pem option to the ssh-keygen commands above to create a new pair in the supported PKCS#1 PEM format.

      For example:

      $ ssh-keygen -m pem -t rsa -N "" -f $HOME/.ssh/id_rsa -b 2048

    These commands generate two files, id_rsa.pub or id_ecdsa.pub containing the public key, and id_rsa or id_ecdsa containing the private key.

  4. Append the contents of the id_rsa.pub or id_ecdsa.pub files into the authorized_keys file in your AM instance(s); for example, into /path/to/openam/security/keys/amster/authorized_keys.

  5. Start the Amster command-line interface.

  6. To connect to AM using a specific private key file, run the connect command with the --private-key, or the -k options, specifying the path to the private key file. For example:

    am> connect --private-key $HOME/.ssh/id_rsa \
 https://openam.example.com:8443/openam
amster openam.example.com:8443>