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

v0.4.0

Browse source 
deployment: prepare v0.4.0 (#350
Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com>
This commit is contained in:
Bobby DeSimone 2019-10-07 19:53:57 -07:00 • committed by GitHub
parent bca5caf77a
commit 28eae36ce1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
24 changed files with 222 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

2
VERSION
View file

@ -1 +1 @@
v0.3.0
v0.4.0

4
docs/.vuepress/config.js
View file

@ -26,10 +26,11 @@ module.exports = {
{ text: "Recipes", link: "/recipes/" },
{ text: "Community", link: "/community/" },
{
text: "🚧Dev", // current tagged version
text: "v0.4.0", // current tagged version
ariaLabel: "Version menu",
items: [
{ text: "🚧Dev", link: "https://master.docs.pomerium.io/docs" },
{ text: "v0.4.x", link: "https://0-4-0.docs.pomerium.io/docs" },
{ text: "v0.3.x", link: "https://0-3-0.docs.pomerium.io/docs" },
{ text: "v0.2.x", link: "https://0-2-0.docs.pomerium.io/docs" },
{ text: "v0.1.x", link: "https://0-1-0.docs.pomerium.io/docs" }
@ -90,6 +91,7 @@ module.exports = {
"reference/certificates",
"reference/impersonation",
"reference/programmatic-access",
"reference/getting-users-identity",
"reference/signed-headers",
"reference/examples",
"reference/reference",

23
docs/docs/CHANGELOG.md
View file

@ -1,15 +1,16 @@
# Changelog
## vUNRELEASED
## v0.4.0
### New
- Allow setting request headers for back-end requests on per route basis in policy. [GH-308]
- Add endpoint to support "forward-auth" integration with third-party ingresses and proxies. Supports [nginx]https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/, [nginx-ingress](https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/), and [Traefik](https://docs.traefik.io/middlewares/forwardauth/). [GH-324]
- Add insecure transport support. [GH-328]
- Add setting to override HTTPS backend's TLS Server Name. [GH-297]
- Add setting to set pomerium's encrypted session in a auth bearer token, or query param.
- Allow setting request headers on a per route basis in policy. [GH-308]
- Support "forward-auth" integration with third-party ingresses and proxies. [nginx](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/), [nginx-ingress](https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/), and [Traefik](https://docs.traefik.io/middlewares/forwardauth/) are currently supported. [GH-324]
- Add insecure transport / TLS termination support. [GH-328]
- Add setting to override a route's TLS Server Name. [GH-297]
- Pomerium's session can now be passed as a [bearer-auth header](https://tools.ietf.org/html/rfc6750) or [query string](https://en.wikipedia.org/wiki/Query_string) in addition to as a session cookie.
- Add host to the main request logger middleware. [GH-308]
- Add AWS cognito identity provider settings. [GH-314]
### Security
@ -21,6 +22,7 @@
- Fixed an issue where CSRF would fail if multiple tabs were open. [GH-306]
- Fixed an issue where pomerium would clean double slashes from paths. [GH-262]
- Fixed a bug where the impersonate form would persist an empty string for groups value if none set. [GH-303]
- Fixed HTTP redirect server which was not redirecting the correct hostname.
### Changed
@ -35,6 +37,12 @@
- Removed `AUTHENTICATE_INTERNAL_URL`/`authenticate_internal_url` which is no longer used.
## v0.3.1
### Security
- Fixes vulnerabilities fixed in [Go 1.13.1](https://groups.google.com/forum/m/#!msg/golang-announce/cszieYyuL9Q/g4Z7pKaqAgAJ) including CVE-2019-16276.
## v0.3.0
### New
@ -61,7 +69,7 @@
- Remove references to [service named ports](https://golang.org/src/net/lookup.go) and instead use their numeric equivalent. [GH-266]
## v0.2.0
## v0.2.1
### Security
@ -285,6 +293,7 @@
[gh-303]: https://github.com/pomerium/pomerium/issues/303
[gh-306]: https://github.com/pomerium/pomerium/issues/306
[gh-308]: https://github.com/pomerium/pomerium/issues/308
[gh-314]: https://github.com/pomerium/pomerium/pull/314
[gh-316]: https://github.com/pomerium/pomerium/pull/316
[gh-319]: https://github.com/pomerium/pomerium/issues/319
[gh-328]: https://github.com/pomerium/pomerium/issues/328

39
docs/docs/identity-providers/cognito.md
View file

@ -2,7 +2,7 @@
## Setting up AWS Cognito
Log in to the [AWS Console](https://console.aws.amazon.com) account.
Log in to the [AWS Console](https://console.aws.amazon.com) account.
Go to **Services** on the top menu, and then search for **Cognito**
@ -24,9 +24,9 @@ Assuming you have chosen to **Review defaults**, you will be presented with the
![AWS Cognito Pool Settings](./img/cognito-pool-settings.png)
You can enable Multi-Factor Authentication (MFA), change your Password requirements, Tag the pool, among many other settings.
You can enable Multi-Factor Authentication (MFA), change your Password requirements, Tag the pool, among many other settings.
If you need to make changes after creating your pool, be aware that some settings will recreate the pool rather than update the existing pool. This will also generate new **Client IDs** and **Client Secrets**. An example would be changing *How do you want your end users to sign in?* in **Attributes** from **Username** to **Email address or phone number**
If you need to make changes after creating your pool, be aware that some settings will recreate the pool rather than update the existing pool. This will also generate new **Client IDs** and **Client Secrets**. An example would be changing _How do you want your end users to sign in?_ in **Attributes** from **Username** to **Email address or phone number**
Once you have created the pool, you can create an **App Client**. This is where you will configure the Pomerium application settings. Choose **Add an App Client**
@ -42,12 +42,12 @@ After this is done, go to **App client settings** (in the Side menu under **App
In the setings for **Pomerium** app, put in the following details
|**Field**|**Description**|
|---------|---------------|
|Callback URL(s)|https://authenticate.corp.example.com/oauth2/callback|
|Enabled Identity Providers|Choose **Cognito User Pool**, unless you have set up another **Identity Provider** (eg SAML)|
|Allowed OAuth Flows|Authorization code grant|
|Allowed OAuth Scopes|Email, OpenID, Profile|
| **Field** | **Description** |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| Callback URL(s) | https://authenticate.corp.example.com/oauth2/callback |
| Enabled Identity Providers | Choose **Cognito User Pool**, unless you have set up another **Identity Provider** (eg SAML) |
| Allowed OAuth Flows | Authorization code grant |
| Allowed OAuth Scopes | Email, OpenID, Profile |
![AWS Cognito App Client Settings](./img/cognito-app-client-settings.png)
@ -77,17 +77,16 @@ An example of using this in a Kubernetes ConfigMap is below: -
apiVersion: v1
data:
config.yaml: |
# Main configuration flags : https://www.pomerium.io/reference/
authenticate_service_url: https://k8s-auth-prod.example.com # The URL you have set up for the Pomerium Authentication service
authenticate_internal_url: https://pomerium-authenticate-service.default.svc.cluster.local
authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local
idp_provider: oidc
idp_provider_url: https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER_POOL_ID}
idp_client_id: 304a12ktcc5djt9d7enj6dsjkg
idp_client_secret: "1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7"
idp_scopes: ["openid", "email", "profile"]
# Main configuration flags : https://www.pomerium.io/reference/
authenticate_service_url: https://k8s-auth-prod.example.com # The URL you have set up for the Pomerium Authentication service
authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local
idp_provider: oidc
idp_provider_url: https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER_POOL_ID}
idp_client_id: 304a12ktcc5djt9d7enj6dsjkg
idp_client_secret: "1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7"
idp_scopes: ["openid", "email", "profile"]
kind: ConfigMap
metadata:
name: pomerium-config

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

@ -8,7 +8,7 @@ meta:
# Pomerium using Helm
This quickstart will show you how to deploy Pomerium with Kubernetes.
This quick-start will show you how to deploy Pomerium with [Helm](https://helm.sh) on [Kubernetes](https://kubernetes.io).
## Prerequisites

BIN
docs/docs/quick-start/img/synology-reverse-proxy.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 90 KiB

After

Width:  |  Height:  |  Size: 952 KiB

Before After
Before After

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

@ -8,7 +8,7 @@ meta:
# Pomerium using Kubernetes
This quickstart will cover how to deploy Pomerium with Kubernetes. 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 use 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.
This quickstart will cover how to deploy Pomerium with Kubernetes.
## Prerequisites

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

@ -26,7 +26,7 @@ Pomerium is lightweight, can easily handle hundreds of concurrent requests, and
- A configured Google OAuth2 [identity provider]
- A [wild-card TLS certificate][certificate documentation]
Though any supported identity provider would work, this guide uses google.
Though any supported [identity provider] would work, this guide uses google.
## Port forwarding
@ -54,7 +54,7 @@ Set the following **Reverse Proxy Rules**.
| Destination Port | 8443 |
| HTTP/2 | Enabled |
| HSTS | Enabled |
| Destination Protocol | HTTPS |
| Destination Protocol | HTTP |
| Destination Hostname | localhost |
| Destination Port | 32443 |
@ -170,20 +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` |
| CERTIFICATE | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/fullchain.cer"` |
| CERTIFICATE_KEY | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/*.int.nas.example.io.key"` |
| CERTIFICATE_AUTHORITY | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/ca.cer"` |
| OVERRIDE_CERTIFICATE_NAME | `*.int.nas.example` |
| 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` |
| SHARED_SECRET | output of `head -c32 /dev/urandom | base64` |
| AUTHORIZE_SERVICE_URL | `https://localhost` |
| 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.

4
docs/docs/readme.md
View file

@ -24,7 +24,7 @@ Pomerium can be used to:
### System Level
Pomerium sits between end users and services which require strong authentication. After verifying identity with your IDP, Pomerium uses a configurable policy to decide how to route your user's request and if they are authorized to the service.
Pomerium sits between end users and services which require strong authentication. After verifying identity with your identity provider (IdP), Pomerium uses a configurable policy to decide how to route your user's request and if they are authorized to the service.
<img alt="pomerium architecture diagram" src="/pomerium-system-context.svg" width="65%">
@ -38,7 +38,7 @@ Pomerium is composed of 3 logical components:
- Verifies all requests with Authentication service
- Processes policy to determine external/internal route mappings
- Authentication Service
- Handles authentication flow to your IDP as needed
- Handles authentication flow to your IdP as needed
- Handles identity verification after initial Authentication
- Authorization Service
- Processes policy to determine permissions for each service

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

@ -42,7 +42,7 @@ Once you've setup your wildcard domain, we can use acme.sh to create a certifica
```bash
# Requires acme.sh @ https://github.com/Neilpang/acme.sh
# Install (after reviewing, obviously) by running :
# Install (after reviewing, obviously) by running :
# $ curl https://get.acme.sh | sh
$HOME/.acme.sh/acme.sh \
--issue \
@ -91,7 +91,7 @@ Success
Verify finished, start to sign.
Cert success.
-----BEGIN CERTIFICATE-----
.... snip...
.... 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
@ -101,12 +101,12 @@ And the full chain certs is there: $HOME/.acme.sh/*.corp.example.com_ecc/fullch
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] | `$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.

6
docs/docs/reference/examples/config/config.example.env
View file

@ -8,10 +8,10 @@
# export LOG_LEVEL="info" # optional, default is debug
export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com
export AUTHORIZE_SERVICE_URL=https://authorize.corp.beyondperimeter.com
# AUTHORIZE_SERVICE_URL defaults to `localhost:5443` in all-in-one mode
# export AUTHORIZE_SERVICE_URL=https://authorize.corp.beyondperimeter.com
# Certificates can be loaded as files or base64 encoded bytes. If neither is set, a
# pomerium will attempt to locate a pair in the root directory
# 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`

9
docs/docs/reference/examples/config/config.example.yaml
View file

@ -6,14 +6,17 @@
# log_level: info # optional, default is debug
authenticate_service_url: https://authenticate.corp.beyondperimeter.com
authorize_service_url: https://authorize.corp.beyondperimeter.com
# authorize_service_url: https://authorize.corp.beyondperimeter.com # usually a behind an ingress url
# Certificates can be loaded as files or base64 encoded bytes. If neither is set, a
# pomerium will attempt to locate a pair in the root directory
# Certificates can be loaded as files or base64 encoded bytes.
# certificate_file: "./cert.pem" # optional, defaults to `./cert.pem`
# certificate_key_file: "./privkey.pem" # optional, defaults to `./certprivkey.pem`
# certificate_authority_file: "./cert.pem"
# alternatively, insecure mode can be used if behind a TLS terminating ingress,
# or when using a sidecar proxy
# insecure_server: true
# base64 encoded cert, eg. `base64 -i cert.pem` / `base64 -i privkey.pem`
# certificate: |
# "xxxxxx"

2
docs/docs/reference/examples/docker/basic.docker-compose.yml
View file

@ -1,7 +1,7 @@
version: "3"
services:
pomerium:
image: pomerium/pomerium:master
image: pomerium/pomerium:v0.4.0
environment:
# Generate new secret keys. e.g. `head -c32 /dev/urandom | base64`
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=

33
docs/docs/reference/examples/docker/nginx.docker-compose.yml
View file

@ -12,10 +12,11 @@ services:
- /var/run/docker.sock:/tmp/docker.sock:ro
pomerium-authenticate:
image: pomerium/pomerium:master # or `build: .` to build from source
image: pomerium/pomerium:v0.4.0 # or `build: .` to build from source
restart: always
environment:
- SERVICES=authenticate
- INSECURE_SERVER=TRUE
# NOTE!: Replace with your identity provider settings https://www.pomerium.io/docs/identity-providers.html
# - IDP_PROVIDER=google
# - IDP_PROVIDER_URL=https://accounts.google.com
@ -24,62 +25,50 @@ services:
# - IDP_SERVICE_ACCOUNT=REPLACE_ME
# NOTE! Generate new secret keys! e.g. `head -c32 /dev/urandom | base64`
# Generated secret keys must match between services
- SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
# Tell nginx how to proxy pomerium's routes
- VIRTUAL_PROTO=https
- VIRTUAL_PROTO=http
- VIRTUAL_HOST=authenticate.corp.beyondperimeter.com
- VIRTUAL_PORT=443
volumes:
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
# Retrieve non-secret config keys from the config file : https://www.pomerium.io/docs/reference/reference/
# See `config.example.yaml` and modify to fit your needs.
- ../config/config.example.yaml:/pomerium/config.yaml:ro
expose:
- 443
pomerium-proxy:
image: pomerium/pomerium:master # or `build: .` to build from source
image: pomerium/pomerium:v0.4.0 # or `build: .` to build from source
restart: always
environment:
- SERVICES=proxy
- INSECURE_SERVER=TRUE
# IMPORTANT! If you are running pomerium behind another ingress (loadbalancer/firewall/etc)
# you must tell pomerium proxy how to communicate using an internal hostname for RPC
- AUTHORIZE_SERVICE_URL=https://pomerium-authorize
- AUTHORIZE_SERVICE_URL=http://pomerium-authorize:443
# When communicating internally, rPC is going to get a name conflict expecting an external
# facing certificate name (i.e. authenticate-service.local vs *.corp.example.com).
- OVERRIDE_CERTIFICATE_NAME=*.corp.beyondperimeter.com
- SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
# Tell nginx how to proxy pomerium's routes
- VIRTUAL_PROTO=https
- VIRTUAL_PROTO=http
- VIRTUAL_HOST=*.corp.beyondperimeter.com
- VIRTUAL_PORT=443
volumes:
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
# Retrieve non-secret config keys from the config file : https://www.pomerium.io/docs/reference/reference/
# See `config.example.yaml` and modify to fit your needs.
- ../config/config.example.yaml:/pomerium/config.yaml:ro
expose:
- 443
pomerium-authorize:
image: pomerium/pomerium:master # or `build: .` to build from source
image: pomerium/pomerium:v0.4.0 # or `build: .` to build from source
restart: always
environment:
- SERVICES=authorize
- SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
# Tell nginx how to proxy pomerium's routes
- VIRTUAL_PROTO=https
- VIRTUAL_HOST=authorize.corp.beyondperimeter.com
- VIRTUAL_PORT=443
- GRPC_INSECURE=TRUE
- GRPC_ADDRESS=:443
volumes:
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
# Retrieve non-secret config keys from the config file : https://www.pomerium.io/docs/reference/reference/
# See `config.example.yaml` and modify to fit your needs.
- ../config/config.example.yaml:/pomerium/config.yaml:ro

15
docs/docs/reference/examples/kubernetes/ingress.nginx.yml
View file

@ -1,12 +1,14 @@
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: pomerium-http
name: pomerium-ingress
annotations:
kubernetes.io/ingress.class: "nginx"
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/proxy-buffer-size: "16k"
# kubernetes.io/tls-acme: "true"
# certmanager.k8s.io/issuer: "letsencrypt-prod"
# nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
# nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
# nginx.ingress.kubernetes.io/proxy-buffer-size: "16k"
# to avoid ingress routing, enable
# nginx.ingress.kubernetes.io/ssl-passthrough: "true"
@ -16,7 +18,6 @@ spec:
hosts:
- "*.corp.beyondperimeter.com"
- "authenticate.corp.beyondperimeter.com"
- "authorize.corp.beyondperimeter.com"
rules:
- host: "*.corp.beyondperimeter.com"
@ -25,7 +26,7 @@ spec:
- paths:
backend:
serviceName: pomerium-proxy-service
servicePort: https
servicePort: http
- host: "authenticate.corp.beyondperimeter.com"
http:
@ -33,4 +34,4 @@ spec:
- paths:
backend:
serviceName: pomerium-authenticate-service
servicePort: https
servicePort: http

3
docs/docs/reference/examples/kubernetes/kubernetes-config.yaml
View file

@ -1,4 +1,7 @@
# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
address: ":80"
insecure_server: true
authenticate_service_url: https://authenticate.corp.beyondperimeter.com
authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local

18
docs/docs/reference/examples/kubernetes/kubernetes_nginx.sh Normal file
View file

@ -0,0 +1,18 @@
#!/bin/bash
echo "=> create config from kubernetes-config.yaml which we will mount"
kubectl create configmap config --from-file="config.yaml"="kubernetes-config.yaml"
echo "=> create our random shared-secret and cookie-secret keys as envars"
kubectl create secret generic shared-secret --from-literal=shared-secret=$(head -c32 /dev/urandom | base64)
kubectl create secret generic cookie-secret --from-literal=cookie-secret=$(head -c32 /dev/urandom | base64)
echo "=> deploy pomerium proxy, authorize, and authenticate"
kubectl apply -f pomerium-proxy.yml
kubectl apply -f pomerium-authenticate.yml
kubectl apply -f pomerium-authorize.yml
echo "=> deploy our test app, httpbin"
kubectl apply -f httpbin.yml
echo "=> deploy nginx-ingress"
kubectl apply -f ingress.yml

32
docs/docs/reference/examples/kubernetes/pomerium-authenticate.yml
View file

@ -2,12 +2,10 @@ apiVersion: v1
kind: Service
metadata:
name: pomerium-authenticate-service
annotations:
cloud.google.com/app-protocols: '{"https":"HTTPS"}'
spec:
ports:
- port: 443
name: https
- port: 80
name: http
selector:
app: pomerium-authenticate
type: NodePort
@ -29,13 +27,13 @@ spec:
app: pomerium-authenticate
spec:
containers:
- image: pomerium/pomerium:master
- image: pomerium/pomerium:v0.4.0
name: pomerium-authenticate
args:
- --config=/etc/pomerium/config.yaml
ports:
- containerPort: 443
name: https
- containerPort: 80
name: http
protocol: TCP
env:
- name: SERVICES
@ -50,27 +48,17 @@ spec:
secretKeyRef:
name: cookie-secret
key: cookie-secret
- name: CERTIFICATE
valueFrom:
secretKeyRef:
name: certificate
key: certificate
- name: CERTIFICATE_KEY
valueFrom:
secretKeyRef:
name: certificate-key
key: certificate-key
readinessProbe:
httpGet:
path: /ping
port: 443
scheme: HTTPS
port: 80
scheme: HTTP
livenessProbe:
httpGet:
path: /ping
port: 443
scheme: HTTPS
initialDelaySeconds: 10
port: 80
scheme: HTTP
initialDelaySeconds: 5
timeoutSeconds: 1
volumeMounts:
- mountPath: /etc/pomerium/

43
docs/docs/reference/examples/kubernetes/pomerium-authorize.yml
View file

@ -2,15 +2,13 @@ apiVersion: v1
kind: Service
metadata:
name: pomerium-authorize-service
annotations:
cloud.google.com/app-protocols: '{"https":"HTTPS"}'
spec:
ports:
- port: 443
name: https
- port: 80
name: grpc
selector:
app: pomerium-authorize
type: NodePort
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
@ -29,13 +27,13 @@ spec:
app: pomerium-authorize
spec:
containers:
- image: pomerium/pomerium:master
- image: pomerium/pomerium:v0.4.0
name: pomerium-authorize
args:
- --config=/etc/pomerium/config.yaml
ports:
- containerPort: 443
name: https
- containerPort: 80
name: grpc
protocol: TCP
env:
- name: SERVICES
@ -45,28 +43,17 @@ spec:
secretKeyRef:
name: shared-secret
key: shared-secret
- name: CERTIFICATE
valueFrom:
secretKeyRef:
name: certificate
key: certificate
- name: CERTIFICATE_KEY
valueFrom:
secretKeyRef:
name: certificate-key
key: certificate-key
readinessProbe:
httpGet:
path: /ping
port: 443
scheme: HTTPS
tcpSocket:
port: 80
initialDelaySeconds: 5
periodSeconds: 10
livenessProbe:
httpGet:
path: /ping
port: 443
scheme: HTTPS
initialDelaySeconds: 10
timeoutSeconds: 1
tcpSocket:
port: 80
initialDelaySeconds: 15
periodSeconds: 20
volumeMounts:
- mountPath: /etc/pomerium/
name: config

32
docs/docs/reference/examples/kubernetes/pomerium-proxy.yml
View file

@ -2,14 +2,12 @@ apiVersion: v1
kind: Service
metadata:
name: pomerium-proxy-service
annotations:
cloud.google.com/app-protocols: '{"https":"HTTPS"}'
spec:
ports:
- port: 443
- port: 80
protocol: TCP
name: https
targetPort: https
name: http
targetPort: http
selector:
app: pomerium-proxy
type: NodePort
@ -31,13 +29,13 @@ spec:
app: pomerium-proxy
spec:
containers:
- image: pomerium/pomerium:master
- image: pomerium/pomerium:v0.4.0
name: pomerium-proxy
args:
- --config=/etc/pomerium/config.yaml
ports:
- containerPort: 443
name: https
- containerPort: 80
name: http
protocol: TCP
env:
- name: SERVICES
@ -52,26 +50,16 @@ spec:
secretKeyRef:
name: cookie-secret
key: cookie-secret
- name: CERTIFICATE
valueFrom:
secretKeyRef:
name: certificate
key: certificate
- name: CERTIFICATE_KEY
valueFrom:
secretKeyRef:
name: certificate-key
key: certificate-key
readinessProbe:
httpGet:
path: /ping
port: 443
scheme: HTTPS
port: 80
scheme: HTTP
livenessProbe:
httpGet:
path: /ping
port: 443
scheme: HTTPS
port: 80
scheme: HTTP
initialDelaySeconds: 10
timeoutSeconds: 1
volumeMounts:

41
docs/docs/reference/getting-users-identity.md Normal file
View file

@ -0,0 +1,41 @@
---
title: Getting the user's identity
description: >-
This article describes how to to get a user's identity with Pomerium.
---
# Getting the user's identity
This article describes how to retrieve a user's identity from a pomerium managed application.
## Headers
By default, pomerium passes the following [response headers] to it's downstream applications to identify the requesting users.
| Header | description |
| :------------------------------------- | -------------------------------------------------------------- |
| `x-pomerium-authenticated-user-id` | Subject is the user's id. |
| `x-pomerium-authenticated-user-email` | Email is the user's email. |
| `x-pomerium-authenticated-user-groups` | Groups is the user's groups. |
| `x-pomerium-iap-jwt-assertion` | **Recommended** Contains the user's details as a signed [JWT]. |
In an ideal environment, the cryptographic authenticity of the user's identifying headers should be enforced at the protocol level using mTLS.
### Recommended : Signed JWT header
For whatever reason, (e.g. an attacker bypasses pomerium's protocol encryption, or it is accidentally turned off), it is possible that the `x-pomerium-authenticated-user-{email,id,groups}` headers could be forged. Therefore, it is highly recommended to use and validate the [JWT] assertion header which adds an additional layer of authenticity.
Verify that the [JWT assertion header](./signed-headers.md) conforms to the following constraints:
| [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 `pomerium-proxy`. |
| `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]: https://jwt.io
[response headers]: https://developer.mozilla.org/en-US/docs/Glossary/Response_header

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

@ -610,7 +610,7 @@ Authenticate Service URL is the externally accessible URL for the authenticate s
- Config File Key: `authorize_service_url`
- Type: `URL`
- Required
- Example: `https://authorize.corp.example.com` or `https://pomerium-authorize-service.default.svc.cluster.local`
- Example: `https://authorize.corp.example.com` or `https://pomerium-authorize-service.default.svc.cluster.local` or `https://localhost:5443`
Authorize Service URL is the location of the internally accessible authorize service. NOTE: Unlike authenticate, authorize has no publicly accessible http handlers so this setting is purely for gRPC communication.

2
docs/docs/releases.md
View file

@ -54,6 +54,8 @@ To see difference between releases, please refer to the changelog and upgrading
For convenience, we maintain hosted documentation for each tagged release. The format for which is `https://{MAJOR}-{MINOR}-{PATCH}.docs.pomerium.io`. For example:
- [github@master](https://master.docs.pomerium.io/)
- [v0.4.0](https://0-4-0.docs.pomerium.io/)
- [v0.3.0](https://0-3-0.docs.pomerium.io/)
- [v0.2.0](https://0-2-0.docs.pomerium.io/)
- [v0.1.0](https://0-1-0.docs.pomerium.io/)

32
docs/docs/upgrading.md
View file

@ -9,10 +9,40 @@ description: >-
## Since 0.3.0
### Breaking: No default certificate location
### Breaking
#### Removed Authenticate Internal URL
The authenticate service no longer uses gRPC to do back channel communication. As a result, `AUTHENTICATE_INTERNAL_URL`/`authenticate_internal_url` is no longer required.
#### No default certificate location
In previous versions, if no explicit certificate pair (in base64 or file form) was set, Pomerium would make a last ditch effort to check for certificate files (`cert.key`/`privkey.pem`) in the root directory. With the introduction of insecure server configuration, we've removed that functionality. If there settings for certificates and insecure server mode are unset, pomerium will give a appropriate error instead of a failed to find/open certificate error.
#### Authorize service health-check is non-http
The Authorize service will no longer respond to `HTTP`-based healthcheck queries when run as a distinct service (vs all-in-one). As an alternative, you can used on TCP based checks. For example, if using [Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-tcp-liveness-probe):
```yaml
---
readinessProbe:
tcpSocket:
port: 443
initialDelaySeconds: 5
periodSeconds: 10
livenessProbe:
tcpSocket:
port: 443
initialDelaySeconds: 15
periodSeconds: 20
```
### Non-breaking changes
#### All-in-one
If service mode (`SERVICES`/`services`) is set to `all`, gRPC communication with the authorize service will by default occur over localhost, on port `:5443`.
## Since 0.2.0
Pomerium `v0.3.0` has no known breaking changes compared to `v0.2.0`.