--- title: Connect to AM description: 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: component: pingam version: 8.1 page_id: pingam:amster:connect-am canonical_url: https://docs.pingidentity.com/pingam/8.1/amster/connect-am.html page_aliases: ["user-guide:amster-connecting.adoc"] section_ids: interactive-login: Interactive login connections proc-interactive-login: Connect with interactive login private-login: Private key connections private-login-local: Connect locally with default private key files sec-getting-started-connect-keys: Connect to a remote AM instance create-RSA-keys: Create and configure a private key pair --- # 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> ```