3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-05-30 09:27:19 +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: "Recipes", link: "/recipes/" },
{ text: "Community", link: "/community/" }, { text: "Community", link: "/community/" },
{ {
text: "🚧Dev", // current tagged version text: "v0.4.0", // current tagged version
ariaLabel: "Version menu", ariaLabel: "Version menu",
items: [ items: [
{ text: "🚧Dev", link: "https://master.docs.pomerium.io/docs" }, { 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.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.2.x", link: "https://0-2-0.docs.pomerium.io/docs" },
{ text: "v0.1.x", link: "https://0-1-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/certificates",
"reference/impersonation", "reference/impersonation",
"reference/programmatic-access", "reference/programmatic-access",
"reference/getting-users-identity",
"reference/signed-headers", "reference/signed-headers",
"reference/examples", "reference/examples",
"reference/reference", "reference/reference",

23
docs/docs/CHANGELOG.md
View file

@ -1,15 +1,16 @@
# Changelog # Changelog
## vUNRELEASED ## v0.4.0
### New ### New
- Allow setting request headers for back-end requests on per route basis in policy. [GH-308] - Allow setting request headers on a 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] - 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 support. [GH-328] - Add insecure transport / TLS termination support. [GH-328]
- Add setting to override HTTPS backend's TLS Server Name. [GH-297] - Add setting to override a route's TLS Server Name. [GH-297]
- Add setting to set pomerium's encrypted session in a auth bearer token, or query param. - 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 host to the main request logger middleware. [GH-308]
- Add AWS cognito identity provider settings. [GH-314]
### Security ### Security
@ -21,6 +22,7 @@
- Fixed an issue where CSRF would fail if multiple tabs were open. [GH-306] - 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 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 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 ### Changed
@ -35,6 +37,12 @@
- Removed `AUTHENTICATE_INTERNAL_URL`/`authenticate_internal_url` which is no longer used. - 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 ## v0.3.0
### New ### 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] - 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 ### Security
@ -285,6 +293,7 @@
[gh-303]: https://github.com/pomerium/pomerium/issues/303 [gh-303]: https://github.com/pomerium/pomerium/issues/303
[gh-306]: https://github.com/pomerium/pomerium/issues/306 [gh-306]: https://github.com/pomerium/pomerium/issues/306
[gh-308]: https://github.com/pomerium/pomerium/issues/308 [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-316]: https://github.com/pomerium/pomerium/pull/316
[gh-319]: https://github.com/pomerium/pomerium/issues/319 [gh-319]: https://github.com/pomerium/pomerium/issues/319
[gh-328]: https://github.com/pomerium/pomerium/issues/328 [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 ## 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** 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) ![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** 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 In the setings for **Pomerium** app, put in the following details
|**Field**|**Description**| | **Field** | **Description** |
|---------|---------------| | -------------------------- | -------------------------------------------------------------------------------------------- |
|Callback URL(s)|https://authenticate.corp.example.com/oauth2/callback| | 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)| | 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 Flows | Authorization code grant |
|Allowed OAuth Scopes|Email, OpenID, Profile| | Allowed OAuth Scopes | Email, OpenID, Profile |
![AWS Cognito App Client Settings](./img/cognito-app-client-settings.png) ![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 apiVersion: v1
data: data:
config.yaml: | config.yaml: |
# Main configuration flags : https://www.pomerium.io/reference/ # 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_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
authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local
idp_provider: oidc
idp_provider: oidc idp_provider_url: https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER_POOL_ID}
idp_provider_url: https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER_POOL_ID} idp_client_id: 304a12ktcc5djt9d7enj6dsjkg
idp_client_id: 304a12ktcc5djt9d7enj6dsjkg idp_client_secret: "1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7"
idp_client_secret: "1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7" idp_scopes: ["openid", "email", "profile"]
idp_scopes: ["openid", "email", "profile"]
kind: ConfigMap kind: ConfigMap
metadata: metadata:
name: pomerium-config name: pomerium-config

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

@ -8,7 +8,7 @@ meta:
# Pomerium using Helm # 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 ## 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 # 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 ## 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 configured Google OAuth2 [identity provider]
- A [wild-card TLS certificate][certificate documentation] - 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 ## Port forwarding
@ -54,7 +54,7 @@ Set the following **Reverse Proxy Rules**.
| Destination Port | 8443 | | Destination Port | 8443 |
| HTTP/2 | Enabled | | HTTP/2 | Enabled |
| HSTS | Enabled | | HSTS | Enabled |
| Destination Protocol | HTTPS | | Destination Protocol | HTTP |
| Destination Hostname | localhost | | Destination Hostname | localhost |
| Destination Port | 32443 | | 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. Go to **Environment** tab.
| Field | Value | | Field | Value |
| ------------------------- | ---------------------------------------------------------------------------------------- | | ------------------------ | --------------------------------------------------------------- |
| POLICY | output of `base64 -i policy.yaml` | | POLICY | output of `base64 -i policy.yaml` |
| CERTIFICATE | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/fullchain.cer"` | | INSECURE_SERVER | `TRUE`, internal routing within docker will not be encrypted. |
| CERTIFICATE_KEY | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/*.int.nas.example.io.key"` | | IDP_CLIENT_SECRET | Values from setting up your [identity provider] |
| CERTIFICATE_AUTHORITY | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/ca.cer"` | | IDP_CLIENT_ID | Values from setting up your [identity provider] |
| OVERRIDE_CERTIFICATE_NAME | `*.int.nas.example` | | IDP_PROVIDER | Values from setting up your [identity provider] (e.g. `google`) |
| IDP_CLIENT_SECRET | Values from setting up your [identity provider] | | COOKIE_SECRET | output of `head -c32 /dev/urandom | base64` |
| IDP_CLIENT_ID | Values from setting up your [identity provider] | | AUTHENTICATE_SERVICE_URL | `https://authenticate.int.nas.example` |
| 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` |
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. 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 ### 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%"> <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 - Verifies all requests with Authentication service
- Processes policy to determine external/internal route mappings - Processes policy to determine external/internal route mappings
- Authentication Service - Authentication Service
- Handles authentication flow to your IDP as needed - Handles authentication flow to your IdP as needed
- Handles identity verification after initial Authentication - Handles identity verification after initial Authentication
- Authorization Service - Authorization Service
- Processes policy to determine permissions for each 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 ```bash
# Requires acme.sh @ https://github.com/Neilpang/acme.sh # 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 # $ curl https://get.acme.sh | sh
$HOME/.acme.sh/acme.sh \ $HOME/.acme.sh/acme.sh \
--issue \ --issue \
@ -91,7 +91,7 @@ Success
Verify finished, start to sign. Verify finished, start to sign.
Cert success. Cert success.
-----BEGIN CERTIFICATE----- -----BEGIN CERTIFICATE-----
.... snip... .... snip...
-----END CERTIFICATE----- -----END CERTIFICATE-----
Your cert is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.cer 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 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: Here's how the above certificates signed by LetsEncrypt correspond to their respective Pomerium configuration settings:
Pomerium Config | Certificate file | Pomerium Config | Certificate file |
--------------------------- | -------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------- |
[CERTIFICATE] | `$HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer` | [CERTIFICATE] | `$HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer` |
[CERTIFICATE_KEY] | `$HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key` | [CERTIFICATE_KEY] | `$HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key` |
[CERTIFICATE_AUTHORITY] | `$HOME/.acme.sh/*.corp.example.com_ecc/ca.cer` | [CERTIFICATE_AUTHORITY] | `$HOME/.acme.sh/*.corp.example.com_ecc/ca.cer` |
[OVERRIDE_CERTIFICATE_NAME] | `*.corp.example.com` | [OVERRIDE_CERTIFICATE_NAME] | `*.corp.example.com` |
Your end users will see a valid certificate for all domains delegated by Pomerium. 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 LOG_LEVEL="info" # optional, default is debug
export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com 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 # Certificates can be loaded as files or base64 encoded bytes.
# pomerium will attempt to locate a pair in the root directory
# See : https://www.pomerium.io/docs/reference/certificates # 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_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_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 # log_level: info # optional, default is debug
authenticate_service_url: https://authenticate.corp.beyondperimeter.com 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 # Certificates can be loaded as files or base64 encoded bytes.
# pomerium will attempt to locate a pair in the root directory
# certificate_file: "./cert.pem" # optional, defaults to `./cert.pem` # certificate_file: "./cert.pem" # optional, defaults to `./cert.pem`
# certificate_key_file: "./privkey.pem" # optional, defaults to `./certprivkey.pem` # certificate_key_file: "./privkey.pem" # optional, defaults to `./certprivkey.pem`
# certificate_authority_file: "./cert.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` # base64 encoded cert, eg. `base64 -i cert.pem` / `base64 -i privkey.pem`
# certificate: | # certificate: |
# "xxxxxx" # "xxxxxx"

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

@ -1,7 +1,7 @@
version: "3" version: "3"
services: services:
pomerium: pomerium:
image: pomerium/pomerium:master image: pomerium/pomerium:v0.4.0
environment: environment:
# Generate new secret keys. e.g. `head -c32 /dev/urandom | base64` # Generate new secret keys. e.g. `head -c32 /dev/urandom | base64`
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI= - 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 - /var/run/docker.sock:/tmp/docker.sock:ro
pomerium-authenticate: 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 restart: always
environment: environment:
- SERVICES=authenticate - SERVICES=authenticate
- INSECURE_SERVER=TRUE
# NOTE!: Replace with your identity provider settings https://www.pomerium.io/docs/identity-providers.html # NOTE!: Replace with your identity provider settings https://www.pomerium.io/docs/identity-providers.html
# - IDP_PROVIDER=google # - IDP_PROVIDER=google
# - IDP_PROVIDER_URL=https://accounts.google.com # - IDP_PROVIDER_URL=https://accounts.google.com
@ -24,62 +25,50 @@ services:
# - IDP_SERVICE_ACCOUNT=REPLACE_ME # - IDP_SERVICE_ACCOUNT=REPLACE_ME
# NOTE! Generate new secret keys! e.g. `head -c32 /dev/urandom | base64` # NOTE! Generate new secret keys! e.g. `head -c32 /dev/urandom | base64`
# Generated secret keys must match between services # Generated secret keys must match between services
- SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M= - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI= - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
# Tell nginx how to proxy pomerium's routes # Tell nginx how to proxy pomerium's routes
- VIRTUAL_PROTO=https - VIRTUAL_PROTO=http
- VIRTUAL_HOST=authenticate.corp.beyondperimeter.com - VIRTUAL_HOST=authenticate.corp.beyondperimeter.com
- VIRTUAL_PORT=443 - VIRTUAL_PORT=443
volumes: 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 - ../config/config.example.yaml:/pomerium/config.yaml:ro
expose: expose:
- 443 - 443
pomerium-proxy: 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 restart: always
environment: environment:
- SERVICES=proxy - SERVICES=proxy
- INSECURE_SERVER=TRUE
# IMPORTANT! If you are running pomerium behind another ingress (loadbalancer/firewall/etc) # 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 # 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 # 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). # facing certificate name (i.e. authenticate-service.local vs *.corp.example.com).
- OVERRIDE_CERTIFICATE_NAME=*.corp.beyondperimeter.com
- SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M= - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI= - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
# Tell nginx how to proxy pomerium's routes # Tell nginx how to proxy pomerium's routes
- VIRTUAL_PROTO=https - VIRTUAL_PROTO=http
- VIRTUAL_HOST=*.corp.beyondperimeter.com - VIRTUAL_HOST=*.corp.beyondperimeter.com
- VIRTUAL_PORT=443 - VIRTUAL_PORT=443
volumes: 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 - ../config/config.example.yaml:/pomerium/config.yaml:ro
expose: expose:
- 443 - 443
pomerium-authorize: 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 restart: always
environment: environment:
- SERVICES=authorize - SERVICES=authorize
- SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M= - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
# Tell nginx how to proxy pomerium's routes - GRPC_INSECURE=TRUE
- VIRTUAL_PROTO=https - GRPC_ADDRESS=:443
- VIRTUAL_HOST=authorize.corp.beyondperimeter.com
- VIRTUAL_PORT=443
volumes: 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/ # 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. # See `config.example.yaml` and modify to fit your needs.
- ../config/config.example.yaml:/pomerium/config.yaml:ro - ../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 apiVersion: extensions/v1beta1
kind: Ingress kind: Ingress
metadata: metadata:
name: pomerium-http name: pomerium-ingress
annotations: annotations:
kubernetes.io/ingress.class: "nginx" kubernetes.io/ingress.class: "nginx"
nginx.ingress.kubernetes.io/force-ssl-redirect: "true" # kubernetes.io/tls-acme: "true"
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" # certmanager.k8s.io/issuer: "letsencrypt-prod"
nginx.ingress.kubernetes.io/proxy-buffer-size: "16k" # 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 # to avoid ingress routing, enable
# nginx.ingress.kubernetes.io/ssl-passthrough: "true" # nginx.ingress.kubernetes.io/ssl-passthrough: "true"
@ -16,7 +18,6 @@ spec:
hosts: hosts:
- "*.corp.beyondperimeter.com" - "*.corp.beyondperimeter.com"
- "authenticate.corp.beyondperimeter.com" - "authenticate.corp.beyondperimeter.com"
- "authorize.corp.beyondperimeter.com"
rules: rules:
- host: "*.corp.beyondperimeter.com" - host: "*.corp.beyondperimeter.com"
@ -25,7 +26,7 @@ spec:
- paths: - paths:
backend: backend:
serviceName: pomerium-proxy-service serviceName: pomerium-proxy-service
servicePort: https servicePort: http
- host: "authenticate.corp.beyondperimeter.com" - host: "authenticate.corp.beyondperimeter.com"
http: http:
@ -33,4 +34,4 @@ spec:
- paths: - paths:
backend: backend:
serviceName: pomerium-authenticate-service 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/ # Main configuration flags : https://www.pomerium.io/docs/reference/reference/
address: ":80"
insecure_server: true
authenticate_service_url: https://authenticate.corp.beyondperimeter.com authenticate_service_url: https://authenticate.corp.beyondperimeter.com
authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local 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 kind: Service
metadata: metadata:
name: pomerium-authenticate-service name: pomerium-authenticate-service
annotations:
cloud.google.com/app-protocols: '{"https":"HTTPS"}'
spec: spec:
ports: ports:
- port: 443 - port: 80
name: https name: http
selector: selector:
app: pomerium-authenticate app: pomerium-authenticate
type: NodePort type: NodePort
@ -29,13 +27,13 @@ spec:
app: pomerium-authenticate app: pomerium-authenticate
spec: spec:
containers: containers:
- image: pomerium/pomerium:master - image: pomerium/pomerium:v0.4.0
name: pomerium-authenticate name: pomerium-authenticate
args: args:
- --config=/etc/pomerium/config.yaml - --config=/etc/pomerium/config.yaml
ports: ports:
- containerPort: 443 - containerPort: 80
name: https name: http
protocol: TCP protocol: TCP
env: env:
- name: SERVICES - name: SERVICES
@ -50,27 +48,17 @@ spec:
secretKeyRef: secretKeyRef:
name: cookie-secret name: cookie-secret
key: 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: readinessProbe:
httpGet: httpGet:
path: /ping path: /ping
port: 443 port: 80
scheme: HTTPS scheme: HTTP
livenessProbe: livenessProbe:
httpGet: httpGet:
path: /ping path: /ping
port: 443 port: 80
scheme: HTTPS scheme: HTTP
initialDelaySeconds: 10 initialDelaySeconds: 5
timeoutSeconds: 1 timeoutSeconds: 1
volumeMounts: volumeMounts:
- mountPath: /etc/pomerium/ - mountPath: /etc/pomerium/

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

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

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

@ -2,14 +2,12 @@ apiVersion: v1
kind: Service kind: Service
metadata: metadata:
name: pomerium-proxy-service name: pomerium-proxy-service
annotations:
cloud.google.com/app-protocols: '{"https":"HTTPS"}'
spec: spec:
ports: ports:
- port: 443 - port: 80
protocol: TCP protocol: TCP
name: https name: http
targetPort: https targetPort: http
selector: selector:
app: pomerium-proxy app: pomerium-proxy
type: NodePort type: NodePort
@ -31,13 +29,13 @@ spec:
app: pomerium-proxy app: pomerium-proxy
spec: spec:
containers: containers:
- image: pomerium/pomerium:master - image: pomerium/pomerium:v0.4.0
name: pomerium-proxy name: pomerium-proxy
args: args:
- --config=/etc/pomerium/config.yaml - --config=/etc/pomerium/config.yaml
ports: ports:
- containerPort: 443 - containerPort: 80
name: https name: http
protocol: TCP protocol: TCP
env: env:
- name: SERVICES - name: SERVICES
@ -52,26 +50,16 @@ spec:
secretKeyRef: secretKeyRef:
name: cookie-secret name: cookie-secret
key: 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: readinessProbe:
httpGet: httpGet:
path: /ping path: /ping
port: 443 port: 80
scheme: HTTPS scheme: HTTP
livenessProbe: livenessProbe:
httpGet: httpGet:
path: /ping path: /ping
port: 443 port: 80
scheme: HTTPS scheme: HTTP
initialDelaySeconds: 10 initialDelaySeconds: 10
timeoutSeconds: 1 timeoutSeconds: 1
volumeMounts: 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` - Config File Key: `authorize_service_url`
- Type: `URL` - Type: `URL`
- Required - 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. 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: 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.3.0](https://0-3-0.docs.pomerium.io/)
- [v0.2.0](https://0-2-0.docs.pomerium.io/) - [v0.2.0](https://0-2-0.docs.pomerium.io/)
- [v0.1.0](https://0-1-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 ## 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. 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 ## Since 0.2.0
Pomerium `v0.3.0` has no known breaking changes compared to `v0.2.0`. Pomerium `v0.3.0` has no known breaking changes compared to `v0.2.0`.