docs: refactor sections, consolidate examples (#1164)

examples/config/config.example.env

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
+
+# Main configuration flags
+# export ADDRESS=":8443"                      # optional, default is 443
+# export POMERIUM_DEBUG=true                  # optional, default is false
+# export SERVICE="all"                        # optional, default is all
+# export LOG_LEVEL="info"                     # optional, default is debug
+
+export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com
+# AUTHORIZE_SERVICE_URL service url will default to localhost in all-in-one mode,
+# otherwise it should be set to a "behind-the-ingress" routable url
+# export AUTHORIZE_SERVICE_URL=https://pomerium-authorize-service.default.svc.cluster.local
+# export CACHE_SERVICE_URL=https://pomerium-cache-service.default.svc.cluster.local
+
+# Certificates can be loaded as files or base64 encoded bytes.
+# See : https://www.pomerium.io/docs/reference/certificates
+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)"
+export COOKIE_SECRET="$(head -c32 /dev/urandom | base64)"
+# If set, a JWT based signature is appended to each request header `x-pomerium-jwt-assertion`
+# export SIGNING_KEY="Replace with base64'd private key from ./scripts/self-signed-sign-key.sh"
+
+# Identity Provider Settings
+
+# Azure
+# export IDP_PROVIDER="azure"
+# export IDP_PROVIDER_URL="https://login.microsoftonline.com/REPLACEME/v2.0"
+# export IDP_CLIENT_ID="REPLACEME
+# export IDP_CLIENT_SECRET="REPLACEME"
+
+## GOOGLE
+export IDP_PROVIDER="google"
+export IDP_PROVIDER_URL="https://accounts.google.com" # optional for google
+
+# OKTA
+# export IDP_PROVIDER="okta"
+# export IDP_CLIENT_ID="REPLACEME"
+# export IDP_CLIENT_SECRET="REPLACEME"
+# export IDP_PROVIDER_URL="https://REPLACEME.oktapreview.com/oauth2/default"
+
+# OneLogin
+# export IDP_PROVIDER="onelogin"
+# export IDP_CLIENT_ID="REPLACEME"
+# export IDP_CLIENT_SECRET="REPLACEME"
+# export IDP_PROVIDER_URL="https://openid-connect.onelogin.com/oidc" #optional, defaults to `https://openid-connect.onelogin.com/oidc`
+
+# export SCOPE="openid email" # generally, you want the default OIDC scopes
+
+# Proxied routes and per-route policies are defined in a policy provided either
+# directly as a base64 encoded yaml/json file, or as the policy key in the configuration
+# file
+export POLICY="$(base64 ./docs/configuration/examples/config/policy.example.yaml)"
+
+# For Group data you must set an IDP_SERVICE_ACCOUNT
+# https://www.pomerium.com/configuration/#identity-provider-service-account
+# export IDP_SERVICE_ACCOUNT=$( echo YOUR_SERVICE_ACCOUNT | base64)

examples/config/config.example.yaml

