+
+## Demo
+
+To make this a bit more concrete, see the following:
+
+1. An **unauthorized** user authenticating with their corporate single-sign-on provider (in this case Google)
+2. The **unauthorized** user being blocked from a protected resource.
+3. The **unauthorized** user signing out from their session.
+4. An **authorized** user authenticating with their corporate single-sign-on provider.
+5. Pomerium delegating and grating access to the requested resource.
+6. The **authorized** user inspecting their user details including group membership.
+
+
## Docs
-To get started with pomerium, check out our [quick start guide].
+For comprehensive docs, and tutorials see our [documentation].
-For comprehensive docs, and tutorials see our [documentation] and the [godocs].
-
-[awesome-zero-trust]: https://github.com/pomerium/awesome-zero-trust
-[documentation]: https://www.pomerium.io/docs/
+[documentation]: https://www.pomerium.io/
[go environment]: https://golang.org/doc/install
[godocs]: https://godoc.org/github.com/pomerium/pomerium
[quick start guide]: https://www.pomerium.io/guide/
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 2329ce861..746fa827c 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -1,7 +1,8 @@
// .vuepress/config.js
module.exports = {
title: "Pomerium",
- description: "An open source identity-aware access proxy.",
+ description:
+ "Pomerium is a beyond-corp inspired, zero trust, open source identity-aware access proxy.",
plugins: {
sitemap: {
hostname: "https://www.pomerium.io"
@@ -10,58 +11,99 @@ module.exports = {
ga: "UA-129872447-2"
}
},
- extend: "@vuepress/theme-default",
+ markdown: {
+ externalLinkSymbol: false
+ },
themeConfig: {
- repo: "pomerium/pomerium",
+ logo: "/logo-long-civez.png",
editLinks: true,
docsDir: "docs",
editLinkText: "Edit this page on GitHub",
lastUpdated: "Last Updated",
nav: [
{ text: "Documentation", link: "/docs/" },
- { text: "Quick Start", link: "/guide/" },
- { text: "Config Reference", link: "/reference/" },
- {
- text: "Versions",
- items: [
- { text: "v0.0.5", link: "https://v0-0-5.docs.pomerium.io/" },
- { text: "v0.0.4", link: "https://v0-0-4.docs.pomerium.io/" }
- ]
- }
+ { text: "Community", link: "/community/" }
+
+ // {
+ // text: "Versions",
+ // items: [
+ // { text: "v0.1.0", link: "https://v0-1-0.docs.pomerium.io/" },
+ // { text: "v0.0.5", link: "https://v0-0-5.docs.pomerium.io/" },
+ // { text: "v0.0.4", link: "https://v0-0-4.docs.pomerium.io/" }
+ // ]
+ // }
],
+
sidebar: {
- "/guide/": guideSidebar("Quick Start"),
- "/docs/": docsSidebar("Documentation")
+ "/docs/": [
+ {
+ title: "",
+ type: "group",
+ collapsable: false,
+ sidebarDepth: 0,
+ children: ["", "background", "releases", "upgrading", "CHANGELOG"]
+ },
+ {
+ title: "Quick Start",
+ collapsable: false,
+ path: "/docs/quick-start/",
+ type: "group",
+ sidebarDepth: 0,
+ children: [
+ "quick-start/",
+ "quick-start/binary",
+ "quick-start/helm",
+ "quick-start/kubernetes",
+ "quick-start/synology"
+ ]
+ },
+ {
+ title: "Identity Providers",
+ collapsable: false,
+ path: "/docs/identity-providers/",
+ type: "group",
+ sidebarDepth: 0,
+ children: [
+ "identity-providers/",
+ "identity-providers/azure",
+ "identity-providers/gitlab",
+ "identity-providers/google",
+ "identity-providers/okta",
+ "identity-providers/one-login"
+ ]
+ },
+ {
+ title: "Reference",
+ collapsable: true,
+ path: "/docs/reference/",
+ type: "group",
+ collapsable: false,
+ sidebarDepth: 1,
+ children: [
+ "reference/certificates",
+ "reference/impersonation",
+ "reference/signed-headers",
+ "reference/examples",
+ "reference/reference"
+ ]
+ }
+ ],
+ "/community/": [
+ {
+ title: "Community",
+ type: "group",
+
+ collapsable: false,
+ sidebarDepth: 1,
+ children: [
+ "",
+ "contributing",
+ "developers-guide",
+ "code-of-conduct",
+ "security"
+ ]
+ }
+ ]
}
}
};
-
-function guideSidebar(title) {
- return [
- {
- title,
- collapsable: false,
- children: ["", "binary", "from-source", "helm", "kubernetes", "synology"]
- }
- ];
-}
-
-function docsSidebar(title) {
- return [
- {
- title,
- collapsable: false,
- children: [
- "",
- "identity-providers",
- "signed-headers",
- "certificates",
- "examples",
- "impersonation",
- "programmatic-access",
- "upgrading",
- "contributing"
- ]
- }
- ];
-}
diff --git a/docs/.vuepress/override.styl b/docs/.vuepress/override.styl
deleted file mode 100644
index 79735ded2..000000000
--- a/docs/.vuepress/override.styl
+++ /dev/null
@@ -1,4 +0,0 @@
-$accentColor = #6c63ff
-$textColor = #2c3e50
-$borderColor = #eaecef
-$codeBgColor = #282c34
\ No newline at end of file
diff --git a/docs/.vuepress/public/account.svg b/docs/.vuepress/public/account.svg
new file mode 100644
index 000000000..555dcc538
--- /dev/null
+++ b/docs/.vuepress/public/account.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/easier-to-manage.svg b/docs/.vuepress/public/easier-to-manage.svg
new file mode 100644
index 000000000..382ca813e
--- /dev/null
+++ b/docs/.vuepress/public/easier-to-manage.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/favicon.ico b/docs/.vuepress/public/favicon.ico
new file mode 100644
index 000000000..50a7612c0
Binary files /dev/null and b/docs/.vuepress/public/favicon.ico differ
diff --git a/docs/.vuepress/public/logo-long-civez.png b/docs/.vuepress/public/logo-long-civez.png
new file mode 100644
index 000000000..4d1c2a853
Binary files /dev/null and b/docs/.vuepress/public/logo-long-civez.png differ
diff --git a/docs/.vuepress/public/logo-long-white-civez.png b/docs/.vuepress/public/logo-long-white-civez.png
new file mode 100644
index 000000000..5b9c72af7
Binary files /dev/null and b/docs/.vuepress/public/logo-long-white-civez.png differ
diff --git a/docs/.vuepress/public/logo-long-white.svg b/docs/.vuepress/public/logo-long-white.svg
index e76e287b9..9b8efeb2e 100644
--- a/docs/.vuepress/public/logo-long-white.svg
+++ b/docs/.vuepress/public/logo-long-white.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/logo-long.svg b/docs/.vuepress/public/logo-long.svg
index 4b9916dc6..3a6de5697 100644
--- a/docs/.vuepress/public/logo-long.svg
+++ b/docs/.vuepress/public/logo-long.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/logo-no-text.svg b/docs/.vuepress/public/logo-no-text.svg
index 528a33564..ffd841103 100644
--- a/docs/.vuepress/public/logo-no-text.svg
+++ b/docs/.vuepress/public/logo-no-text.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/logo-only.png b/docs/.vuepress/public/logo-only.png
index f6965796c..17a7cdd6f 100644
Binary files a/docs/.vuepress/public/logo-only.png and b/docs/.vuepress/public/logo-only.png differ
diff --git a/docs/.vuepress/public/logo-stacked.svg b/docs/.vuepress/public/logo-stacked.svg
index 41d399be9..9e8cd00de 100644
--- a/docs/.vuepress/public/logo-stacked.svg
+++ b/docs/.vuepress/public/logo-stacked.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/logo-white.png b/docs/.vuepress/public/logo-white.png
new file mode 100644
index 000000000..42fde25dd
Binary files /dev/null and b/docs/.vuepress/public/logo-white.png differ
diff --git a/docs/.vuepress/public/logo.svg b/docs/.vuepress/public/logo.svg
index f3a549e94..ac3a4a6fc 100644
--- a/docs/.vuepress/public/logo.svg
+++ b/docs/.vuepress/public/logo.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/pomerium-diagram.svg b/docs/.vuepress/public/pomerium-diagram.svg
new file mode 100644
index 000000000..cca32d6f9
--- /dev/null
+++ b/docs/.vuepress/public/pomerium-diagram.svg
@@ -0,0 +1,2 @@
+
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/pomerium-in-action-800-600.mp4 b/docs/.vuepress/public/pomerium-in-action-800-600.mp4
new file mode 100644
index 000000000..2042ca7e1
Binary files /dev/null and b/docs/.vuepress/public/pomerium-in-action-800-600.mp4 differ
diff --git a/docs/.vuepress/public/remote.svg b/docs/.vuepress/public/remote.svg
new file mode 100644
index 000000000..70717310e
--- /dev/null
+++ b/docs/.vuepress/public/remote.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/secure-server.svg b/docs/.vuepress/public/secure-server.svg
new file mode 100644
index 000000000..a59520606
--- /dev/null
+++ b/docs/.vuepress/public/secure-server.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/.vuepress/public/security-in-depth.svg b/docs/.vuepress/public/security-in-depth.svg
new file mode 100644
index 000000000..4d9d27ae8
--- /dev/null
+++ b/docs/.vuepress/public/security-in-depth.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/.vuepress/styles/palette.styl b/docs/.vuepress/styles/palette.styl
deleted file mode 100644
index cf07438e6..000000000
--- a/docs/.vuepress/styles/palette.styl
+++ /dev/null
@@ -1,16 +0,0 @@
-// colors
-$accentColor = #6E43E8
-$textColor = #24292e
-$borderColor = #e8e8fb
-$codeBgColor = #282c34
-$arrowBgColor = #ccc
-
-// layout
-// $navbarHeight = 3.6rem
-// $sidebarWidth = 20rem
-// $contentWidth = 740px
-
-// // responsive breakpoints
-// $MQNarrow = 959px
-// $MQMobile = 719px
-// $MQMobileNarrow = 419px
diff --git a/docs/.vuepress/theme/components/AlgoliaSearchBox.vue b/docs/.vuepress/theme/components/AlgoliaSearchBox.vue
new file mode 100644
index 000000000..a7a6c0985
--- /dev/null
+++ b/docs/.vuepress/theme/components/AlgoliaSearchBox.vue
@@ -0,0 +1,158 @@
+
+
+
+
+
+
+
diff --git a/docs/.vuepress/theme/components/DropdownLink.vue b/docs/.vuepress/theme/components/DropdownLink.vue
new file mode 100644
index 000000000..0d360830e
--- /dev/null
+++ b/docs/.vuepress/theme/components/DropdownLink.vue
@@ -0,0 +1,179 @@
+
+ {{ data.heroText || $title || 'Hello' }}
+ +{{ data.tagline || $description || 'Welcome to your VuePress site' }}
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+ ![]()
+
+
+
+ {{ feature.title }}
+{{ feature.text }}
+
+
+
+
+
+
+
+ ![]()
+
+ {{ feature.title }}
+{{ feature.text }}
+
-For years, secure remote access meant firewalls, network segmentation, and VPNs. However, several [high-profile](https://en.wikipedia.org/wiki/Operation_Aurora) [security](https://krebsonsecurity.com/2014/02/target-hackers-broke-in-via-hvac-company/) breaches have shown the limitations of [perimeter](https://www.redbooks.ibm.com/redpapers/pdfs/redp4397.pdf) [security](https://en.wikipedia.org/wiki/Perimeter_Security), namely:
+## In action
-- Perimeter security does a poor job of addressing the insider-threat and 28% percent of breaches are [by internal actors](http://www.documentwereld.nl/files/2018/Verizon-DBIR_2018-Main_report.pdf).
-- The _impenetrable fortress_ theory of perimeter security is anything but in practice; most corporate networks have multiple entry points, lots of firewall rules, and constant pressure to expand network segmentation boundaries.
-- Even defining "what" a perimeter is is difficult as corporate networks have come to consist of an increasingly [heterogeneous](https://youtu.be/bDJb8WOJYdA?t=532) mix of on-premise, public, and private clouds.
-- VPNs frustrate end-users, give a false sense of security, and often fail to provide defense-in-depth.
+To make this a bit more concrete, see the following short video which demonstrates:
-Or for the visually inclined.
+1. An **unauthorized** user authenticating with their corporate single-sign-on provider (in this case Google)
+2. The **unauthorized** user being blocked from a protected resource.
+3. The **unauthorized** user signing out from their session.
+4. An **authorized** user authenticating with their corporate single-sign-on provider.
+5. Pomerium delegating and grating access to the requested resource.
+6. The **authorized** user inspecting their user details including group membership.
-
-
-> SSL added and removed here :^) - [NSA](https://www.zdnet.com/article/google-the-nsa-and-the-need-for-locking-down-datacenter-traffic/)
-
-### Zero-trust
-
-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.
-- Act like you are already breached, because you probably are.
-- 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 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.
-
-
-### Books
-
-- [Zero Trust Networks](http://shop.oreilly.com/product/0636920052265.do) by Gilman and Barth
-
-### Papers
-
-- Forrester [Build Security Into Your Network's DNA: The Zero Trust Network Architecture](http://www.virtualstarmedia.com/downloads/Forrester_zero_trust_DNA.pdf)
-- Google BeyondCorp 1 [An overview: "A New Approach to Enterprise Security"](https://research.google.com/pubs/pub43231.html)
-- Google BeyondCorp 2 [How Google did it: "Design to Deployment at Google"](https://research.google.com/pubs/pub44860.html)
-- Google BeyondCorp 3 [Google's front-end infrastructure: "The Access Proxy"](https://research.google.com/pubs/pub45728.html)
-- Google BeyondCorp 4 [Migrating to BeyondCorp: Maintaining Productivity While Improving Security](https://research.google.com/pubs/pub46134.html)
-- Google BeyondCorp 5 [The human element: "The User Experience"](https://research.google.com/pubs/pub46366.html)
-- Google BeyondCorp 6 [Secure your endpoints: "Building a Healthy Fleet"](https://ai.google/research/pubs/pub47356)
-
-### Posts
-
-- Google [Securing your business and securing your fleet the BeyondCorp way](https://cloud.google.com/blog/products/identity-security/securing-your-business-and-securing-your-fleet-the-beyondcorp-way)
-- Google [Preparing for a BeyondCorp world: Understanding your device inventory](https://cloud.google.com/blog/products/identity-security/preparing-beyondcorp-world-understanding-your-device-inventory)
-- Google [How BeyondCorp can help businesses be more productive](https://www.blog.google/products/google-cloud/how-beyondcorp-can-help-businesses-be-more-productive/)
-- Google [How to use BeyondCorp to ditch your VPN, improve security and go to the cloud](https://www.blog.google/products/google-cloud/how-use-beyondcorp-ditch-your-vpn-improve-security-and-go-cloud/)
-- Wall Street Journal [Google Moves Its Corporate Applications to the Internet](https://blogs.wsj.com/cio/2015/05/11/google-moves-its-corporate-applications-to-the-internet/)
-
-### Videos
-
-- [USENIX Enigma 2016 - NSA TAO Chief on Disrupting Nation State Hackers](https://youtu.be/bDJb8WOJYdA?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf)
-- [What, Why, and How of Zero Trust Networking](https://youtu.be/eDVHIfVSdIo?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Armon Dadgar, Hashicorp
-- [O'Reilly Security 2017 NYC Beyondcorp: Beyond Fortress Security](https://youtu.be/oAvDASLehpY?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Neal Muller, Google
-- [Be Ready for BeyondCorp: enterprise identity, perimeters and your application](https://youtu.be/5UiWAlwok1s?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Jason Kent
-
-[identity provider]: ../docs/identity-providers.md
-[sso]: https://en.wikipedia.org/wiki/Single_sign-on
+
diff --git a/docs/docs/certificates.md b/docs/docs/reference/certificates.md
similarity index 94%
rename from docs/docs/certificates.md
rename to docs/docs/reference/certificates.md
index 43c7168b8..b2b5aa579 100644
--- a/docs/docs/certificates.md
+++ b/docs/docs/reference/certificates.md
@@ -36,7 +36,7 @@ Since one of Pomerium's core [principles] is to treat internal and external traf
First, you'll want to set a [CNAME](https://en.wikipedia.org/wiki/CNAME_record) record for wild-card domain name you will be using with Pomerium.
-
+
Once you've setup your wildcard domain, we can use acme.sh to create a certificate-signing request with LetsEncrypt.
@@ -69,7 +69,7 @@ Not Found domain api file:
LetsEncrypt will respond with the corresponding `TXT` record needed to verify our domain.
-
+
It may take a few minutes for the DNS records to propagate. Once it does, you can run the following command to complete the certificate request process.
@@ -110,9 +110,9 @@ Pomerium Config | Certificate file
Your end users will see a valid certificate for all domains delegated by Pomerium.
-
+
-
+
## Resources
diff --git a/docs/docs/examples.md b/docs/docs/reference/examples.md
similarity index 78%
rename from docs/docs/examples.md
rename to docs/docs/reference/examples.md
index bdec12f61..38dd4b19a 100644
--- a/docs/docs/examples.md
+++ b/docs/docs/reference/examples.md
@@ -2,7 +2,7 @@
sidebarDepth: 2
---
-# Example configs
+# Config 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.
@@ -12,15 +12,17 @@ Remember to set your identity provider settings and to generate new secret keys!
:::
+[[toc]]
+
## Configurations
#### Configuration File
-<<< @/docs/docs/examples/config/config.example.yaml
+<<< @/docs/docs/reference/examples/config/config.example.yaml
#### Environmental Variables
-<<< @/docs/docs/examples/config/config.example.env
+<<< @/docs/docs/reference/examples/config/config.example.env
## Binary
@@ -34,7 +36,6 @@ 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`
-
## Docker
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.
@@ -50,7 +51,7 @@ Customize for your identity provider run `docker-compose up -f basic.docker-comp
#### basic.docker-compose.yml
-<<< @/docs/docs/examples/docker/basic.docker-compose.yml
+<<< @/docs/docs/reference/examples/docker/basic.docker-compose.yml
#### NGINX micro-services
@@ -63,7 +64,7 @@ Customize for your identity provider run `docker-compose up -f nginx.docker-comp
#### nginx.docker-compose.yml
-<<< @/docs/docs/examples/docker/nginx.docker-compose.yml
+<<< @/docs/docs/reference/examples/docker/nginx.docker-compose.yml
## Helm
@@ -98,31 +99,31 @@ Customize for your identity provider run `docker-compose up -f nginx.docker-comp
#### authenticate.deploy.yml
-<<< @/docs/docs/examples/kubernetes/authenticate.deploy.yml
+<<< @/docs/docs/reference/examples/kubernetes/authenticate.deploy.yml
#### authenticate.service.yml
-<<< @/docs/docs/examples/kubernetes/authenticate.service.yml
+<<< @/docs/docs/reference/examples/kubernetes/authenticate.service.yml
#### authorize.deploy.yml
-<<< @/docs/docs/examples/kubernetes/authorize.deploy.yml
+<<< @/docs/docs/reference/examples/kubernetes/authorize.deploy.yml
#### authorize.service.yml
-<<< @/docs/docs/examples/kubernetes/authorize.service.yml
+<<< @/docs/docs/reference/examples/kubernetes/authorize.service.yml
#### proxy.deploy.yml
-<<< @/docs/docs/examples/kubernetes/proxy.deploy.yml
+<<< @/docs/docs/reference/examples/kubernetes/proxy.deploy.yml
#### proxy.service.yml
-<<< @/docs/docs/examples/kubernetes/proxy.service.yml
+<<< @/docs/docs/reference/examples/kubernetes/proxy.service.yml
#### ingress.yml
-<<< @/docs/docs/examples/kubernetes/ingress.yml
+<<< @/docs/docs/reference/examples/kubernetes/ingress.yml
[helloworld]: https://hub.docker.com/r/tutum/hello-world
[httpbin]: https://httpbin.org/
diff --git a/docs/docs/examples/config/config.example.env b/docs/docs/reference/examples/config/config.example.env
similarity index 100%
rename from docs/docs/examples/config/config.example.env
rename to docs/docs/reference/examples/config/config.example.env
diff --git a/docs/docs/examples/config/config.example.yaml b/docs/docs/reference/examples/config/config.example.yaml
similarity index 100%
rename from docs/docs/examples/config/config.example.yaml
rename to docs/docs/reference/examples/config/config.example.yaml
diff --git a/docs/docs/examples/config/config.minimal.env b/docs/docs/reference/examples/config/config.minimal.env
similarity index 100%
rename from docs/docs/examples/config/config.minimal.env
rename to docs/docs/reference/examples/config/config.minimal.env
diff --git a/docs/docs/examples/config/config.minimal.yaml b/docs/docs/reference/examples/config/config.minimal.yaml
similarity index 100%
rename from docs/docs/examples/config/config.minimal.yaml
rename to docs/docs/reference/examples/config/config.minimal.yaml
diff --git a/docs/docs/examples/config/policy.example.yaml b/docs/docs/reference/examples/config/policy.example.yaml
similarity index 100%
rename from docs/docs/examples/config/policy.example.yaml
rename to docs/docs/reference/examples/config/policy.example.yaml
diff --git a/docs/docs/examples/docker/basic.docker-compose.yml b/docs/docs/reference/examples/docker/basic.docker-compose.yml
similarity index 100%
rename from docs/docs/examples/docker/basic.docker-compose.yml
rename to docs/docs/reference/examples/docker/basic.docker-compose.yml
diff --git a/docs/docs/examples/docker/nginx.docker-compose.yml b/docs/docs/reference/examples/docker/nginx.docker-compose.yml
similarity index 100%
rename from docs/docs/examples/docker/nginx.docker-compose.yml
rename to docs/docs/reference/examples/docker/nginx.docker-compose.yml
diff --git a/docs/docs/examples/kubernetes/authenticate.deploy.yml b/docs/docs/reference/examples/kubernetes/authenticate.deploy.yml
similarity index 100%
rename from docs/docs/examples/kubernetes/authenticate.deploy.yml
rename to docs/docs/reference/examples/kubernetes/authenticate.deploy.yml
diff --git a/docs/docs/examples/kubernetes/authenticate.service.yml b/docs/docs/reference/examples/kubernetes/authenticate.service.yml
similarity index 100%
rename from docs/docs/examples/kubernetes/authenticate.service.yml
rename to docs/docs/reference/examples/kubernetes/authenticate.service.yml
diff --git a/docs/docs/examples/kubernetes/authorize.deploy.yml b/docs/docs/reference/examples/kubernetes/authorize.deploy.yml
similarity index 100%
rename from docs/docs/examples/kubernetes/authorize.deploy.yml
rename to docs/docs/reference/examples/kubernetes/authorize.deploy.yml
diff --git a/docs/docs/examples/kubernetes/authorize.service.yml b/docs/docs/reference/examples/kubernetes/authorize.service.yml
similarity index 100%
rename from docs/docs/examples/kubernetes/authorize.service.yml
rename to docs/docs/reference/examples/kubernetes/authorize.service.yml
diff --git a/docs/docs/examples/kubernetes/ingress.nginx.yml b/docs/docs/reference/examples/kubernetes/ingress.nginx.yml
similarity index 100%
rename from docs/docs/examples/kubernetes/ingress.nginx.yml
rename to docs/docs/reference/examples/kubernetes/ingress.nginx.yml
diff --git a/docs/docs/examples/kubernetes/ingress.yml b/docs/docs/reference/examples/kubernetes/ingress.yml
similarity index 100%
rename from docs/docs/examples/kubernetes/ingress.yml
rename to docs/docs/reference/examples/kubernetes/ingress.yml
diff --git a/docs/docs/examples/kubernetes/proxy.deploy.yml b/docs/docs/reference/examples/kubernetes/proxy.deploy.yml
similarity index 100%
rename from docs/docs/examples/kubernetes/proxy.deploy.yml
rename to docs/docs/reference/examples/kubernetes/proxy.deploy.yml
diff --git a/docs/docs/examples/kubernetes/proxy.service.yml b/docs/docs/reference/examples/kubernetes/proxy.service.yml
similarity index 100%
rename from docs/docs/examples/kubernetes/proxy.service.yml
rename to docs/docs/reference/examples/kubernetes/proxy.service.yml
diff --git a/docs/docs/reference/img/certificate-domain-challenge.png b/docs/docs/reference/img/certificate-domain-challenge.png
new file mode 100644
index 000000000..7f0dcc71c
Binary files /dev/null and b/docs/docs/reference/img/certificate-domain-challenge.png differ
diff --git a/docs/docs/reference/img/certificate-wildcard-domain.png b/docs/docs/reference/img/certificate-wildcard-domain.png
new file mode 100644
index 000000000..bf7b8c395
Binary files /dev/null and b/docs/docs/reference/img/certificate-wildcard-domain.png differ
diff --git a/docs/docs/reference/img/certificates-ssl-report.png b/docs/docs/reference/img/certificates-ssl-report.png
new file mode 100644
index 000000000..a56663a8d
Binary files /dev/null and b/docs/docs/reference/img/certificates-ssl-report.png differ
diff --git a/docs/docs/reference/img/certificates-valid-secure-certificate.png b/docs/docs/reference/img/certificates-valid-secure-certificate.png
new file mode 100644
index 000000000..68fc6275e
Binary files /dev/null and b/docs/docs/reference/img/certificates-valid-secure-certificate.png differ
diff --git a/docs/docs/reference/img/inspect-headers.png b/docs/docs/reference/img/inspect-headers.png
new file mode 100644
index 000000000..09c5bbf49
Binary files /dev/null and b/docs/docs/reference/img/inspect-headers.png differ
diff --git a/docs/docs/reference/img/jaeger.png b/docs/docs/reference/img/jaeger.png
new file mode 100644
index 000000000..ea1b1b53d
Binary files /dev/null and b/docs/docs/reference/img/jaeger.png differ
diff --git a/docs/docs/impersonation/pomerium-user-impersonation.mp4 b/docs/docs/reference/img/pomerium-user-impersonation.mp4
similarity index 100%
rename from docs/docs/impersonation/pomerium-user-impersonation.mp4
rename to docs/docs/reference/img/pomerium-user-impersonation.mp4
diff --git a/docs/docs/reference/img/security-headers.png b/docs/docs/reference/img/security-headers.png
new file mode 100644
index 000000000..d8833385a
Binary files /dev/null and b/docs/docs/reference/img/security-headers.png differ
diff --git a/docs/docs/reference/img/verifying-headers-1.png b/docs/docs/reference/img/verifying-headers-1.png
new file mode 100644
index 000000000..087de50cd
Binary files /dev/null and b/docs/docs/reference/img/verifying-headers-1.png differ
diff --git a/docs/docs/reference/img/verifying-headers-2.png b/docs/docs/reference/img/verifying-headers-2.png
new file mode 100644
index 000000000..67883ef7a
Binary files /dev/null and b/docs/docs/reference/img/verifying-headers-2.png differ
diff --git a/docs/docs/impersonation.md b/docs/docs/reference/impersonation.md
similarity index 92%
rename from docs/docs/impersonation.md
rename to docs/docs/reference/impersonation.md
index ebc62a938..a7e1f10e0 100644
--- a/docs/docs/impersonation.md
+++ b/docs/docs/reference/impersonation.md
@@ -36,7 +36,7 @@ In certain circumstances, it's useful for an administrative user to impersonate
Here's what it looks like.
-