moves shared secret, redirects

Author: ZPain8464

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

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.
+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.
 

content/docs/reference/shared-secret.mdx

@@ -96,7 +96,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.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). When Pomerium services share a mismatched secret, or these services share a secret that is not the same secret set in the Databroker service, 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/troubleshooting.mdx

@@ -466,6 +466,10 @@ https://0-20-0.docs.pomerium.com/category/guides https://0-20-0.docs.pomerium.co
 /docs/reference/signing-key /docs/reference/signing-key-settings#signing-key
 /docs/reference/signing-key-file /docs/reference/signing-key-settings#signing-key-file
 
+# Shared Secret settings
+/docs/reference/shared-secret /docs/reference/shared-secret-settings#shared-secret
+/docs/reference/shared-secret-file /docs/reference/shared-secret-settings#shared-secret-file
+
 # Topics links - now concepts
 /docs/topics/auth-logs /docs/capabilities/audit-logs
 /docs/topics/single-sign-out.html /docs/capabilities/single-sign-out