Configuring public/private key pairs for tokens

Configure public/private key pairs for signing and verifying tokens in your API Connect deployment.

About this task

By default, an API Connect deployment receives one public/private key pair, which is used repeatedly. The public/private key pair is generated for you the first time you start API Connect after installing or upgrading it. The keys are stored in a keystore object. You can add and revoke keys, and configure a rotation through keys for enhanced security.

You can configure key pairs for tokens in the Cloud Manager user interface, or by using the Toolkit CLI.

Using the Cloud Manager UI to configure public/private key pairs

Use the Cloud Manager user interface to configure key pairs for signing and verifying tokens.

About this task

Manage Keystore assignment and Keystore history for tokens

Procedure

In the Cloud Manager, click .
In the Settings navigation list, click Signed Token.

The Signed Token page displays the list of supported tokens for signing.
Review the current token settings:
- Click Payload to display the payload code for the set of tokens.
- Click History log next to a token to view its previous keystore assignments (this history never includes the current keystore assignment). The most recent assignment displays at the top of the list. You can remove any keystore assignment from the history by clicking .
To add or change a keystore assignment for a token, complete the following steps:
1. On the Signed Token page, click Edit.
2. On the Edit signed token page, select a keystore for the token you want to modify.
3. Click Save to save your changes and update the keystore history.
  
  Changes take effect immediately.
  
  The previously selected keystore is added to the history for the token that you just updated. The history never includes the current keystore assignment.

Using the Toolkit CLI to configure public/private key pairs

Use the Toolkit CLI to configure key pairs for signing and verifying tokens.

About this task

Use the following properties to the keystore URLs that contain the public/private key pair for each type of token. For each setting, the list of keystores is an array of strings, with each string representing the complete URL of a keystore. The first keystore in the array (keystore_url_0) is the one that is currently in use.

access_token:

access_token_keystore_urls: [keystore_url_0, keystore_url_n]

id_token:

id_token_keystore_urls: [keystore_url_0, keystore_url_n]

temporary_token:

temporary_token_keystore_urls: [keystore_url_0, keystore_url_n]

The keystore URLs can be lengthy. You can avoid errors by writing the settings in a file and uploading that file. Format the settings as a .yaml file (you can choose the file name) and upload the file using the toolkit CLI. The following example configures a different keystore for each type of token:

access_token_keystore_urls:
  - >-
    https://mgmt_endpoint_url/api/orgs/1cdb71a1-b53c-4b66-b162-1b0f45ca8a54/keystores/de5298dd-a00b-45a0-9d08-96c5d93e1273
id_token_keystore_urls:
  - >-
    https://mgmt_endpoint_url/api/orgs/1cdb71a1-b53c-4b66-b162-1b0f45ca8a54/keystores/85a21745-8ac3-499d-929a-2d017bade815
temporary_token_keystore_urls:
  - >-
    https://mgmt_endpoint_url/api/orgs/1cdb71a1-b53c-4b66-b162-1b0f45ca8a54/keystores/63d6462f-c93d-439b-b422-0e604381e97a

Procedure

Create a YAML file with the keystore settings for each type of token as shown in the example.

For information on using input files with the toolkit CLI, see Reading input from the command line.
Run the following command to log in to a management server as a member of the cloud administration organization:
```
apic login --server mgmt_endpoint_url --username user_id --password password --realm admin/identity_provider
```
Cloud settings are stored on a management server and you must log in to the server before you can access the settings with the CLI.
You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
```
apic identity-providers:list --scope admin --server mgmt_endpoint_url --fields title,realm
```
For example:
```
apic identity-providers:list --scope admin --server myserver.com --fields title,realm
total_results: 2
results:
  - title: Cloud Manager User Registry
    realm: admin/default-idp-1
  - title: Corporate LDAP user registry
    realm: admin/corporate-ldap
```
The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default Cloud Manager Local User Registry for login as a member of the cloud administration organization is default-idp-1.
For more information on logging in, see Logging in to a management server.

Upload the YAML file with the new settings by running the following command:

apic cloud-settings:update --server mgmt_endpoint_url my_token_keystore_settings.yaml

Run the following command to log out of the management server:
```
apic logout --server mgmt_endpoint_url
```