From 0d3ef4564e91193eaeba8786716a83c1f58c0246 Mon Sep 17 00:00:00 2001 From: Caleb Doxsey Date: Wed, 4 Aug 2021 16:00:31 -0600 Subject: [PATCH] doc updates (#2433) * remove reference to EdDSA, fix numbering, typo * fix ppl example * update jwt verification routes * update kubernetes route * update local oidc routes * update mtls routes * fix transmission policy * policy -> routes * update settings * fix has * update numbering --- docs/docs/topics/getting-users-identity.md | 8 ++++---- docs/docs/topics/tcp-support.md | 2 +- docs/guides/jwt-verification.md | 9 ++++++--- docs/guides/kubernetes.md | 7 +++++-- docs/guides/local-oidc.md | 9 ++++++--- docs/guides/mtls.md | 7 +++++-- docs/guides/transmission.md | 6 +++--- docs/reference/readme.md | 2 +- docs/reference/settings.yaml | 2 +- examples/config/config.example.yaml | 6 ++++-- examples/config/route.example.yaml | 6 ++++-- 11 files changed, 40 insertions(+), 24 deletions(-) diff --git a/docs/docs/topics/getting-users-identity.md b/docs/docs/topics/getting-users-identity.md index b8aeaf946..bef9d5d86 100644 --- a/docs/docs/topics/getting-users-identity.md +++ b/docs/docs/topics/getting-users-identity.md @@ -12,7 +12,7 @@ This article describes how to retrieve a user's identity from a pomerium managed To secure your app with signed headers, you'll need the following: - An application you want users to connect to. -- A [JWT] library. We strongly recommend using `ES256` or `EdDSA` over `RSA` based algorithms which are often much faster. When in doubt, use `ES256` +- A [JWT] library. We strongly recommend using `ES256` over `RSA` based algorithms which are often much faster. When in doubt, use `ES256` ## Verification @@ -69,7 +69,7 @@ $ curl https://authenticate.int.example.com/.well-known/pomerium/jwks.json | jq Though you will very likely be verifying signed-headers programmatically in your application's middleware, and using a third-party JWT library, if you are new to JWT it may be helpful to show what manual verification looks like. -1\. Provide pomerium with a base64 encoded Elliptic Curve ([NIST P-256] aka [secp256r1] aka prime256v1) Private Key. In production, you'd likely want to get these from your KMS. +1. Provide pomerium with a base64 encoded Elliptic Curve ([NIST P-256] aka [secp256r1] aka prime256v1) Private Key. In production, you'd likely want to get these from your KMS. ```bash # see ./scripts/generate_self_signed_signing_key.sh @@ -85,13 +85,13 @@ Copy the base64 encoded value of your private key to `pomerium-proxy`'s environm SIGNING_KEY=ZxqyyIPPX0oWrrOwsxXgl0hHnTx3mBVhQ2kvW1YB4MM= ``` -1. Reload `pomerium-proxy`. Navigate to httpbin (by default, `https://httpbin.corp.${YOUR-DOMAIN}.com`), and login as usual. Click **request inspection**. Select `/headers'. Click **try it out** and then **execute**. You should see something like the following. +1. Reload `pomerium-proxy`. Navigate to httpbin (by default, `https://httpbin.corp.${YOUR-DOMAIN}.com`), and login as usual. Click **request inspection**. Select `/headers`. Click **try it out** and then **execute**. You should see something like the following. ![httpbin displaying jwt headers](./img/inspect-headers.png) 1. `X-Pomerium-Jwt-Assertion` is the signature value. It's less scary than it looks and basically just a compressed, json blob as described above. Navigate to [jwt.io] which provides a helpful GUI to manually verify JWT values. -2. Paste the value of `X-Pomerium-Jwt-Assertion` header token into the `Encoded` form. You should notice that the decoded values look much more familiar. +1. Paste the value of `X-Pomerium-Jwt-Assertion` header token into the `Encoded` form. You should notice that the decoded values look much more familiar. ![httpbin displaying decoded jwt](./img/verifying-headers-1.png) diff --git a/docs/docs/topics/tcp-support.md b/docs/docs/topics/tcp-support.md index 00859fc19..94ea61a7e 100644 --- a/docs/docs/topics/tcp-support.md +++ b/docs/docs/topics/tcp-support.md @@ -39,7 +39,7 @@ routes: - email: is: contractor@not-example.com - groups: - has: ["datascience@example.com"] + has: "datascience@example.com" ``` Notes: diff --git a/docs/guides/jwt-verification.md b/docs/guides/jwt-verification.md index 6e8196d81..9ce2444cf 100644 --- a/docs/guides/jwt-verification.md +++ b/docs/guides/jwt-verification.md @@ -206,11 +206,14 @@ cookie_secret: WwMtDXWaRDMBQCylle8OJ+w4kLIDIGd8W3cB4/zFFtg= shared_secret: WwMtDXWaRDMBQCylle8OJ+w4kLIDIGd8W3cB4/zFFtg= signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUdxWllpVzJycVo3TUdKTGp4bnNZVWJJcmZxNFdwR044RlgzQVh2UnRjSHdvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFYVd1UkNKMjFrL2JvUjNNRytPOVlHQjNXR0R1anVXMHFLVWhucUVwVS9JKzFoZmhuZEJ0WApDZGFpaGVGb0FOWXVCRUp3MFZhRml6QnVZb3l5RVAzOXBRPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo= -policy: +routes: - from: https://verify.localhost.pomerium.io to: http://envoy-jwt-checker:10000 - allowed_domains: - - pomerium.com + policy: + - allow: + or: + - domain: + is: pomerium.com pass_identity_headers: true ``` diff --git a/docs/guides/kubernetes.md b/docs/guides/kubernetes.md index 1bc15f69b..335cc6768 100644 --- a/docs/guides/kubernetes.md +++ b/docs/guides/kubernetes.md @@ -194,8 +194,11 @@ The policy should be a base64-encoded block of yaml: to: https://kubernetes.default.svc tls_skip_verify: true allow_spdy: true - allowed_domains: - - pomerium.com + policy: + - allow: + or: + - domain: + is: pomerium.com kubernetes_service_account_token: "..." #$(kubectl get secret/"$(kubectl get serviceaccount/pomerium -o json | jq -r '.secrets[0].name')" -o json | jq -r .data.token | base64 -d) ``` diff --git a/docs/guides/local-oidc.md b/docs/guides/local-oidc.md index 36c4c2fb9..02c24fc06 100644 --- a/docs/guides/local-oidc.md +++ b/docs/guides/local-oidc.md @@ -78,11 +78,14 @@ idp_client_secret: bar cookie_secret: # https://www.pomerium.io/configuration/#policy -policy: +routes: - from: https://verify.localhost.pomerium.io to: http://verify - allowed_domains: - - example.org + policy: + - allow: + or: + - domain: + is: example.org ``` ### identityprovider.json diff --git a/docs/guides/mtls.md b/docs/guides/mtls.md index f04e4171c..5b4a09346 100644 --- a/docs/guides/mtls.md +++ b/docs/guides/mtls.md @@ -73,10 +73,13 @@ idp_provider: "google" idp_client_id: YOUR_CLIENT_ID idp_client_secret: YOUR_SECRET -policy: +routes: - from: "https://verify.localhost.pomerium.io:8443" to: "https://verify.org" - allow_public_unauthenticated_access: true + policy: + - allow: + or: + - accept: true ``` Start Pomerium with: diff --git a/docs/guides/transmission.md b/docs/guides/transmission.md index e56c54fc5..26debac6e 100644 --- a/docs/guides/transmission.md +++ b/docs/guides/transmission.md @@ -40,7 +40,7 @@ In addition to a working instance of Pomerium, have ready the [private IP addres Edit your `config.yaml` file to add the following policy. Note that `<>` denotes placeholder values that must be replaced if copying this config directly: ```yml -policy: +routes: - from: https:// # Replace with the domain you want to use to access Transmission to: http://:9091 # Replace with the private network address of the Transmission host, or `localhost` if running on the same host. policy: @@ -49,7 +49,7 @@ policy: - email: is: myUser@mydomain.com # Replace with authorized user(s), or remove if using group permissions only. - groups: - has: [""] # Replace with authorized user group(s), or remove if using user permissions only. + has: "" # Replace with authorized user group(s), or remove if using user permissions only. ``` Remember to restart the Pomerium instance after saving your changes. @@ -112,4 +112,4 @@ You should now be able to authenticate and access your Transmission daemon remot In addition to the lock symbol in your browser's address bar, you can go to `/.pomerium` to view and confirm your session details. [Transmission]: https://transmissionbt.com/ -[quick start]: /docs/install/readme.md \ No newline at end of file +[quick start]: /docs/install/readme.md diff --git a/docs/reference/readme.md b/docs/reference/readme.md index 6950bde23..bdf739a6c 100644 --- a/docs/reference/readme.md +++ b/docs/reference/readme.md @@ -1641,7 +1641,7 @@ If set, enables proxying of websocket connections. - Required - Example: `https://authorize.corp.example.com` -Authorize Service URL is the location of the internally accessible authorize service. Multiple URLs can be specified with `authorize_service_url`. +Authorize Service URL is the location of the internally accessible authorize service. Multiple URLs can be specified with `authorize_service_urls`. ### Google Cloud Serverless Authentication Service Account diff --git a/docs/reference/settings.yaml b/docs/reference/settings.yaml index 2d9ded733..2df029ac0 100644 --- a/docs/reference/settings.yaml +++ b/docs/reference/settings.yaml @@ -1782,7 +1782,7 @@ settings: - Required - Example: `https://authorize.corp.example.com` doc: | - Authorize Service URL is the location of the internally accessible authorize service. Multiple URLs can be specified with `authorize_service_url`. + Authorize Service URL is the location of the internally accessible authorize service. Multiple URLs can be specified with `authorize_service_urls`. shortdoc: | Authorize Service URL is the location of the internally accessible authorize service. - name: "Google Cloud Serverless Authentication Service Account" diff --git a/examples/config/config.example.yaml b/examples/config/config.example.yaml index 66031dc14..b79c6c480 100644 --- a/examples/config/config.example.yaml +++ b/examples/config/config.example.yaml @@ -100,11 +100,13 @@ routes: - email: is: bdd@pomerium.io - groups: - has: ["admins", "developers"] + has: "admins" + - groups: + has: "developers" - from: https://hello.localhost.pomerium.io to: http://localhost:8080 policy: - allow: or: - groups: - has: ["admins@pomerium.io"] + has: "admins@pomerium.io" diff --git a/examples/config/route.example.yaml b/examples/config/route.example.yaml index 32845c60d..28cb43cfa 100644 --- a/examples/config/route.example.yaml +++ b/examples/config/route.example.yaml @@ -31,11 +31,13 @@ routes: - email: is: bdd@pomerium.io - groups: - has: ["admins", "developers"] + has: "admins" + - groups: + has: "developers" - from: https://hello.localhost.pomerium.io to: http://localhost:8080 policy: - allow: or: - groups: - has: ["admins@pomerium.io"] + has: "admins@pomerium.io"