mirror of
https://github.com/kemko/nomad.git
synced 2026-01-01 16:05:42 +03:00
0906f788f0
Adds an additional check in the Keyring.Delete RPC to make sure we're not trying to delete a key that's been used to encrypt a variable. It also adds a -force flag for the CLI/API to sidestep that check.
267 lines
6.8 KiB
Plaintext
267 lines
6.8 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Keyring - Operator - HTTP API
|
|
description: |-
|
|
The /operator/keyring endpoints provide tools for Nomad operators to interact with the root keyring.
|
|
---
|
|
|
|
# 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][wi]. The response is in the [JWKS][rfc7517] format as is commonly
|
|
used by JWT auth methods.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|-----------------------------|--------------------|
|
|
| `GET` | `/.well-known/jwks.json` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|--------------|
|
|
| `YES` | `none` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ nomad operator api '/.well-known/jwks.json'
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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][oidc-disco] for using
|
|
[workload identities][wi] 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`][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.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|-------------------------------------|--------------------|
|
|
| `GET` | `/.well-known/openid-configuration` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|--------------|
|
|
| `NO` | `none` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ nomad operator api '/.well-known/openid-configuration'
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|-----------------------------|--------------------|
|
|
| `GET` | `/v1/operator/keyring/keys` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|--------------|
|
|
| `YES` | `management` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/operator/keyring/keys
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|-------------------------------|--------------------|
|
|
| `PUT` | `/v1/operator/keyring/rotate` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|--------------|
|
|
| `NO` | `management` |
|
|
|
|
|
|
### 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
|
|
|
|
```shell-session
|
|
$ curl \
|
|
-XPUT \
|
|
https://localhost:4646/v1/operator/keyring/rotate
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
| Method | Path | Produces |
|
|
|----------|------------------------------------|--------------------|
|
|
| `DELETE` | `/v1/operator/keyring/key/:key_id` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|--------------|
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `force` `(bool: false)` - Remove the key even if it was used to sign an existing variable
|
|
or workload identity.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
-XDELETE \
|
|
https://localhost:4646/v1/operator/keyring/key/68237d9-1770-4d34-9c41-1f220107fc10
|
|
```
|
|
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 16
|
|
}
|
|
```
|
|
|
|
|
|
[Key Management]: /nomad/docs/operations/key-management
|
|
[`nomad operator root keyring`]: /nomad/docs/commands/operator/root/keyring-rotate
|
|
[blocking queries]: /nomad/api-docs#blocking-queries
|
|
[oidc-disco]: https://openid.net/specs/openid-connect-discovery-1_0.html
|
|
[oidc_issuer]: /nomad/docs/configuration/server#oidc_issuer
|
|
[required ACLs]: /nomad/api-docs#acls
|
|
[rfc7517]: https://datatracker.ietf.org/doc/html/rfc7517
|
|
[wi]: /nomad/docs/concepts/workload-identity
|