RSA Authentication Workflow

This pages describes the implementation of RSA Authentication. For the API reference of RSA Session Authenticate and Key Manager Authenticate, see the following API endpoints:

Summary

The Authentication process requires the following steps:

  1. The user creates a public/private RSA key pair.

  2. The admin imports the public key into the pod using the Admin Console or public APIs.

  3. The user creates a short-lived JWT (JSON Web Token) and signs it with their private key.

  4. The bot makes a call the the authentication endpoints. Here, the server checks the signature of the JWT against the public key and returns an authentication token.

Session Token Management

Supported Ciphers for the SSL/TLS session

1. Create an RSA Key Pair

The public/private key pair for signing authentication requests requires the following:

Note: This script requires the openssl package.

Generate the PKCS#1 keys manually using the following commands:

Generate the PKCS#8 keys manually using the following commands. You can provide the Service Account's username as the Common Name (CN) but it is not a mandatory requirement.

Sign the authentication request using either privatekey.pkcs8 or privatekey.pem, depending on the support available in the JWT library.

The file publickey.pem is the public key. This is the key you will import into the pod in step 2.

2. Import Public Key into the Pod

Navigate to the Admin Console and create a new Service Account. Copy the contents of the pubkey.pem file you just created and paste into the textbox under the Authentication section:

Add your bot's basic information:

If successful, you should see the following:

3. Generate a signed JWT Token

To authenticate on the Pod and the Key Manager, the bot must call the authentication endpoints, passing a short-lived JWT token in the body of the request. The JWT token must contain the following:

  • a subject matching the username of the user to authenticate

  • an expiration time of no more than 5 minutes from the current timestamp (needed to prevent replay attacks)

  • a signature by a private RSA key matching a public key stored for the user in the Pod

The following script generates the authentication request:

The output of the script is a JWT:

The authentication token can be inspected on https://jwt.io/ or https://www.jsonwebtoken.io/.

4. Authenticate

Obtain a valid Session Token by making a POST request to your company's Session Auth endpoint:

A successful response:

Obtain a valid Key Manager Token by making a POST request to your company's Key Manager Auth endpoint:

A successful response:

Replace/Revoke Key

You can replace the public key pubkeyA for a user with a new key, pubkeyB (for example, as part of an organization's key rotation schedule). Note the following outcomes:

  • When a key is replaced, the key pubkeyA becomes the user's previous key, and the newly uploaded pubkeyB becomes the current key.

  • The previous key is valid for 72 hours, but you can extend that period indefinitely in intervals of 72 hours.

  • While the previous key is valid, both keys can be used for authentication. When it expires, it can no longer be used to authenticate the user.

  • A user can have at most one previous key.

Alternatively, you can revoke a user key (current or previous), for example, if the key is compromised. Note the following outcomes:

  • When a key is revoked, it can no longer be used for authentication.

  • If a user has a non-expired previous key and their current key is revoked, the previous key becomes the new current key.

  • When a key is revoked, the user's sessions initiated with RSA authentication are invalidated.

To replace/revoke a key, navigate to the Bot's account in the admin portal > RSA > Replace or Revoke:

You can also use the following REST API call to programmatically replace a public key:

Additionally you can programmatically revoke a public key using either currentKey or previousKey. Use the following REST request to programmatically revoke a public key using currentKey:

Use the following REST request to programmatically revoke a public key using previousKey:

Extending a Public Key

Use the following REST request to programmatically extend a public key:

Restricted Key Operations:

Last updated

Was this helpful?