3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-06-03 11:22:45 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge remote-tracking branch 'origin/master' into feature/envoy

Browse source
This commit is contained in:
Caleb Doxsey 2020-05-08 11:17:30 -06:00 • committed by Travis Groth
parent 99e788a9b4
commit 02615b8b6c
48 changed files with 1283 additions and 561 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/configuration/examples/config/config.example.env
View file

@ -15,10 +15,12 @@ export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com
# Certificates can be loaded as files or base64 encoded bytes.
# See : https://www.pomerium.io/docs/reference/certificates
export CERTIFICATE_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer" # optional, defaults to `./cert.pem`
export CERTIFICATE_KEY_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key" # optional, defaults to `./certprivkey.pem`
# export CERTIFICATE="xxxxxx" # base64 encoded cert, eg. `base64 -i cert.pem`
# export CERTIFICATE_KEY="xxxx" # base64 encoded key, eg. `base64 -i privkey.pem`
export AUTOCERT=TRUE # Use Let's Encrypt to fetch certs. Port 80/443 must be internet accessible.
# export AUTOCERT_DIR="./certs" # The path where you want to place your certificates
# export CERTIFICATE_FILE="xxxx" # optional, defaults to `./cert.pem`
# export CERTIFICATE_KEY_FILE="xxx" # optional, defaults to `./certprivkey.pem`
# export CERTIFICATE="xxx" # base64 encoded cert, eg. `base64 -i cert.pem`
# export CERTIFICATE_KEY="xxx" # base64 encoded key, eg. `base64 -i privkey.pem`
# Generate 256 bit random keys e.g. `head -c32 /dev/urandom | base64`
export SHARED_SECRET="$(head -c32 /dev/urandom | base64)"

3
docs/configuration/examples/config/config.minimal.env
View file

@ -1,8 +1,7 @@
#!/bin/bash
# See : https://www.pomerium.io/docs/reference/certificates
export CERTIFICATE_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer" # optional, defaults to `./cert.pem`
export CERTIFICATE_KEY_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key" # optional, defaults to `./certprivkey.pem`
export AUTOCERT=TRUE # Use Let's Encrypt to fetch certs. Port 80/443 must be internet accessible.
# 256 bit random keys
export SHARED_SECRET="$(head -c32 /dev/urandom | base64)"

6
docs/configuration/examples/config/config.minimal.yaml
View file

@ -4,8 +4,10 @@
authenticate_service_url: https://authenticate.localhost.pomerium.io
# certificate settings: https://www.pomerium.io/docs/reference/certificates.html
certificate_file: "./_wildcard.localhost.pomerium.io.pem"
certificate_key_file: "./_wildcard.localhost.pomerium.io-key.pem"
autocert: true
# REMOVE FOR PRODUCTION
autocert_use_staging: true
# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
idp_provider: google

18
docs/configuration/examples/docker/autocert.docker-compose.yml Normal file
View file

@ -0,0 +1,18 @@
version: "3"
services:
pomerium:
image: pomerium/pomerium:v0.7.0
environment:
# Generate new secret keys. e.g. `head -c32 /dev/urandom | base64`
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
volumes:
# Use a volume to store ACME certificates
- pomerium:/data:rw
ports:
- 443:443
# https://httpbin.corp.beyondperimeter.com --> Pomerium --> http://httpbin
httpbin:
image: kennethreitz/httpbin:latest
expose:
- 80

205
docs/configuration/readme.md
View file

