Skip to content

Commit ad85026

Browse files
ZPain8464kenjenkins
authored andcommitted
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]>
1 parent 4b27f4e commit ad85026

8 files changed

+43
-169
lines changed

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

+1-2
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ curl https://your-app.corp.example.com/.well-known/pomerium/jwks.json | jq
9898

9999
:::caution
100100

101-
In order to use the `/.well-known/pomerium/jwks.json` endpoint you must set either the [Signing Key] or [Signing Key File] configuration option.
101+
In order to use the `/.well-known/pomerium/jwks.json` endpoint, you must set the [Signing Key] configuration option.
102102

103103
:::
104104

@@ -168,4 +168,3 @@ In an actual client, you'll want to ensure that all the other claims values are
168168
[nist p-256]: https://csrc.nist.gov/csrc/media/events/workshop-on-elliptic-curve-cryptography-standards/documents/papers/session6-adalier-mehmet.pdf
169169
[pass identity headers]: /docs/reference/routes/pass-identity-headers-per-route
170170
[signing key]: /docs/reference/signing-key
171-
[signing key file]: /docs/reference/signing-key-file

content/docs/reference/reference.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -541,7 +541,7 @@
541541
"shared-secret-file": {
542542
"id": "shared-secret-file",
543543
"title": "Shared Secret File",
544-
"path": "/shared-secret-file",
544+
"path": "/shared-secret",
545545
"description": "File path containing base64-encoded shared secret.",
546546
"services": [],
547547
"type": "string",
@@ -1485,7 +1485,7 @@
14851485
"signing-key-file": {
14861486
"id": "signing-key-file",
14871487
"title": "Signing Key File",
1488-
"path": "/signing-key-file",
1488+
"path": "/signing-key",
14891489
"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.",
14901490
"services": [],
14911491
"type": "string",

content/docs/reference/shared-secret-file.mdx

-79
This file was deleted.

content/docs/reference/shared-secret.mdx

+19-15
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
---
22
id: shared-secret
33
title: Shared Secret
4-
description: |
5-
Shared Secret is the base64 encoded 256-bit key used to mutually authenticate requests between services.
4+
description: This page discusses shared secret settings in Pomerium, which are used to mutually authenticate requests between Pomerium services.
65
keywords:
76
- reference
87
- Shared Secret
@@ -18,24 +17,29 @@ import TabItem from '@theme/TabItem';
1817

1918
## Summary
2019

21-
**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.
20+
**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.
21+
22+
:::note
23+
24+
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).
25+
26+
:::
2227

2328
## How to configure
2429

2530
<Tabs>
2631
<TabItem value="Core" label="Core">
2732

28-
| **Config file keys** | **Environment variables** | **Type** | **Usage** |
29-
| :-- | :-- | :-- | :-- |
30-
| `shared_secret` | `SHARED_SECRET` | `string` | **required** (unless using [shared_secret_file](/docs/reference/shared-secret-file)) |
31-
32-
:::tip **Note**
33+
| **Config file keys** | **Environment variables** | **Type** | **Usage** |
34+
| :------------------- | :------------------------ | :------- | :----------- |
35+
| `shared_secret` | `SHARED_SECRET` | `string` | **required** |
36+
| `shared_secret_file` | `SHARED_SECRET_FILE` | `string` | **required** |
3337

34-
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.
38+
:::enterprise Shared Secret in Enterprise Configurations
3539

36-
If you are connecting to the Console, your Pomerium Core and Console configurations require the same shared secret.
40+
If you're connecting to the [Enterprise Console](/docs/enterprise), your Pomerium Core and Enterprise configurations each require the same shared secret.
3741

38-
See the [**Enterprise Quickstart**](/docs/enterprise/quickstart) for an example implementation.
42+
See the [Enterprise Quickstart](/docs/enterprise/quickstart) for an example implementation.
3943

4044
:::
4145

@@ -54,7 +58,7 @@ shared_secret: wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs=
5458
```
5559
5660
```bash
57-
SHARED_SECRET=wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs=
61+
SHARED_SECRET_FILE='/run/secrets/POMERIUM_SHARED_SECRET'
5862
```
5963

6064
</TabItem>
@@ -65,9 +69,9 @@ SHARED_SECRET=wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs=
6569
</TabItem>
6670
<TabItem value="Kubernetes" label="Kubernetes">
6771

68-
| **Name** | **Type** | **Usage** |
69-
| :-- | :-- | :-- |
70-
| `secrets.shared_secret` | `string` | **required** (unless using [shared_secret_file](/docs/reference/shared-secret-file)) |
72+
| **Name** | **Type** | **Usage** |
73+
| :---------------------- | :------- | :----------- |
74+
| `secrets.shared_secret` | `string` | **required** |
7175

7276
See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more information.
7377

content/docs/reference/signing-key-file.mdx

-65
This file was deleted.

content/docs/reference/signing-key.mdx

+13-4
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
id: signing-key
55
title: Signing Key
66
description: |
7-
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.
7+
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.
88
keywords:
99
- reference
1010
- Signing Key
@@ -18,8 +18,6 @@ import TabItem from '@theme/TabItem';
1818

1919
# Signing Key
2020

21-
## Summary
22-
2321
**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.
2422

2523
## How to configure
@@ -30,6 +28,7 @@ import TabItem from '@theme/TabItem';
3028
| **Config file keys** | **Environment variables** | **Type** | **Usage** |
3129
| :------------------- | :------------------------ | :------- | :----------- |
3230
| `signing_key` | `SIGNING_KEY` | `string` | **optional** |
31+
| `signing_key_file` | `SIGNING_KEY_FILE` | `string` | **optional** |
3332

3433
</TabItem>
3534
<TabItem value="Enterprise" label="Enterprise">
@@ -48,6 +47,16 @@ See Kubernetes [bootstrap secrets](/docs/k8s/reference#spec) for more informatio
4847
</TabItem>
4948
</Tabs>
5049

50+
## Examples
51+
52+
```yaml
53+
signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUNUWHlVQ0phYmlHTW1wd3VqYlBmWHhNS2MzWjNFM0tEcmlEbmQwZktiTmtvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFM1FYQmZ1eEV1UEhJT0ZDb3RaaXBOMUFqM3UrOUtFRWd4RFVURW9CcjYxYXpaYWFvYlRGbwo0cGY3WFRSbzVhM2U2aDdKUW9wckp4QSszd0dwTUpSYWl3PT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
54+
```
55+
56+
```bash
57+
SIGNING_KEY_FILE='/run/secrets/POMERIUM_SIGNING_KEY'
58+
```
59+
5160
### How to use signing key
5261

5362
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
95104

96105
If multiple keys are provided, only the first will be used for signing.
97106

98-
## Key rotation
107+
### Key rotation
99108

100109
To implement key rotation, follow a 3-step process:
101110

content/docs/troubleshooting.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ Events:
148148

149149
### Shared Secret Mismatch
150150

151-
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.
151+
Pomerium's independent services communicate securely using a [shared secret](/docs/reference/shared-secret). If any services have mismatched secrets, Pomerium will fail.
152152

153153
Pomerium Core will log a shared secret mismatch with:
154154

@@ -163,7 +163,7 @@ Pomerium Core will log a shared secret mismatch with:
163163
}
164164
```
165165

166-
And Pomerium Enterprise will log the error with:
166+
Pomerium Enterprise will log a shared secret mismatch with:
167167

168168
```json
169169
{

static/_redirects

+6
Original file line numberDiff line numberDiff line change
@@ -461,6 +461,12 @@ https://0-20-0.docs.pomerium.com/category/guides https://0-20-0.docs.pomerium.co
461461
/docs/reference/x-forwarded-for-http-header /docs/reference/x-forwarded-for-settings#skip-xff-append
462462
/docs/reference/the-number-of-trusted-hops /docs/reference/x-forwarded-for-settings#xff-number-of-trusted-hops
463463

464+
# Signing Key
465+
/docs/reference/signing-key-file /docs/reference/signing-key
466+
467+
# Shared Secret
468+
/docs/reference/shared-secret-file /docs/reference/shared-secret
469+
464470
# Topics links - now concepts
465471
/docs/topics/auth-logs /docs/capabilities/audit-logs
466472
/docs/topics/single-sign-out.html /docs/capabilities/single-sign-out

0 commit comments

Comments
 (0)