About connecting instances to CloudGate Key Manager

To be able to connect to CloudGate Key Manager, the following software needs to be installed and configured on the instance:

• OpenSSH 6.9 or higher
• A command-line utitlity that is able to make HTTP requests such as curl (recommended), or wget

Upon SSH authentication, for the server instance to be able to retrieve SSH key information, it needs to send an HTTP or HTTPS GET request to CloudGate Key Manager. This request needs to contain the following parameters:

account

The name of the operating system-level account that is being authenticated to. For example, if the user is trying to log in with j.t.kirk@enterprise.starfleet.org, the value of this parameter will be j.t.kirk.

key

The fingerprint of the key that the user is using to authenticate.

instance

The name or ID of the server instance that the user is authenticating to. This can be the instance's host name, or the instance name/ID that was assigned by the cloud service provider. This value needs to correspond to the name/ID that is configured for the instance in CloudGate Key Manager.

#!/usr/bin/env bash

instance=$(/usr/bin/curl -s 'http://169.254.169.254/latest/meta-data/instance-id')

/usr/bin/curl --get --max-time 5 --data-urlencode "account=$1" \
                                 --data-urlencode "key=$2" \
                                 --data-urlencode "instance=$instance" \
                                 http://172.17.0.100 \
|| echo -n;

This script is to be called by the SSH server whenever a user tries to perform an SSH login.

1. The script uses curl to retrieve the instance's ID from Amazon's EC2 metadata service.
2. The script then uses curl again to pass the instance ID, along with information received from the SSH server (see Configuring the SSH server), to CloudGate Key Manager (available at 172.17.0.100 in the example above).
3. CloudGate Key Manager will evaluate the request, and if the user who owns the key is allowed to access the specified account on the specified instance, it will return the corresponding public key to the script, which in turn will pass it on to the SSH server to complete the authentication procedure.
   Note: The script uses a request timeout setting of 5 seconds. If CloudGate Key Manager does not respond within this period, or the request fails for any other reason, the script will return an empty value to the SSH server, causing it to fall back on other authorized keys or authentication methods.

After preparing the script to connect to CloudGate Key Manager, the SSH server needs to be configured to call the connection script upon user login. To do this, some changes need to be made to the SSH server's configuration file, which typically resides at /etc/ssh/sshd_config (see the OpenSSH manual for additional information). In particular, the following configuration options are relevant:

PubkeyAuthentication

This option specifies whether public key authentication is allowed, and defaults to yes.

AuthorizedKeysCommand

This option specifies the command that needs to be executed to retrieve authorized keys.

AuthorizedKeysCommandUser

This option specifies the user under whose account the above command is executed.

For use with CloudGate Key Manager and the connection script created in the previous section, the configuration could look as follows:

PubkeyAuthentication yes
AuthorizedKeysCommand /etc/ssh/get_authorized_keys.sh %u %f
AuthorizedKeysCommandUser root