Client-Authentication Setup

After the Key Manager client packages have been installed, configure the clients to authenticate to a Key Manager front end, and vice versa.

For command-line clients: You need to set up API credentials for authenticating the client to the Key Manager front end. Supported API credentials include Key Manager API tokens, and SSL certificates (trusted or self-signed). For authenticating the Key Manager front end to the client, you will also need to obtain the Key Manager front end root-CA certificate.
For API clients: For authenticating the Key Manager front end to the client, you need to obtain the Key Manager front end root-CA certificate.

Determine the Required Certificates and CAs

This section describes how to determine the certificate requirements for client connections.

For authenticating Key Manager clients to the Key Manager front end, you will need to obtain the certificate of the root CA on the Key Manager front end server-certificate chain.
If opting to use SSL certificates for verifying the command-line client to the Key Manager front end, you will need to enroll for a certificate from a client-certificate CA trusted by the Key Manager front end. For this you will need to determine the trusted client-certificate CAs.

To verify the required certificates and the CAs who may issue them, run the following command on the Key Manager front end:

$ openssl s_client -showcerts -connect 127.0.0.1:443

The certificate chain of the Key Manager front end may be found under the Certificate chain section.

---
Certificate chain
0 s:/CN=frontend.example.com
  i:/C=US/O=Example Inc./CN=Example Authority
-----BEGIN CERTIFICATE-----
<Certificate data>
-----END CERTIFICATE-----
1 s:/C=US/O=Example Inc./CN=Example Authority
  i:/C=US/O=Another Example Inc./CN=Another Example Authority
-----BEGIN CERTIFICATE-----
<Certificate data>
-----END CERTIFICATE-----
...
n s:/C=US/O=Example Root CA Inc./CN=Example Root CA Authority
  i:/C=US/O=Example Root CA Inc./CN=Example Root CA Authority
-----BEGIN CERTIFICATE-----
<Certificate data>
-----END CERTIFICATE-----
---

There are multiple ways for obtaining the root-CA certificate:

Typically, you may request and obtain the root-CA certificate from any of the CAs (issuers) specified in the Certificate chain.
If available, copy the root-CA certificate from the command output.
If your Key Manager front end uses the default self-signed server certificate and (set up using setup- nginx), you can get the root-CA certificate from the following file on your Key Manager front end:

/etc/pki/tls/certs/ukmca.crt

Note that in production environments, we recommend all Key Manager Servers to be configured with trusted certificates.

If you are planning on setting up command-line clients with SSL client certificates (instead of API tokens), you will also need to determine the CAs that may issue client certificates. The applicable CAs are named under the Acceptable client certificate CA names section in the command output.

---
Acceptable client certificate CA names
/C=US/O=Example Organization/CN=Example CA 1
/C=US/O=Example Organization/CN=Example CA 2
---

note

Acceptable client-certificate authorities can be modified by adding and removing CA certificates from the client-CA-certificate file on the Key Manager front end. For more information about configuring server-side certificates, see Setting Up GUI and API services (Front End Only).

Authentication Setup for Command-Line Clients

This section describes the steps for setting up API credentials for command-line clients. For information about setting up credentials for API clients, see Section Authentication Setup for API Clients instead.

The necessary API credentials and certificates can be obtained and set up in any of the following ways:

Option 1: Using an API token

Create an API token for the client user. This can be done via the Key Manager GUI, on the Accounts→API tokens page.
Download the API token by performing a Download Token action on the API token. You will need to provide the credentials of the currently logged-in user (not the credentials of the client user). Copy the API-token file to the machine from which you are running the client.
Obtain the root-CA certificate of the Key Manager front end , as described in Determine the Required Certificates and CAs.
Set the API-token location using the SSHMGR_TOKEN environment variable (replace /path/to/token.txt with the actual path of the token file):
```
$ export SSHMGR_TOKEN=/path/to/token.txt
```
Set the root-CA-certificate location. This can be done in one of the following ways:
- Place the root-CA certificate to ~/crt/ca.crt, where ~ is the home directory of the client user.
- Specify the root-CA-certificate-file location by setting the environment variable SSHMGR_CA.
The client user must be made the owner of the credential files (API token, and root-CA certificate if used). To do this, run a command like the following for each credential file (replace user with the user name of the client user, replace usergroup with the user group of the client user, replace /path/to/file with the path of the credential file):
```
# chown user:usergroup /path/to/file
```
API tokens allow access to the API without the need to specify any additional credentials. For this reason you should ensure that the API-token file is only accessible to the owning user of the API token, similarly to the following (replace /path/to/token.txt with the path to the API-token file):
```
chmod go-rwx /path/to/token.txt
```

