mirror of
https://github.com/pomerium/pomerium.git
synced 2025-06-21 12:08:19 +02:00
envoy: Initial changes
This commit is contained in:
Travis Groth
parent
8f78497e99
commit
99e788a9b4
107 changed files with 2542 additions and 3322 deletions
|
|
@ -1,36 +1,5 @@
|
|||
# Changelog
|
||||
|
||||
## v0.8.0
|
||||
|
||||
To see a complete list of changes [see the diff](https://github.com/pomerium/pomerium/compare/v0.7.0...v0.8.0).
|
||||
|
||||
### New
|
||||
|
||||
- cryptutil: add automatic certificate management @desimone [GH-644]
|
||||
- implement path-based route matching @calebdoxsey [GH-615]
|
||||
- internal/identity: implement github provider support @Lumexralph [GH-582]
|
||||
- proxy: add configurable JWT claim headers @travisgroth (#596)
|
||||
- proxy: remove extra session unmarshalling @desimone (#592)
|
||||
|
||||
### Changes
|
||||
|
||||
- ci: Switch integration tests from minikube to kind @travisgroth [GH-656]
|
||||
- integration-tests: add CORS test @calebdoxsey [GH-662]
|
||||
- integration-tests: add websocket enabled/disabled test @calebdoxsey [GH-661]
|
||||
- integration-tests: set_request_headers and preserve_host_header options @calebdoxsey [GH-668]
|
||||
- pre-commit: add pre-commit configuration @calebdoxsey [GH-666]
|
||||
- proxy: improve JWT header behavior @travisgroth [GH-642]
|
||||
|
||||
## Fixed
|
||||
|
||||
- authorize: fix authorization check for allowed_domains to only match current route @calebdoxsey [GH-624]
|
||||
- authorize: fix unexpected panic on reload @travisgroth [GH-652]
|
||||
- site: fix site on mobile @desimone [GH-597]
|
||||
|
||||
### Documentation
|
||||
|
||||
- deploy: autocert documentation and defaults @travisgroth [GH-658]
|
||||
|
||||
## v0.7.5
|
||||
|
||||
### Fixed
|
||||
|
|
@ -77,7 +46,7 @@ There were no changes in the v0.7.1 release, but we updated the build process sl
|
|||
|
||||
### New
|
||||
|
||||
- *: remove import path comments @desimone [GH-545]
|
||||
- \*: remove import path comments @desimone [GH-545]
|
||||
- authenticate: make callback path configurable @desimone [GH-493]
|
||||
- authenticate: return 401 for some specific error codes @cuonglm [GH-561]
|
||||
- authorization: log audience claim failure @desimone [GH-553]
|
||||
|
|
@ -162,7 +131,6 @@ There were no changes in the v0.7.1 release, but we updated the build process sl
|
|||
- config: Remove CookieRefresh [GH-428] @u5surf [GH-436]
|
||||
- config: validate that `shared_key` does not contain whitespace @travisgroth [GH-427]
|
||||
- httputil : wrap handlers for additional context @desimone [GH-413]
|
||||
- forward-auth: validate using forwarded uri header @branchmispredictor [GH-600]
|
||||
|
||||
### Fixed
|
||||
|
||||
|
|
|
|||
|
|
@ -5,6 +5,7 @@ sidebarDepth: 0
|
|||
meta:
|
||||
- name: keywords
|
||||
content: pomerium community contributing pr code
|
||||
|
||||
description: >-
|
||||
This document describes how you can find issues to work on, fix/add
|
||||
documentation, and how setup Pomerium for local development.
|
||||
|
|
@ -92,4 +93,4 @@ We use [Netlify](https://www.netlify.com) to build and host our docs. One of nic
|
|||
[httpbin]: https://httpbin.org/
|
||||
[identity provider]: ../identity-providers/readme.md
|
||||
[make]: https://en.wikipedia.org/wiki/Make_(software)
|
||||
[tls certificates]: ../reference/certificates.md
|
||||
[wild-card tls certificate]: ../reference/certificates.md
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The following quick-start guide covers how to configure and run Pomerium using t
|
|||
## Prerequisites
|
||||
|
||||
- A configured [identity provider]
|
||||
- [TLS certificates]
|
||||
- A [wild-card TLS certificate]
|
||||
|
||||
## Download
|
||||
|
||||
|
|
@ -52,6 +52,6 @@ Browse to `external-httpbin.your.domain.example`. Connections between you and [h
|
|||
[download]: https://github.com/pomerium/pomerium/releases
|
||||
[environmental configuration variables]: https://12factor.net/config
|
||||
[httpbin]: https://httpbin.org/
|
||||
[identity provider]: ../identity-providers/
|
||||
[identity provider]: ../docs/identity-providers/
|
||||
[make]: https://en.wikipedia.org/wiki/Make_(software)
|
||||
[tls certificates]: ../reference/certificates.md
|
||||
[wild-card tls certificate]: ../reference/certificates.md
|
||||
|
|
|
|||
|
|
@ -73,6 +73,6 @@ Browse to `httpbin.localhost.pomerium.io`. Connections between you and [httpbin]
|
|||
|
||||
[configuration variables]: ../../configuration/readme.md
|
||||
[httpbin]: https://httpbin.org/
|
||||
[identity provider]: ../identity-providers/
|
||||
[identity provider]: ../docs/identity-providers/
|
||||
[make]: https://en.wikipedia.org/wiki/Make_(software)
|
||||
[tls certificates]: ../reference/certificates.md
|
||||
[wild-card tls certificate]: ../reference/certificates.md
|
||||
|
|
|
|||
|
|
@ -17,19 +17,17 @@ This quick-start will show you how to deploy Pomerium with [Helm](https://helm.s
|
|||
- Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
|
||||
- Install the [Google Cloud SDK](https://cloud.google.com/kubernetes-engine/docs/quickstart)
|
||||
- Install [helm](https://helm.sh/docs/using_helm/)
|
||||
- [TLS certificates]
|
||||
- A [wild-card TLS certificate]
|
||||
|
||||
Though there are [many ways](https://unofficial-kubernetes.readthedocs.io/en/latest/setup/pick-right-solution/) to work with Kubernetes, for the purpose of this guide, we will be using Google's [Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). That said, most of the following steps should be very similar using any other provider.
|
||||
Though there are [many ways](https://kubernetes.io/docs/setup/pick-right-solution/) to work with Kubernetes, for the purpose of this guide, we will be using Google's [Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). That said, most of the following steps should be very similar using any other provider.
|
||||
|
||||
In addition to sharing many of the same features as the Kubernetes quickstart guide, the default helm deployment script also includes a bootstrapped certificate authority enabling mutually authenticated and encrypted communication between services that does not depend on the external LetsEncrypt certificates. Having the external domain certificate de-coupled makes it easier to renew external certificates.
|
||||
|
||||
## Configure
|
||||
|
||||
Download and modify the following helm_gke.sh script and values file to match your [identity provider] and [TLS certificates] settings.
|
||||
Download and modify the following [helm_gke.sh script][./scripts/helm_gke.sh] to match your [identity provider] and [wild-card tls certificate] settings.
|
||||
|
||||
<<<@/docs/configuration/examples/helm/helm_gke.sh
|
||||
|
||||
<<<@/docs/configuration/examples/kubernetes/values.yaml
|
||||
<<<@/scripts/helm_gke.sh
|
||||
|
||||
## Run
|
||||
|
||||
|
|
@ -58,4 +56,4 @@ You can also navigate to the special pomerium endpoint `httpbin.your.domain.exam
|
|||
[identity provider]: ../identity-providers/readme.md
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[tls certificates]: ../reference/certificates.md
|
||||
[wild-card tls certificate]: ../reference/certificates.md
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ This quickstart will cover how to deploy Pomerium with Kubernetes.
|
|||
## Prerequisites
|
||||
|
||||
- A configured [identity provider]
|
||||
- [TLS certificates]
|
||||
- A [wild-card TLS certificate]
|
||||
- A [Google Cloud Account](https://console.cloud.google.com/)
|
||||
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
|
||||
- [Google Cloud SDK](https://cloud.google.com/kubernetes-engine/docs/quickstart)
|
||||
|
|
@ -29,7 +29,7 @@ cd $HOME/pomerium/docs/configuration/examples/kubernetes
|
|||
|
||||
## Configure
|
||||
|
||||
Edit [./kubernetes_gke.sh] making sure to change the identity provider secret value to match your [identity provider] and [TLS certificates] settings.
|
||||
Edit [./kubernetes_gke.sh] making sure to change the identity provider secret value to match your [identity provider] and [wild-card tls certificate] settings.
|
||||
|
||||
<<<@/docs/configuration/examples/kubernetes/kubernetes_gke.sh
|
||||
|
||||
|
|
@ -63,9 +63,9 @@ You can also navigate to the special pomerium endpoint `httpbin.your.domain.exam
|
|||
|
||||
|
||||
|
||||
[./kubernetes_gke.sh]: ../../configuration/examples.md#google-kubernetes-engine
|
||||
[example kubernetes files]: ../../configuration/examples.md#google-kubernetes-engine
|
||||
[./kubernetes_gke.sh]: ../reference/examples#google-kubernetes-engine
|
||||
[example kubernetes files]: ../reference/examples#google-kubernetes-engine
|
||||
[identity provider]: ../identity-providers/readme.md
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[tls certificates]: ../reference/certificates.md
|
||||
[wild-card tls certificate]: ../reference/certificates.md
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ In the following quick-start, we'll create a minimal but complete environment fo
|
|||
|
||||
- A configured [identity provider]
|
||||
- [Docker] and [docker-compose]
|
||||
- [TLS certificates]
|
||||
- A [wild-card TLS certificate]
|
||||
|
||||
## Configure
|
||||
|
||||
|
|
@ -26,26 +26,12 @@ Create a [configuration file] (e.g `config.yaml`) for defining Pomerium's config
|
|||
|
||||
Ensure the `docker-compose.yml` contains the correct path to your `config.yaml`.
|
||||
|
||||
### Autocert Docker-compose
|
||||
Ensure you have set up the requisite DNS and port forwarding in [TLS certificates]
|
||||
### Docker-compose
|
||||
|
||||
Download the following `docker-compose.yml` file and modify it to:
|
||||
|
||||
- generate new secrets
|
||||
- mount your [TLS certificates]
|
||||
- mount your `config.yaml` [configuration file]
|
||||
- Set `autocert_use_staging` to `false` once you have finished testing
|
||||
|
||||
<<< @/docs/configuration/examples/docker/autocert.docker-compose.yml
|
||||
|
||||
Please note that you should use a persistent volume to store certificate data, or you may exhaust your domain quota on Let's Encrypt.
|
||||
|
||||
### Wildcard Docker-compose
|
||||
|
||||
Download the following `docker-compose.yml` file and modify it to:
|
||||
|
||||
- generate new secrets
|
||||
- mount your [TLS certificates]
|
||||
- mount your [wild-card TLS certificate]
|
||||
- mount your `config.yaml` [configuration file]
|
||||
|
||||
<<< @/docs/configuration/examples/docker/basic.docker-compose.yml
|
||||
|
|
@ -72,4 +58,4 @@ You can also navigate to the special pomerium endpoint `httpbin.corp.yourdomain.
|
|||
[docker-compose]: https://docs.docker.com/compose/install/
|
||||
[httpbin]: https://httpbin.org/
|
||||
[identity provider]: ../identity-providers/readme.md
|
||||
[tls certificates]: ../reference/certificates.md
|
||||
[wild-card tls certificate]: ../reference/certificates.md
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ Pomerium is lightweight, can easily handle hundreds of concurrent requests, and
|
|||
- A [docker-capable] synology product
|
||||
- A [Google Cloud Account](https://console.cloud.google.com/)
|
||||
- A configured Google OAuth2 [identity provider]
|
||||
- [TLS certificates][certificate documentation]
|
||||
- A [wild-card TLS certificate][certificate documentation]
|
||||
|
||||
Though any supported [identity provider] would work, this guide uses google.
|
||||
|
||||
|
|
@ -46,17 +46,17 @@ Click **Create**.
|
|||
|
||||
Set the following **Reverse Proxy Rules**.
|
||||
|
||||
Field | Description
|
||||
-------------------- | -----------
|
||||
Description | pomerium
|
||||
Source Protocol | HTTPS
|
||||
Source Hostname | *
|
||||
Destination Port | 8443
|
||||
HTTP/2 | Enabled
|
||||
HSTS | Enabled
|
||||
Destination Protocol | HTTP
|
||||
Destination Hostname | localhost
|
||||
Destination Port | 32443
|
||||
| Field | Description |
|
||||
| -------------------- | ----------- |
|
||||
| Description | pomerium |
|
||||
| Source Protocol | HTTPS |
|
||||
| Source Hostname | \* |
|
||||
| Destination Port | 8443 |
|
||||
| HTTP/2 | Enabled |
|
||||
| HSTS | Enabled |
|
||||
| Destination Protocol | HTTP |
|
||||
| Destination Hostname | localhost |
|
||||
| Destination Port | 32443 |
|
||||
|
||||
|
||||
|
||||
|
|
@ -76,9 +76,9 @@ Once the certificate is showing on the list of certificates screen we need to te
|
|||
|
||||
**Click configure**
|
||||
|
||||
Services | Certificate
|
||||
-------- | -------------------
|
||||
*:8443 | `*.int.nas.example`
|
||||
| Services | Certificate |
|
||||
| -------- | ------------------- |
|
||||
| \*:8443 | `*.int.nas.example` |
|
||||
|
||||
|
||||
|
||||
|
|
@ -170,15 +170,15 @@ These are the minimum set of configuration settings to get Pomerium running in t
|
|||
|
||||
Go to **Environment** tab.
|
||||
|
||||
Field | Value
|
||||
------------------------ | ---------------------------------------------------------------
|
||||
POLICY | output of `base64 -i policy.yaml`
|
||||
INSECURE_SERVER | `TRUE`, internal routing within docker will not be encrypted.
|
||||
IDP_CLIENT_SECRET | Values from setting up your [identity provider]
|
||||
IDP_CLIENT_ID | Values from setting up your [identity provider]
|
||||
IDP_PROVIDER | Values from setting up your [identity provider] (e.g. `google`)
|
||||
COOKIE_SECRET | output of `head -c32 /dev/urandom | base64`
|
||||
AUTHENTICATE_SERVICE_URL | `https://authenticate.int.nas.example`
|
||||
| Field | Value |
|
||||
| ------------------------ | --------------------------------------------------------------- |
|
||||
| POLICY | output of `base64 -i policy.yaml` |
|
||||
| INSECURE_SERVER | `TRUE`, internal routing within docker will not be encrypted. |
|
||||
| IDP_CLIENT_SECRET | Values from setting up your [identity provider] |
|
||||
| IDP_CLIENT_ID | Values from setting up your [identity provider] |
|
||||
| IDP_PROVIDER | Values from setting up your [identity provider] (e.g. `google`) |
|
||||
| COOKIE_SECRET | output of `head -c32 /dev/urandom | base64` |
|
||||
| AUTHENTICATE_SERVICE_URL | `https://authenticate.int.nas.example` |
|
||||
|
||||
For a detailed explanation, and additional options, please refer to the [configuration variable docs]. Also note, though not covered in this guide, settings can be made via a mounted configuration file.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,9 +8,7 @@ meta:
|
|||
|
||||
# Certificates
|
||||
|
||||
[Certificates](https://en.wikipedia.org/wiki/X.509) and [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) play a vital role in [zero-trust][principles] networks, and in Pomerium.
|
||||
|
||||
This document covers a few options in how to generate and set up TLS certificates suitable for working with pomerium.
|
||||
[Certificates](https://en.wikipedia.org/wiki/X.509) and [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) play a vital role in [zero-trust][principles] networks, and in Pomerium. This document covers how to generate and set up wild-card certificates suitable for working with pomerium.
|
||||
|
||||
This guide uses the following tools and resources:
|
||||
|
||||
|
|
@ -18,7 +16,13 @@ This guide uses the following tools and resources:
|
|||
- [Google Domains](https://domains.google.com/) registrar will be used to set up our wildcard domain and certificate validation. But any registrar would do and some providers support [automatic renewal](https://github.com/Neilpang/acme.sh/wiki/dnsapi).
|
||||
- [acme.sh](https://github.com/Neilpang/acme.sh) will be used to retrieve the wild-card domain certificate. Any [LetsEncrypt client](https://letsencrypt.org/docs/client-options/) that supports wildcard domains would work.
|
||||
|
||||
It should be noted that there are countless ways of building and managing [public-key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure). And although we hope this guide serves as a helpful baseline for generating and securing pomerium with certificates, these instructions should be modified to meet your own organization's tools, needs, and constraints. In a production environment you will likely be using your corporate load balancer, or a key management system to manage your certificate authority infrastructure.
|
||||
It should be noted that there are countless ways of building and managing [public-key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure). And although we hope this guide serves as a helpful baseline for generating and securing pomerium with certificates, these instructions should be modified to meet your own organization's tools, needs, and constraints.
|
||||
|
||||
::: warning
|
||||
|
||||
LetsEncrypt certificates must be renewed [every 90 days](https://letsencrypt.org/2015/11/09/why-90-days.html).
|
||||
|
||||
:::
|
||||
|
||||
## Why
|
||||
|
||||
|
|
@ -28,43 +32,40 @@ Since one of Pomerium's core [principles] is to treat internal and external traf
|
|||
- Pomerium's services **regardless** of if the network is "trusted"
|
||||
- Pomerium and the destination application
|
||||
|
||||
## Setting up DNS
|
||||
## How
|
||||
|
||||
First, you'll want to set a [CNAME](https://en.wikipedia.org/wiki/CNAME_record) record for wild-card domain name you will be using with Pomerium.
|
||||
|
||||
|
||||
|
||||
## Certificates
|
||||
|
||||
### Per-route automatic certificates
|
||||
|
||||
Pomerium itself can be used to retrieve, manage, and renew certificates certificates for free using Let's Encrypt, the only requirement is that Pomerium is able to receive public traffic on ports `80`/`443`. This is probably the easiest option.
|
||||
|
||||
```yaml
|
||||
autocert: true
|
||||
```
|
||||
|
||||
See the [Autocert] and [Autocert Directory] settings for more details.
|
||||
|
||||
### Self-signed wildcard certificate
|
||||
|
||||
In production, we'd use a public certificate authority such as LetsEncrypt. But for a local proof of concept or for development, we can use [mkcert](https://mkcert.dev/) to make locally trusted development certificates with any names you'd like. The easiest, is probably to use `*.localhost.pomerium.io` which we've already pre-configured to point back to localhost.
|
||||
|
||||
```bash
|
||||
# Install mkcert.
|
||||
go get -u github.com/FiloSottile/mkcert
|
||||
# Bootstrap mkcert's root certificate into your operating system's trust store.
|
||||
mkcert -install
|
||||
# Create your wildcard domain.
|
||||
# *.localhost.pomerium.io is helper domain we've hard-coded to route to localhost
|
||||
mkcert "*.localhost.pomerium.io"
|
||||
```
|
||||
|
||||
### Manual DNS Let's Encrypt wildcard certificate
|
||||
|
||||
Once you've setup your wildcard domain, we can use acme.sh to create a certificate-signing request with LetsEncrypt.
|
||||
|
||||
<<< @/docs/docs/reference/sh/generate_wildcard_cert.sh
|
||||
```bash
|
||||
# Requires acme.sh @ https://github.com/Neilpang/acme.sh
|
||||
# Install (after reviewing, obviously) by running :
|
||||
# $ curl https://get.acme.sh | sh
|
||||
$HOME/.acme.sh/acme.sh \
|
||||
--issue \
|
||||
-k ec-256 \
|
||||
-d '*.corp.example.com' \
|
||||
--dns \
|
||||
--yes-I-know-dns-manual-mode-enough-go-ahead-please
|
||||
|
||||
Creating domain key
|
||||
The domain key is here: $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key
|
||||
Single domain='*.corp.example.com'
|
||||
Getting domain auth token for each domain
|
||||
Getting webroot for domain='*.corp.example.com'
|
||||
Add the following TXT record:
|
||||
Domain: '_acme-challenge.corp.example.com'
|
||||
TXT value: 'Yz0B1Uf2xjyUI7Cr9-k96P2PQnw3RIK32dMViuvT58s'
|
||||
Please be aware that you prepend _acme-challenge. before your domain
|
||||
so the resulting subdomain will be: _acme-challenge.corp.example.com
|
||||
Please add the TXT records to the domains, and re-run with --renew.
|
||||
Please check log file for more details: $HOME/.acme.sh/acme.sh.log
|
||||
Removing DNS records.
|
||||
Not Found domain api file:
|
||||
```
|
||||
|
||||
LetsEncrypt will respond with the corresponding `TXT` record needed to verify our domain.
|
||||
|
||||
|
|
@ -72,12 +73,40 @@ LetsEncrypt will respond with the corresponding `TXT` record needed to verify ou
|
|||
|
||||
It may take a few minutes for the DNS records to propagate. Once it does, you can run the following command to complete the certificate request process.
|
||||
|
||||
```bash
|
||||
# Complete the certificate request now that we have validated our domain
|
||||
$HOME/.acme.sh/acme.sh \
|
||||
--renew \
|
||||
--ecc \
|
||||
-k ec-256 \
|
||||
-d '*.corp.example.com' \
|
||||
--dns \
|
||||
--yes-I-know-dns-manual-mode-enough-go-ahead-please
|
||||
|
||||
Renew: '*.corp.example.com'
|
||||
Single domain='*.corp.example.com'
|
||||
Getting domain auth token for each domain
|
||||
Verifying: *.corp.example.com
|
||||
Success
|
||||
Verify finished, start to sign.
|
||||
Cert success.
|
||||
-----BEGIN CERTIFICATE-----
|
||||
.... snip...
|
||||
-----END CERTIFICATE-----
|
||||
Your cert is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.cer
|
||||
Your cert key is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key
|
||||
The intermediate CA cert is in $HOME/.acme.sh/*.corp.example.com_ecc/ca.cer
|
||||
And the full chain certs is there: $HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer
|
||||
```
|
||||
|
||||
Here's how the above certificates signed by LetsEncrypt correspond to their respective Pomerium configuration settings:
|
||||
|
||||
Pomerium Config | Certificate file
|
||||
------------------------------ | --------------------------------------------------------------
|
||||
[CERTIFICATE] | `$HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer`
|
||||
[CERTIFICATE_KEY][certificate] | `$HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key`
|
||||
| Pomerium Config | Certificate file |
|
||||
| --------------------------- | -------------------------------------------------------------- |
|
||||
| [CERTIFICATE] | `$HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer` |
|
||||
| [CERTIFICATE_KEY] | `$HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key` |
|
||||
| [CERTIFICATE_AUTHORITY] | `$HOME/.acme.sh/*.corp.example.com_ecc/ca.cer` |
|
||||
| [OVERRIDE_CERTIFICATE_NAME] | `*.corp.example.com` |
|
||||
|
||||
Your end users will see a valid certificate for all domains delegated by Pomerium.
|
||||
|
||||
|
|
@ -85,12 +114,6 @@ Your end users will see a valid certificate for all domains delegated by Pomeriu
|
|||
|
||||
|
||||
|
||||
::: warning
|
||||
|
||||
LetsEncrypt certificates must be renewed [every 90 days](https://letsencrypt.org/2015/11/09/why-90-days.html).
|
||||
|
||||
:::
|
||||
|
||||
## Resources
|
||||
|
||||
Certificates, TLS, and Public Key Cryptography is a vast subject we cannot adequately cover here so if you are new to or just need a brush up, the following resources may be helpful:
|
||||
|
|
@ -100,11 +123,9 @@ Certificates, TLS, and Public Key Cryptography is a vast subject we cannot adequ
|
|||
- [Use TLS](https://smallstep.com/blog/use-tls.html) covers why TLS should be used everywhere; not just for securing typical internet traffic but for securing service communication in both "trusted" and adversarial situations.
|
||||
- [Everything you should know about certificates and PKI but are too afraid to ask](https://smallstep.com/blog/everything-pki.html)
|
||||
|
||||
[autocert]: ../../configuration/readme.md#autocert
|
||||
[autocert directory]: ../../configuration/readme.md#autocert-directory
|
||||
[certificate]: ../../configuration/readme.md#certificates
|
||||
[certificate]: ../../configuration/readme.md#certificate
|
||||
[certificate_authority]: ../../configuration/readme.md#certificate-authority
|
||||
[certificate_key]: ../../configuration/readme.md#certificates
|
||||
[certificate_key]: ../../configuration/readme.md#certificate-key
|
||||
[override_certificate_name]: ../../configuration/readme.md#override-certificate-name
|
||||
[principles]: ../#why
|
||||
[zero-trust]: ../#why
|
||||
[principles]: ../docs/#why
|
||||
[zero-trust]: ../docs/#why
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
title: Getting the user's identity
|
||||
description: This article describes how to to get a user's identity with Pomerium.
|
||||
description: >-
|
||||
This article describes how to to get a user's identity with Pomerium.
|
||||
---
|
||||
|
||||
# Getting the user's identity
|
||||
|
|
@ -18,19 +19,19 @@ To secure your app with signed headers, you'll need the following:
|
|||
|
||||
A JWT attesting to the authorization of a given request is added to the downstream HTTP request header `x-pomerium-jwt-assertion`. You should verify that the JWT contains at least the following claims:
|
||||
|
||||
[JWT] | description
|
||||
:------: | ------------------------------------------------------------------------------------------------------
|
||||
`exp` | Expiration time in seconds since the UNIX epoch. Allow 1 minute for skew.
|
||||
`iat` | Issued-at time in seconds since the UNIX epoch. Allow 1 minute for skew.
|
||||
`aud` | The client's final domain e.g. `httpbin.corp.example.com`.
|
||||
`iss` | Issuer must be the URL of your authentication domain e.g. `authenticate.corp.example`.
|
||||
`sub` | Subject is the user's id. Can be used instead of the `x-pomerium-authenticated-user-id` header.
|
||||
`email` | Email is the user's email. Can be used instead of the `x-pomerium-authenticated-user-email` header.
|
||||
`groups` | Groups is the user's groups. Can be used instead of the `x-pomerium-authenticated-user-groups` header.
|
||||
| [JWT] | description |
|
||||
| :------: | ------------------------------------------------------------------------------------------------------ |
|
||||
| `exp` | Expiration time in seconds since the UNIX epoch. Allow 1 minute for skew. |
|
||||
| `iat` | Issued-at time in seconds since the UNIX epoch. Allow 1 minute for skew. |
|
||||
| `aud` | The client's final domain e.g. `httpbin.corp.example.com`. |
|
||||
| `iss` | Issuer must be the URL of your authentication domain e.g. `authenticate.corp.example`. |
|
||||
| `sub` | Subject is the user's id. Can be used instead of the `x-pomerium-authenticated-user-id` header. |
|
||||
| `email` | Email is the user's email. Can be used instead of the `x-pomerium-authenticated-user-email` header. |
|
||||
| `groups` | Groups is the user's groups. Can be used instead of the `x-pomerium-authenticated-user-groups` header. |
|
||||
|
||||
### Manual verification
|
||||
|
||||
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.
|
||||
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. The following guide assumes you are using the provided [docker-compose.yml] as a base and [httpbin]. Httpbin gives us a convenient way of inspecting client headers.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -48,17 +49,17 @@ 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.
|
||||
2. 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. `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.
|
||||
3. `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.
|
||||
4. 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. Finally, we want to cryptographically verify the validity of the token. To do this, we will need the signer's public key. You can simply copy and past the output of `cat ec_public.pem`.
|
||||
5. Finally, we want to cryptographically verify the validity of the token. To do this, we will need the signer's public key. You can simply copy and past the output of `cat ec_public.pem`.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,24 +0,0 @@
|
|||
#!/bin/bash
|
||||
# acme.sh : https://github.com/Neilpang/acme.sh
|
||||
# curl https://get.acme.sh | sh
|
||||
# NOTA BENE:
|
||||
# if you use a DNS service that supports API access, you may be able to automate
|
||||
# this process. See https://github.com/Neilpang/acme.sh/wiki/dnsapi
|
||||
|
||||
echo "=> first generate a certificate signing request!"
|
||||
$HOME/.acme.sh/acme.sh \
|
||||
--issue \
|
||||
-k ec-256 \
|
||||
-d '*.corp.example.com' \
|
||||
--dns \
|
||||
--yes-I-know-dns-manual-mode-enough-go-ahead-please
|
||||
|
||||
read -p "press anykey once you've updated your TXT entries"
|
||||
|
||||
$HOME/.acme.sh/acme.sh \
|
||||
--renew \
|
||||
--ecc \
|
||||
-k ec-256 \
|
||||
-d '*.corp.example.com' \
|
||||
--dns \
|
||||
--yes-I-know-dns-manual-mode-enough-go-ahead-please
|
||||
|
|
@ -5,7 +5,7 @@ description: >-
|
|||
for Pomerium. Please read it carefully.
|
||||
---
|
||||
|
||||
# Since 0.7.0
|
||||
# Since 0.8.0
|
||||
|
||||
## Breaking
|
||||
|
||||
|
|
@ -17,7 +17,6 @@ Although it's unlikely anyone ever used it, prior to 0.8.0 the policy configurat
|
|||
policy:
|
||||
- from: "https://example.com/some/path"
|
||||
```
|
||||
|
||||
The proxy and authorization server would simply ignore the path and route/authorize based on the host name.
|
||||
|
||||
With the introduction of `prefix`, `path` and `regex` fields to the policy route configuration, we decided not to support using a path in the `from` url, since the behavior was somewhat ambiguous and better handled by the explicit fields.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue