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 <[email protected]>

* 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 <[email protected]>

* updates 'share' to 'contain'

* updates contain to exchange

* updates wording

---------

Co-authored-by: Kenneth Jenkins <[email protected]>

Author: 2 people

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

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",

content/docs/reference/shared-secret-file.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
 
 <Tabs>
 <TabItem value="Core" label="Core">
 
-| **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'
 ```
 
 </TabItem>
@@ -65,9 +69,9 @@ SHARED_SECRET=wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs=
 </TabItem>
 <TabItem value="Kubernetes" label="Kubernetes">
 
-| **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.
 

content/docs/reference/shared-secret.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** |
 
 </TabItem>
 <TabItem value="Enterprise" label="Enterprise">
@@ -48,6 +47,16 @@ See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more informatio
 </TabItem>
 </Tabs>
 
+## 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:
 

content/docs/reference/signing-key-file.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
 {

content/docs/reference/signing-key.mdx

@@ -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