docs: update examples for v0.0.5 (#147)

2025-07-29 14:39:40 +02:00 · 2019-06-03 14:05:28 -07:00 · 2019-06-03 14:05:28 -07:00 · 14403ce388
commit 14403ce388
parent 8de453dae3
21 changed files with 339 additions and 239 deletions
--- a/docs/docs/examples.md
+++ b/docs/docs/examples.md
@ -1,5 +1,5 @@
 ---
-sidebarDepth: 3
+sidebarDepth: 2
 ---

 # Example configs
@ -24,7 +24,14 @@ Remember to set your identity provider settings and to generate new secret keys!

 Customize for your identity provider and run `./bin/pomerium -config config.yaml`

-<<< @/config.example.yaml
+#### Config file example
+
+<<< @/docs/docs/examples/config/config.example.yaml
+
+#### Environmental variable example
+
+<<< @/docs/docs/examples/config/config.example.env
+

 ## Docker

@ -35,7 +42,7 @@ Uses the [latest pomerium build](https://hub.docker.com/r/pomerium/pomerium) fro
 - Minimal container-based configuration.
 - Docker and Docker-Compose based.
 - Runs a single container for all pomerium services
- Routes default to on-premise [helloworld], [httpbin].
+- Routes default to on-premise [httpbin].

 Customize for your identity provider run `docker-compose up -f basic.docker-compose.yml`

--- a/docs/docs/examples/config/config.example.env
+++ b/docs/docs/examples/config/config.example.env
@ -0,0 +1,66 @@
+#!/bin/bash
+# Main configuration flags : https://www.pomerium.io/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
+export AUTHORIZE_SERVICE_URL=https://authorize.corp.beyondperimeter.com
+
+# Certificates can be loaded as files or base64 encoded bytes. If neither is set, a
+# pomerium will attempt to locate a pair in the root directory
+# See : https://www.pomerium.io/docs/certificates.html
+export CERTIFICATE_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer"                      # optional, defaults to `./cert.pem`
+export CERTIFICATE_KEY_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key" # optional, defaults to `./certprivkey.pem`
+# export CERTIFICATE="xxxxxx"                 # base64 encoded cert, eg. `base64 -i cert.pem`
+# export CERTIFICATE_KEY="xxxx"               # base64 encoded key, eg. `base64 -i privkey.pem`
+
+# 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"
+
+# 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
+
+# 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 :
+# export IDP_SERVICE_ACCOUNT=$(echo '{"impersonate_user": "bdd@pomerium.io"}' | base64)
+
+# 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/docs/examples/config/policy.example.yaml)"
--- a/docs/docs/examples/config/config.example.yaml
+++ b/docs/docs/examples/config/config.example.yaml
@ -0,0 +1,92 @@
+# Main configuration flags : https://www.pomerium.io/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: https://authorize.corp.beyondperimeter.com
+
+# Certificates can be loaded as files or base64 encoded bytes. If neither is set, a
+# pomerium will attempt to locate a pair in the root directory
+# certificate_file: "./cert.pem" # optional, defaults to `./cert.pem`
+# certificate_key_file: "./privkey.pem" # optional, defaults to `./certprivkey.pem`
+# certificate_authority_file: "./cert.pem"
+
+# 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"
+
+# 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
+# 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
+
+# Proxied routes and per-route policies are defined in a policy block
+policy:
+  - from: httpbin.corp.beyondperimeter.com
+    to: http://httpbin
+    allowed_domains:
+      - pomerium.io
+    cors_allow_preflight: true
+    timeout: 30s
+  - from: external-httpbin.corp.beyondperimeter.com
+    to: httpbin.org
+    allowed_domains:
+      - gmail.com
+  - from: weirdlyssl.corp.beyondperimeter.com
+    to: http://neverssl.com
+    allowed_users:
+      - bdd@pomerium.io
+    allowed_groups:
+      - admins
+      - developers
+  - from: hello.corp.beyondperimeter.com
+    to: http://hello:8080
+    allowed_groups:
+      - admins
+  - from: external-search.corp.beyondperimeter.com
+    to: google.com
+    allow_public_unauthenticated_access: true
--- a/docs/docs/examples/config/config.minimal.env
+++ b/docs/docs/examples/config/config.minimal.env
@ -0,0 +1,9 @@
+#!/bin/bash
+
+# See : https://www.pomerium.io/docs/certificates.html
+export CERTIFICATE_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer"                      # optional, defaults to `./cert.pem`
+export CERTIFICATE_KEY_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key" # optional, defaults to `./certprivkey.pem`
+
+# 256 bit random keys
+export SHARED_SECRET="$(head -c32 /dev/urandom | base64)"
+export COOKIE_SECRET="$(head -c32 /dev/urandom | base64)"
--- a/docs/docs/examples/config/config.minimal.yaml
+++ b/docs/docs/examples/config/config.minimal.yaml
@ -0,0 +1,17 @@
+# See detailed configuration settings : https://www.pomerium.io/reference/
+authenticate_service_url: https://authenticate.corp.beyondperimeter.com
+authorize_service_url: https://authorize.corp.beyondperimeter.com
+
+# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
+idp_provider: google
+idp_client_id: REPLACE_ME
+idp_client_secret: REPLACE_ME
+
+policy:
+  - from: httpbin.corp.beyondperimeter.com
+    to: http://httpbin
+    allowed_domains:
+      - pomerium.io
+  - from: external-httpbin.corp.beyondperimeter.com
+    to: https://httpbin.org
+    allow_public_unauthenticated_access: true
--- a/docs/docs/examples/config/policy.example.yaml
+++ b/docs/docs/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/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: httpbin.corp.beyondperimeter.com
+    to: http://localhost:8000
+    allowed_domains:
+      - pomerium.io
+    cors_allow_preflight: true
+    timeout: 30s
+  - from: external-httpbin.corp.beyondperimeter.com
+    to: httpbin.org
+    allowed_domains:
+      - gmail.com
+  - from: weirdlyssl.corp.beyondperimeter.com
+    to: http://neverssl.com
+    allowed_users:
+      - bdd@pomerium.io
+    allowed_groups:
+      - admins
+      - developers
+  - from: hello.corp.beyondperimeter.com
+    to: http://localhost:8080
+    allowed_groups:
+      - admins@pomerium.io
--- a/docs/docs/examples/docker/basic.docker-compose.yml
+++ b/docs/docs/examples/docker/basic.docker-compose.yml
@ -1,42 +1,23 @@
-# Example Pomerium configuration.
-#
-# NOTE! Change IDP_* settings to match your identity provider settings!
-# NOTE! Generate new SHARED_SECRET and COOKIE_SECRET keys! e.g. `head -c32 /dev/urandom | base64`
-# NOTE! Replace `corp.beyondperimeter.com` with whatever your domain is
-# NOTE! Make sure certificate files (cert.pem/privkey.pem) are in the same directory as this file
-# NOTE! Make sure your policy file (policy.example.yaml) is in the same directory as this file
-
 version: "3"
 services:
  pomerium:
-    image: pomerium/pomerium:latest # or `build: .` to build from source
+    image: pomerium/pomerium:v0.0.5
    environment:
-      - POMERIUM_DEBUG=true
      - SERVICES=all
-      - IDP_PROVIDER=google
-      - IDP_PROVIDER_URL=https://accounts.google.com
-      - IDP_CLIENT_ID=REPLACE_ME.apps.googleusercontent.com
-      - IDP_CLIENT_SECRET=REPLACE_ME
+      # Generate new secret keys. e.g. `head -c32 /dev/urandom | base64`
      - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
      - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
-      - CERTIFICATE_FILE=cert.pem
-      - CERTIFICATE_KEY_FILE=privkey.pem
-      - AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com
-      - AUTHORIZE_SERVICE_URL=https://authorize.corp.beyondperimeter.com
    volumes:
-      - ./cert.pem:/pomerium/cert.pem:ro
-      - ./privkey.pem:/pomerium/privkey.pem:ro
-      - ./config.example.policy.only.yaml:/pomerium/config.yaml:ro
+      # Mount your domain's certificates : https://www.pomerium.io/docs/certificates.html
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
+      # Mount your config file : https://www.pomerium.io/reference/
+      - ../config/config.minimal.yaml:/pomerium/config.yaml:ro
    ports:
      - 443:443

-  # https://httpbin.corp.beyondperimeter.com
+  # https://httpbin.corp.beyondperimeter.com --> Pomerium --> http://httpbin
  httpbin:
    image: kennethreitz/httpbin:latest
    expose:
-      - 80
-  # https://hello.corp.beyondperimeter.com
-  hello:
-    image: gcr.io/google-samples/hello-app:1.0
-    expose:
-      - 8080
+      - 80
--- a/docs/docs/examples/docker/nginx.docker-compose.yml
+++ b/docs/docs/examples/docker/nginx.docker-compose.yml
@ -5,34 +5,39 @@ services:
    ports:
      - "443:443"
    volumes:
-      # NOTE!!! : nginx must be supplied with your wildcard certificates. And it expects
-      # it in the format of whatever your wildcard domain name is in.
+      # NOTE!!! : nginx must be supplied with your wildcard certificates.
      # see : https://github.com/jwilder/nginx-proxy#wildcard-certificates
-      # So, if your subdomain is corp.beyondperimeter.com, you'd have the following :
-      - ./cert.pem:/etc/nginx/certs/corp.beyondperimeter.com.crt:ro
-      - ./privkey.pem:/etc/nginx/certs/corp.beyondperimeter.com.key:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/etc/nginx/certs/corp.beyondperimeter.com.crt:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/etc/nginx/certs/corp.beyondperimeter.com.key:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro

  pomerium-authenticate:
    image: pomerium/pomerium:latest # or `build: .` to build from source
    restart: always
    environment:
-      - POMERIUM_DEBUG=true
      - SERVICES=authenticate
-      # Identity Provider Settings (Must be changed!)
+      # NOTE!: Replace with your identity provider settings https://www.pomerium.io/docs/identity-providers.html
      - IDP_PROVIDER=google
      - IDP_PROVIDER_URL=https://accounts.google.com
      - IDP_CLIENT_ID=REPLACE_ME.apps.googleusercontent.com
      - IDP_CLIENT_SECRET=REPLACE_ME
+      # - IDP_CLIENT_SECRET=REPLACE_ME
+      # NOTE! Generate new secret keys! e.g. `head -c32 /dev/urandom | base64`
+      # Generated secret keys must match between services
+
      - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
      - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
-      # nginx settings
+      # Tell nginx how to proxy pomerium's routes
      - VIRTUAL_PROTO=https
      - VIRTUAL_HOST=authenticate.corp.beyondperimeter.com
      - VIRTUAL_PORT=443
    volumes:
-      - ./cert.pem:/pomerium/cert.pem:ro
-      - ./privkey.pem:/pomerium/privkey.pem:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
+      # Retrieve non-secret config keys from the config file : https://www.pomerium.io/reference/
+      # See `config.example.yaml` and modify to fit your needs.
+      - ../config/config.example.yaml:/pomerium/config.yaml:ro
+
    expose:
      - 443

@ -40,26 +45,26 @@ services:
    image: pomerium/pomerium:latest # or `build: .` to build from source
    restart: always
    environment:
-      - POMERIUM_DEBUG=true
      - SERVICES=proxy
-      - AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com
      # IMPORTANT! If you are running pomerium behind another ingress (loadbalancer/firewall/etc)
      # you must tell pomerium proxy how to communicate using an internal hostname for RPC
-      - AUTHENTICATE_INTERNAL_URL=pomerium-authenticate
+      - AUTHENTICATE_INTERNAL_URL=https://pomerium-authenticate
      - AUTHORIZE_SERVICE_URL=https://pomerium-authorize
      # When communicating internally, rPC is going to get a name conflict expecting an external
      # facing certificate name (i.e. authenticate-service.local vs *.corp.example.com).
      - OVERRIDE_CERTIFICATE_NAME=*.corp.beyondperimeter.com
      - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
      - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
-      # nginx settings
+      # Tell nginx how to proxy pomerium's routes
      - VIRTUAL_PROTO=https
      - VIRTUAL_HOST=*.corp.beyondperimeter.com
      - VIRTUAL_PORT=443
    volumes:
-      - ./cert.pem:/pomerium/cert.pem:ro
-      - ./privkey.pem:/pomerium/privkey.pem:ro
-      - ./config.example.policy.only.yaml:/pomerium/config.yaml:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
+      # Retrieve non-secret config keys from the config file : https://www.pomerium.io/reference/
+      # See `config.example.yaml` and modify to fit your needs.
+      - ../config/config.example.yaml:/pomerium/config.yaml:ro
    expose:
      - 443

@ -67,17 +72,18 @@ services:
    image: pomerium/pomerium:latest # or `build: .` to build from source
    restart: always
    environment:
-      - POMERIUM_DEBUG=true
      - SERVICES=authorize
      - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
-      # nginx settings
+      # Tell nginx how to proxy pomerium's routes
      - VIRTUAL_PROTO=https
      - VIRTUAL_HOST=authorize.corp.beyondperimeter.com
      - VIRTUAL_PORT=443
    volumes:
-      - ./cert.pem:/pomerium/cert.pem:ro
-      - ./privkey.pem:/pomerium/privkey.pem:ro
-      - ./config.example.policy.only.yaml:/pomerium/config.yaml:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
+      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
+      # Retrieve non-secret config keys from the config file : https://www.pomerium.io/reference/
+      # See `config.example.yaml` and modify to fit your needs.
+      - ../config/config.example.yaml:/pomerium/config.yaml:ro
    expose:
      - 443

--- a/docs/docs/examples/kubernetes/authenticate.deploy.yml
+++ b/docs/docs/examples/kubernetes/authenticate.deploy.yml
@ -25,6 +25,8 @@ spec:
          env:
            - name: SERVICES
              value: authenticate
+            - name: AUTHENTICATE_SERVICE_URL
+              value: https://authenticate.corp.beyondperimeter.com
            - name: IDP_PROVIDER
              value: google
            - name: IDP_PROVIDER_URL
--- a/docs/docs/identity-providers.md
+++ b/docs/docs/identity-providers.md
@ -3,7 +3,7 @@ title: Identity Providers
 description: >-
  This article describes how to connect Pomerium to third-party identity
  providers / single-sign-on services. You will need to generate keys, copy
-  these into your promerium settings, and enable the connection.
+  these into your Pomerium settings, and enable the connection.
 ---

 # Identity Provider Configuration
@ -129,11 +129,11 @@ 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**
+| 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](./gitlab/gitlab-create-application.png)

@ -170,10 +170,10 @@ On the **Credentials** page, click **Create credentials** and choose **OAuth [Cl

 On the **Create [Client ID]** page, select **Web application**. In the new fields that display, set the following parameters:

-Field                    | Description
------------------------ | --------------------------------------------------------------------
-Name                     | The name of your web app
-Authorized redirect URIs | Redirect URL (e.g.`https://authenticate.corp.example.com/oauth2/callback`)
+| Field                    | Description                                                                |
+| ------------------------ | -------------------------------------------------------------------------- |
+| Name                     | The name of your web app                                                   |
+| Authorized redirect URIs | Redirect URL (e.g.`https://authenticate.corp.example.com/oauth2/callback`) |

 ![Web App Credentials Configuration](./google/google-create-client-id-config.png)

@ -246,13 +246,13 @@ On the **Create New Application** page, select the **Web** for your application.

 Next, provide the following information for your application settings:

-Field                        | Description
---------------------------- | ---------------------------------------------------------------------
-Name                         | The name of your application.
-Base URIs (optional)         | The domain(s) of your application.
-Login redirect URIs          | Redirect URL (e.g.`https://authenticate.corp.example.com/oauth2/callback`).
-Group assignments (optional) | The user groups that can sign in to this application.
-Grant type allowed           | **You must enable Refresh Token.**
+| Field                        | Description                                                                 |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| Name                         | The name of your application.                                               |
+| Base URIs (optional)         | The domain(s) of your application.                                          |
+| Login redirect URIs          | Redirect URL (e.g.`https://authenticate.corp.example.com/oauth2/callback`). |
+| Group assignments (optional) | The user groups that can sign in to this application.                       |
+| Grant type allowed           | **You must enable Refresh Token.**                                          |

 ![Okta Create Application Settings](./okta/okta-create-app-settings.png)

@ -270,23 +270,23 @@ Select your desired authorization server and navigate to the **claims tab**. Cli

 ![Okta configure group claim](./okta/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
+| 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
+| 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](./okta/okta-list-groups-claim.png)

--- a/docs/docs/readme.md
+++ b/docs/docs/readme.md
@ -1,3 +1,11 @@
+---
+title: Overview
+lang: en-US
+meta:
+  - name: keywords
+    content: pomerium identity-access-proxy beyondcorp zero-trust reverse-proxy ztn
+---
+
 # Overview

 ## What
@ -28,7 +36,7 @@ Or for the visually inclined.

 ### Zero-trust

-Pomerium -- and zero-trust more broadly -- attempts to mitigate these shortcomings by adopting principles like:
+Pomerium attempts to mitigate these shortcomings by adopting principles like:

 - Trust flows from identity, device-state, and context; not network location.
 - Treat both internal and external networks as completely untrusted.
@ -36,11 +44,12 @@ Pomerium -- and zero-trust more broadly -- attempts to mitigate these shortcomin
 - Every device, user, and application's communication should be authenticated, authorized, and encrypted.
 - Access policy should be dynamic, and built from multiple sources.

+This security model has typically been referred to as zero-trust or BeyondCorp-inspired. 
+
 ## Resources

-Pomerium was designed around the security model originally articulated by [John Kindervag](http://www.virtualstarmedia.com/downloads/Forrester_zero_trust_DNA.pdf) in 2010, and by Google in 2011 which as a result of the [Operation Aurora](https://en.wikipedia.org/wiki/Operation_Aurora) breach.
+Pomerium was inspired by the security model originally articulated by [John Kindervag](http://www.virtualstarmedia.com/downloads/Forrester_zero_trust_DNA.pdf) in 2010, and by Google in 2011 as a result of the [Operation Aurora](https://en.wikipedia.org/wiki/Operation_Aurora) breach.

-Typically this approach to security is called either zero-trust or BeyondCorp-inspired. Here's a curated list of resources covering th

 ### Books