From f8a65b6c29ad0c725820c652fc84f219809a3e67 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Tue, 31 Oct 2023 13:06:08 -0700 Subject: [PATCH] docs: changelog & basic docs for 1.7 WI changes (#18936) Changelog entries and bare minimum docs for workload identity changes in 1.7. --- .changelog/18035.txt | 3 + .changelog/18123.txt | 3 + .changelog/18262.txt | 3 + .changelog/18691.txt | 3 + .changelog/18882.txt | 3 + website/content/api-docs/operator/keyring.mdx | 104 ++++++++++++++++++ 6 files changed, 119 insertions(+) create mode 100644 .changelog/18035.txt create mode 100644 .changelog/18123.txt create mode 100644 .changelog/18262.txt create mode 100644 .changelog/18691.txt create mode 100644 .changelog/18882.txt diff --git a/.changelog/18035.txt b/.changelog/18035.txt new file mode 100644 index 00000000000..733a6cc498c --- /dev/null +++ b/.changelog/18035.txt @@ -0,0 +1,3 @@ +```release-note:improvement +api: Add JWKS HTTP API endpoint +``` diff --git a/.changelog/18123.txt b/.changelog/18123.txt new file mode 100644 index 00000000000..6ee3acdf86f --- /dev/null +++ b/.changelog/18123.txt @@ -0,0 +1,3 @@ +```release-note:improvement +identity: Add support for multiple workload identities +``` diff --git a/.changelog/18262.txt b/.changelog/18262.txt new file mode 100644 index 00000000000..d4c9f8532e6 --- /dev/null +++ b/.changelog/18262.txt @@ -0,0 +1,3 @@ +```release-note:improvement +identity: Support jwt expiration and rotation +``` diff --git a/.changelog/18691.txt b/.changelog/18691.txt new file mode 100644 index 00000000000..3b11ab0cb3d --- /dev/null +++ b/.changelog/18691.txt @@ -0,0 +1,3 @@ +```release-note:feature +**Workload Identity IDP:** Nomad's workload identities may now be used with third parties that support JWT or OIDC IDPs such as the AWS IAM OIDC Provider. +``` diff --git a/.changelog/18882.txt b/.changelog/18882.txt new file mode 100644 index 00000000000..f3c4d08929f --- /dev/null +++ b/.changelog/18882.txt @@ -0,0 +1,3 @@ +```release-note:improvement +identity: default to RS256 for new workload ids +``` diff --git a/website/content/api-docs/operator/keyring.mdx b/website/content/api-docs/operator/keyring.mdx index ad4975c1213..7080d4828e4 100644 --- a/website/content/api-docs/operator/keyring.mdx +++ b/website/content/api-docs/operator/keyring.mdx @@ -16,6 +16,106 @@ 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 @@ -154,4 +254,8 @@ $ curl \ [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