Option 2: Using trusted certificates

Create a private key for the client:
```
$ openssl genrsa -out client.key 2048
```
This generates the client key client.key to the current working directory.
To obtain the client certificate, you must generate a Certificate Signing Request (CSR) (replace clientuser with the name of the Key Manager account that is used by the client user, replace clientuser@example.com with the email address of the API user):
```
$ openssl req -subj '/CN=clientuser/emailAddress=clientuser@example.com' \
-key client.key -new -out client.csr
```
This generates the CSR client.csr to the current working directory.

note
For AD users, the User Principal Name (UPN) of the account is to be specified as the CN. For example:
/CN=alice@example.com
Obtain the client certificate by enrolling the CSR with a client-certificate CA that is trusted by the Key Manager front end. If required, also obtain the Key Manager front end root-CA certificate. The appropriate CAs can be determined according to the instructions provided in Determine the Required Certificates and CAs.
Obtain the root-CA certificate of the Key Manager front end , as described in Determine the Required Certificates and CAs.
Copy the previously obtained/created client key, client certificate, and the Key Manager front end root- CA certificate to the machine where you are setting up the command-line client. Set up command-line client to use the key and the certificates. This can be done in one of the following ways:
- Place the key and the certificate files to the following locations (replace ~ with the home-directory path of the client user):
  - Client key: ~/crt/client.key
  - Client certificate: ~/crt/client.crt
  - root-CA certificate: ~/crt/ca.crt
- Specify the file locations by setting the following environment variables:
  - SSHMGR_CERT: Path of the client certificate file.
  - SSHMGR_KEY: Path of the client key file.
  - SSHMGR_CA: Path of the root-CA certificate.
The client user must be made the owner of the key and certificate files. To do this, run a command like the following for each key and certificate file (replace user with the user name of the client user, replace usergroup with the user group of the client user, replace /path/to/file with the path of the client- key, client-certificate, or the root-CA-certificate file:
```
# chown user:usergroup /path/to/file
```

Option 3: Using self-signed certificates

note

This option is available only if the server is authenticated using the self-signed certificates set up by setup-nginx, which was run during Key Manager Server setup.

Run the following on a Key Manager Server (replace apiuser with the name of the Key Manager account that has API access permissions, created in Creating a Key Manager Client User:
```
# /opt/sshmgr/bin/ssh-mgr-certmake apiuser
```
This creates the client key client.key, the client certificate client.crt, and the root-CA certificate ca.crt in a crt folder under the current working directory.
Copy the previously-created client key, client certificate, and the Key Manager front end root-CA certificate to the machine where you are setting up the command-line client. Set up command-line client to use the key and the certificates. This can be done in one of the following ways:
- Place the key and the certificate files to the following locations (replace ~ with the home-directory path of the client user):
  - Client key: ~/crt/client.key
  - Client certificate: ~/crt/client.crt
  - root-CA certificate: ~/crt/ca.crt
- Specify the file locations by setting the following environment variables:
  - SSHMGR_CERT: Path of the client certificate file.
  - SSHMGR_KEY: Path of the client key file.
  - SSHMGR_CA: Path of the root-CA certificate.
The client user must be made the owner of the key and certificate files. To do this, run a command like the following for each key and certificate file (replace user with the user name of the client user, replace usergroup with the user group of the client user, replace /path/to/file with the path of the client- key, client-certificate, or the root-CA-certificate file:
```
# chown user:usergroup /path/to/file
```

Authentication Setup for API Clients

This section describes the steps for setting up API credentials for API clients. For information about setting up credentials for command-line clients, see Authentication Setup for Command-Line Clients instead.

For API clients, you will need to set up the root-CA certificate of the Key Manager front end. To do this:

Obtain the root-CA certificate of the Key Manager front end, as described in Determine the Required Certificates and CAs. Copy the root-CA-certificate file to the machine from which you are running the API client.
Configure the API client to use the root-CA certificate for all requests. The command is to be run as the client user (replace /path/to/ca.crt with the path to the root-CA-certificate file):
```
$ /opt/sshmgr/bin/ssh-mgr-cli client config request ca_file_path /path/to/ca.crt
```
Ensure that the root-CA certificate is readable for the client user (replace user:usergroup with the comma-separated user name and user group of the client user, replace /path/to/ca.crt with the path to the root-CA-certificate file):
```
# chown user:usergroup /path/to/ca.crt
$ chmod u+r /path/to/ca.crt
```

Determine the Required Certificates and CAs​

Authentication Setup for Command-Line Clients​

Option 1: Using an API token​

Option 2: Using trusted certificates​

Option 3: Using self-signed certificates​

Authentication Setup for API Clients​