From ad850260a00240782fb6bcac7286f4e5a7b96aae Mon Sep 17 00:00:00 2001 From: zachary painter <60552605+ZPain8464@users.noreply.github.com> Date: Tue, 30 Jul 2024 17:46:39 -0400 Subject: [PATCH] Updates secrets settings (#1535) * adds redirects and merges settings * moves shared secret, redirects * fixes breaking links * runs prettier * Update content/docs/reference/shared-secret.mdx Co-authored-by: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> * updates signign key settings * updates shared secret * fixes breaking links * runs prettier * incorporates feedback * runs prettier * revert some unnecessary changes Revert the addition of some #shared-secret anchor tags in links, the change to the sidebar label for the Signing Key page, and remove two unnecessary redirects. * Update content/docs/capabilities/getting-users-identity.md Co-authored-by: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> * updates 'share' to 'contain' * updates contain to exchange * updates wording --------- Co-authored-by: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> --- .../capabilities/getting-users-identity.md | 3 +- content/docs/reference/reference.json | 4 +- content/docs/reference/shared-secret-file.mdx | 79 ------------------- content/docs/reference/shared-secret.mdx | 34 ++++---- content/docs/reference/signing-key-file.mdx | 65 --------------- content/docs/reference/signing-key.mdx | 17 +++- content/docs/troubleshooting.mdx | 4 +- static/_redirects | 6 ++ 8 files changed, 43 insertions(+), 169 deletions(-) delete mode 100644 content/docs/reference/shared-secret-file.mdx delete mode 100644 content/docs/reference/signing-key-file.mdx diff --git a/content/docs/capabilities/getting-users-identity.md b/content/docs/capabilities/getting-users-identity.md index 3696e47c9..34f3463ef 100644 --- a/content/docs/capabilities/getting-users-identity.md +++ b/content/docs/capabilities/getting-users-identity.md @@ -98,7 +98,7 @@ curl https://your-app.corp.example.com/.well-known/pomerium/jwks.json | jq :::caution -In order to use the `/.well-known/pomerium/jwks.json` endpoint you must set either the [Signing Key] or [Signing Key File] configuration option. +In order to use the `/.well-known/pomerium/jwks.json` endpoint, you must set the [Signing Key] configuration option. ::: @@ -168,4 +168,3 @@ In an actual client, you'll want to ensure that all the other claims values are [nist p-256]: https://csrc.nist.gov/csrc/media/events/workshop-on-elliptic-curve-cryptography-standards/documents/papers/session6-adalier-mehmet.pdf [pass identity headers]: /docs/reference/routes/pass-identity-headers-per-route [signing key]: /docs/reference/signing-key -[signing key file]: /docs/reference/signing-key-file diff --git a/content/docs/reference/reference.json b/content/docs/reference/reference.json index 464c8e43c..5655f7e15 100644 --- a/content/docs/reference/reference.json +++ b/content/docs/reference/reference.json @@ -541,7 +541,7 @@ "shared-secret-file": { "id": "shared-secret-file", "title": "Shared Secret File", - "path": "/shared-secret-file", + "path": "/shared-secret", "description": "File path containing base64-encoded shared secret.", "services": [], "type": "string", @@ -1485,7 +1485,7 @@ "signing-key-file": { "id": "signing-key-file", "title": "Signing Key File", - "path": "/signing-key-file", + "path": "/signing-key", "description": "File path to a secret containing the signing key, 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.", "services": [], "type": "string", diff --git a/content/docs/reference/shared-secret-file.mdx b/content/docs/reference/shared-secret-file.mdx deleted file mode 100644 index 092eea803..000000000 --- a/content/docs/reference/shared-secret-file.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -id: shared-secret-file -title: Shared Secret File -description: | - Shared Secret is the base64 encoded 256-bit key used to mutually authenticate requests between services. -keywords: - - reference - - Shared Secret File -pagination_prev: null -pagination_next: null -toc_max_heading_level: 2 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Shared Secret File - -## Summary - -**Shared Secret File** is the location of a file containing the base64-encoded, 256-bit key used to mutually authenticate requests between services. It's critical that secret keys are random, and stored safely. - -## How to configure - - - - -| **Config file keys** | **Environment variables** | **Type** | **Usage** | -| :-- | :-- | :-- | :-- | -| `shared_secret_file` | `SHARED_SECRET_FILE` | `string` | **required** (unless using [shared_secret]) | - -:::tip - -Pomerium Core configurations do not require a `shared_secret` or `shared_secret_file`. You only need to include a shared secret if you are running the Console. - -If you are connecting to the Console, your Pomerium Core and Console configurations require the same shared secret. - -See the [**Enterprise Quickstart**](/docs/enterprise/quickstart) for an example implementation. - -::: - -### Examples - -`shared_secret_file` points to a file containing the secret. This is useful when deploying in environments that provide secret management like [Docker Swarm](https://docs.docker.com/engine/swarm/secrets/). - -To generate a key, run the following command: - -```shell -head -c32 /dev/urandom | base64 -``` - -Place the value in your `shared_secret_file`: - -```yaml -shared_secret_file: '/run/secrets/POMERIUM_SHARED_SECRET' -``` - -:::note - -If you adjust your shared secret and/or how it's accessed by Pomerium, you may create a [**secret mismatch**](/docs/troubleshooting#shared-secret-mismatch). - -::: - - - - -`shared_secret_file` is a bootstrap configuration setting and is not configurable in the Console. - - - - -| **Name** | -| :---------------------- | -| `secrets.shared_secret` | - -See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more information. - - - diff --git a/content/docs/reference/shared-secret.mdx b/content/docs/reference/shared-secret.mdx index da10073be..448796796 100644 --- a/content/docs/reference/shared-secret.mdx +++ b/content/docs/reference/shared-secret.mdx @@ -1,8 +1,7 @@ --- id: shared-secret title: Shared Secret -description: | - Shared Secret is the base64 encoded 256-bit key used to mutually authenticate requests between services. +description: This page discusses shared secret settings in Pomerium, which are used to mutually authenticate requests between Pomerium services. keywords: - reference - Shared Secret @@ -18,24 +17,29 @@ import TabItem from '@theme/TabItem'; ## Summary -**Shared Secret** is the base64-encoded, 256-bit key used to mutually authenticate requests between services. It's critical that secret keys are random, and stored safely. +**Shared Secret** is the base64-encoded, 256-bit key used to mutually authenticate requests between Pomerium services. It's critical that secret keys are random, and stored safely. + +:::note + +If you adjust your shared secret and/or how it's accessed by Pomerium, you may create a [**secret mismatch**](/docs/troubleshooting#shared-secret-mismatch). + +::: ## How to configure -| **Config file keys** | **Environment variables** | **Type** | **Usage** | -| :-- | :-- | :-- | :-- | -| `shared_secret` | `SHARED_SECRET` | `string` | **required** (unless using [shared_secret_file](/docs/reference/shared-secret-file)) | - -:::tip **Note** +| **Config file keys** | **Environment variables** | **Type** | **Usage** | +| :------------------- | :------------------------ | :------- | :----------- | +| `shared_secret` | `SHARED_SECRET` | `string` | **required** | +| `shared_secret_file` | `SHARED_SECRET_FILE` | `string` | **required** | -Pomerium Core configurations do not require a `shared_secret` or `shared_secret_file`. You only need to include a shared secret if you are running the Console. +:::enterprise Shared Secret in Enterprise Configurations -If you are connecting to the Console, your Pomerium Core and Console configurations require the same shared secret. +If you're connecting to the [Enterprise Console](/docs/enterprise), your Pomerium Core and Enterprise configurations each require the same shared secret. -See the [**Enterprise Quickstart**](/docs/enterprise/quickstart) for an example implementation. +See the [Enterprise Quickstart](/docs/enterprise/quickstart) for an example implementation. ::: @@ -54,7 +58,7 @@ shared_secret: wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs= ``` ```bash -SHARED_SECRET=wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs= +SHARED_SECRET_FILE='/run/secrets/POMERIUM_SHARED_SECRET' ``` @@ -65,9 +69,9 @@ SHARED_SECRET=wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs= -| **Name** | **Type** | **Usage** | -| :-- | :-- | :-- | -| `secrets.shared_secret` | `string` | **required** (unless using [shared_secret_file](/docs/reference/shared-secret-file)) | +| **Name** | **Type** | **Usage** | +| :---------------------- | :------- | :----------- | +| `secrets.shared_secret` | `string` | **required** | See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more information. diff --git a/content/docs/reference/signing-key-file.mdx b/content/docs/reference/signing-key-file.mdx deleted file mode 100644 index 5c648f05f..000000000 --- a/content/docs/reference/signing-key-file.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -id: signing-key-file -title: Signing Key File -description: | - File path to a secret containing the signing key. -keywords: - - reference - - Signing Key File -pagination_prev: null -pagination_next: null -toc_max_heading_level: 2 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Signing Key File - -## Summary - -**Signing Key File** is the path to a file containing a [Signing Key](./signing-key). - -The signing key is the private key used to sign a user's attestation JWT, which can be consumed by upstream applications to pass along identifying user session information such as username, id, and groups. - -See [Signing Key](./signing-key) for more information. - -## How to configure - - - - -| **Config file keys** | **Environment variables** | **Type** | **Usage** | -| :------------------- | :------------------------ | :------- | :----------- | -| `signing_key_file` | `SIGNING_KEY_FILE` | `string` | **optional** | - -### Examples - -Signing Key File is useful when deploying in environments that provide secret management like [Docker Swarm](https://docs.docker.com/engine/swarm/secrets/). - -For example: - -```yaml -signing_key_file: '/run/secrets/POMERIUM_SIGNING_KEY' -``` - -```bash -SIGNING_KEY_FILE='/run/secrets/POMERIUM_SIGNING_KEY' -``` - - - - -`signing_key_file` is a bootstrap configuration setting and is not configurable in the Console. - - - - -| **Name** | **Type** | **Usage** | -| :-------------------- | :------- | :----------- | -| `secrets.signing_key` | `string` | **optional** | - -See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more information. - - - diff --git a/content/docs/reference/signing-key.mdx b/content/docs/reference/signing-key.mdx index 64cff3876..c976ec280 100644 --- a/content/docs/reference/signing-key.mdx +++ b/content/docs/reference/signing-key.mdx @@ -4,7 +4,7 @@ id: signing-key title: Signing Key description: | - 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. If multiple keys are provided only the first will be used for signing. + This page discusses the signing key settings Pomerium uses to sign the Pomerium JWT that's sent to upstream services to verify a user's identity. keywords: - reference - Signing Key @@ -18,8 +18,6 @@ import TabItem from '@theme/TabItem'; # Signing Key -## Summary - **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. ## How to configure @@ -30,6 +28,7 @@ import TabItem from '@theme/TabItem'; | **Config file keys** | **Environment variables** | **Type** | **Usage** | | :------------------- | :------------------------ | :------- | :----------- | | `signing_key` | `SIGNING_KEY` | `string` | **optional** | +| `signing_key_file` | `SIGNING_KEY_FILE` | `string` | **optional** | @@ -48,6 +47,16 @@ See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more informatio +## Examples + +```yaml +signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUNUWHlVQ0phYmlHTW1wd3VqYlBmWHhNS2MzWjNFM0tEcmlEbmQwZktiTmtvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFM1FYQmZ1eEV1UEhJT0ZDb3RaaXBOMUFqM3UrOUtFRWd4RFVURW9CcjYxYXpaYWFvYlRGbwo0cGY3WFRSbzVhM2U2aDdKUW9wckp4QSszd0dwTUpSYWl3PT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo= +``` + +```bash +SIGNING_KEY_FILE='/run/secrets/POMERIUM_SIGNING_KEY' +``` + ### How to use signing key If set, the signing key's public key(s) can be retrieved by hitting Pomerium's well-known JWKS endpoint: @@ -95,7 +104,7 @@ If no certificate is specified, one will be generated and the base64'd public ke If multiple keys are provided, only the first will be used for signing. -## Key rotation +### Key rotation To implement key rotation, follow a 3-step process: diff --git a/content/docs/troubleshooting.mdx b/content/docs/troubleshooting.mdx index b6bb9fc4b..a841f964c 100644 --- a/content/docs/troubleshooting.mdx +++ b/content/docs/troubleshooting.mdx @@ -148,7 +148,7 @@ Events: ### Shared Secret Mismatch -Pomerium's independent services communicate securely using a [shared secret](/docs/reference/shared-secret). When services or the databroker have mismatched secrets, Pomerium will fail. +Pomerium's independent services communicate securely using a [shared secret](/docs/reference/shared-secret). If any services have mismatched secrets, Pomerium will fail. Pomerium Core will log a shared secret mismatch with: @@ -163,7 +163,7 @@ Pomerium Core will log a shared secret mismatch with: } ``` -And Pomerium Enterprise will log the error with: +Pomerium Enterprise will log a shared secret mismatch with: ```json { diff --git a/static/_redirects b/static/_redirects index c41a8dd9a..6ed681fea 100644 --- a/static/_redirects +++ b/static/_redirects @@ -461,6 +461,12 @@ https://0-20-0.docs.pomerium.com/category/guides https://0-20-0.docs.pomerium.co /docs/reference/x-forwarded-for-http-header /docs/reference/x-forwarded-for-settings#skip-xff-append /docs/reference/the-number-of-trusted-hops /docs/reference/x-forwarded-for-settings#xff-number-of-trusted-hops +# Signing Key +/docs/reference/signing-key-file /docs/reference/signing-key + +# Shared Secret +/docs/reference/shared-secret-file /docs/reference/shared-secret + # Topics links - now concepts /docs/topics/auth-logs /docs/capabilities/audit-logs /docs/topics/single-sign-out.html /docs/capabilities/single-sign-out