Signing Key

Signing Key is one or more PEM-encoded private keys used to sign a user's attestation JWT, which can be consumed by upstream applications to pass along identifying user information like username, ID, and groups. See Continuous Identity Verification for more information on this topic.

If the signing key is not configured explicitly, a signing key will be derived from the shared secret.

How to configure

Core

Config file keys	Environment variables	Type	Usage
signing_key	SIGNING_KEY	string	optional
signing_key_file	SIGNING_KEY_FILE	string	optional

Examples

signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUNUWHlVQ0phYmlHTW1wd3VqYlBmWHhNS2MzWjNFM0tEcmlEbmQwZktiTmtvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFM1FYQmZ1eEV1UEhJT0ZDb3RaaXBOMUFqM3UrOUtFRWd4RFVURW9CcjYxYXpaYWFvYlRGbwo0cGY3WFRSbzVhM2U2aDdKUW9wckp4QSszd0dwTUpSYWl3PT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=

SIGNING_KEY_FILE='/run/secrets/POMERIUM_SIGNING_KEY'

Enterprise

signing_key is a bootstrap configuration setting and is not configurable in the Console.

Kubernetes

Name	Type	Usage
secrets.signing_key	string	optional

See Kubernetes bootstrap secrets for more information.

JWKS endpoint

An upstream application can retrieve the corresponding public key(s) from Pomerium's JWKS endpoint:

/.well-known/pomerium/jwks.json

This allows the application to verify the integrity of the Pomerium JWT.

For example, assuming you have generated an ES256 key with the following commands:

# Generates an P-256 (ES256) signing key
openssl ecparam  -genkey  -name prime256v1  -noout  -out ec_private.pem
# careful! this will output your private key in terminal
cat ec_private.pem | base64

You can verify that the public key is available from Pomerium's JWKS endpoint:

curl https://route.int.example.com/.well-known/pomerium/jwks.json | jq

{
  "keys": [
    {
      "use": "sig",
      "kty": "EC",
      "kid": "ccc5bc9d835ff3c8f7075ed4a7510159cf440fd7bf7b517b5caeb1fa419ee6a1",
      "crv": "P-256",
      "alg": "ES256",
      "x": "QCN7adG2AmIK3UdHJvVJkldsUc6XeBRz83Z4rXX8Va4",
      "y": "PI95b-ary66nrvA55TpaiWADq8b3O1CYIbvjqIHpXCY"
    }
  ]
}

If multiple keys are supplied in the PEM data, the first one will be used for signing, but all of them will be published to the JWKS endpoint. This allows for key rotation.

Key rotation

To implement key rotation, follow a 3-step process:

1. Generate a new key and add it to the existing PEM data.
2. Swap the order of the keys in the PEM data so that the new key is first and will be used for all subsequent signing.
3. Remove the old key from the list.

With sufficient time between the steps, this process should be resilient to caching of the JWKS endpoint by applications.