Updates secrets settings

content/docs/reference/reference.json

@@ -532,7 +532,7 @@
   "shared-secret": {
     "id": "shared-secret",
     "title": "Shared Secret",
-    "path": "/shared-secret",
+    "path": "/shared-secret-settings#shared-secret",
     "description": "Shared Secret is the base64-encoded, 256-bit key used to mutually authenticate requests between services.",
     "services": [],
     "type": "string",
@@ -541,7 +541,7 @@
   "shared-secret-file": {
     "id": "shared-secret-file",
     "title": "Shared Secret File",
-    "path": "/shared-secret-file",
+    "path": "/shared-secret-settings#shared-secret-file",
     "description": "File path containing base64-encoded shared secret.",
     "services": [],
     "type": "string",
@@ -1476,7 +1476,7 @@
   "signing-key": {
     "id": "signing-key",
     "title": "Signing Key",
-    "path": "/signing-key",
+    "path": "/signing-key-settings#signing-key",
     "description": "Signing Key is the 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",
@@ -1485,7 +1485,7 @@
   "signing-key-file": {
     "id": "signing-key-file",
     "title": "Signing Key File",
-    "path": "/signing-key-file",
+    "path": "/signing-key-settings#signing-key-file",
     "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.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.
+id: shared-secret-settings
+title: Shared Secret Settings
+description: This page discusses shared secret settings in Pomerium, which are used to mutually authenticate requests between Pomerium services.
 keywords:
   - reference
   - Shared Secret
@@ -14,33 +13,39 @@ toc_max_heading_level: 2
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Shared Secret
+# Shared Secret Settings
 
-## Summary
+## Shared Secret
 
-**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.
 
-## How to configure
+### 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)) |
+| `shared_secret` | `SHARED_SECRET` | `string` | \***optional** |
 
-:::tip **Note**
+\* Standalone Pomerium Core configurations do not require a `shared_secret` or `shared_secret_file`. If you don't set a shared secret, Pomerium will generate one for you.
 
-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.
 
 :::
 
 ### Examples
 
+:::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).
+
+:::
+
 To generate a key, run the following command:
 
 ```shell
@@ -67,7 +72,69 @@ SHARED_SECRET=wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs=
 
 | **Name** | **Type** | **Usage** |
 | :-- | :-- | :-- |
-| `secrets.shared_secret` | `string` | **required** (unless using [shared_secret_file](/docs/reference/shared-secret-file)) |
+| `secrets.shared_secret` | `string` | **required** |
+
+See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more information.
+
+</TabItem>
+</Tabs>
+
+## Shared Secret File
+
+**Shared Secret File** is the location of a file containing 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.
+
+### How to configure
+
+<Tabs>
+<TabItem value="Core" label="Core">
+
+| **Config file keys** | **Environment variables** | **Type** | **Usage** |
+| :-- | :-- | :-- | :-- |
+| `shared_secret_file` | `SHARED_SECRET_FILE` | `string` | \***optional** |
+
+\* Standalone Pomerium Core configurations do not require a `shared_secret` or `shared_secret_file`. If you don't set a shared secret, Pomerium will generate one for you.
+
+:::enterprise Shared Secret in Enterprise Configurations
+
+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.
+
+:::
+
+### Examples
+
+:::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` 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'
+```
+
+</TabItem>
+<TabItem value="Enterprise" label="Enterprise">
+
+`shared_secret_file` is a bootstrap configuration setting and is not configurable in the Console.
+
+</TabItem>
+<TabItem value="Kubernetes" label="Kubernetes">
+
+| **Name** | **Type** | **Usage** |
+| :-- | :-- | :-- |
+| `secrets.shared_secret` | `string` | **required** |
 
 See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more information.