v0.5.0 (#375)

VERSION

@@ -1 +1 @@
-v0.4.2
+v0.5.0

docs/.vuepress/config.js

@@ -23,8 +23,8 @@ module.exports = {
     lastUpdated: "Last Updated",
     nav: [
       { text: "Documentation", link: "/docs/" },
+      { text: "Configuration", link: "/configuration/" },
       { text: "Recipes", link: "/recipes/" },
-      { text: "Community", link: "/community/" },
       { text: "Enterprise", link: "/enterprise/" },
 
       {
@@ -32,6 +32,7 @@ module.exports = {
         ariaLabel: "Version menu",
         items: [
           { text: "🚧Dev", link: "https://master.docs.pomerium.io/docs" },
+          { text: "v0.5.x", link: "https://0-5-0.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" },
@@ -83,12 +84,24 @@ module.exports = {
             "identity-providers/",
             "identity-providers/azure",
             "identity-providers/cognito",
-            "identity-providers/gitlab",
             "identity-providers/google",
             "identity-providers/okta",
             "identity-providers/one-login"
           ]
         },
+        {
+          title: "Community",
+          collapsable: false,
+          path: "/docs/community/",
+          type: "group",
+          sidebarDepth: 0,
+          children: [
+            "community/",
+            "community/contributing",
+            "community/code-of-conduct",
+            "community/security"
+          ]
+        },
         {
           title: "Reference",
           collapsable: true,
@@ -102,22 +115,11 @@ module.exports = {
             "reference/programmatic-access",
             "reference/getting-users-identity",
             "reference/signed-headers",
-            "reference/examples",
+            // "reference/examples",
-            "reference/reference",
             "reference/production-deployment"
           ]
         }
       ],
-      "/community/": [
-        {
-          title: "Community",
-          type: "group",
-
-          collapsable: false,
-          sidebarDepth: 1,
-          children: ["", "contributing", "code-of-conduct", "security"]
-        }
-      ],
       "/recipes/": [
         {
           title: "Recipes",
@@ -136,6 +138,15 @@ module.exports = {
           sidebarDepth: 1,
           children: [""]
         }
+      ],
+      "/configuration/": [
+        {
+          title: "Configuration",
+          type: "group",
+          collapsable: false,
+          sidebarDepth: 1,
+          children: ["", "examples"]
+        }
       ]
     }
   }

docs/.vuepress/public/_redirects

@@ -1,3 +1,17 @@
+/docs/reference/reference			/configuration/
+/docs/reference/reference.html		/configuration/
+
+/community/							/docs/community/
+/community/index.html				/docs/community/
+/community/contributing				/docs/community/contributing.html
+/community/contributing.html		/docs/community/contributing.html
+/community/code-of-conduct			/docs/community/code-of-conduct.html		
+/community/code-of-conduct.html		/docs/community/code-of-conduct.html		
+/community/security					/docs/community/security.html		
+/community/security.html			/docs/community/security.html		
+
+/docs/reference/examples.html		/configuration/examples.html
+
 /reference/				/docs/reference/reference.html
 /guide/					/docs/quick-start/
 /guide/kubernetes.html	/docs/quick-start/kubernetes.html

docs/configuration/examples.md

@@ -1,10 +1,19 @@
 ---
+title: Examples
+lang: en-US
 sidebarDepth: 2
+meta:
+  - name: keywords
+    content: pomerium community help bugs updates features
+
+description: >-
+  This document describes how you users can stay up to date with pomerium,
+  report issues, get help, and suggest new features.
 ---
 
-# Config Examples
+# Examples
 
-A collection of copy-and-paste-able configurations for various types of clouds, use-cases, and deployments. These files can also be found in the git repository in the `docs/docs/examples/` directory.
+A collection of copy-and-paste-able configurations for various types of clouds, use-cases, and deployments. These files can also be found in the git repository in the `docs/configuration/examples/` directory.
 
 :::tip
 
@@ -14,15 +23,15 @@ Remember to set your identity provider settings and to generate new secret keys!
 
 [[toc]]
 
-## Configurations
+## Settings
 
-#### Configuration File
+### Configuration File
 
-<<< @/docs/docs/reference/examples/config/config.example.yaml
+<<< @/docs/configuration/examples/config/config.example.yaml
 
-#### Environmental Variables
+### Environmental Variables
 
-<<< @/docs/docs/reference/examples/config/config.example.env
+<<< @/docs/configuration/examples/config/config.example.env
 
 ## Binary
 
@@ -40,7 +49,7 @@ Customize for your identity provider and run `./bin/pomerium -config config.yaml
 
 Uses the [latest pomerium build](https://hub.docker.com/r/pomerium/pomerium) from docker hub. Docker and docker-compose are great tools for standing up and testing multiple service, and containers without having to stand-up a full on cluster.
 
-#### Basic
+### All-in-One
 
 - Minimal container-based configuration.
 - Docker and Docker-Compose based.
@@ -51,9 +60,9 @@ Customize for your identity provider run `docker-compose up -f basic.docker-comp
 
 #### basic.docker-compose.yml
 
-<<< @/docs/docs/reference/examples/docker/basic.docker-compose.yml
+<<< @/docs/configuration/examples/docker/basic.docker-compose.yml
 
-#### NGINX micro-services
+### Distinct Services
 
 - Docker and Docker-Compose based.
 - Uses pre-configured built-in nginx load balancer
@@ -64,7 +73,7 @@ Customize for your identity provider run `docker-compose up -f nginx.docker-comp
 
 #### nginx.docker-compose.yml
 
-<<< @/docs/docs/reference/examples/docker/nginx.docker-compose.yml
+<<< @/docs/configuration/examples/docker/nginx.docker-compose.yml
 
 ## Helm
 
@@ -73,13 +82,13 @@ Customize for your identity provider run `docker-compose up -f nginx.docker-comp
 - Routes default to hosted version of httpbin.org
 - Includes installer script
 
-#### helm_gke.sh
+### GKE
 
 - Uses Google Kubernetes Engine's built-in ingress to do [HTTPS load balancing]
 
 <<< @/scripts/helm_gke.sh
 
-#### helm_aws.sh
+### AWS ECS
 
 - Uses Amazon Elastic Container Service
 
@@ -95,27 +104,27 @@ Customize for your identity provider run `docker-compose up -f nginx.docker-comp
 
 #### kubernetes_gke
 
-<<< @/docs/docs/reference/examples/kubernetes/kubernetes_gke.sh
+<<< @/docs/configuration/examples/kubernetes/kubernetes_gke.sh
 
 #### kubernetes-config.yaml
 
-<<< @/docs/docs/reference/examples/kubernetes/kubernetes-config.yaml
+<<< @/docs/configuration/examples/kubernetes/kubernetes-config.yaml
 
 #### pomerium-authenticate.yml
 
-<<< @/docs/docs/reference/examples/kubernetes/pomerium-authenticate.yml
+<<< @/docs/configuration/examples/kubernetes/pomerium-authenticate.yml
 
 #### pomerium-authorize.yml
 
-<<< @/docs/docs/reference/examples/kubernetes/pomerium-authorize.yml
+<<< @/docs/configuration/examples/kubernetes/pomerium-authorize.yml
 
 #### pomerium-proxy.yml
 
-<<< @/docs/docs/reference/examples/kubernetes/pomerium-proxy.yml
+<<< @/docs/configuration/examples/kubernetes/pomerium-proxy.yml
 
 #### ingress.yml
 
-<<< @/docs/docs/reference/examples/kubernetes/ingress.yml
+<<< @/docs/configuration/examples/kubernetes/ingress.yml
 
 [helloworld]: https://hub.docker.com/r/tutum/hello-world
 [httpbin]: https://httpbin.org/

docs/configuration/examples/config/config.example.env

@@ -33,12 +33,6 @@ export COOKIE_SECRET="$(head -c32 /dev/urandom | base64)"
 # export IDP_CLIENT_ID="REPLACEME
 # export IDP_CLIENT_SECRET="REPLACEME"
 
-# Gitlab
-# export IDP_PROVIDER="gitlab"
-# export IDP_PROVIDER_URL="https://gitlab.onprem.example.com" # optional, defaults to `https://gitlab.com`
-# 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
@@ -64,4 +58,4 @@ export IDP_PROVIDER_URL="https://accounts.google.com" # optional for google
 # 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/docs/examples/config/policy.example.yaml)"
+export POLICY="$(base64 ./docs/configuration/examples/config/policy.example.yaml)"

docs/configuration/examples/config/config.example.yaml

@@ -39,12 +39,6 @@ authenticate_service_url: https://authenticate.corp.beyondperimeter.com
 # idp_client_id: "REPLACEME
 # idp_client_secret: "REPLACEME"
 
-# Gitlab
-# idp_provider: "gitlab"
-# idp_provider_url: "https://gitlab.onprem.example.com" # optional, defaults to `https://gitlab.com`
-# idp_client_id: "REPLACEME
-# idp_client_secret: "REPLACEME"
-
 ## GOOGLE
 # idp_provider: "google"
 # idp_provider_url: "https://accounts.google.com" # optional for google

docs/configuration/examples/docker/basic.docker-compose.yml

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

docs/configuration/examples/docker/nginx.docker-compose.yml

@@ -12,7 +12,7 @@ services:
       - /var/run/docker.sock:/tmp/docker.sock:ro
 
   pomerium-authenticate:
-    image: pomerium/pomerium:v0.4.2 # or `build: .` to build from source
+    image: pomerium/pomerium:v0.5.0 # or `build: .` to build from source
     restart: always
     environment:
       - SERVICES=authenticate
@@ -38,7 +38,7 @@ services:
       - 443
 
   pomerium-proxy:
-    image: pomerium/pomerium:v0.4.2 # or `build: .` to build from source
+    image: pomerium/pomerium:v0.5.0 # or `build: .` to build from source
     restart: always
     environment:
       - SERVICES=proxy
@@ -60,7 +60,7 @@ services:
       - 443
 
   pomerium-authorize:
-    image: pomerium/pomerium:v0.4.2 # or `build: .` to build from source
+    image: pomerium/pomerium:v0.5.0 # or `build: .` to build from source
     restart: always
     environment:
       - SERVICES=authorize

docs/configuration/examples/kubernetes/pomerium-authenticate.yml

@@ -27,7 +27,7 @@ spec:
         app: pomerium-authenticate
     spec:
       containers:
-        - image: pomerium/pomerium:v0.4.2
+        - image: pomerium/pomerium:v0.5.0
           name: pomerium-authenticate
           args:
             - --config=/etc/pomerium/config.yaml

docs/configuration/examples/kubernetes/pomerium-authorize.yml

@@ -27,7 +27,7 @@ spec:
         app: pomerium-authorize
     spec:
       containers:
-        - image: pomerium/pomerium:v0.4.2
+        - image: pomerium/pomerium:v0.5.0
           name: pomerium-authorize
           args:
             - --config=/etc/pomerium/config.yaml

docs/configuration/examples/kubernetes/pomerium-proxy.yml

@@ -29,7 +29,7 @@ spec:
         app: pomerium-proxy
     spec:
       containers:
-        - image: pomerium/pomerium:v0.4.2
+        - image: pomerium/pomerium:v0.5.0
           name: pomerium-proxy
           args:
             - --config=/etc/pomerium/config.yaml

docs/configuration/readme.md

@@ -1,17 +1,15 @@
 ---
-title: Config Reference
+title: Settings
 lang: en-US
 sidebarDepth: 1
 meta:
   - name: keywords
-    content: pomerium identity-access-proxy beyondcorp zero-trust reverse-proxy ztn
+    content: configuration options settings pomerium
 ---
 
-# Options
+# Configuration Settings
 
-Pomerium can be configured using a configuration file ([YAML]/[JSON]/[TOML]) or [environmental variables]. In general, environmental variable keys are identical to config file keys but are in uppercase.
+Pomerium can be configured using a configuration file ([YAML]/[JSON]/[TOML]) or [environmental variables]. In general, environmental variable keys are identical to config file keys but are in uppercase. If you are coming from a kubernetes or docker background this should feel familiar. If not, check out the following primers.
-
-If you are coming from a kubernetes or docker background this should feel familiar. If not, check out the following primers.
 
 - [Store config in the environment](https://12factor.net/config)
 - [Kubernetes: Environment variables](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/)
@@ -22,11 +20,11 @@ Using both [environmental variables] and config file keys is allowed and encoura
 
 Pomerium will automatically reload the configuration file if it is changed. At this time, only policy is re-configured when this reload occurs, but additional options may be added in the future. It is suggested that your policy is stored in a configuration file so that you can take advantage of this feature.
 
-# Global settings
+## Shared Settings
 
 These are configuration variables shared by all services, in all service modes.
 
-## Service Mode
+### Service Mode
 
 - Environmental Variable: `SERVICES`
 - Config File Key: `services`
@@ -36,7 +34,7 @@ These are configuration variables shared by all services, in all service modes.
 
 Service mode sets the pomerium service(s) to run. If testing, you may want to set to `all` and run pomerium in "all-in-one mode." In production, you'll likely want to spin up several instances of each service mode for high availability.
 
-## Address
+### Address
 
 - Environmental Variable: `ADDRESS`
 - Config File Key: `address`
@@ -47,29 +45,29 @@ Service mode sets the pomerium service(s) to run. If testing, you may want to se
 
 Address specifies the host and port to serve HTTP requests from. If empty, `:443` is used.
 
-## Administrators
+### Administrators
 
 - Environmental Variable: `ADMINISTRATORS`
 - Config File Key: `administrators`
 - Type: slice of `string`
 - Example: `"admin@example.com,admin2@example.com"`
 
-Administrative users are [super user](https://en.wikipedia.org/wiki/Superuser) that can sign in as another user or group. User impersonation allows administrators to temporarily sign in as a different user.
+Administrative users are [super user](https://en.wikipedia.org/wiki/Superuser) that can sign in as another user or group. User impersonation allows administrators to temporarily impersonate a different user.
 
-## Shared Secret
+### Shared Secret
 
 - Environmental Variable: `SHARED_SECRET`
 - Config File Key: `shared_secret`
 - Type: [base64 encoded] `string`
 - Required
 
-Shared Secret is the base64 encoded 256-bit key used to mutually authenticate requests between services. It's critical that secret keys are random, and store safely. Use a key management system or `/dev/urandom/` to generate a key. For example:
+Shared Secret is the base64 encoded 256-bit key used to mutually authenticate requests between services. It's critical that secret keys are random, and stored safely. Use a key management system or `/dev/urandom/` to generate a key. For example:
 
 ```
 head -c32 /dev/urandom | base64
 ```
 
-## Debug
+### Debug
 
 - Environmental Variable: `POMERIUM_DEBUG`
 - Config File Key: `pomerium_debug`
@@ -102,7 +100,7 @@ If `false`
 {"level":"info","OverrideCertificateName":"","addr":"auth.corp.beyondperimeter.com:443","time":"2019-02-18T10:41:03-08:00","message":"proxy/authenticator: grpc connection"}
 ```
 
-## Log Level
+### Log Level
 
 - Environmental Variable: `LOG_LEVEL`
 - Config File Key: `log_level`
@@ -112,7 +110,7 @@ If `false`
 
 Log level sets the global logging level for pomerium. Only logs of the desired level and above will be logged.
 
-## Insecure Server
+### Insecure Server
 
 - Environmental Variable: `INSECURE_SERVER`
 - Config File Key: `insecure_server`
@@ -127,7 +125,7 @@ This setting can be useful in a situation where you have Pomerium behind a TLS t
 Pomerium should _never_ be exposed to the internet without TLS encryption.
 :::
 
-## Certificate
+### Certificate
 
 - Environmental Variable: either `CERTIFICATE` or `CERTIFICATE_FILE`
 - Config File Key: `certificate` or `certificate_file`
@@ -136,7 +134,7 @@ Pomerium should _never_ be exposed to the internet without TLS encryption.
 
 Certificate is the x509 _public-key_ used to establish secure HTTP and gRPC connections.
 
-## Certificate Key
+### Certificate Key
 
 - Environmental Variable: either `CERTIFICATE_KEY` or `CERTIFICATE_KEY_FILE`
 - Config File Key: `certificate_key` or `certificate_key_file`
@@ -145,7 +143,7 @@ Certificate is the x509 _public-key_ used to establish secure HTTP and gRPC conn
 
 Certificate key is the x509 _private-key_ used to establish secure HTTP and gRPC connections.
 
-## Global Timeouts
+### Global Timeouts
 
 - Environmental Variables: `TIMEOUT_READ` `TIMEOUT_WRITE` `TIMEOUT_READ_HEADER` `TIMEOUT_IDLE`
 - Config File Key: `timeout_read` `timeout_write` `timeout_read_header` `timeout_idle`
@@ -159,11 +157,11 @@ Timeouts set the global server timeouts. For route-specific timeouts, see [polic
 
 > For a deep dive on timeout values see [these](https://blog.cloudflare.com/the-complete-guide-to-golang-net-http-timeouts/) [two](https://blog.cloudflare.com/exposing-go-on-the-internet/) excellent blog posts.
 
-## GRPC Options
+### GRPC Options
 
 These settings control upstream connections to the Authorize service.
 
-### GRPC Address
+#### GRPC Address
 
 - Environmental Variable: `GRPC_ADDRESS`
 - Config File Key: `grpc_address`
@@ -173,7 +171,7 @@ These settings control upstream connections to the Authorize service.
 
 Address specifies the host and port to serve GRPC requests from. Defaults to `:443` (or `:5443` in all in one mode).
 
-### GRPC Insecure
+#### GRPC Insecure
 
 - Environmental Variable: `GRPC_INSECURE`
 - Config File Key: `grpc_insecure`
@@ -182,7 +180,7 @@ Address specifies the host and port to serve GRPC requests from. Defaults to `:4
 
 If set, GRPC Insecure disables transport security for communication between the proxy and authorize components. If running in all-in-one mode, defaults to true as communication will run over localhost's own socket.
 
-### GRPC Client Timeout
+#### GRPC Client Timeout
 
 Maximum time before canceling an upstream RPC request. During transient failures, the proxy will retry upstreams for this duration, if possible. You should leave this high enough to handle backend service restart and rediscovery so that client requests do not fail.
 
@@ -191,7 +189,7 @@ Maximum time before canceling an upstream RPC request. During transient failures
 - Type: [Go Duration](https://golang.org/pkg/time/#Duration.String) `string`
 - Default: `10s`
 
-### GRPC Client DNS RoundRobin
+#### GRPC Client DNS RoundRobin
 
 Enable grpc DNS based round robin load balancing. This method uses DNS to resolve endpoints and does client side load balancing of _all_ addresses returned by the DNS record. Do not disable unless you have a specific use case.
 
@@ -200,7 +198,7 @@ Enable grpc DNS based round robin load balancing. This method uses DNS to resolv
 - Type: `bool`
 - Default: `true`
 
-## HTTP Redirect Address
+### HTTP Redirect Address
 
 - Environmental Variable: `HTTP_REDIRECT_ADDR`
 - Config File Key: `http_redirect_addr`
@@ -210,7 +208,7 @@ Enable grpc DNS based round robin load balancing. This method uses DNS to resolv
 
 If set, the HTTP Redirect Address specifies the host and port to redirect http to https traffic on. If unset, no redirect server is started.
 
-## Metrics Address
+### Metrics Address
 
 - Environmental Variable: `METRICS_ADDRESS`
 - Config File Key: `metrics_address`
@@ -227,7 +225,7 @@ Expose a prometheus format HTTP endpoint on the specified port. Disabled by defa
 
 :::
 
-### Metrics tracked
+**Metrics tracked**
 
 | Name                                          | Type      | Description                                                             |
 | :-------------------------------------------- | :-------- | :---------------------------------------------------------------------- |
@@ -252,20 +250,20 @@ Expose a prometheus format HTTP endpoint on the specified port. Disabled by defa
 | pomerium_config_last_reload_success_timestamp | Gauge     | The timestamp of the last successful configuration reload by service    |
 | pomerium_build_info                           | Gauge     | Pomerium build metadata by git revision, service, version and goversion |
 
-## Tracing
+### Tracing
 
 Tracing tracks the progression of a single user request as it is handled by Pomerium.
 
 Each unit work is called a Span in a trace. Spans include metadata about the work, including the time spent in the step (latency), status, time events, attributes, links. You can use tracing to debug errors and latency issues in your applications, including in downstream connections.
 
-### Shared Tracing Settings
+#### 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/). | ❌       |
 
-### Jaeger
+#### Jaeger
 
 [Jaeger](https://www.jaegertracing.io/) is a distributed tracing system released as open source by Uber Technologies. It is used for monitoring and troubleshooting microservices-based distributed systems, including:
 
@@ -284,7 +282,7 @@ Each unit work is called a Span in a trace. Spans include metadata about the wor
 
 ![jaeger example trace](./img/jaeger.png) pomerium_config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service pomerium_build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion
 
-## Forward Auth
+### Forward Auth
 
 - Environmental Variable: `FORWARD_AUTH_URL`
 - Config File Key: `forward_auth_url`
@@ -295,13 +293,13 @@ Each unit work is called a Span in a trace. Spans include metadata about the wor
 
 Forward authentication creates an endpoint that can be used with third-party proxies that do not have rich access control capabilities ([nginx](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html), [nginx-ingress](https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/), [ambassador](https://www.getambassador.io/reference/services/auth-service/), [traefik](https://docs.traefik.io/middlewares/forwardauth/)). Forward authentication allow you to delegate authentication and authorization for each request to Pomerium.
 
-### Request flow
+#### Request flow
 
 ![pomerium forward auth request flow](./img/auth-flow-diagram.svg)
 
-### Examples
+#### Examples
 
-#### NGINX Ingress
+##### NGINX Ingress
 
 Some reverse-proxies, such as nginx split access control flow into two parts: verification and sign-in redirection. Notice the additional path `/verify` used for `auth-url` indicating to Pomerium that it should return a `401` instead of redirecting and starting the sign-in process.
 
@@ -330,7 +328,7 @@ spec:
               servicePort: 80
 ```
 
-### Traefik docker-compose
+#### Traefik docker-compose
 
 ```yml
 version: "3"
@@ -360,6 +358,181 @@ services:
       - "traefik.http.routers.httpbin.middlewares=test-auth@docker"
 ```
 
+## Authenticate Service
+
+### Authenticate Service URL
+
+- Environmental Variable: `AUTHENTICATE_SERVICE_URL`
+- Config File Key: `authenticate_service_url`
+- Type: `URL`
+- Required
+- Example: `https://authenticate.corp.example.com`
+
+Authenticate Service URL is the externally accessible URL for the authenticate service.
+
+### Identity Provider Name
+
+- Environmental Variable: `IDP_PROVIDER`
+- Config File Key: `idp_provider`
+- Type: `string`
+- Required
+- Options: `azure` `google` `okta` `onelogin` or `oidc`
+
+Provider is the short-hand name of a built-in OpenID Connect (oidc) identity provider to be used for authentication. To use a generic provider,set to `oidc`.
+
+See [identity provider] for details.
+
+### Identity Provider Client ID
+
+- Environmental Variable: `IDP_CLIENT_ID`
+- Config File Key: `idp_client_id`
+- Type: `string`
+- Required
+
+Client ID is the OAuth 2.0 Client Identifier retrieved from your identity provider. See your identity provider's documentation, and our [identity provider] docs for details.
+
+### Identity Provider Client Secret
+
+- Environmental Variable: `IDP_CLIENT_SECRET`
+- Config File Key: `idp_client_secret`
+- Type: `string`
+- Required
+
+Client Secret is the OAuth 2.0 Secret Identifier retrieved from your identity provider. See your identity provider's documentation, and our [identity provider] docs for details.
+
+### Identity Provider URL
+
+- Environmental Variable: `IDP_PROVIDER_URL`
+- Config File Key: `idp_provider_url`
+- Type: `string`
+- Required, depending on provider
+
+Provider URL is the base path to an identity provider's [OpenID connect discovery document](https://openid.net/specs/openid-connect-discovery-1_0.html). For example, google's URL would be `https://accounts.google.com` for [their discover document](https://accounts.google.com/.well-known/openid-configuration).
+
+### Identity Provider Scopes
+
+- Environmental Variable: `IDP_SCOPES`
+- Config File Key: `idp_scopes`
+- Type: `[]string` comma separated list of oauth scopes.
+- Default: `oidc`,`profile`, `email`, `offline_access` (typically)
+- Optional for built-in identity providers.
+
+Identity provider scopes correspond to access privilege scopes as defined in Section 3.3 of OAuth 2.0 RFC6749\. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. If you are using a built-in provider, you probably don't want to set customized scopes.
+
+### Identity Provider Service Account
+
+- Environmental Variable: `IDP_SERVICE_ACCOUNT`
+- Config File Key: `idp_service_account`
+- Type: `string`
+- Required, depending on provider
+
+Identity Provider Service Account is field used to configure any additional user account or access-token that may be required for querying additional user information during authentication. For a concrete example, Google an additional service account and to make a follow-up request to query a user's group membership. For more information, refer to the [identity provider] docs to see if your provider requires this setting.
+
+## Proxy Service
+
+### Signing Key
+
+- Environmental Variable: `SIGNING_KEY`
+- Config File Key: `signing_key`
+- Type: [base64 encoded] `string`
+- Optional
+
+Signing key is the base64 encoded key used to sign outbound requests. For more information see the [signed headers](./signed-headers.md) docs.
+
+### Authenticate Service URL
+
+- Environmental Variable: `AUTHENTICATE_SERVICE_URL`
+- Config File Key: `authenticate_service_url`
+- Type: `URL`
+- Required
+- Example: `https://authenticate.corp.example.com`
+
+Authenticate Service URL is the externally accessible URL for the authenticate service.
+
+### Authorize Service URL
+
+- Environmental Variable: `AUTHORIZE_SERVICE_URL`
+- Config File Key: `authorize_service_url`
+- Type: `URL`
+- Required; inferred in all-in-one mode to be localhost.
+- Example: `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.
+
+If your load balancer does not support gRPC pass-through you'll need to set this value to an internally routable location (`https://pomerium-authorize-service.default.svc.cluster.local`) instead of an externally routable one (`https://authorize.corp.example.com`).
+
+### Override Certificate Name
+
+- Environmental Variable: `OVERRIDE_CERTIFICATE_NAME`
+- Config File Key: `override_certificate_name`
+- Type: `int`
+- Optional (but typically required if Authenticate Internal Service Address is set)
+- Example: `*.corp.example.com` if wild card or `authenticate.corp.example.com`/`authorize.corp.example.com`
+
+Secure service communication can fail if the external certificate does not match the internally routed service hostname/[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication). This setting allows you to override that value.
+
+### Certificate Authority
+
+- Environmental Variable: `CERTIFICATE_AUTHORITY` or `CERTIFICATE_AUTHORITY_FILE`
+- Config File Key: `certificate_authority` or `certificate_authority_file`
+- Type: [base64 encoded] `string` or relative file location
+- Optional
+
+Certificate Authority is set when behind-the-ingress service communication uses self-signed certificates. Be sure to include the intermediary certificate.
+
+### Headers
+
+- Environmental Variable: `HEADERS`
+- Config File Key: `headers`
+- Type: map of `strings` key value pairs
+- Examples:
+
+  - Comma Separated: `X-Content-Type-Options:nosniff,X-Frame-Options:SAMEORIGIN`
+  - JSON: `'{"X-Test": "X-Value"}'`
+  - YAML:
+
+    ```yaml
+    headers:
+      X-Test: X-Value
+    ```
+
+- To disable: `disable:true`
+
+- Default :
+
+  ```javascript
+  X-Content-Type-Options : nosniff,
+  X-Frame-Options:SAMEORIGIN,
+  X-XSS-Protection:1; mode=block,
+  Strict-Transport-Security:max-age=31536000; includeSubDomains; preload,
+  ```
+
+Headers specifies a mapping of [HTTP Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) to be added to proxied requests. _Nota bene_ Downstream application headers will be overwritten by Pomerium's headers on conflict.
+
+By default, conservative [secure HTTP headers](https://www.owasp.org/index.php/OWASP_Secure_Headers_Project) are set.
+
+![pomerium security headers](./img/security-headers.png)
+
+### Refresh Cooldown
+
+- Environmental Variable: `REFRESH_COOLDOWN`
+- Config File Key: `refresh_cooldown`
+- Type: [Duration](https://golang.org/pkg/time/#Duration) `string`
+- Example: `10m`, `1h45m`
+- Default: `5m`
+
+Refresh cooldown is the minimum amount of time between allowed manually refreshed sessions.
+
+### Default Upstream Timeout
+
+- Environmental Variable: `DEFAULT_UPSTREAM_TIMEOUT`
+- Config File Key: `default_upstream_timeout`
+- Type: [Duration](https://golang.org/pkg/time/#Duration) `string`
+- Example: `10m`, `1h45m`
+- Default: `30s`
+
+Default Upstream Timeout is the default timeout applied to a proxied route when no `timeout` key is specified by the policy.
+
 ## Policy
 
 - Environmental Variable: `POLICY`
@@ -369,7 +542,7 @@ services:
 
 Policy contains route specific settings, and access control details. If you are configuring via POLICY environment variable, just the contents of the policy needs to be passed. If you are configuring via file, the policy should be present under the policy key. For example,
 
-<<< @/docs/docs/reference/examples/config/policy.example.yaml
+<<< @/docs/configuration/examples/config/policy.example.yaml
 
 A list of policy configuration variables follows.
 
@@ -504,8 +677,6 @@ Set Request Headers allows you to set static values for given request headers. T
   to: https://httpbin.org
   allowed_users:
     - bdd@pomerium.io
-    - bobbydesimone@gmail.com
-    - bobby@tdia.com
   set_request_headers:
     # works auto-magically!
     # https://httpbin.corp.example.com/basic-auth/root/hunter42
@@ -513,181 +684,6 @@ Set Request Headers allows you to set static values for given request headers. T
     X-Your-favorite-authenticating-Proxy: "Pomerium"
 ```
 
-# Authenticate Service
-
-## Authenticate Service URL
-
-- Environmental Variable: `AUTHENTICATE_SERVICE_URL`
-- Config File Key: `authenticate_service_url`
-- Type: `URL`
-- Required
-- Example: `https://authenticate.corp.example.com`
-
-Authenticate Service URL is the externally accessible URL for the authenticate service.
-
-## Identity Provider Name
-
-- Environmental Variable: `IDP_PROVIDER`
-- Config File Key: `idp_provider`
-- Type: `string`
-- Required
-- Options: `azure` `google` `okta` `gitlab` `onelogin` or `oidc`
-
-Provider is the short-hand name of a built-in OpenID Connect (oidc) identity provider to be used for authentication. To use a generic provider,set to `oidc`.
-
-See [identity provider] for details.
-
-## Identity Provider Client ID
-
-- Environmental Variable: `IDP_CLIENT_ID`
-- Config File Key: `idp_client_id`
-- Type: `string`
-- Required
-
-Client ID is the OAuth 2.0 Client Identifier retrieved from your identity provider. See your identity provider's documentation, and our [identity provider] docs for details.
-
-## Identity Provider Client Secret
-
-- Environmental Variable: `IDP_CLIENT_SECRET`
-- Config File Key: `idp_client_secret`
-- Type: `string`
-- Required
-
-Client Secret is the OAuth 2.0 Secret Identifier retrieved from your identity provider. See your identity provider's documentation, and our [identity provider] docs for details.
-
-## Identity Provider URL
-
-- Environmental Variable: `IDP_PROVIDER_URL`
-- Config File Key: `idp_provider_url`
-- Type: `string`
-- Required, depending on provider
-
-Provider URL is the base path to an identity provider's [OpenID connect discovery document](https://openid.net/specs/openid-connect-discovery-1_0.html). For example, google's URL would be `https://accounts.google.com` for [their discover document](https://accounts.google.com/.well-known/openid-configuration).
-
-## Identity Provider Scopes
-
-- Environmental Variable: `IDP_SCOPES`
-- Config File Key: `idp_scopes`
-- Type: `[]string` comma separated list of oauth scopes.
-- Default: `oidc`,`profile`, `email`, `offline_access` (typically)
-- Optional for built-in identity providers.
-
-Identity provider scopes correspond to access privilege scopes as defined in Section 3.3 of OAuth 2.0 RFC6749\. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. If you are using a built-in provider, you probably don't want to set customized scopes.
-
-## Identity Provider Service Account
-
-- Environmental Variable: `IDP_SERVICE_ACCOUNT`
-- Config File Key: `idp_service_account`
-- Type: `string`
-- Required, depending on provider
-
-Identity Provider Service Account is field used to configure any additional user account or access-token that may be required for querying additional user information during authentication. For a concrete example, Google an additional service account and to make a follow-up request to query a user's group membership. For more information, refer to the [identity provider] docs to see if your provider requires this setting.
-
-# Proxy Service
-
-## Signing Key
-
-- Environmental Variable: `SIGNING_KEY`
-- Config File Key: `signing_key`
-- Type: [base64 encoded] `string`
-- Optional
-
-Signing key is the base64 encoded key used to sign outbound requests. For more information see the [signed headers](./signed-headers.md) docs.
-
-## Authenticate Service URL
-
-- Environmental Variable: `AUTHENTICATE_SERVICE_URL`
-- Config File Key: `authenticate_service_url`
-- Type: `URL`
-- Required
-- Example: `https://authenticate.corp.example.com`
-
-Authenticate Service URL is the externally accessible URL for the authenticate service.
-
-## Authorize Service URL
-
-- Environmental Variable: `AUTHORIZE_SERVICE_URL`
-- Config File Key: `authorize_service_url`
-- Type: `URL`
-- Required; inferred in all-in-one mode to be localhost.
-- Example: `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.
-
-If your load balancer does not support gRPC pass-through you'll need to set this value to an internally routable location (`https://pomerium-authorize-service.default.svc.cluster.local`) instead of an externally routable one (`https://authorize.corp.example.com`).
-
-## Override Certificate Name
-
-- Environmental Variable: `OVERRIDE_CERTIFICATE_NAME`
-- Config File Key: `override_certificate_name`
-- Type: `int`
-- Optional (but typically required if Authenticate Internal Service Address is set)
-- Example: `*.corp.example.com` if wild card or `authenticate.corp.example.com`/`authorize.corp.example.com`
-
-Secure service communication can fail if the external certificate does not match the internally routed service hostname/[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication). This setting allows you to override that value.
-
-## Certificate Authority
-
-- Environmental Variable: `CERTIFICATE_AUTHORITY` or `CERTIFICATE_AUTHORITY_FILE`
-- Config File Key: `certificate_authority` or `certificate_authority_file`
-- Type: [base64 encoded] `string` or relative file location
-- Optional
-
-Certificate Authority is set when behind-the-ingress service communication uses self-signed certificates. Be sure to include the intermediary certificate.
-
-## Headers
-
-- Environmental Variable: `HEADERS`
-- Config File Key: `headers`
-- Type: map of `strings` key value pairs
-- Examples:
-
-  - Comma Separated: `X-Content-Type-Options:nosniff,X-Frame-Options:SAMEORIGIN`
-  - JSON: `'{"X-Test": "X-Value"}'`
-  - YAML:
-
-    ```yaml
-    headers:
-      X-Test: X-Value
-    ```
-
-- To disable: `disable:true`
-
-- Default :
-
-  ```javascript
-  X-Content-Type-Options : nosniff,
-  X-Frame-Options:SAMEORIGIN,
-  X-XSS-Protection:1; mode=block,
-  Strict-Transport-Security:max-age=31536000; includeSubDomains; preload,
-  ```
-
-Headers specifies a mapping of [HTTP Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) to be added to proxied requests. _Nota bene_ Downstream application headers will be overwritten by Pomerium's headers on conflict.
-
-By default, conservative [secure HTTP headers](https://www.owasp.org/index.php/OWASP_Secure_Headers_Project) are set.
-
-![pomerium security headers](./img/security-headers.png)
-
-## Refresh Cooldown
-
-- Environmental Variable: `REFRESH_COOLDOWN`
-- Config File Key: `refresh_cooldown`
-- Type: [Duration](https://golang.org/pkg/time/#Duration) `string`
-- Example: `10m`, `1h45m`
-- Default: `5m`
-
-Refresh cooldown is the minimum amount of time between allowed manually refreshed sessions.
-
-## Default Upstream Timeout
-
-- Environmental Variable: `DEFAULT_UPSTREAM_TIMEOUT`
-- Config File Key: `default_upstream_timeout`
-- Type: [Duration](https://golang.org/pkg/time/#Duration) `string`
-- Example: `10m`, `1h45m`
-- Default: `30s`
-
-Default Upstream Timeout is the default timeout applied to a proxied route when no `timeout` key is specified by the policy.
-
 [base64 encoded]: https://en.wikipedia.org/wiki/Base64
 [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
 [identity provider]: ./identity-providers.md

docs/docs/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## vUnreleased
+## v0.5.0
 
 ### New
 
@@ -11,7 +11,7 @@
 
 ### Security
 
-- Some identity providers (Okta and Azure) previously used mutable signifiers to set and assert group membership. Group membership for all providers now use globally unique and immutable identifiers when available.
+- Some identity providers (Okta, Onelogin, and Azure) previously used mutable signifiers to set and assert group membership. Group membership for all providers now use globally unique and immutable identifiers when available.
 
 ### Changed
 
@@ -19,6 +19,7 @@
 - Okta no longer uses tokens to retrieve group membership. Group membership is now fetched using Okta's HTTP API. [Group membership](https://developer.okta.com/docs/reference/api/groups/) is now determined by the globally unique and immutable `ID` field.
 - Okta now requires an additional set of credentials to be used to query for group membership set as a [service account](https://www.pomerium.io/docs/reference/reference.html#identity-provider-service-account).
 - URLs are no longer validated to be on the same domain-tree as the authenticate service. Managed routes can live on any domain.
+- OneLogin no longer uses tokens to retrieve group membership. Group membership is now fetched using OneLogin's HTTP API. [Group membership](https://developers.onelogin.com/openid-connect/api/user-info/) is now determined by the globally unique and immutable `ID` field.
 
 ### Removed
 

docs/docs/community/code-of-conduct.md

@@ -1,5 +1,10 @@
 ---
 title: Code of Conduct
+lang: en-US
+sidebarDepth: 0
+meta:
+  - name: keywords
+    content: pomerium community contributing code-of-conduct
 ---
 
 # Contributor Covenant Code of Conduct

docs/docs/community/contributing.md

@@ -1,5 +1,11 @@
 ---
 title: Contributing
+lang: en-US
+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.
@@ -78,13 +84,13 @@ Pomerium supports setting [configuration variables] using both environmental var
 
 Create a config file (`config.yaml`). This file will be use to determine Pomerium's configuration settings, routes, and access-policies. Consider the following example:
 
-<<< @/docs/docs/reference/examples/config/config.minimal.yaml
+<<< @/docs/configuration/examples/config/config.minimal.yaml
 
 #### Environmental Variables
 
 As mentioned above, Pomerium supports mixing and matching where configuration details are set. For example, we can specify our secret values and domains certificates as [environmental configuration variables].
 
-<<< @/docs/docs/reference/examples/config/config.minimal.env
+<<< @/docs/configuration/examples/config/config.minimal.env
 
 #### Run
 

docs/docs/community/readme.md

@@ -1,5 +1,11 @@
 ---
 title: Overview
+lang: en-US
+sidebarDepth: 0
+meta:
+  - name: keywords
+    content: pomerium community help bugs updates features
+
 description: >-
   This document describes how you users can stay up to date with pomerium,
   report issues, get help, and suggest new features.

docs/docs/community/security.md

@@ -1,3 +1,12 @@
+---
+title: Security
+lang: en-US
+sidebarDepth: 0
+meta:
+  - name: keywords
+    content: pomerium security disclosure vulnerabilities
+---
+
 # Security
 
 We deeply appreciate any effort to discover and disclose security vulnerabilities responsibly.

docs/docs/identity-providers/azure.md

@@ -64,6 +64,8 @@ Next you need to ensure that the Pomerium's Redirect URL is listed in allowed re
 
 Next, in order to retrieve group information from Active Directory, we need to enable the necessary permissions for the [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/auth-v2-service#azure-ad-endpoint-considerations).
 
+Please note, [Group ID](https://docs.microsoft.com/en-us/graph/api/group-get?view=graph-rest-1.0&tabs=http) not group name will be used to affirm group membership.
+
 On the **App registrations** page, click **API permissions**. Click the **Add a permission** button and select **Microsoft Graph API**, select **Delegated permissions**. Under the **Directory** row, select the checkbox for **Group.Read.All**.
 
 ![Azure add group membership claims](./img/azure-api-settings.png)
@@ -104,8 +106,8 @@ IDP_CLIENT_ID="REPLACE-ME"
 IDP_CLIENT_SECRET="REPLACE-ME"
 ```
 
-[client id]: ../reference/reference.md#identity-provider-client-id
+[client id]: ../../configuration/readme.md#identity-provider-client-id
-[client secret]: ../reference/reference.md#identity-provider-client-secret
+[client secret]: ../../configuration/readme.md#identity-provider-client-secret
 [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
 [oauth2]: https://oauth.net/2/
 [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect

docs/docs/identity-providers/cognito.md

@@ -1,3 +1,12 @@
+---
+title: AWS Cognito
+lang: en-US
+# sidebarDepth: 0
+meta:
+  - name: keywords
+    content: amazon aws cognito open-id oidc
+---
+
 # AWS Cognito
 
 ## Setting up AWS Cognito

docs/docs/identity-providers/gitlab.md

@@ -1,48 +0,0 @@
-# Gitlab
-
-:::warning
-
-Support was removed in v0.0.3 because Gitlab does not provide callers with a user email, under any scope, to a caller unless that user has selected her email to be public. Pomerium support is blocked until [this gitlab bug](https://gitlab.com/gitlab-org/gitlab-ce/issues/44435#note_88150387) is fixed.
-
-:::
-
-Log in to your Gitlab account and go to the [APIs & services](https://console.developers.google.com/projectselector/apis/credentials).
-
-Navigate to **User Settings** then **Applications** using the left-hand menu.
-
-On the **Applications** page, add a new application by setting the following parameters:
-
-| Field        | Description                                                                |
-| ------------ | -------------------------------------------------------------------------- |
-| Name         | The name of your web app                                                   |
-| Redirect URI | Redirect URL (e.g.`https://authenticate.corp.example.com/oauth2/callback`) |
-| Scopes       | **Must** select **read_user** and **openid**                               |
-
-![Create New Credentials](./img/gitlab-create-application.png)
-
-1.Click **Save Application** to proceed.
-
-Your [Client ID] and [Client Secret] will be displayed:
-
-![Gitlab OAuth Client ID and Secret](./img/gitlab-credentials.png)
-
-Set [Client ID] and [Client Secret] in Pomerium's settings. Your [environmental variables] should look something like this.
-
-```bash
-IDP_PROVIDER="gitlab"
-# NOTE!!! Provider url is optional, but should be set if you are running an on-premise instance
-# defaults to : https://gitlab.com, a local copy would look something like `http://gitlab.corp.beyondperimeter.com`
-IDP_PROVIDER_URL="https://gitlab.com"
-IDP_CLIENT_ID="yyyy"
-IDP_CLIENT_SECRET="xxxxxx"
-```
-
-When a user first uses Pomerium to login, they will be presented with an authorization screen similar to the following.
-
-![gitlab access authorization screen](./img/gitlab-verify-access.png)
-
-[client id]: ../reference/reference.md#identity-provider-client-id
-[client secret]: ../reference/reference.md#identity-provider-client-secret
-[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
-[oauth2]: https://oauth.net/2/
-[openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect

docs/docs/identity-providers/google.md

@@ -1,3 +1,12 @@
+---
+title: Google / GSuite
+lang: en-US
+sidebarDepth: 0
+meta:
+  - name: keywords
+    content: google gsuite gmail oidc openid-connect
+---
+
 # Google
 
 Log in to your Google account and go to the [APIs & services](https://console.developers.google.com/projectselector/apis/credentials). Navigate to **Credentials** using the left-hand menu.
@@ -46,12 +55,12 @@ Then, you'll need to manually open an editor and add an `impersonate_user` field
 
 :::
 
-```json
+```git
 {
   "type": "service_account",
   "client_id": "109818058799274859509",
   ...
-  "impersonate_user": "user@pomerium.io"
++  "impersonate_user": "user@pomerium.io"
   ...
 }
 ```
@@ -80,8 +89,8 @@ IDP_CLIENT_SECRET="xxxxxx"
 IDP_SERVICE_ACCOUNT="zzzz" # output of `cat service-account-key.json | base64`
 ```
 
-[client id]: ../reference/reference.md#identity-provider-client-id
+[client id]: ../../configuration/readme.md#identity-provider-client-id
-[client secret]: ../reference/reference.md#identity-provider-client-secret
+[client secret]: ../../configuration/readme.md#identity-provider-client-secret
 [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
 [oauth2]: https://oauth.net/2/
 [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect

docs/docs/identity-providers/okta.md

@@ -1,7 +1,18 @@
+---
+title: Okta
+lang: en-US
+sidebarDepth: 0
+meta:
+  - name: keywords
+    content: okta oidc
+---
+
 # Okta
 
 [Log in to your Okta account](https://login.okta.com) and head to your Okta dashboard. Select **Applications** on the top menu. On the Applications page, click the **Add Application** button to create a new app.
 
+## Create OpenID Connect Application
+
 ![Okta Applications Dashboard](./img/okta-app-dashboard.png)
 
 On the **Create New Application** page, select the **Web** for your application.
@@ -24,47 +35,28 @@ Click **Done** to proceed. You'll be taken to the **General** page of your app.
 
 Go to the **General** page of your app and scroll down to the **Client Credentials** section. This section contains the **[Client ID]** and **[Client Secret]** to be used in the next step.
 
+## Service account
+
 ![Okta Client ID and Secret](./img/okta-client-id-and-secret.png)
 
-Next, we'll configure Okta to pass along a custom OpenID Connect claim to establish group membership. To do so, click the **API** menu item, and select **Authorization Servers**.
+Next, we'll create API token so that Pomerium can retrieve and establish group membership. To do so, click the **API** menu item, and select **Tokens**.
 
-![Okta authorization servers](./img/okta-authorization-servers.png)
+![Okta api token](./img/okta-api-token.png)
 
-Select your desired authorization server and navigate to the **claims tab**. Click **Add Claim** and configure the group claim for **ID Token** as follows.
+Set this token in pomerium as your `IDP_SERVICE_ACCOUNT`. [Group ID](https://developer.okta.com/docs/reference/api/groups/) will be used to affirm group membership.
-
-![Okta configure group claim](./img/okta-configure-groups-claim.png)
-
-| Field                 | Value                 |
-| --------------------- | --------------------- |
-| Name                  | groups                |
-| Include in token type | **ID Token**, Always. |
-| Value Type            | Groups                |
-| Filter                | Matches regex `.*`    |
-| Include in            | Any scope             |
-
-Add an another, almost identical, claim but this time for **Access Token**.
-
-| Field                 | Value                     |
-| --------------------- | ------------------------- |
-| Name                  | groups                    |
-| Include in token type | **Access Token**, Always. |
-| Value Type            | Groups                    |
-| Filter                | Matches regex `.*`        |
-| Include in            | Any scope                 |
-
-![Okta list group claims](./img/okta-list-groups-claim.png)
 
 Finally, configure Pomerium with the identity provider settings retrieved in the previous steps. Your [environmental variables] should look something like this.
 
 ```bash
 IDP_PROVIDER="okta"
 IDP_PROVIDER_URL="https://dev-108295-admin.oktapreview.com/"
-IDP_CLIENT_ID="0oairksnr0C0fEJ7l0h7"
+IDP_CLIENT_ID="REPLACE_ME"
-IDP_CLIENT_SECRET="xxxxxx"
+IDP_CLIENT_SECRET="REPLACE_ME"
+IDP_SERVICE_ACCOUNT="REPLACE_ME" # api token
 ```
 
-[client id]: ../reference/reference.md#identity-provider-client-id
+[client id]: ../../configuration/readme.md#identity-provider-client-id
-[client secret]: ../reference/reference.md#identity-provider-client-secret
+[client secret]: ../../configuration/readme.md#identity-provider-client-secret
 [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
 [oauth2]: https://oauth.net/2/
 [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect

docs/docs/identity-providers/one-login.md

@@ -2,6 +2,8 @@
 
 Log in to your [OneLogin](https://www.onelogin.com/) account and head to the dashboard.
 
+## Create OpenID Connect App
+
 Click **Apps** on the top menu. Select the **Add apps** menu item.
 
 ![One Login Add a New App](./img/one-login-add-app.png)
@@ -26,17 +28,11 @@ Under **Token Timeout settings** set **Refresh Token** to 60 minutes (or whateve
 
 ![One Login SSO settings](./img/one-login-sso-settings.png)
 
-[OneLogin's OIDC implementation](https://developers.onelogin.com/openid-connect/scopes) supports the `groups` which can return either the user's group or role which can be used within pomerium to enforced group-based ACL policy.
+## Groups
 
-To return the user's Active Directory field, configure the group to return `member_of`. In the Default if no value field, select **User Roles** and Select **Semicolon Delimited** in the adjacent field. **Select Save**
+Group membership will be fetched using a follow up HTTP API call using your `CLIENT_ID` and `CLIENT_SECRET` as credentials. A [Group's ID](https://developers.onelogin.com/openid-connect/api/user-info) will be used to affirm user group membership.
 
-![OneLogin set role](./img/one-login-oidc-params.png)
+## Pomerium Configuration
-
-**Alternatively**, groups can return the _roles_ a user is assigned. In the Default if no value field, select **User Roles** and Select **Semicolon Delimited** in the adjacent field. **Select Save**
-
-![OneLogin set role](./img/one-login-oidc-groups-param.png)
-
-Finally, configure Pomerium with the identity provider settings retrieved in the previous steps. Your [environmental variables] should look something like this.
 
 ```bash
 IDP_PROVIDER="onelogin"
@@ -49,8 +45,8 @@ After reloading Pomerium, you should be able to see any login events from your O
 
 ![One Login Events Dashboard](./img/one-login-events.png)
 
-[client id]: ../reference/reference.md#identity-provider-client-id
+[client id]: ../../configuration/readme.md#identity-provider-client-id
-[client secret]: ../reference/reference.md#identity-provider-client-secret
+[client secret]: ../../configuration/readme.md#identity-provider-client-secret
 [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
 [oauth2]: https://oauth.net/2/
 [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect

docs/docs/identity-providers/readme.md

@@ -18,8 +18,8 @@ In this guide we'll cover how to do the following for each identity provider:
 2. Generate a **[Client ID]** and **[Client Secret]**.
 3. Configure Pomerium to use the **[Client ID]** and **[Client Secret]** keys.
 
-[client id]: ../reference/reference.md#identity-provider-client-id
+[client id]: ../../configuration/readme.md#identity-provider-client-id
-[client secret]: ../reference/reference.md#identity-provider-client-secret
+[client secret]: ../../configuration/readme.md#identity-provider-client-secret
 [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
 [oauth2]: https://oauth.net/2/
 [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect

docs/docs/quick-start/binary.md

@@ -27,13 +27,13 @@ Pomerium supports setting [configuration variables] using both environmental var
 
 Create a config file (`config.yaml`). This file will be used to determine Pomerium's configuration settings, routes, and access-policies. Consider the following example:
 
-<<< @/docs/docs/reference/examples/config/config.minimal.yaml
+<<< @/docs/configuration/examples/config/config.minimal.yaml
 
 ### Environmental Variables
 
 As mentioned above, Pomerium supports mixing and matching configuration. For example, we can specify our secret values and domains certificates as [environmental configuration variables], and set the rest as part of the configuration file.
 
-<<< @/docs/docs/reference/examples/config/config.minimal.env
+<<< @/docs/configuration/examples/config/config.minimal.env
 
 ## Run
 
@@ -48,7 +48,7 @@ source ./env
 
 Browse to `external-httpbin.your.domain.example`. Connections between you and [httpbin] will now be proxied and managed by Pomerium.
 
-[configuration variables]: ../reference/reference.md
+[configuration variables]: ../../configuration/readme.md
 [download]: https://github.com/pomerium/pomerium/releases
 [environmental configuration variables]: https://12factor.net/config
 [httpbin]: https://httpbin.org/

docs/docs/quick-start/kubernetes.md

@@ -8,7 +8,7 @@ meta:
 
 # Pomerium using Kubernetes
 
-This quickstart will cover how to deploy Pomerium with Kubernetes. 
+This quickstart will cover how to deploy Pomerium with Kubernetes.
 
 ## Prerequisites
 
@@ -24,14 +24,14 @@ Retrieve the latest copy of pomerium's source-code by cloning the repository.
 
 ```bash
 git clone https://github.com/pomerium/pomerium.git $HOME/pomerium
-cd $HOME/pomerium/docs/docs/reference/examples/kubernetes
+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.
 
-<<<@/docs/docs/reference/examples/kubernetes/kubernetes_gke.sh
+<<<@/docs/configuration/examples/kubernetes/kubernetes_gke.sh
 
 ## Run
 
@@ -43,7 +43,7 @@ Run [./kubernetes_gke.sh] which will:
 4. Configure an ingress load balancer.
 
 ```bash
-cd $HOME/pomerium/docs/docs/reference/examples/kubernetes
+cd $HOME/pomerium/docs/configuration/examples/kubernetes
 sh ./kubernetes_gke.sh
 ```
 

docs/docs/quick-start/readme.md

@@ -22,7 +22,7 @@ In the following quick-start, we'll create a minimal but complete environment fo
 
 Create a [configuration file] (e.g `config.yaml`) for defining Pomerium's configuration settings, routes, and access-policies. Consider the following example:
 
-<<< @/docs/docs/reference/examples/config/config.minimal.yaml
+<<< @/docs/configuration/examples/config/config.minimal.yaml
 
 Ensure the `docker-compose.yml` contains the correct path to your `config.yaml`.
 
@@ -34,7 +34,7 @@ Download the following `docker-compose.yml` file and modify it to:
 - mount your [wild-card TLS certificate]
 - mount your `config.yaml` [configuration file]
 
-<<< @/docs/docs/reference/examples/docker/basic.docker-compose.yml
+<<< @/docs/configuration/examples/docker/basic.docker-compose.yml
 
 ## Run
 
@@ -48,7 +48,7 @@ Docker will automatically download the required [container images] for Pomerium
 
 You should now be able access to the routes (e.g. `https://httpbin.corp.yourdomain.example`) as specified in your policy file.
 
-[configuration file]: ../reference/reference.md
+[configuration file]: ../../configuration/readme.md
 [container images]: https://hub.docker.com/r/pomerium/pomerium
 [docker]: https://docs.docker.com/install/
 [docker-compose]: https://docs.docker.com/compose/install/

docs/docs/quick-start/synology.md

@@ -211,7 +211,7 @@ And just to be safe, try logging in from another google account to see what happ
 ![Synology done](./img/synology-step-4-unauthorized.png)
 
 [certificate documentation]: ../reference/certificates.md
-[configuration variable docs]: ../reference/reference.md
+[configuration variable docs]: ../../configuration/readme.md
 [diskstation manager]: https://www.synology.com/en-us/dsm
 [docker-capable]: https://www.synology.com/en-us/dsm/packages/Docker
 [httpbin]: https://httpbin.org

docs/docs/readme.md

@@ -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 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.
+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%">
 
@@ -44,7 +44,7 @@ Pomerium is composed of 3 logical components:
   - Processes policy to determine permissions for each service
   - Handles authorization check for all user sessions
 
-In production deployments, it is recommended that you deploy each component separately.  This allows you to limit external attack surface, as well as scale and manage the services independently.
+In production deployments, it is recommended that you deploy each component separately. This allows you to limit external attack surface, as well as scale and manage the services independently.
 
 In test deployments, all three components may run from a single binary and configuration.
 
@@ -60,7 +60,6 @@ After initial authentication to provide a session token, only the authorization
 <img alt="pomerium architecture diagram" src="/pomerium-auth-flow.svg">
 </a>
 
-
 ## In action
 
 To make this a bit more concrete, see the following short video which demonstrates:

docs/docs/reference/certificates.md

@@ -123,9 +123,9 @@ Certificates, TLS, and Public Key Cryptography is a vast subject we cannot adequ
 - [Use TLS](https://smallstep.com/blog/use-tls.html) covers why TLS should be used everywhere; not just for securing typical internet traffic but for securing service communication in both "trusted" and adversarial situations.
 - [Everything you should know about certificates and PKI but are too afraid to ask](https://smallstep.com/blog/everything-pki.html)
 
-[certificate]: ../reference/#certificate
+[certificate]: ../../configuration/readme.md#certificate
-[certificate_authority]: ../reference/#certificate-authority
+[certificate_authority]: ../../configuration/readme.md#certificate-authority
-[certificate_key]: ../reference/#certificate-key
+[certificate_key]: ../../configuration/readme.md#certificate-key
-[override_certificate_name]: ../reference/#override-certificate-name
+[override_certificate_name]: ../../configuration/readme.md#override-certificate-name
 [principles]: ../docs/#why
 [zero-trust]: ../docs/#why

docs/docs/reference/impersonation.md

@@ -37,7 +37,7 @@ In certain circumstances, it's useful for an administrative user to impersonate
 Here's what it looks like.
 
 <video width="100%" height="600" controls=""><source src="./img/pomerium-user-impersonation.mp4" type="video/mp4">
-  Your browser does not support the video tag.
+Your browser does not support the video tag.
 </video>
 
-[configuration settings]: ../reference/#administrators
+[configuration settings]: ../../configuration/readme.md#administrators

docs/docs/reference/production-deployment.md

@@ -6,98 +6,96 @@ description: >-
 
 # Production Deployment
 
-This page covers the topic of running Pomerium in a production configuration.  See the [quick start section](../quick-start/) for canned example configurations.  
+This page covers the topic of running Pomerium in a production configuration. See the [quick start section](../quick-start/) for canned example configurations.
 
 Please also see [architecture](../#architecture) for information on component interactions.
 
 ## Service Mode
 
-For configuration of the service mode, see [Service Mode](../reference/reference.md#service-mode).
+For configuration of the service mode, see [Service Mode](../../configuration/readme.md#service-mode).
 
 ### All in One
 
-In smaller deployments or while testing, it may be desirable to run in "all-in-one" mode.  This reduces resource footprint and simplifies DNS configuration.  All URLs point at the same pomerium service instance.
+In smaller deployments or while testing, it may be desirable to run in "all-in-one" mode. This reduces resource footprint and simplifies DNS configuration. All URLs point at the same pomerium service instance.
 
 ### Discrete Services
 
-In larger footprints, it is recommended to run Pomerium as a collection of discrete service clusters.  This limits blast radius in the event of vulnerabilities and allows for per-service [scaling](#scaling) and monitoring.
+In larger footprints, it is recommended to run Pomerium as a collection of discrete service clusters. This limits blast radius in the event of vulnerabilities and allows for per-service [scaling](#scaling) and monitoring.
 
-In more complicated deployments, you may also choose to share aspects of the control plane across multiple logical Proxy clusters.  Examples:
+In more complicated deployments, you may also choose to share aspects of the control plane across multiple logical Proxy clusters. Examples:
 
-1. You want central AuthN and AuthZ but need to support a number of independently configured Proxy clusters 
+1. You want central AuthN and AuthZ but need to support a number of independently configured Proxy clusters
 2. You want central AuthZ but different Proxy clusters need different IDPs
 
-In both configurations, you must ensure the [Shared Secret](../reference/#shared-secret) matches across services.  You must also ensure Proxy and Authenticate external names sit within the same domain.
+In both configurations, you must ensure the [Shared Secret](../../configuration/readme.md#shared-secret) matches across services. You must also ensure Proxy and Authenticate external names sit within the same domain.
-
 
 ## Scaling
 
 In dedicated service mode, you have the opportunity to scale the components of Pomerium independently.
 
-Pomerium's components are stateless, and may all be scaled horizontally or vertically.  In general, horizontal scaling is recommended.
+Pomerium's components are stateless, and may all be scaled horizontally or vertically. In general, horizontal scaling is recommended.
 
 ### Proxy
 
-Proxy service, as the name implies, is responsible for proxying all user traffic, in addition to performing Authentication and Authorization checks.  The proxy is directly in path for user traffic.
+Proxy service, as the name implies, is responsible for proxying all user traffic, in addition to performing Authentication and Authorization checks. The proxy is directly in path for user traffic.
 
-Proxy will need resources scaled in conjunction with request count and may need average request size accounted for.  The heavier your user traffic, the more resources the Proxy service should have provisioned.
+Proxy will need resources scaled in conjunction with request count and may need average request size accounted for. The heavier your user traffic, the more resources the Proxy service should have provisioned.
 
 ### Authorize
 
-The Authorize service is responsible for policy checks during requests.  It is in the hot path for user requests but does not directly handle user traffic.
+The Authorize service is responsible for policy checks during requests. It is in the hot path for user requests but does not directly handle user traffic.
 
-Authorize will need resources scaled in conjunction with request count.  Request size and type should be of a constant complexity.
+Authorize will need resources scaled in conjunction with request count. Request size and type should be of a constant complexity.
 
 ### Authenticate
 
-The Authenticate service handles session token renewal, creation, and interaction with your Identity Provider.  The Authenticate service between a successful session setup or renewal and session expiration.
+The Authenticate service handles session token renewal, creation, and interaction with your Identity Provider. The Authenticate service between a successful session setup or renewal and session expiration.
 
-Authenticate requires significantly fewer resources than other components due to the only-occasional requirement to establish/renew sessions.  Add resources to the Authenticate service if you have a high session churn rate.  The requests should be constant time and complexity, but may vary by Identity Provider implementation.
+Authenticate requires significantly fewer resources than other components due to the only-occasional requirement to establish/renew sessions. Add resources to the Authenticate service if you have a high session churn rate. The requests should be constant time and complexity, but may vary by Identity Provider implementation.
 
 ## Load Balancing
 
-In any production deployment, running multiple replicas of each Pomerium service is strongly recommended.  Each service has slightly different concerns about utilizing the replicas for HA and scaling, enumerated below.
+In any production deployment, running multiple replicas of each Pomerium service is strongly recommended. Each service has slightly different concerns about utilizing the replicas for HA and scaling, enumerated below.
 
 ### Proxy
 
 You should provide a TCP or HTTP(s) load balancer between end users and the Proxy services.
 
-Proxy can handle its own SSL termination but is not a full web server.  If you need any special capabilities such as redirects, sticky sessions, etc, it is typical to put Pomerium behind an L7 load balancer or ingress controller.
+Proxy can handle its own SSL termination but is not a full web server. If you need any special capabilities such as redirects, sticky sessions, etc, it is typical to put Pomerium behind an L7 load balancer or ingress controller.
-
 
 ### Authenticate
 
 You should provide a TCP or HTTP(s) load balancer between end users and the Authorize services.
 
-Authenticate is compatible with any L4 or L7/HTTP load balancer.  Session stickiness should not be required and it is typical to have Authenticate be a named vhost on the same L7 load balancer as the Proxy service.
+Authenticate is compatible with any L4 or L7/HTTP load balancer. Session stickiness should not be required and it is typical to have Authenticate be a named vhost on the same L7 load balancer as the Proxy service.
 
 ### Authorize
 
-You do **not** need to provide a load balancer between the Proxy and the Authorize services.  Authorize utilizes GRPC and thus has special requirements if you should chose to use an external load balancer.  GRPC can perform client based load balancing, and in most configurations is the best architecture.
+You do **not** need to provide a load balancer between the Proxy and the Authorize services. Authorize utilizes GRPC and thus has special requirements if you should chose to use an external load balancer. GRPC can perform client based load balancing, and in most configurations is the best architecture.
 
-By default, the Proxy will automatically connect to all IPs returned by a DNS query for the name of the Authorize service.  Proxy will then regularly re-query DNS for changes to the Authorize service cluster.  Health checks and failover are automatic.
+By default, the Proxy will automatically connect to all IPs returned by a DNS query for the name of the Authorize service. Proxy will then regularly re-query DNS for changes to the Authorize service cluster. Health checks and failover are automatic.
 
-**Many load balancers do not support HTTP2 yet.  Please verify with your hardware, software or cloud provider**
+**Many load balancers do not support HTTP2 yet. Please verify with your hardware, software or cloud provider**
 
 If you choose to use an external proxying load balancer instead of the default client implementation:
- - L7 mode requires HTTP2 support or Authorize requests will fail
+
- - L4 (TCP) mode, GRPC/HTTP2 traffic from a Proxy instance will be pinned to a single Authorize instance due to the way HTTP2 multiplexes requests over a single established connection
+- L7 mode requires HTTP2 support or Authorize requests will fail
- - Due to the above limitations it is highly desirable to only use a load balancer which supports HTTP2 at Layer 7
+- L4 (TCP) mode, GRPC/HTTP2 traffic from a Proxy instance will be pinned to a single Authorize instance due to the way HTTP2 multiplexes requests over a single established connection
- 
+- Due to the above limitations it is highly desirable to only use a load balancer which supports HTTP2 at Layer 7
 
 ## High Availability
 
 As mentioned in [scaling](#scaling), Pomerium components themselves are stateless and support horizontal scale out for both availability and performance reasons.
 
-A given service type does not require communication with its peer instances to provide high availability.  Eg, a proxy service does not communicate with other proxies.
+A given service type does not require communication with its peer instances to provide high availability. Eg, a proxy service does not communicate with other proxies.
 
-Regardless of the service mode, it is recommended you run 2+ instances of Pomerium with as much physical and logical separation as possible.  For example, in Cloud environments, you should deploy instances of each service to at least 2 different zones.  On-prem environments should deploy 2+ instances to independent hardware.  
+Regardless of the service mode, it is recommended you run 2+ instances of Pomerium with as much physical and logical separation as possible. For example, in Cloud environments, you should deploy instances of each service to at least 2 different zones. On-prem environments should deploy 2+ instances to independent hardware.
 
 Ensure that you have enough spare capacity to handle the scope of your failure domains.
 
 ## SSL/TLS Certificates
 
-Pomerium utilizes TLS end to end, so the placement, certificate authorities and covered subjects are critical to align correctly.  
+Pomerium utilizes TLS end to end, so the placement, certificate authorities and covered subjects are critical to align correctly.
 
 In a typical deployment, a minimum of two certs are required:
 
@@ -109,10 +107,12 @@ In a typical deployment, a minimum of two certs are required:
   - Must cover the subject name from the Proxy's perspective
 
 If you have L7 load balancing in front of the Proxy/Authenticate:
-  - Your wildcard certificate should live on the load balancer
+
-  - Your Authenticate and Proxy services will need a certificate accepted by the load balancer
+- Your wildcard certificate should live on the load balancer
-  - Your load balancer can be configured to verify the identity of the Authenticate and Proxy certificates
+- Your Authenticate and Proxy services will need a certificate accepted by the load balancer
+- Your load balancer can be configured to verify the identity of the Authenticate and Proxy certificates
 
 If you have TLS enabled applications behind the proxy:
-  - you may provide a client certificate for the Proxy service to connect to downstream services with and verify
+
-  - the Proxy may be configured to verify the name and certificate authority of downstream services with either the standard Root CA bundle or a custom CA
+- you may provide a client certificate for the Proxy service to connect to downstream services with and verify
+- the Proxy may be configured to verify the name and certificate authority of downstream services with either the standard Root CA bundle or a custom CA

docs/docs/reference/programmatic-access.md

@@ -7,63 +7,81 @@ description: >-
 
 # Programmatic access
 
-This page describes how to access Pomerium endpoints programmatically.
+This page describes how to obtain Pomerium access credentials programmatically via a web-based oauth2 based authorization flow. If you have ever used Google's `gcloud` commandline app, the mechanism is very similar.
 
-## Configuration
+## Components
 
-Every identity provider has slightly different methods for issuing OAuth 2.0 access tokens [suitable][proof key for code exchange] for machine-to-machine use, please review your identity provider's documentation. For example:
+### Login API
 
-- [Google Oauth2 2.0 for Desktop Apps](https://developers.google.com/identity/protocols/OAuth2InstalledApp)
+The API returns a signed, sign-in url that can be used to complete a user-driven login process with Pomerium and your identity provider. The Login API endpoints takes a `redirect_uri` query param as an argument which points to the location of the callback server to be called following a successful login.
-- [Okta PKCE Flow](https://developer.okta.com/docs/concepts/auth-overview/#authorization-code-flow)
-- [Azure Active Directory using the OAuth 2.0 code grant flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code)
 
-For the sake of illustration, this guide and example scripts will use Google as the underlying identity provider.
+For example:
 
-### Identity Provider Configuration
+```bash
+$ curl "https://httpbin.example.com/.pomerium/api/v1/login?redirect_uri=http://localhost:8000"
 
-To configure programmatic access for Pomerium we'll need to set up **an additional** OAuth 2.0 client ID that can issue `id_tokens` whose [audience](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) matches the Client ID of Pomerium. Follow these instructions adapted from [Google's documentation](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_desktop_app):
+https://authenticate.example.com/.pomerium/sign_in?redirect_uri=http%3A%2F%2Flocalhost%3Fpomerium_programmatic_destination_url%3Dhttps%253A%252F%252Fhttpbin.corp.example%252F.pomerium%252Fapi%252Fv1%252Flogin%253Fredirect_uri%253Dhttp%253A%252F%252Flocalhost&sig=hsLuzJctmgsN4kbMeQL16fe_FahjDBEcX0_kPYfg8bs%3D&ts=1573262981
+```
 
-1. Go to the [Credentials page](https://console.cloud.google.com/apis/credentials).
+### Callback handler
-2. Select the project with the Pomerium secured resource.
-3. Click **Create credentials**, then select **OAuth Client ID**.
-4. Under **Application type**, select **Other**, add a **Name**, then click **Create**.
-5. On the OAuth client window that appears, note the **client ID** and **client secret**.
-6. On the **Credentials** window, your new **Other** credentials appear along with the primary client ID that's used to access your application.
 
-### High level flow
+It is the script or application's responsibility to create a HTTP callback handler. Authenticated sessions are returned in the form of a [callback](https://developer.okta.com/docs/concepts/auth-overview/#what-kind-of-client-are-you-building) from pomerium to a HTTP server. This is the `redirect_uri` value used to build Login API's URL, and represents the URL of a (usually local) http server responsible for receiving the resulting user session in the form of `pomerium_jwt` and `pomerium_refresh_token` query parameters.
 
-The application interacting with Pomerium will roughly have to manage the following access flow.
+See the python script below for example of how to start a callback server, and store the session payload.
 
-1. A user authenticates with the OpenID Connect identity provider. This typically requires handling the [Proof Key for Code Exchange] process.
+### Refresh API
-2. Exchange the code from the [Proof Key for Code Exchange] for a valid `refresh_token`.
-3. Using the `refresh_token` from the last step, request the identity provider issue a new `id_token` which has our Pomerium app's `client_id` as the `audience`.
-4. Exchange the identity provider issued `id_token` for a `pomerium` token (e.g. `https://authenticate.{your-domain}/api/v1/token`).
-5. Use the pomerium issued `Token` [authorization bearer token] for all requests to Pomerium protected endpoints until it's `Expiry`. Authorization policy will be tied to the user as normal.
 
-### Expiration and revocation
+The Refresh API allows for a valid refresh token enabled session, using an `Authorization: Pomerium` bearer token, to refresh the current user session and return a new user session (`jwt`) and refresh token (`refresh_token`). If successfully, a new updated refresh token and identity session are returned as a json response.
 
-Your application should handle token expiration. If the session expires before work is done, the identity provider issued `refresh_token` can be used to create a new valid session by repeating steps 3 and on.
+```bash
+$ curl \
+	-H "Accept: application/json" \
+	-H "Authorization: Pomerium $(cat cred-from-above-step.json | jq -r .refresh_token)" \
+	https://authenticate.example.com/api/v1/refresh
 
-Also, you should write your code to anticipate the possibility that a granted `refresh_token` may stop working. For example, a refresh token might stop working if the underlying user changes passwords, revokes access, or if the administrator removes rotates or deletes the OAuth Client ID.
+{
+  "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token":"fXiWCF_z1NWKU3yZ...."
+}
+
+```
+
+:::tip
+Note that the Authorization refresh token is set to Authorization `Pomerium` _not_ `Bearer`.
+:::
+
+## Handling expiration and revocation
+
+Your application should handle token expiration. If the session expires before work is done, the identity provider issued `refresh_token` can be used to create a new valid session.
+
+Also, your script or application should anticipate the possibility that a granted `refresh_token` may stop working. For example, a refresh token might stop working if the underlying user changes passwords, revokes access, or if the administrator removes rotates or deletes the OAuth Client ID.
+
+## High level workflow
+
+The application interacting with Pomerium must manage the following workflow. Consider the following example where a script or program desires delegated, programmatic access to the domain `httpbin.corp.domain.example`:
+
+1. The script or application requests a new login url from the pomerium managed endpoint (e.g. `https://httpbin.corp.domain.example/.pomerium/api/v1/login`) and takes a `redirect_uri` as an argument.
+1. The script or application opens a browser or redirects the user to the returned login page.
+1. The user completes the identity providers login flow.
+1. The identity provider makes a callback to pomerium's authenticate service (e.g. `authenticate.corp.domain.example`) .
+1. Pomerium's authenticate service creates a user session and redirect token, then redirects back to the the managed endpoint (e.g. `httpbin.corp.domain.example`)
+1. Pomerium's proxy service and makes a callback request to the original `redirect_uri` with the user session and refresh token as arguments.
+1. The script or application is responsible for handling that http callback request, and securely handling the callback session (`pomerium_jwt`) and refresh token (`pomerium_refresh_token`) queryparams.
+1. The script or application can now make any requests as normal, by setting the `Authorization: Pomerium ${pomerium_jwt}` header.
+1. If the script or application encounters a `401` error or token expiration error, the script or application can make a request the authenticate service's refresh api endpoint (e.g. `https://authenticate.corp.domain.example/api/v1/refresh`) with the `Authorization: Pomerium ${pomerium_refresh_token}` header. Note that the refresh token is used, not the user session jwt. If successful, a new user session jwt and refresh token will be returned and requests can continue as before.
 
 ## Example Code
 
-It's not as bad as it sounds. Please see the following minimal but complete examples.
+Please consider see the following minimal but complete python example.
-
-### Python
 
 ```bash
-python scripts/programmatic_access.py --client-secret REPLACE_ME \
+python3 scripts/programmatic_access.py \
-    --client-id 851877082059-85tfqg9hlm8j9km5d9uripd0dvk72mvk.apps.googleusercontent.com \
+	--dst https://httpbin.example.com/headers \
-    --pomerium-client-id 851877082059-bfgkpj09noog7as3gpc3t7r6n9sjbgs6.apps.googleusercontent.com
+	--refresh-endpoint https://authenticate.example.com/api/v1/refresh
 ```
 
 <<< @/scripts/programmatic_access.py
 
-### Bash
-
-<<< @/scripts/programmatic_access.sh
-
 [authorization bearer token]: https://developers.google.com/gmail/markup/actions/verifying-bearer-tokens
 [identity provider]: ../identity-providers/readme.md
 [proof key for code exchange]: https://tools.ietf.org/html/rfc7636

docs/docs/releases.md

@@ -55,6 +55,7 @@ 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.5.0](https://0-5-0.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/)

docs/docs/upgrading.md

@@ -13,18 +13,22 @@ description: >-
 
 #### Subdomain requirement dropped
 
-- Pomerium services and managed routes are no longer required to be on the same domain-tree. Access can be delegated to any route, on any domain (that you have access to, of course).
+- Pomerium services and managed routes are no longer required to be on the same domain-tree root. Access can be delegated to any route, on any domain (that you have access to, of course).
 
 #### Azure AD
 
-- The Azure AD provider now uses the globally unique and immutable`ID` instead of `group name` to attest a user's [group membership](https://docs.microsoft.com/en-us/graph/api/group-get?view=graph-rest-1.0&tabs=http). Please update your policies to use Group `ID`s instead of group names.
+- Azure Active Directory now uses the globally unique and immutable`ID` instead of `group name` to attest a user's [group membership](https://docs.microsoft.com/en-us/graph/api/group-get?view=graph-rest-1.0&tabs=http). Please update your policies to use group `ID` instead of group name.
 
 #### Okta
 
-- Okta no longer uses tokens to retrieve group membership. [Group membership](https://developer.okta.com/docs/reference/api/groups/) is now fetched using Okta's API. Please update your policies to use Group `ID`s instead of group names.
+- Okta no longer uses tokens to retrieve group membership. [Group membership](https://developer.okta.com/docs/reference/api/groups/) is now fetched using Okta's API.
-- Okta's group membership is now determined by the globally unique and immutable ID field.
+- Okta's group membership is now determined by the globally unique and immutable ID field. Please update your policies to use group `ID` instead of group name.
 - Okta now requires an additional set of credentials to be used to query for group membership set as a [service account](https://www.pomerium.io/docs/reference/reference.html#identity-provider-service-account).
 
+#### OneLogin
+
+- OneLogin [group membership](https://developers.onelogin.com/openid-connect/api/user-info) is now determined by the globally unique and immutable ID field. Please update your policies to use group `ID` instead of group name.
+
 #### Force Refresh Removed
 
 Force refresh has been removed from the dashboard. Logging out and back in again should have the equivalent desired effect.
@@ -173,5 +177,5 @@ Usage of the POLICY_FILE envvar is no longer supported. Support for file based p
 
 The configuration variable [Authenticate Internal Service URL] must now be a valid [URL](https://golang.org/pkg/net/url/#URL) type and contain both a hostname and valid `https` schema.
 
-[policy]: ./reference/reference.md#policy
+[policy]: ./configuration/readme.md#policy
-[authenticate internal service url]: ./reference/reference.md#authenticate-service-url
+[authenticate internal service url]: ./configuration/readme.md#authenticate-service-url

docs/recipes/ad-guard.md

@@ -10,7 +10,7 @@ description: >-
 
 # Securing AdGuard Home
 
-This guide covers how to add authentication and authorization to an instance of AdGuard while giving us a great excuse to demonstrate how to use Pomerium's [add headers](../docs/reference/reference.md) functionality to **transparently pass along basic authentication credentials to a downstream app**.
+This guide covers how to add authentication and authorization to an instance of AdGuard while giving us a great excuse to demonstrate how to use Pomerium's [add headers](../docs/configuration/readme.md) functionality to **transparently pass along basic authentication credentials to a downstream app**.
 
 ## What is AdGuard?
 

docs/recipes/kubernetes.md

@@ -284,10 +284,10 @@ Finally, we get to install Pomerium! 🎉 Once again, we will use Helm to deploy
 
 ```bash
 helm install stable/pomerium \
-  --name "helm-pomerium" \
+	--name "helm-pomerium" \
 	--set config.rootDomain="domain.example" \
-  --set config.existingConfig="config" \
+	--set config.existingConfig="config" \
-  --set authenticate.idp.provider="google" \
+	--set authenticate.idp.provider="google" \
 	--set authenticate.idp.clientID="YOUR_CLIENT_ID" \
 	--set authenticate.idp.clientSecret="YOUR_SECRET"
 ```

scripts/programmatic_access.py

@@ -14,10 +14,10 @@ done = False
 parser = argparse.ArgumentParser()
 parser.add_argument("--login", action="store_true")
 parser.add_argument(
-    "--dst", default="https://httpbin.imac.bdd.io/headers",
+    "--dst", default="https://httpbin.example.com/headers",
 )
 parser.add_argument(
-    "--refresh-endpoint", default="https://authenticate.imac.bdd.io/api/v1/refresh",
+    "--refresh-endpoint", default="https://authenticate.example.com/api/v1/refresh",
 )
 parser.add_argument("--server", default="localhost", type=str)
 parser.add_argument("--port", default=8000, type=int)