@@ -0,0 +1,85 @@
+# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
+#
+# address: ":8443" # optional, default is 443
+# pomerium_debug: true # optional, default is false
+# service: "all" # optional, default is all
+# log_level: info # optional, default is debug
+
+authenticate_service_url: https://authenticate.corp.beyondperimeter.com
+# authorize service url will default to localhost in all-in-one mode, otherwise
+# it should be set to a "behind-the-ingress" routable url
+# authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local
+# cache_service_url: https://pomerium-cache-service.default.svc.cluster.local
+
+# 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"
+# certificate_key: |
+#  "xxxx"
+
+# Generate 256 bit random keys  e.g. `head -c32 /dev/urandom | base64`
+# shared_secret: hsJIQsx9KKx4qVlggg/T3AuLTmVu0uHhwTQgMPlVs7U=
+# cookie_secret: WwMtDXWaRDMBQCylle8OJ+w4kLIDIGd8W3cB4/zFFtg=
+# If set, a JWT based signature is appended to each request header `x-pomerium-jwt-assertion`
+# signing_key: "Replace with base64'd private key from ./scripts/self-signed-sign-key.sh"
+
+# Identity Provider Settings
+
+# Azure
+# idp_provider: "azure"
+# idp_provider_url: "https://login.microsoftonline.com/REPLACEME/v2.0"
+# idp_client_id: "REPLACEME
+# idp_client_secret: "REPLACEME"
+
+## GOOGLE
+# idp_provider: "google"
+# idp_provider_url: "https://accounts.google.com" # optional for google
+# idp_client_id: "REPLACEME
+# idp_client_secret: "REPLACEME
+
+# IF GSUITE and you want to get user groups you will need to set a service account
+# see identity provider docs for gooogle for more info :
+# idp_service_account: $(echo '{"impersonate_user": "bdd@pomerium.io"}' | base64)
+
+# OKTA
+# idp_provider: "okta"
+# idp_client_id: "REPLACEME"
+# idp_client_secret: "replaceme"
+# idp_provider_url: "https://REPLACEME.oktapreview.com/oauth2/default"
+
+# OneLogin
+# idp_provider: "onelogin"
+# idp_client_id: "REPLACEME"
+# idp_client_secret: "REPLACEME"
+# idp_provider_url: "https://openid-connect.onelogin.com/oidc" #optional, defaults to `https://openid-connect.onelogin.com/oidc`
+
+# scope: "openid email" # generally, you want the default OIDC scopes
+
+# For Group data you must set an IDP_SERVICE_ACCOUNT
+# idp_service_account: YOUR_SERVICE_ACCOUNT
+
+# Proxied routes and per-route policies are defined in a policy block
+policy:
+  - from: https://httpbin.corp.beyondperimeter.com
+    to: http://httpbin
+    allowed_domains:
+      - pomerium.io
+    cors_allow_preflight: true
+    timeout: 30s
+  - from: https://external-httpbin.corp.beyondperimeter.com
+    to: https://httpbin.org
+    allowed_domains:
+      - gmail.com
+  - from: https://hello.corp.beyondperimeter.com
+    to: http://hello:8080
+    allowed_groups:
+      - admins@pomerium.io

examples/config/config.minimal.env

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+# See : https://www.pomerium.io/docs/reference/certificates
+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)"
+export COOKIE_SECRET="$(head -c32 /dev/urandom | base64)"

examples/config/config.minimal.yaml

@@ -0,0 +1,25 @@
+# See detailed configuration settings : https://www.pomerium.io/docs/reference/reference/
+
+# this is the domain the identity provider will callback after a user authenticates
+authenticate_service_url: https://authenticate.localhost.pomerium.io
+
+# certificate settings:  https://www.pomerium.io/docs/reference/certificates.html
+autocert: true
+
+# REMOVE FOR PRODUCTION
+autocert_use_staging: true
+
+# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
+idp_provider: google
+idp_client_id: REPLACE_ME
+idp_client_secret: REPLACE_ME
+
+# Generate 256 bit random keys  e.g. `head -c32 /dev/urandom | base64`
+cookie_secret: WwMtDXWaRDMBQCylle8OJ+w4kLIDIGd8W3cB4/zFFtg=
+
+# https://www.pomerium.io/configuration/#policy
+policy:
+  - from: https://httpbin.localhost.pomerium.io
+    to: https://httpbin.org
+    allowed_users:
+      - bdd@pomerium.io

examples/config/policy.example.yaml

@@ -0,0 +1,31 @@
+# This file contains only policy and route configuration details. Other
+# configuration settings required by pomerium are excluded for clarity.
+# See: https://www.pomerium.io/docs/reference/reference/
+#
+# For a complete self contained configuration see : config.example.yaml.
+# Or, mix and match a policy file (this) with env vars : config.example.env
+
+# Proxied routes and per-route policies are defined in a policy block
+# NOTA BENE: You must uncomment the bellow 'policy' key if you are loading policy as a file.
+# policy:
+- from: https://httpbin.corp.beyondperimeter.com
+  to: http://localhost:8000
+  allowed_domains:
+    - pomerium.io
+  cors_allow_preflight: true
+  timeout: 30s
+- from: https://external-httpbin.corp.beyondperimeter.com
+  to: https://httpbin.org
+  allowed_domains:
+    - gmail.com
+- from: https://weirdlyssl.corp.beyondperimeter.com
+  to: http://neverssl.com
+  allowed_users:
+    - bdd@pomerium.io
+  allowed_groups:
+    - admins
+    - developers
+- from: https://hello.corp.beyondperimeter.com
+  to: http://localhost:8080
+  allowed_groups:
+    - admins@pomerium.io