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#signing-key
+[signing key file]: /docs/reference/signing-key#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#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#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#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#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#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#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#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#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#shared-secret) mismatch between services. See [Troubleshooting - Shared Secret Mismatch](/docs/reference/shared-secret#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#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#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#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

@@ -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.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/signing-key.mdx

@@ -3,8 +3,9 @@
 
 id: signing-key
 title: Signing Key
+sidebar_label: Signing Key Settings
 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 +19,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 +29,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 +48,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 +105,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: