Managing the public/private key pairs for signing tokens

Why do you need public/private key pairs?

API Connect uses a public/private key pair to sign and verify the following tokens:

• access_token: Verifies that the user has permission to access resources.
• id_token: Stored within the access token to specifies the user’s ID.Confirm?
• temporary_token: Provides for short-lived access so that the user can log in and receive an access token. For example, when the user receives a link for resetting a password or to register for an account.

How does APIC use the public/private key pair?

Each API Connect deployment is assigned a public key, which is made openly available, plus a corresponding private key, which can only be accessed by that deployment. To verify a user’s access to resources for a transaction, API Connect signs every token with the private key. Any other party can use the openly available public key to verify the signature. Because the private key is not shared, it can be used repeatedly instead of generating a new value for each signature.

When your app accesses an API endpoint, the access_token is in JWT format and includes a 'kid" value that is the new key.

How can you manage public/private key pairs?

By default, your deployment is assigned one key pair, which is stored in a keystore and never expires. The same key pair is used for signing and verify all tokens. The key pair consists of a public key and a private key:

• key_signing: The private key that API Connect uses for signing tokens
• key_verify: The public key that anyone can access and use for verifying token signatures

API Connect uses the following cloud settings to determine which public/private keystores are used for each type of token:

• access_token_keystore_urls: [keystore_url_0, keystore_url_n]
• id_token _keystore_urls: [keystore_url_0, keystore_url_n]
• temporary_token _keystore_urls: [keystore_url_0, keystore_url_n]

Each setting specifies an array of URLs where the keystores are hosted, with the keystore at position 0 representing the current key pair. You can optionally generate additional key pairs, store them in new keystores, and use them with the tokens to enhance security. Each key pair is stored in its own keystore and can be set to expire at a different time. Providing a different key pair for each type of token is a good practice because it limits the damage if a token is compromised.

If you specify one keystore for a token, that key pair is used for every new token of the same type, and it never expires. If you specify multiple keystores, you can assign a lifetime to each and when the keys in the first keystore expire, the keys are obtained from the next keystore in the list, and so on.

You can use the public/private key pairs and keystores to perform the following operations with tokens:

Sign a token

The first keystore in the array is the current keystore; use its key_signing key to sign tokens.

Verify a token's signature

To verify a token's signature, start with the current keystore (the first in the array). If the token doesn’t match the key_verify key, move to the older keystores and compare the token with the key_verify value in each.

Add key pairs

When you create a new key pair, add the keys to a separate keystore, and then add that keystore’s URL to the end of the token’s keystore array. The first keystore in the array is the “current” keystore, and subsequent keystores in the array are used in turn.

Revoke key pairs

If you suspect that a token is compromised, you can revoke they keys for signing and verifying it. To revoke a key pair, delete the corresponding keystore from the token’s keystore array. Removing a keystore removes the keys that were used for signing and verifying tokens, and invalidates all of the tokens that were issued with that key pair.

Attention: You must always retain at least one key pair for signing and verifying tokens.

Rotate through keystores to periodically change the key pairs in use

To rotate through key pairs for a token, configure at least two keystores for the token. Specify the “current” keystore first in the array, followed by the “next” keystores. Make sure that the each keystore’s lifetime overlaps that of the next keystore so that keys from the current keystore don’t expire before the new key pair takes effect.

Before you configure the lifetime for a keystore, you can refer to the Onboarding section of the Cloud Settings page to quickly see the lifetime that is configured for each type of token. Then make sure you specify enough keystores, with long enough lifetimes, to span each token’s lifetime. For example, if the temporary_token lives for 72 hours and the key used for signing it lives for 24 hours, you need to provide at least 3 sets of keys to span the token’s lifetime:

temporary_token: [keystore1, keystore2, keystore3]