Updates secrets settings

content/docs/capabilities/getting-users-identity.md

@@ -167,5 +167,5 @@ In an actual client, you'll want to ensure that all the other claims values are
 [key management service]: https://en.wikipedia.org/wiki/Key_management
 [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
+[signing key]: /docs/reference/signing-key-settings#signing-key
+[signing key file]: /docs/reference/signing-key-settings#signing-key-file

content/docs/core/quickstart.md

@@ -71,7 +71,7 @@ Although identity verification failed, you successfully integrated Pomerium with
 
 :::tip
 
-Because this guide doesn't include a [signing key](/docs/reference/signing-key) in the configuration, identity verification will fail.
+Because this guide doesn't include a [signing key](/docs/reference/signing-key-settings#signing-key) in the configuration, identity verification will fail.
 
 See [Identity Verification](/docs/capabilities/getting-users-identity) for more information on how Pomerium can use JWTs for authentication.
 

content/docs/courses/fundamentals/jwt-verification.md

@@ -97,7 +97,7 @@ If that’s a lot to take in, don’t worry, Pomerium handles a lot of it for yo
 There are two settings that you need to configure to implement identity verification with signed headers:
 
 - [Pass Identity Headers](/docs/reference/routes/pass-identity-headers-per-route)
-- [Signing Key](/docs/reference/signing-key)
+- [Signing Key](/docs/reference/signing-key-settings#signing-key)
 
 :::info **Global and Route Settings**
 

content/docs/enterprise/changelog.mdx

@@ -292,7 +292,7 @@ Added support for the Rego [**`print()`**](https://www.openpolicyagent.org/docs/
 - Impersonation - Impersonation is now done on an individual session basis.
 - Various other bug fixes and improvements.
 
-[`signing key`]: /docs/reference/signing-key
+[`signing key`]: /docs/reference/signing-key-settings#signing-key
 [google cloud serverless]: /docs/reference/routes/enable-google-cloud-serverless-authentication
 [policy language]: /docs/capabilities/ppl
 [runtime]: /docs/capabilities/reports.md#runtime

content/docs/enterprise/upgrading.mdx

@@ -140,7 +140,7 @@ Pomerium Core would only perform user authentication and session refresh with th
 
 ### Before You Upgrade
 
-- The [`signing-key`](/docs/reference/signing-key) has been replaced with [`authenticate-service-url`](/docs/reference/authenticate-service-url). Instead of manually setting the signing key in the Enterprise Console to match the Authenticate Service, we specify the trusted URL of the Authenticate Service to pull the signing key from.
+- The [`signing-key`](/docs/reference/signing-key-settings#signing-key) has been replaced with [`authenticate-service-url`](/docs/reference/authenticate-service-url). Instead of manually setting the signing key in the Enterprise Console to match the Authenticate Service, we specify the trusted URL of the Authenticate Service to pull the signing key from.
 
   The `signing-key` key will continue to work for existing configurations, but [device enrollment](/docs/capabilities/device-identity#new-enrollment-enterprise) will not work until it is replaced by `authenticate-service-url`.
 
@@ -151,7 +151,7 @@ Pomerium Core would only perform user authentication and session refresh with th
 - `signing-key` is now a required option to improve request security from Pomerium Core. The value should match the one set in Pomerium Core. See the [signing key] reference page for more information on generating a key.
 - `audience` is now a required option to improve request security from Pomerium Core. The value should match the Enterprise Console's external URL hostname, as defined in the [`from`](/docs/reference/routes) field in the Routes entry (not including the protocol).
 
-[signing key]: /docs/reference/signing-key
+[signing key]: /docs/reference/signing-key-settings#signing-key
 
 ### Helm Installations
 

content/docs/guides/tooljet.mdx

@@ -49,7 +49,7 @@ Next, you need to:
 - Replace [email protected] with the email associated with your IdP
 - Generate a signing key
 
-To generate a [signing key](/docs/reference/signing-key), use the commands below:
+To generate a [signing key](/docs/reference/signing-key-settings#signing-key), use the commands below:
 
 ```bash
 # Generates a P-256 (ES256) signing key
@@ -133,7 +133,7 @@ Next, you need to:
 - Replace [email protected] with the email associated with your IdP
 - Generate a signing key
 
-To generate a [signing key](/docs/reference/signing-key), use the commands below:
+To generate a [signing key](/docs/reference/signing-key-settings#signing-key), use the commands below:
 
 ```bash
 # Generates a P-256 (ES256) signing key

content/docs/identity-providers/oidc.mdx

@@ -179,7 +179,7 @@ Note the following points:
 
 :::caution
 
-Do not use the **signing key** in the example above in a production environment. See [**Signing Keys**](/docs/reference/signing-key) for more information on generating and using signing keys.
+Do not use the **signing key** in the example above in a production environment. See [**Signing Keys**](/docs/reference/signing-key-settings#signing-key) for more information on generating and using signing keys.
 
 :::
 

content/docs/internals/data-storage.md

@@ -94,4 +94,4 @@ Configuration options for each backend are detailed in the [**databroker configu
 
 ## Troubleshooting
 
-Most issues with the Databroker service are caused by a [`shared_secret`](/docs/reference/shared-secret) mismatch between services. See [Troubleshooting - Shared Secret Mismatch](/docs/reference/shared-secret) for details.
+Most issues with the Databroker service are caused by a [`shared_secret`](/docs/reference/shared-secret-settings#shared-secret) mismatch between services. See [Troubleshooting - Shared Secret Mismatch](/docs/reference/shared-secret-settings#shared-secret) for details.

content/docs/k8s/reference.md

@@ -216,7 +216,7 @@ PomeriumSpec defines Pomerium-specific configuration parameters.
                 </p>
                 <p>
                     <strong>Required.</strong>&#160;
-                    Secrets references a Secret with Pomerium bootstrap parameters. <p> <ul> <li><a href="https://pomerium.com/docs/reference/shared-secret"><code>shared_secret</code></a> - secures inter-Pomerium service communications. </li> <li><a href="https://pomerium.com/docs/reference/cookie-secret"><code>cookie_secret</code></a> - encrypts Pomerium session browser cookie. See also other <a href="#cookie">Cookie</a> parameters. </li> <li><a href="https://pomerium.com/docs/reference/signing-key"><code>signing_key</code></a> signs Pomerium JWT assertion header. See <a href="https://www.pomerium.com/docs/topics/getting-users-identity">Getting the user's identity</a> guide. </li> </ul> </p> <p> In a default Pomerium installation manifest, they would be generated via a <a href="https://github.com/pomerium/ingress-controller/blob/main/config/gen_secrets/job.yaml">one-time job</a> and stored in a <code>pomerium/bootstrap</code> Secret. You may re-run the job to rotate the secrets, or update the Secret values manually. </p>
+                    Secrets references a Secret with Pomerium bootstrap parameters. <p> <ul> <li><a href="https://pomerium.com/docs/reference/shared-secret-settings#shared-secret"><code>shared_secret</code></a> - secures inter-Pomerium service communications. </li> <li><a href="https://pomerium.com/docs/reference/cookie-secret"><code>cookie_secret</code></a> - encrypts Pomerium session browser cookie. See also other <a href="#cookie">Cookie</a> parameters. </li> <li><a href="https://pomerium.com/docs/reference/signing-key-settings#signing-key"><code>signing_key</code></a> signs Pomerium JWT assertion header. See <a href="https://www.pomerium.com/docs/topics/getting-users-identity">Getting the user's identity</a> guide. </li> </ul> </p> <p> In a default Pomerium installation manifest, they would be generated via a <a href="https://github.com/pomerium/ingress-controller/blob/main/config/gen_secrets/job.yaml">one-time job</a> and stored in a <code>pomerium/bootstrap</code> Secret. You may re-run the job to rotate the secrets, or update the Secret values manually. </p>
                 </p>
 
                     Format: reference to Kubernetes resource with namespace prefix: <code>namespace/name</code> format.

content/docs/reference/downstream-mtls-settings.mdx

@@ -168,7 +168,7 @@ The Ingress Controller does not support these settings.
 
    This matches the default behavior of many popular reverse proxies, such as Apache httpd and Caddy.
 
-   Note that in this mode, client certificates will be required even for internal Pomerium routes, such as the authenticate URL (if using the self-hosted authenticate service) and the /.pomerium/ page (the page showing details of a user's current login session). In particular, any upstream services that perform [JWT verification](/docs/capabilities/getting-users-identity) will not be able to access the default [JWKS endpoint](/docs/reference/signing-key#how-to-use-signing-key). You may need to host your own JWKS endpoint, or provide some other means of distributing the JWT verification key(s).
+   Note that in this mode, client certificates will be required even for internal Pomerium routes, such as the authenticate URL (if using the self-hosted authenticate service) and the /.pomerium/ page (the page showing details of a user's current login session). In particular, any upstream services that perform [JWT verification](/docs/capabilities/getting-users-identity) will not be able to access the default [JWKS endpoint](/docs/reference/signing-key-settings#signing-key#how-to-use-signing-key). You may need to host your own JWKS endpoint, or provide some other means of distributing the JWT verification key(s).
 
    This mode also adds a requirement that any configured [**CRL**](#crl) is valid only between its `thisUpdate` and `nextUpdate` timestamps. _If an invalid CRL is provided for a certain CA, no certificates issued by that CA will be allowed._
 

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)) |
+| **Config file keys** | **Environment variables** | **Type** | **Usage**      |
+| :------------------- | :------------------------ | :------- | :------------- |
+| `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
@@ -65,9 +70,71 @@ 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.
+
+</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.