3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-08-06 10:21:05 +02:00
Code Issues Projects Releases Packages Wiki Activity

Docs: Update JWT Verification Guide (#2746) (#2787)

Browse source 
* WIP update

* init mutual auth topic page

* WIP

* update JWT verification guide

* s/Java/Json/g

* remove Mutual Auth topic page and references

The new page will be reviewed and added as a separate PR

* fix JSON capitalization throughout

* copy edit to jwt-verification.md

Co-authored-by: cmo-pomerium <91488121+cmo-pomerium@users.noreply.github.com>

Co-authored-by: Alex Fornuto <afornuto@pomerium.com>
Co-authored-by: cmo-pomerium <91488121+cmo-pomerium@users.noreply.github.com>
This commit is contained in:
backport-actions-token[bot] 2021-11-29 15:18:38 -06:00 • committed by GitHub
parent 05dc39215e
commit 86614b5b0e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 200 additions and 190 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/docs/topics/getting-users-identity.md
View file

@ -5,7 +5,7 @@ description: This article describes how to to get a user's identity with Pomeriu
# Getting the user's identity # Getting the user's identity
This article describes how to retrieve a user's identity from a pomerium managed application. Pomerium uses JSON Web Tokens (JWT) to attest that a given request was handled by Pomerium's authorizer service. This article describes how to retrieve a user's identity from a pomerium managed application. Pomerium uses JSON web tokens (JWT) to attest that a given request was handled by Pomerium's authorizer service.
## Prerequisites ## Prerequisites

2
docs/docs/topics/original-request-context.md
View file

@ -14,7 +14,7 @@ In enterprise environments where multiple services protected by Pomerium communi
## Abstract ## Abstract
When a User communicates with a service downstream of Pomerium, the service can identify that user by the `X-Pomerium-JWT-Assertion` header, added by Pomerium, which provides as a value a Java Web Token (**JWT**) identifying the user. When a User communicates with a service downstream of Pomerium, the service can identify that user by the `X-Pomerium-JWT-Assertion` header, added by Pomerium, which provides as a value a JSON web token (**JWT**) identifying the user.
Should that service need to communicate with another Pomerium-protected service to construct the response, that connection should be authorized through Pomerium with a [Service Account](/enterprise/concepts.md#service-accounts). Service accounts should be provided to Pomerium from the first service as a bearer token header, i.e. `Authorization: Bearer Pomerium-${service_acount_jwt}`. This header is how the secondary service authenticates the machine-to-machine interaction. Should that service need to communicate with another Pomerium-protected service to construct the response, that connection should be authorized through Pomerium with a [Service Account](/enterprise/concepts.md#service-accounts). Service accounts should be provided to Pomerium from the first service as a bearer token header, i.e. `Authorization: Bearer Pomerium-${service_acount_jwt}`. This header is how the secondary service authenticates the machine-to-machine interaction.

2
docs/enterprise/console-settings.yaml
View file

@ -256,7 +256,7 @@ settings:
:::: ::::
::::: :::::
1. After you click **Submit**, the modal presents the Java Web Token (**JWT**) for the service account. Temporarily save it somewhere secure, as you will not be able to view it again: 1. After you click **Submit**, the modal presents the JSON web token (**JWT**) for the service account. Temporarily save it somewhere secure, as you will not be able to view it again:
![Service Account Added](../img/service-account-jwt.png) ![Service Account Added](../img/service-account-jwt.png)

2
docs/enterprise/reference/configure.md
View file

@ -276,7 +276,7 @@ Before you begin, confirm you are in the correct Namespace. A service account ca
:::: ::::
::::: :::::
1. After you click **Submit**, the modal presents the Java Web Token (**JWT**) for the service account. Temporarily save it somewhere secure, as you will not be able to view it again: 1. After you click **Submit**, the modal presents the JSON web token (**JWT**) for the service account. Temporarily save it somewhere secure, as you will not be able to view it again:
![Service Account Added](../img/service-account-jwt.png) ![Service Account Added](../img/service-account-jwt.png)

2
docs/guides/grafana.md
View file

@ -44,7 +44,7 @@ cache_ttl = 60m
This configuration: This configuration:
- enables authentication by java web token (**JWT**), - enables authentication by JSON web token (**JWT**),
- defines the header to look at to provide the JWT, - defines the header to look at to provide the JWT,
- associates the email_claim in the JWT with the email of the Grafana user, - associates the email_claim in the JWT with the email of the Grafana user,
- specifies the location of the signing key for the JWT to validate it, - specifies the location of the signing key for the JWT to validate it,

380
docs/guides/jwt-verification.md
View file

@ -11,220 +11,230 @@ description: >-
# JWT Verification # JWT Verification
This example demonstrates how to verify the [Pomerium JWT assertion header](https://www.pomerium.io/reference/#pass-identity-headers) using [Envoy](https://www.envoyproxy.io/). This is useful for legacy or 3rd party applications which can't be modified to perform verification themselves. This example demonstrates how to verify the [Pomerium JWT assertion header](https://www.pomerium.io/reference/#pass-identity-headers) using [Envoy](https://www.envoyproxy.io/). This is useful for legacy or 3rd party applications which can't be modified to perform verification themselves.
This guide is a practical demonstration of some of the concept of mutual authentication, using JSON web tokens (**JWTs**).
## Requirements ## Requirements
- [Docker](https://www.docker.com/) - [Docker](https://www.docker.com/)
- [Docker Compose](https://docs.docker.com/compose/) - [Docker Compose](https://docs.docker.com/compose/)
- [mkcert](https://github.com/FiloSottile/mkcert) - [mkcert](https://github.com/FiloSottile/mkcert)
This guide assumes you already have a working IdP connection to provide user data. See our [Identity Provider](/docs/identity-providers/readme.md) docs for more information.
## Overview ## Overview
Two services are configured in a `docker-compose.yaml` file: Three services are configured in a `docker-compose.yaml` file:
- `pomerium` running an all-in-one deployment of Pomerium on `*.localhost.pomerium.io` - `pomerium` running an all-in-one deployment of Pomerium on `*.localhost.pomerium.io`
- `envoy-jwt-checker` running envoy with a JWT Authn filter - `envoy-jwt-checker` running envoy with a JWT Authn filter
- `httpbin` as our example legacy application without JWT verifivation.
Once running, the user visits [verify.localhost.pomerium.io](https://verify.localhost.pomerium.io), is authenticated through [authenticate.localhost.pomerium.io](https://authenticate.localhost.pomerium.io), and then the HTTP request is sent to envoy which proxies it to [`verify.pomerium.com`](https://verify.pomerium.com). In our Docker Compose configuration we'll define two networks. `pomerium` and `envoy-jwt-checker` will be on the `frontend` network, simulating your local area network (**LAN**). `envoy-jwt-checker` will also be on the `backend` network, along with `httpbin`. This means that `envoy-jwt-checker` is the only other service that can communicate with `httpbin`.
Before allowing the request Envoy will verify the signed JWT assertion header using the public key defined by [authenticate.localhost.pomerium.io/.well-known/pomerium/jwks.json](https://authenticate.int.example.com/.well-known/pomerium/jwks.json). Once running, the user visits [verify.localhost.pomerium.io], is authenticated through [authenticate.localhost.pomerium.io], and then the HTTP request is sent to envoy which proxies it to the httpbin app.
Before allowing the request Envoy will verify the signed JWT assertion header using the public key defined by `authenticate.localhost.pomerium.io/.well-known/pomerium/jwks.json`.
## Setup ## Setup
### 1. Docker Compose The configuration presented here assumes a working route to the domain space `*.localhost.pomerium.io`. You can make entries in your `hosts` file for the domains used or change this value to match your local environment.
Create a `docker-compose.yaml` file containing:
```yaml ::: tip
version: "3.8" Mac and Linux users can use DNSMasq to map the `*.localhost.pomerium.io` domain (including all subdomains) to a specified test address:
services:
pomerium:
image: pomerium/pomerium:latest
ports:
- "443:443"
volumes:
- type: bind
source: ./cfg/pomerium.yaml
target: /pomerium/config.yaml
- type: bind
source: ./certs/_wildcard.localhost.pomerium.io.pem
target: /pomerium/_wildcard.localhost.pomerium.io.pem
- type: bind
source: ./certs/_wildcard.localhost.pomerium.io-key.pem
target: /pomerium/_wildcard.localhost.pomerium.io-key.pem
envoy-jwt-checker: - [Local Development with Wildcard DNS] (macOS)
image: envoyproxy/envoy:v1.17.1 - [Local Development with Wildcard DNS on Linux]
ports: :::
- "10000:10000"
volumes:
- type: bind
source: ./cfg/envoy.yaml
target: /etc/envoy/envoy.yaml
```
### 2. Certificates 1. Create a `docker-compose.yaml` file containing:
Using [`mkcert`](https://github.com/FiloSottile/mkcert) generate a certificate for `*.localhost.pomerium.io` in a `certs` directory:
```bash ```yaml
mkdir certs version: "3.9"
cd certs networks:
mkcert '*.localhost.pomerium.io' frontend:
``` driver: "bridge"
backend:
### 3. Envoy Configuration driver: "bridge"
Create a `cfg` directory containing the following `envoy.yaml` file: services:
```yaml
admin:
access_log_path: /dev/null
address:
socket_address: { address: 127.0.0.1, port_value: 9901 }
static_resources:
listeners:
- name: ingress-http
address:
socket_address: { address: 0.0.0.0, port_value: 10000 }
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
codec_type: AUTO
route_config:
name: verify
virtual_hosts:
- name: verify
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: egress-verify
auto_host_rewrite: true
http_filters:
- name: envoy.filters.http.jwt_authn
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
providers:
pomerium:
issuer: authenticate.localhost.pomerium.io
audiences:
- verify.localhost.pomerium.io
from_headers:
- name: X-Pomerium-Jwt-Assertion
remote_jwks:
http_uri:
uri: https://authenticate.localhost.pomerium.io/.well-known/pomerium/jwks.json
cluster: egress-authenticate
timeout: 1s
rules:
- match:
prefix: /
requires:
provider_name: pomerium
- name: envoy.filters.http.router
clusters:
- name: egress-verify
connect_timeout: 0.25s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: verify
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: verify.pomerium.com
port_value: 443
transport_socket:
name: tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
sni: verify.pomerium.com
- name: egress-authenticate
connect_timeout: '0.25s'
type: STRICT_DNS
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: authenticate
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: pomerium
port_value: 443
transport_socket:
name: tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
sni: authenticate.localhost.pomerium.io
```
Envoy configuration can be quite verbose, but the crucial bit is the HTTP filter:
```yaml
- name: envoy.filters.http.jwt_authn
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
providers:
pomerium: pomerium:
issuer: authenticate.localhost.pomerium.io image: pomerium/pomerium:latest
audiences: ports:
- verify.localhost.pomerium.io - "443:443"
from_headers: volumes:
- name: X-Pomerium-Jwt-Assertion - type: bind
remote_jwks: source: ./cfg/pomerium.yaml
http_uri: target: /pomerium/config.yaml
uri: https://authenticate.localhost.pomerium.io/.well-known/pomerium/jwks.json - type: bind
cluster: egress-authenticate source: ./certs/_wildcard.localhost.pomerium.io.pem
timeout: 1s target: /pomerium/_wildcard.localhost.pomerium.io.pem
rules: - type: bind
- match: source: ./certs/_wildcard.localhost.pomerium.io-key.pem
prefix: / target: /pomerium/_wildcard.localhost.pomerium.io-key.pem
requires: networks:
provider_name: pomerium - frontend
```
This configuration pulls the JWT out of the `X-Pomerium-Jwt-Assertion` header, verifies the `iss` and `aud` claims and checks the signature via the public key defined at the `jwks.json` endpoint. Documentation for additional configuration options is available here: [Envoy JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter#config-http-filters-jwt-authn). envoy-jwt-checker:
image: envoyproxy/envoy:v1.17.1
ports:
- "10000:10000"
volumes:
- type: bind
source: ./cfg/envoy.yaml
target: /etc/envoy/envoy.yaml
networks:
frontend:
aliases:
- "httpbin-sidecar"
backend:
### 4. Pomerium Configuration httpbin:
Create a `pomerium.yaml` file in the `cfg` directory containing: image: kennethreitz/httpbin
ports:
- "80:80"
networks:
- backend
```
```yaml 1. Using [`mkcert`](https://github.com/FiloSottile/mkcert), generate a certificate for `*.localhost.pomerium.io` in a `certs` directory:
authenticate_service_url: https://authenticate.localhost.pomerium.io
certificate_file: "/pomerium/_wildcard.localhost.pomerium.io.pem" ```bash
certificate_key_file: "/pomerium/_wildcard.localhost.pomerium.io-key.pem" mkdir certs
cd certs
mkcert '*.localhost.pomerium.io'
```
idp_provider: google 1. Create a `cfg` directory containing the following `envoy.yaml` file. Envoy configuration can be quite verbose, but the crucial bit is the HTTP filter (highlighted below):
idp_client_id: REPLACE_ME
idp_client_secret: REPLACE_ME
cookie_secret: WwMtDXWaRDMBQCylle8OJ+w4kLIDIGd8W3cB4/zFFtg= ```yaml{30-49}
shared_secret: WwMtDXWaRDMBQCylle8OJ+w4kLIDIGd8W3cB4/zFFtg= admin:
signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUdxWllpVzJycVo3TUdKTGp4bnNZVWJJcmZxNFdwR044RlgzQVh2UnRjSHdvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFYVd1UkNKMjFrL2JvUjNNRytPOVlHQjNXR0R1anVXMHFLVWhucUVwVS9JKzFoZmhuZEJ0WApDZGFpaGVGb0FOWXVCRUp3MFZhRml6QnVZb3l5RVAzOXBRPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo= access_log_path: /dev/null
address:
socket_address: { address: 127.0.0.1, port_value: 9901 }
routes: static_resources:
- from: https://verify.localhost.pomerium.io listeners:
to: http://envoy-jwt-checker:10000 - name: ingress-http
policy: address:
- allow: socket_address: { address: 0.0.0.0, port_value: 10000 }
or: filter_chains:
- domain: - filters:
is: pomerium.com - name: envoy.filters.network.http_connection_manager
pass_identity_headers: true typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
codec_type: AUTO
route_config:
name: verify
virtual_hosts:
- name: httpbin
domains: ["httpbin-sidecar"]
routes:
- match:
prefix: "/"
route:
cluster: egress-httpbin
auto_host_rewrite: true
http_filters:
- name: envoy.filters.http.jwt_authn
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
providers:
pomerium:
issuer: authenticate.localhost.pomerium.io
audiences:
- httpbin.localhost.pomerium.io
from_headers:
- name: X-Pomerium-Jwt-Assertion
remote_jwks:
http_uri:
uri: https://authenticate.localhost.pomerium.io/.well-known/pomerium/jwks.json
cluster: egress-authenticate
timeout: 1s
rules:
- match:
prefix: /
requires:
provider_name: pomerium
- name: envoy.filters.http.router
clusters:
- name: egress-httpbin
connect_timeout: 0.25s
type: STRICT_DNS
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: httpbin
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: httpbin
port_value: 80
- name: egress-authenticate
connect_timeout: '0.25s'
type: STRICT_DNS
lb_policy: ROUND_ROBIN
load_assignment:
cluster_name: authenticate
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: pomerium
port_value: 443
transport_socket:
name: tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
sni: authenticate.localhost.pomerium.io
```
``` This configuration pulls the JWT out of the `X-Pomerium-Jwt-Assertion` header, verifies the `iss` and `aud` claims and checks the signature via the public key defined at the `jwks.json` endpoint. Documentation for additional configuration options is available here: [Envoy JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter#config-http-filters-jwt-authn).
You will need to replace the identity provider credentials for this to work. 1. Create a `pomerium.yaml` file in the `cfg` directory containing:
```yaml
authenticate_service_url: https://authenticate.localhost.pomerium.io
certificate_file: "/pomerium/_wildcard.localhost.pomerium.io.pem"
certificate_key_file: "/pomerium/_wildcard.localhost.pomerium.io-key.pem"
idp_provider: google
idp_client_id: REPLACE_ME
idp_client_secret: REPLACE_ME
cookie_secret: REPLACE_ME
shared_secret: REPLACE_ME
signing_key: REPLACE_ME
routes:
- from: https://httpbin.localhost.pomerium.io
to: http://httpbin-sidecar:10000
pass_identity_headers: true
policy:
- allow:
or:
- domain:
is: example.com
```
Replace the identity provider credentials, secrets, and signing key. Adjust the policy to match your configuration.
## Run ## Run
You should now be able to run the example with:
```bash You should now be able to run the example with the following steps.
docker-compose up
```
Visit [verify.localhost.pomerium.io](https://verify.localhost.pomerium.io), login and you see the Pomerium verify page. However, visiting Envoy directly via [localhost:10000](http://localhost:10000) should return a `Jwt is missing` error, thus requiring Pomerium to access Envoy. 1. Turn on the example configuration in Docker:
```bash
docker-compose up
```
1. Visit [httpbin.localhost.pomerium.io](https://httpbin.localhost.pomerium.io). Login and you will be redirected to the httpbin page.
1. In this network configuration you cannot access `httpbin` directly. However, visiting Envoy directly via [localhost.pomerium.io:10000/](http://localhost.pomerium.io:10000/) will return a `Jwt is missing` error, confirming that you must authenticate with Pomerium to access Envoy, and any services accessible through it.
[authenticate.localhost.pomerium.io]: https://authenticate.localhost.pomerium.io
[httpbin.localhost.pomerium.io]: https://verify.localhost.pomerium.io
[Local Development with Wildcard DNS on Linux]: https://sixfeetup.com/blog/local-development-with-wildcard-dns-on-linux
[Local Development with Wildcard DNS]: https://blog.thesparktree.com/local-development-with-wildcard-dns
[verify.localhost.pomerium.io]: https://verify.localhost.pomerium.io