PingAM

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 tree for administrator users, configured in the AM instance. The authentication tree is specified in the Administrator Authentication Configuration property under Realms > Top Level Realm > Authentication > Settings > Core.

The ldapService authentication tree, 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 tree. 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://am.example.com:8443/am

    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://am.example.com:8443/am

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

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

Private key connections

Amster can connect to an AM instance by using a private key pair and an authentication tree 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 amsterService authentication tree. Changing or removing this tree could prevent Amster connecting to AM.

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

    Default private keypair files
    File name Description

    /path/to/am/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/am/security/keys/amster/amster_rsa

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

    /path/to/am/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/am/security/keys/amster/amster_rsa \
 https://am.example.com:8443/am
amster am.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/am/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://am.example.com:8443/am
amster am.example.com:8443>