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's 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 makes use of the default authentication chain for administrator users configured in the AM instance. To locate this property, log in to AM 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.

To 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

    Tip

    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 username and password to authenticate to AM:

    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 a 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 install 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 NameDescription

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

    Holds the public keys of trusted Amster clients. AM check 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 install 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.


Connecting Locally with Default Private Key Files

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

To Connect Locally With the Default Key Pair

Perform the following steps to connect to a local AM instance using the default key pair:

  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>

Connecting 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.

To Create and Configure a Private Key Pair

To create a new key pair and append the public key to the AM instance perform the following steps:

  1. Login to the Amster server.

  2. Create a directory for the keys, for example, $HOME/.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 rsaoption: 

      $ ssh-keygen -t rsa -N "" -f $HOME/.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 a 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 $HOME/.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

    Note

    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

    The 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>
Read a different version of :