Skip to main content

Obtaining API Credentials

Obtain credentials for authenticating and authorizing to the Key Manager API. This can be done in either of the following ways:

  • Obtaining a Key Manager API token.

  • Obtaining SSL client certificates.

Obtaining a Key Manager API token​

This section provides instructions for obtaining a Key Manager API token to be used as API credentials. Skip this section if you are opting to set up the API connection using client certificates.

To create a token for connecting to the API:

  1. Access the Key Manager GUI using an account with Administrator permissions.

  2. On the Accounts→API tokens page, create a new API token for the API user.

  3. Download the newly created API token to a secure location. The token data will need to be uploaded to User Portal later.

Obtaining Client Certificates​

This section provides instructions for obtaining client certificates to be used as API credentials. Skip this section if you are opting to set up the API connection using an API token instead.

The User Portal connects to the Key Manager API via HTTPS, which means that you must set up the necessary certificates for client authentication.

To set up the certificates required for connecting to the API:

  1. You must obtain or create the certificate files for the API user. The required certificate files are:

  • client key

  • client certificate

  • Root-CA certificate on the Key Manager front end server-certificate chain.

    Typically, CAs attach their entire certificate chain to their certificate responses. In such cases, it is enough to extract the root certificate from the chain.

For production environments, we recommend that you use trusted certificates issued by your CA. For evaluation installations, you can create self-signed certificates using the utilities provided with Key Manager:

Option 1: Getting trusted certificates​

i. Create a private key for the client on any machine with openssl:

# openssl genrsa -out `client.key` 2048

This generates the client key client.key to the current working directory.

ii. To obtain the client certificate and the CA certificate, you must generate a Certificate Signing Request (CSR) (replace apiuser with the name of the API user, which you created in Creating a Key Manager API User):

# openssl req -subj '/CN=apiuser' -key `client.key` -new -out `client.csr`

This generates the CSR client.csr to the current working directory.

iii.Enroll for the client certificate by sending the CSR to your CA. This CA must be one of the acceptable client-certificate authorities on the Key Manager front end.

You can verify the applicable CAs with a command like the following (replace frontend.example.com with the address of the Key Manager front end):

# openssl s_client -showcerts -connect frontend.example.com:443

In the output of the command, you can verify the list of acceptable CAs under Acceptable client certificate CA names, which should look similar to the following:

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

Acceptable client-certificate authorities can be defined in the client-CA-certificate file, located on the Key Manager front end. For more information about configuring server-side certificates, see the PrivX Key Manager Installation Manual.

iv. Obtain the root-CA certificate on the Key Manager front end server-certificate chain. The name of the correct root CA can be determined from the output of this command:

# openssl s_client -showcerts -connect frontend.example.com:443 -showcerts

The name of the root CA can be determined from the Certificate chain section, which looks similar to the following:

---
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:

  • Copy the root-CA certificate from the command output.

  • Typically, you may request and obtain the root-CA certificate from any of the issuers (CAs) specified in the Certificate chain.

Option 2: Creating self-signed certificates​

note

This option is available only if the Key Manager 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 API user, which was created in Creating a Key Manager API User):

$ cd /opt/sshmgr/bin/
$ sudo ./ssh-mgr-certmake apiuser

This creates the client key client.key, the client certificate client.crt, and the certificate (chain) of the CA ca.crt under /opt/sshmgr/bin/crt/.