@ -80,7 +80,7 @@ Enabling the debug flag will result in sensitive information being logged!!!
:::
By default, JSON encoded logs are produced. Debug enables colored, human-readable logs to be streamed to [standard out](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)>). In production, it's recommended to be set to `false`.
By default, JSON encoded logs are produced. Debug enables colored, human-readable logs to be streamed to [standard out](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)>>>). In production, it's recommended to be set to `false`.
For example, if `true`
@ -127,23 +127,76 @@ Pomerium should _never_ be exposed to the internet without TLS encryption.
:::
### Certificate
### Autocert
- Environmental Variable: either `CERTIFICATE` or `CERTIFICATE_FILE`
- Config File Key: `certificate` or `certificate_file`
- Type: [base64 encoded] `string` or relative file location
- Required
- Environmental Variable: `AUTOCERT`
- Config File Key: `autocert`
- Type: `bool`
- Optional
Certificate is the x509 _public-key_ used to establish secure HTTP and gRPC connections.
Turning on autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS certificates from [Let's Encrypt][letsencrypt] for each of your managed pomerium routes as well as for the authenticate service. This setting must be used in conjunction with `Certificate Folder` as Autocert must have a place to persist, and share certificate data between services. Provides [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).
### Certificate Key
This setting can be useful in a situation where you do not have Pomerium behind a TLS terminating ingress or proxy that is already handling your public certificates on your behalf.
- Environmental Variable: either `CERTIFICATE_KEY` or `CERTIFICATE_KEY_FILE`
- Config File Key: `certificate_key` or `certificate_key_file`
:::warning
By using autocert, you agree to the [Let's Encrypt Subscriber Agreement](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf). There are [_strict_ usage limits](https://letsencrypt.org/docs/rate-limits/) per domain you should be aware of. Consider testing with `autocert_use_staging` first.
:::
:::warning
Autocert requires that port `443` be accessible from the internet in order to complete a [TLS-ALPN-01 challenge](https://letsencrypt.org/docs/challenge-types/#tls-alpn-01).
:::
### Autocert Directory
- Environmental Variable: either `AUTOCERT_DIR`
- Config File Key: `autocert_dir`
- Type: `string` pointing to the path of the directory
- Required if using Autocert setting
- Default:
- `/data/autocert` in published Pomerium docker images
- [$XDG_DATA_HOME](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
- `$HOME/.local/share/pomerium`
Autocert directory is path in which autocert will store x509 certificate data.
### Autocert Use Staging
- Environmental Variable: `AUTOCERT_USE_STAGING`
- Config File Key: `autocert_use_staging`
- Type: `bool`
- Optional
Let's Encrypt has strict [usage limits](https://letsencrypt.org/docs/rate-limits/). Enabling this setting allows you to use Let's Encrypt's [staging environment](https://letsencrypt.org/docs/staging-environment/) which has much more lax usage limits.
### Certificates
- Config File Key: `certificates` (not yet settable using environmental variables)
- Config File Key: `certificate` / `certificate_key`
- Config File Key: `certificate_file` / `certificate_key_file`
- Environmental Variable: `CERTIFICATE` / `CERTIFICATE_KEY`
- Environmental Variable: `CERTIFICATE_FILE` / `CERTIFICATE_KEY_FILE`
- Type: array of relative file locations `string`
- Type: [base64 encoded] `string`
- Required
- Type: certificate relative file location `string`
- Required (if insecure not set)
Certificate key is the x509 _private-key_ used to establish secure HTTP and gRPC connections.
Certificates are the x509 _public-key_ and _private-key_ used to establish secure HTTP and gRPC connections. Any combination of the above can be used together, and are additive. Use in conjunction with `Autocert` to get OCSP stapling.
For example, if specifying multiple certificates at once:
```yaml
certificates:
- cert: "$HOME/.acme.sh/authenticate.example.com_ecc/fullchain.cer"
key: "$HOME/.acme.sh/authenticate.example.com_ecc/authenticate.example.com.key"
- cert: "$HOME/.acme.sh/httpbin.example.com_ecc/fullchain.cer"
key: "$HOME/.acme.sh/httpbin.example.com_ecc/httpbin.example.com.key"
- cert: "$HOME/.acme.sh/prometheus.example.com_ecc/fullchain.cer"
key: "$HOME/.acme.sh/prometheus.example.com_ecc/prometheus.example.com.key"
```
### Global Timeouts
@ -321,62 +374,62 @@ Expose a prometheus format HTTP endpoint on the specified port. Disabled by defa
**Metrics tracked**
Name | Type | Description
--------------------------------------------- | --------- | -----------------------------------------------------------------------
boltdb_free_alloc_size_bytes | Gauge | Bytes allocated in free pages
boltdb_free_page_n | Gauge | Number of free pages on the freelist
boltdb_freelist_inuse_size_bytes | Gauge | Bytes used by the freelist
boltdb_open_txn | Gauge | number of currently open read transactions
boltdb_pending_page_n | Gauge | Number of pending pages on the freelist
boltdb_txn | Gauge | total number of started read transactions
boltdb_txn_cursor_total | Counter | Total number of cursors created
boltdb_txn_node_deref_total | Counter | Total number of node dereferences
boltdb_txn_node_total | Counter | Total number of node allocations
boltdb_txn_page_alloc_size_bytes_total | Counter | Total bytes allocated
boltdb_txn_page_total | Counter | Total number of page allocations
boltdb_txn_rebalance_duration_ms_total | Counter | Total time spent rebalancing
boltdb_txn_rebalance_total | Counter | Total number of node rebalances
boltdb_txn_spill_duration_ms_total | Counter | Total time spent spilling
boltdb_txn_spill_total | Counter | Total number of nodes spilled
boltdb_txn_split_total | Counter | Total number of nodes split
boltdb_txn_write_duration_ms_total | Counter | Total time spent writing to disk
boltdb_txn_write_total | Counter | Total number of writes performed
groupcache_cache_hits_total | Counter | Total cache hits in local or cluster cache
groupcache_cache_hits_total | Counter | Total cache hits in local or cluster cache
groupcache_gets_total | Counter | Total get request, including from peers
groupcache_loads_deduped_total | Counter | gets without cache hits after duplicate suppression
groupcache_loads_total | Counter | Total gets without cache hits
groupcache_local_load_errs_total | Counter | Total local load errors
groupcache_local_loads_total | Counter | Total good local loads
groupcache_peer_errors_total | Counter | Total errors from peers
groupcache_peer_loads_total | Counter | Total remote loads or cache hits without error
groupcache_server_requests_total | Counter | Total gets from peers
grpc_client_request_duration_ms | Histogram | GRPC client request duration by service
grpc_client_request_size_bytes | Histogram | GRPC client request size by service
grpc_client_requests_total | Counter | Total GRPC client requests made by service
grpc_client_response_size_bytes | Histogram | GRPC client response size by service
grpc_server_request_duration_ms | Histogram | GRPC server request duration by service
grpc_server_request_size_bytes | Histogram | GRPC server request size by service
grpc_server_requests_total | Counter | Total GRPC server requests made by service
grpc_server_response_size_bytes | Histogram | GRPC server response size by service
http_client_request_duration_ms | Histogram | HTTP client request duration by service
http_client_request_size_bytes | Histogram | HTTP client request size by service
http_client_requests_total | Counter | Total HTTP client requests made by service
http_client_response_size_bytes | Histogram | HTTP client response size by service
http_server_request_duration_ms | Histogram | HTTP server request duration by service
http_server_request_size_bytes | Histogram | HTTP server request size by service
http_server_requests_total | Counter | Total HTTP server requests handled by service
http_server_response_size_bytes | Histogram | HTTP server response size by service
pomerium_build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion
pomerium_config_checksum_int64 | Gauge | Currently loaded configuration checksum by service
pomerium_config_last_reload_success | Gauge | Whether the last configuration reload succeeded by service
pomerium_config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service
redis_conns | Gauge | Number of total connections in the pool
redis_hits_total | Counter | Total number of times free connection was found in the pool
redis_idle_conns | Gauge | Number of idle connections in the pool
redis_misses_total | Counter | Total number of times free connection was NOT found in the pool
redis_stale_conns_total | Counter | Total number of stale connections removed from the pool
redis_timeouts_total | Counter | Total number of times a wait timeout occurred
| Name | Type | Description |
| --------------------------------------------- | --------- | ----------------------------------------------------------------------- |
| boltdb_free_alloc_size_bytes | Gauge | Bytes allocated in free pages |
| boltdb_free_page_n | Gauge | Number of free pages on the freelist |
| boltdb_freelist_inuse_size_bytes | Gauge | Bytes used by the freelist |
| boltdb_open_txn | Gauge | number of currently open read transactions |
| boltdb_pending_page_n | Gauge | Number of pending pages on the freelist |
| boltdb_txn | Gauge | total number of started read transactions |
| boltdb_txn_cursor_total | Counter | Total number of cursors created |
| boltdb_txn_node_deref_total | Counter | Total number of node dereferences |
| boltdb_txn_node_total | Counter | Total number of node allocations |
| boltdb_txn_page_alloc_size_bytes_total | Counter | Total bytes allocated |
| boltdb_txn_page_total | Counter | Total number of page allocations |
| boltdb_txn_rebalance_duration_ms_total | Counter | Total time spent rebalancing |
| boltdb_txn_rebalance_total | Counter | Total number of node rebalances |
| boltdb_txn_spill_duration_ms_total | Counter | Total time spent spilling |
| boltdb_txn_spill_total | Counter | Total number of nodes spilled |
| boltdb_txn_split_total | Counter | Total number of nodes split |
| boltdb_txn_write_duration_ms_total | Counter | Total time spent writing to disk |
| boltdb_txn_write_total | Counter | Total number of writes performed |
| groupcache_cache_hits_total | Counter | Total cache hits in local or cluster cache |
| groupcache_cache_hits_total | Counter | Total cache hits in local or cluster cache |
| groupcache_gets_total | Counter | Total get request, including from peers |
| groupcache_loads_deduped_total | Counter | gets without cache hits after duplicate suppression |
| groupcache_loads_total | Counter | Total gets without cache hits |
| groupcache_local_load_errs_total | Counter | Total local load errors |
| groupcache_local_loads_total | Counter | Total good local loads |
| groupcache_peer_errors_total | Counter | Total errors from peers |
| groupcache_peer_loads_total | Counter | Total remote loads or cache hits without error |
| groupcache_server_requests_total | Counter | Total gets from peers |
| grpc_client_request_duration_ms | Histogram | GRPC client request duration by service |
| grpc_client_request_size_bytes | Histogram | GRPC client request size by service |
| grpc_client_requests_total | Counter | Total GRPC client requests made by service |
| grpc_client_response_size_bytes | Histogram | GRPC client response size by service |
| grpc_server_request_duration_ms | Histogram | GRPC server request duration by service |
| grpc_server_request_size_bytes | Histogram | GRPC server request size by service |
| grpc_server_requests_total | Counter | Total GRPC server requests made by service |
| grpc_server_response_size_bytes | Histogram | GRPC server response size by service |
| http_client_request_duration_ms | Histogram | HTTP client request duration by service |
| http_client_request_size_bytes | Histogram | HTTP client request size by service |
| http_client_requests_total | Counter | Total HTTP client requests made by service |
| http_client_response_size_bytes | Histogram | HTTP client response size by service |
| http_server_request_duration_ms | Histogram | HTTP server request duration by service |
| http_server_request_size_bytes | Histogram | HTTP server request size by service |
| http_server_requests_total | Counter | Total HTTP server requests handled by service |
| http_server_response_size_bytes | Histogram | HTTP server response size by service |
| pomerium_build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion |
| pomerium_config_checksum_int64 | Gauge | Currently loaded configuration checksum by service |
| pomerium_config_last_reload_success | Gauge | Whether the last configuration reload succeeded by service |
| pomerium_config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service |
| redis_conns | Gauge | Number of total connections in the pool |
| redis_hits_total | Counter | Total number of times free connection was found in the pool |
| redis_idle_conns | Gauge | Number of idle connections in the pool |
| redis_misses_total | Counter | Total number of times free connection was NOT found in the pool |
| redis_stale_conns_total | Counter | Total number of stale connections removed from the pool |
| redis_timeouts_total | Counter | Total number of times a wait timeout occurred |
### Tracing
@ -386,10 +439,10 @@ Each unit work is called a Span in a trace. Spans include metadata about the wor
#### Shared Tracing Settings
Config Key | Description | Required
:--------------- | :---------------------------------------------------------------- | --------
tracing_provider | The name of the tracing provider. (e.g. jaeger) | ✅
tracing_debug | Will disable [sampling](https://opencensus.io/tracing/sampling/). | ❌
| Config Key | Description | Required |
| :--------------- | :---------------------------------------------------------------- | -------- |
| tracing_provider | The name of the tracing provider. (e.g. jaeger) | ✅ |
| tracing_debug | Will disable [sampling](https://opencensus.io/tracing/sampling/). | ❌ |
#### Jaeger
@ -401,10 +454,10 @@ tracing_debug | Will disable [sampling](https://opencensus.io/tracing/samplin
- Service dependency analysis
- Performance / latency optimization
Config Key | Description | Required
:-------------------------------- | :------------------------------------------ | --------
tracing_jaeger_collector_endpoint | Url to the Jaeger HTTP Thrift collector. | ✅
tracing_jaeger_agent_endpoint | Send spans to jaeger-agent at this address. | ✅
| Config Key | Description | Required |
| :-------------------------------- | :------------------------------------------ | -------- |
| tracing_jaeger_collector_endpoint | Url to the Jaeger HTTP Thrift collector. | ✅ |
| tracing_jaeger_agent_endpoint | Send spans to jaeger-agent at this address. | ✅ |
#### Example

3
docs/docs/community/contributing.md
View file

@ -5,7 +5,6 @@ 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.
@ -93,4 +92,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)
[wild-card tls certificate]: ../reference/certificates.md
[tls certificates]: ../reference/certificates.md

4
docs/docs/quick-start/binary.md
View file

@ -13,7 +13,7 @@ The following quick-start guide covers how to configure and run Pomerium using t
## Prerequisites
- A configured [identity provider]
- A [wild-card TLS certificate]
- [TLS certificates]
## Download
@ -54,4 +54,4 @@ Browse to `external-httpbin.your.domain.example`. Connections between you and [h
[httpbin]: https://httpbin.org/
[identity provider]: ../docs/identity-providers/
[make]: https://en.wikipedia.org/wiki/Make_(software)
[wild-card tls certificate]: ../reference/certificates.md
[tls certificates]: ../reference/certificates.md

2
docs/docs/quick-start/from-source.md
View file

@ -75,4 +75,4 @@ Browse to `httpbin.localhost.pomerium.io`. Connections between you and [httpbin]
[httpbin]: https://httpbin.org/
[identity provider]: ../docs/identity-providers/
[make]: https://en.wikipedia.org/wiki/Make_(software)
[wild-card tls certificate]: ../reference/certificates.md
[tls certificates]: ../reference/certificates.md

6
docs/docs/quick-start/helm.md
View file

@ -17,7 +17,7 @@ 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/)
- A [wild-card TLS certificate]
- [TLS certificates]
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.
@ -25,7 +25,7 @@ In addition to sharing many of the same features as the Kubernetes quickstart gu
## Configure
Download and modify the following [helm_gke.sh script][./scripts/helm_gke.sh] to match your [identity provider] and [wild-card tls certificate] settings.
Download and modify the following [helm_gke.sh script][./scripts/helm_gke.sh] to match your [identity provider] and [TLS certificates] settings.
<<<@/scripts/helm_gke.sh
@ -56,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
[wild-card tls certificate]: ../reference/certificates.md
[tls certificates]: ../reference/certificates.md

6
docs/docs/quick-start/kubernetes.md
View file

@ -13,7 +13,7 @@ This quickstart will cover how to deploy Pomerium with Kubernetes.
## Prerequisites
- A configured [identity provider]
- A [wild-card TLS certificate]
- [TLS certificates]
- 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 [wild-card tls certificate] settings.
Edit [./kubernetes_gke.sh] making sure to change the identity provider secret value to match your [identity provider] and [TLS certificates] settings.
<<<@/docs/configuration/examples/kubernetes/kubernetes_gke.sh
@ -68,4 +68,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
[wild-card tls certificate]: ../reference/certificates.md
[tls certificates]: ../reference/certificates.md

22
docs/docs/quick-start/readme.md
View file

@ -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]
- A [wild-card TLS certificate]
- [TLS certificates]
## Configure
@ -26,12 +26,26 @@ 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`.
### Docker-compose
### Autocert Docker-compose
Ensure you have set up the requisite DNS and port forwarding in [TLS certificates]
Download the following `docker-compose.yml` file and modify it to:
- generate new secrets
- mount your [wild-card TLS certificate]
- 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 `config.yaml` [configuration file]
<<< @/docs/configuration/examples/docker/basic.docker-compose.yml
@ -58,4 +72,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
[wild-card tls certificate]: ../reference/certificates.md
[tls certificates]: ../reference/certificates.md

48
docs/docs/quick-start/synology.md
View file

@ -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]
- A [wild-card TLS certificate][certificate documentation]
- [TLS certificates][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
![Synology setup nginx reverse proxy](./img/synology-reverse-proxy.png)
@ -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`
![Synology assign wildcard certificate](./img/synology-certifciate-assignment.png)
@ -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.

111
docs/docs/reference/certificates.md
View file

@ -8,7 +8,9 @@ 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 how to generate and set up wild-card 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 a few options in how to generate and set up TLS certificates suitable for working with pomerium.
This guide uses the following tools and resources:
@ -16,13 +18,7 @@ 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.
::: warning
LetsEncrypt certificates must be renewed [every 90 days](https://letsencrypt.org/2015/11/09/why-90-days.html).
:::
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.
## Why
@ -32,81 +28,54 @@ 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
## How
## Setting up DNS
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.
![pomerium add a text entry to your dns records](./img/certificate-wildcard-domain.png)
Once you've setup your wildcard domain, we can use acme.sh to create a certificate-signing request with LetsEncrypt.
## 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
```
### 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
# 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:
# 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
LetsEncrypt will respond with the corresponding `TXT` record needed to verify our domain.
![pomerium add a text entry to your dns records](./img/certificate-domain-challenge.png)
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] | `$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` |
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`
Your end users will see a valid certificate for all domains delegated by Pomerium.
@ -114,6 +83,12 @@ Your end users will see a valid certificate for all domains delegated by Pomeriu
![pomerium certificates A+ ssl labs rating](./img/certificates-ssl-report.png)
::: 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:
@ -123,9 +98,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)
[certificate]: ../../configuration/readme.md#certificate
[certificate]: ../../configuration/readme.md#certificates
[certificate_authority]: ../../configuration/readme.md#certificate-authority
[certificate_key]: ../../configuration/readme.md#certificate-key
[certificate_key]: ../../configuration/readme.md#certificates
[override_certificate_name]: ../../configuration/readme.md#override-certificate-name
[principles]: ../docs/#why
[zero-trust]: ../docs/#why

24
docs/docs/reference/sh/generate_wildcard_cert.sh Executable file
View file

@ -0,0 +1,24 @@
#!/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