JSON Web Key Sets

A JSON Web Key Set (JWKS) is a set of keys that contain amongst other things the keys needed to verify JSON Web Tokens (JWT). These JWTs are issued by the authorization server and signed within ReachFive using either the HS256 or RS256 signing algorithms.

This page focuses on JWK Sets and how to manage them via the ReachFive Console and API. For details on decoding tokens, see the Decode tokens page.

We at ReachFive support two different algorithms that sign JSON Web Tokens:

Algorithm Description

RS256

Generates asymmetric signatures, meaning a private key is used to sign the JSON Web Token and a public key is used to verify the signature.

HS256

Uses the client secret to cipher and decipher the JWT.

For the rest of this guide, we will focus only on the RS256 algorithm.

JSON Web Key (JWK): A JSON object that represents a cryptographic key.

JSON Web Key Set (JWKS): A JSON object that represents a set of JWKs. Note this must have a keys member - an array of JWKs.


RFC7517

A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC7159] data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs.

See RFC7517 for more details.

Global vs Client JWKS

When signing JSON Web Tokens using the RS256 algorithm, you have two different approaches currently available to you for managing these JWK Sets:

  • Global RSA Public Key: This means that the global RSA private key is used to cipher tokens while the public key is used to decipher tokens, for all clients in your account. This means that your clients will cipher tokens the same way.

  • Client-specific RSA Public Keys: This approach applies a unique key pair (public/private) to each of the clients in your account. This means your clients will cipher tokens differently.

Here, we will discuss the advantages of using a client-specific approach when handling JWK Sets.

Client-specific RSA Public Keys

Unlike using an account-based RSA Public Key, a client-specific approach offers a more secure way of issuing tokens. It is more secure because a given client is independent of other clients within your account and can’t decipher the token issued by another client.

Manage JWK Sets from console

You can manage your JSON Web Keys from the ReachFive Console.

These instructions are only applicable if you are using the RS256 algorithm.

Prerequisites

  • You must have access to the ReachFive Console.

  • You must have a Developer, Manager, or Administrator role.

  • You must have an existing client or you should create a new client.

Instructions

  1. Go to Settings  Clients.

  2. Select an existing client or create a New client.

  3. Scroll down until you see JWT Algorithm.

  4. Choose RS256 from the dropdown menu.

  5. Generate a client-specific key pair or sync the client to the global RSA key pair.

    • Client-specific

    • Global

    1. Click the Rotate button.

    2. Confirm you want to rotate the RSA key pair.

    The RSA key pair for this client is now independent of the account-based (global) RSA key pair.

    1. Click the Account sync. button.

    2. Confirm you want to synchronize the client RSA key pair with the account-based (global) pair.

    The RSA key pair for this client is now synced with the account-based (global) RSA key pair.

You can see your JSON Web Key Sets using the /jwks.json endpoint from your console. Example: <account>.reach5.net/jwks.json. See the parameters below for more information on the sets.

Manage JSON Web Keys with API

You can manage JSON Web Keys from the ReachFive Management API. Use the following operations to sync, revoke, rotate, and retrieve JWK from the set.

Endpoint Notes

POST /api/v1/site/keys

Generates (rotates) a new account-based (global) RSA key pair.

GET /jwks.json

Retrieves all JWK sets for an account.

POST /api/v1/clients/:clientId/keys

Generates (rotates) a new RSA key pair for the specified client in the operation.

PUT /api/v1/clients/:clientId/keys

Synchronizes the client-specific RSA key pair back with the account-based (global) RSA key pair.

DELETE /api/v1/clients/:clientId/jwks/:kid

Revokes a JSON Web Key for the specific client and key.

JWK Set parameters

JSON Web Tokens (JWT) use digital signatures to verify the authenticity of data they contain.

Check out the JWT website for a thorough introduction to JSON Web Tokens.

The JSON Web Key and JSON Web Key Sets sign and encrypt these tokens. When using the ReachFive Console endpoint (/jwks.json) or the ReachFive Identity API, you can see the array of keys (JSON Web Key Set).

JWK Set example

{
    "keys": [
        {
        "kty": "RSA",
        "e": "AQAB",
        "x5t": "NjU3NDI5ZTZhODU0YjQzMGFiYzkwNGNkZDkwNmZkMzZmOWEzNWVmMQ",
        "use": "sig",
        "kid": "e600c72b-125a-4b30-86a5-9697af62f2a1",
        "x5c": [
            "MIICujCCAaKgAwIBAgIECI8fsTANBgkqhkiG9w0BAQsFADAfMR0wGwYDVQQDExR0ZXN0LWFsZXgucmVhY2g1Lm5ldDAeFw0yMDA3MjkwOTM0MjlaFw0yMjAyMTcxNDIwMzNaMB8xHTAbBgNVBAMTFHRlc3QtYWxleC5yZWFjaDUubmV0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlzRszUeQ4WiSqvmYxMP10ngm8ALIoUwMH7Oa8vrZgD5pqalPjetPAxeVcAv2gTyDlOwtB0fGvlQo6n78pd9pTbgrzUjhmFuYN6OCfT6eN/2wu0LmwryFS2mbh7/1DTiKd2tZaRalskPECXTKkeks85HVqanB0860BYlGvQvfgrvhCWXXFJJeXvNwYNFYdDdrFQhoeOAEvRDKg9DdHZf6XzSR6Qk3w51FKn2b7imen/G52itD/kIen1hqqB2Jwt9SWyX5MSGySY2QwC18F6Dfs8L+t0mwCo6grGW9264Z5vlO0PWssEqGIX/ez6nk1ZdHXhoXwJ0W+6QzeQlUN8jNoQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQAETbMWro4HI4ZuqtnjMZrgEOpx6WhAtxpMx5XFPVWbdp/DpPySotoWbbD6qCtYc34E+ec7mH7aHVap+Gl2IyeSHTht4FXfF9q/1Oj/fis/4DDi1iq00rJsU18D71mZ9FGWCWlO1nhW1KSTGbRJ3E0wSrNabcvaXcwEHokR3zm+xfRWjtbrq2hQ19R16xyOLVy4zrF95QxP4UN+Cvm8nmYur6bSqv+gCMvDsl+O/gtRHGgpUukHEJwnee1R3+1aIv+9zOF3HaaUC5neOLBFITGmeXgi8G2IhbG+JoXh/GUkb66TZUlUAM3qXYNL9Nf+2MQ7nAPTXcxlmImFUUrnv0c3"
            ],
        "alg": "RS256",
        "n": "lzRszUeQ4WiSqvmYxMP10ngm8ALIoUwMH7Oa8vrZgD5pqalPjetPAxeVcAv2gTyDlOwtB0fGvlQo6n78pd9pTbgrzUjhmFuYN6OCfT6eN_2wu0LmwryFS2mbh7_1DTiKd2tZaRalskPECXTKkeks85HVqanB0860BYlGvQvfgrvhCWXXFJJeXvNwYNFYdDdrFQhoeOAEvRDKg9DdHZf6XzSR6Qk3w51FKn2b7imen_G52itD_kIen1hqqB2Jwt9SWyX5MSGySY2QwC18F6Dfs8L-t0mwCo6grGW9264Z5vlO0PWssEqGIX_ez6nk1ZdHXhoXwJ0W-6QzeQlUN8jNoQ"
        },
        …​
    ]
}

JWK Set parameter definitions

Parameter Description

kty

Identifies the cryptographic algorithm family used with the key.

possible values

  • RSA

e

The public RSA key value used for RSA Key blinding operations.

x5t

a base64url-encoded SHA-1 thumbprint of the DER encoding of an X.509 certificate RFC5280

use

Identifies the intended use of the public key

possible values

  • sig = signature

  • enc = encryption

kid

The key identifier.

This is a case-sensitive string.

x5c

Specifies a chain of PKIX certificates.

alg

Identifies the algorithm intended for use with the key. For example: RSA256.

n

The modulus RSA key value used for RSA Key blinding operations.