Keyring Operator HTTP API

The /operator/keyring endpoints manage encryption root keys used for storing variables and signing workload identities, including examining active encryption keys, rotating keys, or removing unused keys.

See the Key Management documentation for information how these capabilities are used. For instructions on how to use the CLI to perform these operations manually, please see the documentation for the nomad operator root keyring commands.

List Active Public Keys

This endpoint retrieves a list of active public keys used to sign workload identities. The response is in the JWKS format as is commonly used by JWT auth methods.

The table below shows this endpoint's support for blocking queries and required ACLs.

Sample Request

$ nomad operator api '/.well-known/jwks.json'

Sample Response

{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "15a95f48-001a-8be5-5da9-d94901d022c9",
      "alg": "RS256",
      "n": "6sImUQR6A...FB7bKn02dKw",
      "e": "AQAB"
    },
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "b7f6a3a7-14f9-4ac5-f713-32c9bce1fa93",
      "alg": "RS256",
      "n": "zEdiUB3DFuM...ii3kQvOf_eDApBDWJhfQw",
      "e": "AQAB"
    }
  ]
}

OIDC Discovery

This endpoint retrieves OIDC configuration metadata for using workload identities with third party services. Nomad will act as an identity provider (IDP) to allow third parties to authenticate workload identity JWTs based on the OIDC configurationa and JWKS.

Most third parties will require this endpoint be accessible through a publically resolvable domain name and HTTPS signed by a trusted certificate authority.

You must set the oidc_issuer Server agent configuration parameter before this endpoint is enabled. In most situations you will also need to run a proxy or load balancer for in front of this endpoint to serve the contents with HTTPS using a trusted certificate.

The table below shows this endpoint's support for blocking queries and required ACLs.

Sample Request

$ nomad operator api '/.well-known/openid-configuration'

Sample Response

{
  "id_token_signing_alg_values_supported": [
    "RS256",
    "EdDSA"
  ],
  "issuer": "http://example.com",
  "jwks_uri": "http://example.com/.well-known/jwks.json",
  "response_types_supported": [
    "code"
  ],
  "subject_types_supported": [
    "public"
  ]
}

List Keys

This endpoint retrieves a list of root keys known to the cluster. Note that only key metadata is returned and the key material is never made available via the HTTP API.

The table below shows this endpoint's support for blocking queries and required ACLs.

Sample Request

$ curl \
    https://localhost:4646/v1/operator/keyring/keys

Sample Response

[
  {
    "Algorithm": "aes256-gcm",
    "CreateIndex": 13,
    "CreateTime": 1662665630638648800,
    "KeyID": "26cbda57-e01e-188d-5f39-b6e3fca95a5b",
    "ModifyIndex": 13,
    "State": "active"
  },
  {
    "Algorithm": "aes256-gcm",
    "CreateIndex": 6,
    "CreateTime": 1662665528857979100,
    "KeyID": "64b96f4b-f167-f2dd-9148-7867f7e420e3",
    "ModifyIndex": 12,
    "State": "inactive"
  },
  {
    "Algorithm": "aes256-gcm",
    "CreateIndex": 12,
    "CreateTime": 1662665624108063000,
    "KeyID": "f9725e52-9b49-5b55-a8eb-083e23db4a3e",
    "ModifyIndex": 13,
    "State": "inactive"
  }
]

Rotate Key

This endpoint forces the server to rotate the active root key.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• full (bool: false) - Decrypt all existing variables and re-encrypt with the new key. This API request will immediately return and the re-encryption process will run asynchronously on the leader.

Sample Request

$ curl \
    -XPUT \
    https://localhost:4646/v1/operator/keyring/rotate

Sample Response

{
  "Index": 13,
  "Key": {
    "Algorithm": "aes256-gcm",
    "CreateIndex": 0,
    "CreateTime": 1662665630638648800,
    "KeyID": "26cbda57-e01e-188d-5f39-b6e3fca95a5b",
    "ModifyIndex": 0,
    "State": "active"
  }
}

Delete Key

This endpoint deletes a root key in the inactive state.

The table below shows this endpoint's support for blocking queries and required ACLs.

Sample Request

$ curl \
    -XDELETE \
    https://localhost:4646/v1/operator/keyring/key/68237d9-1770-4d34-9c41-1f220107fc10

Sample Response

{
  "Index": 16
}