docs: add nginx example (#1329)

* docs: add nginx example

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
This commit is contained in:
Travis Groth 2020-08-26 17:10:23 -04:00 committed by GitHub
parent 51bdf9baae
commit a69b9957a1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 336 additions and 0 deletions

View file

@ -155,6 +155,7 @@ module.exports = {
"kubernetes-dashboard", "kubernetes-dashboard",
"local-oidc", "local-oidc",
"mtls", "mtls",
'nginx',
"tiddlywiki", "tiddlywiki",
"vs-code-server", "vs-code-server",
], ],

99
docs/guides/nginx.md Normal file
View file

@ -0,0 +1,99 @@
---
title: Nginx
lang: en-US
meta:
- name: keywords
content: pomerium identity-access-proxy nginx
description: >-
This guide covers how to use Pomerium to protect services behind an nginx
proxy.
---
# Securing Nginx
This recipe's sources can be found [on github](https://github.com/pomerium/pomerium/tree/master/examples/nginx)
At the end, you will have a locally running install of [httpbin](https://httpbin.org/) behind nginx with policy enforced by Pomerium.
## Background
Nginx can be [configured](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/) to authorize requests by calling an external authorization service. Pomerium is compatible with this external authentication protocol and can thus be used to protect services behind nginx. In this configuration, Pomerium does not proxy traffic, but authorizes it on behalf of nginx. This is useful for integrating into existing load balancer infrastructure.
For more information on using Pomerium as an external authorization endpoint, see [forward auth](https://www.pomerium.com/reference/#forward-auth) in the Pomerium docs.
## How It Works
- Create a standard pomerium configuration to authenticate against your identity provider (IdP)
- Configure nginx to authorize incoming requests via pomerium
- Pomerium authenticates users via IdP
- Nginx queries Pomerium on each request to verify the traffic is authorized
- Pomerium verifies the traffic against policy, responding to nginx
- Nginx proxies the traffic or responds with an error
## Pre-requisites
This recipe is designed to run on a local docker-compose instance. The included configuration can be adopted for any nginx deployment.
- docker
- docker-compose
- A copy of the [example repo](https://github.com/pomerium/pomerium/tree/master/examples/nginx) checked out
- Valid credentials for your OIDC provider
- (Optional) `mkcert` to generate locally trusted certificates
## Certificates (optional)
This demo comes with its own certificates, but they will generate warnings in your browser. You may instead provide your own or use [mkcert](https://github.com/FiloSottile/mkcert) to generate locally trusted certificates.
After installing `mkcert`, run the following inside the example repo:
```bash
mkcert -install
mkcert '*.localhost.pomerium.io'
```
This will install a trusted CA and generate a new wildcard certificate:
- `_wildcard.localhost.pomerium.io.pem`
- `_wildcard.localhost.pomerium.io-key.pem`
To provide your own certificates through another mechanism, please overwrite these files or update `docker-compose.yaml` accordingly.
## Configure
### Pomerium
Update `config.yaml` with your IdP settings and desired policy
<<< @/examples/nginx/config.yaml
### Nginx - pomerium
Nginx configuration for Pomerium endpoints
<<< @/examples/nginx/pomerium.conf
### Nginx - httpbin
Nginx configuration for the protected endpoint
<<< @/examples/nginx/httpbin.conf
### Docker Compose
<<< @/examples/nginx/docker-compose.yaml
Run `docker-compose up`. After a few seconds, browse to [httpbin.localhost.pomerium.io](https://httpbin.localhost.pomerium.io).
You should be prompted to log in through your IdP and then granted access to the deployed `httpbin` instance.
## That's it!
Your `httpbin` install is protected by Pomerium.
## Adapting
To re-use the configuration in this demo in other contexts:
- Update `httpbin.conf` to reflect the correct forward auth URL in `location @error401`
- Update `pomerium.conf` to reflect the pomerium hostname(s) or IP(s) in `upstream pomerium`
- Update `pomerium.conf` to reflect your pomerium authenticate and forward auth hostnames in `server_name`

17
examples/nginx/README.md Normal file
View file

@ -0,0 +1,17 @@
# Pomerium as external auth provider for Nginx
Run this demo locally on your docker-compose capable workstation, or replace `localhost.pomerium.io` with your own domain if running on a server.
## Includes
- Authentication and Authorization managed by pomerium
- Routing / reverse proxying handled by nginx
## How
- Update `config.yaml` for your e-mail address, if not using gmail/google.
- Replace secrets in `config.yaml`.
- Run `docker-compose up` from this directory.
- Navigate to `https://httpbin.localhost.pomerium.io`
- ???
- Profit

View file

@ -0,0 +1,28 @@
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDXfeTmeNmQFK3r
CrLcdh9pVrsSjbNOAP2BIQ3AfGdf/S0UqjU1UhXOb2gLm5Dsj/vFvs/fSkiahBdj
7zR1dh7jdOnf3QgcAjIMTo7sJggsABHBF0vHVMXJtNoWmZ+AYOirsn22N3EoUNmX
jlr19LnW07DtkHJFPYsYFy01uOEKGbzKQh8E6DFv3tPNp/raUHkGSAUpT11tZcdf
vbSHuSN4xzGOs6T9QCnu0wCGb2MJNa8l5dhtVuy59jcZWM2i4EBLnXsYbHhkg/uZ
xnVfm3YxgNM8bA2T1DqSUxjpLt7Dty9MHBaEyHVrH/nXYluF1wI7jNC2A7dE6VKq
AkSmFKG7AgMBAAECggEARCYmW9TgSTahAfIyOpKIwJGTO/zgNc0OXuYLKVKuhqbU
uPJTPXemOdD1wKYEISwv3YvIxb8CUwtvMkWV+4fNoPV6eTe3ttPi7A10Ga61auTi
uIQbjQB8RJwTVI5k6P681n/uTdAe0zcueUWl8p7gntX34EmMOeWKtaWuwIylbsG8
Ftvls8dI/soHUBgZT9HHo3ZitaRQtDYN+YjqAWfQCtPFrBJ5TPS9W6z3cmB/2l19
nkwZljomj+mJZseEStQUOH/YXf7jpZCWNuxj9l9C+/F5pmiQX6w87thohVXFPmXx
zEExPHePvThx4CxrUGyBeWfzUaYMfzx1T/gyMixDYQKBgQD642G2ElXQSnlZZoLf
gMYTazAjtv7PIRVcVjOJfUORx5LP4sV7CkWokIMdbzfiVkerWt6kb2HDhBskvdFW
ag6Fl8t/Miyi+ZTrE/PmZJqs7fGtmSqjY8wWKfcN6gyTPkh789DXU7ddJIiJLQ10
sf5Mg2sQkMLQo5XnnauV/SmKiQKBgQDb4eL/MmSR7yKnjxjvek7xXJGqaEXBmazn
pUhp6B+7aHsAg/u71DjzirMn2Ra3+WQ+sDQwbkMQuokqBPUij0Bcv61QSaocjrnb
PmwtXlHeyk9RnGj60oW55gIuJw0EseI17IaqHJPyDNVCQ9WJteI4y8Da+m0E5ohZ
udXzk9DpIwKBgCK3xnS4ktFxDNvXOLMPEdnsEkxO7XHiRR9y+kzDXc9Vi7ZizisZ
n8wUu2AeXOBgSiinOXoNw7yXkl4COm633GyWNd3TJqQi332sVCsErvbRMolwUZss
mzhR9FMjmTvi+YrVkYfKmOw1uwMojd0hKGyUHwO61IqkqIDVq8Hkt5PpAoGBAMlH
RdwF7ToJhdeMjm7pr0oSSuWK/g/y9Ow3yMnpyuJrCe2248FUy61k0gswFjPi/3jD
I4MR7CJsHxNv5lX0fB5q9+P/CtGJdWjVA4GkTZ175I/4dcDk5bT+cBB/ftNFYqWq
Frux3Vw9kxpNrjOZY7RKEAhkJVfPEBHSo5+NODexAoGAXohoO9jOeLtYFOYRdKxj
bbL7fwiR+ecBakiuakoIFc+ibH57fDvxA6YkbLFOVNrpsTVNIbgO9Jois3GhrEGH
8TbGfohpmwC7nZ62aFJSNxD48gYvYzMamo0WymM1uH3jwlJY/kVO6KHopcN8+kQS
/zG8+V/OgnBBvyfWWX8ygio=
-----END PRIVATE KEY-----

View file

@ -0,0 +1,24 @@
-----BEGIN CERTIFICATE-----
MIIEAjCCAmqgAwIBAgIRAJGdiQDsLfchZYUtx06mQpswDQYJKoZIhvcNAQELBQAw
RTEeMBwGA1UEChMVbWtjZXJ0IGRldmVsb3BtZW50IENBMQ0wCwYDVQQLEwR0ZXN0
MRQwEgYDVQQDEwtta2NlcnQgdGVzdDAeFw0xOTA2MDEwMDAwMDBaFw0zMDA4MjQx
OTQyNTBaMDgxJzAlBgNVBAoTHm1rY2VydCBkZXZlbG9wbWVudCBjZXJ0aWZpY2F0
ZTENMAsGA1UECxMEdGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
ANd95OZ42ZAUresKstx2H2lWuxKNs04A/YEhDcB8Z1/9LRSqNTVSFc5vaAubkOyP
+8W+z99KSJqEF2PvNHV2HuN06d/dCBwCMgxOjuwmCCwAEcEXS8dUxcm02haZn4Bg
6KuyfbY3cShQ2ZeOWvX0udbTsO2QckU9ixgXLTW44QoZvMpCHwToMW/e082n+tpQ
eQZIBSlPXW1lx1+9tIe5I3jHMY6zpP1AKe7TAIZvYwk1ryXl2G1W7Ln2NxlYzaLg
QEudexhseGSD+5nGdV+bdjGA0zxsDZPUOpJTGOku3sO3L0wcFoTIdWsf+ddiW4XX
AjuM0LYDt0TpUqoCRKYUobsCAwEAAaN6MHgwDgYDVR0PAQH/BAQDAgWgMBMGA1Ud
JQQMMAoGCCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAU0t8UaNj7
xry1h0qnTAm8Sxv69aMwIgYDVR0RBBswGYIXKi5sb2NhbGhvc3QucG9tZXJpdW0u
aW8wDQYJKoZIhvcNAQELBQADggGBAJhOdplKGoR7/83qDjELdjhaoecZASqs5M+P
Sxm7z5s+KSbElebw6/rHJciKAlT9tqHQO6CqliQ9hl4AHWxi+cjpwfxyqWn/VGIa
4WoGyInd/I2PDne+5bIj0MXkikilk5NsJtypvGGjZJTF2T07QfXLlLi3nYTMHYzt
TLZpu7vK+B2ZGCGG4o9pws5ZFjtuOXEDGsE1APPp3xjvC/uJt2xgqo4XcRGIVHgm
mY2yi5KmUCAv0HHdDjxZoqEDazv8t/VuPc3hJcuUcIBZvyMFyPNMqN5ePI7D5TkD
zOqW28I8jpB5zdDpCr4qXsU+Cf+4fB0jDncBq95n1v8EJsm7zeTIFZNgLv3ISthF
lGEFS1zv+ybCOYPl3H0yd13S6N4QUHbESXHvZ2l2V1qDiKrfFcVhQ5ZEDD7/HDqT
N+v7zzMOzmPNCSiky1lMMj/vP87AjaliJnvBcT4F5iU867ws/Refh+yege2l6roO
LEM1YmdMYuNFbCsS2BbQsK9mbDkcmQ==
-----END CERTIFICATE-----

View file

@ -0,0 +1,21 @@
# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
pomerium_debug: true
address: :80
cookie_secret: YVFTMIfW8yBJw+a6sYwdW8rHbU+IAAV/SUkCTg9Jtpo=
shared_secret: 80ldlrU2d7w+wVpKNfevk6fmb8otEx6CqOfshj2LwhQ=
idp_provider: "google"
idp_client_id: REPLACEME
idp_client_secret: REPLACEME
insecure_server: true
forward_auth_url: http://fwdauth.localhost.pomerium.io
authenticate_service_url: https://authenticate.localhost.pomerium.io
policy:
- from: https://httpbin.localhost.pomerium.io
to: https://httpbin
allowed_domains:
- pomerium.com
- gmail.com

View file

@ -0,0 +1,24 @@
version: "3"
services:
nginx:
image: nginx
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./httpbin.conf:/etc/nginx/conf.d/httpbin.conf
- ./pomerium.conf:/etc/nginx/conf.d/pomerium.conf
- ./_wildcard.localhost.pomerium.io.pem:/etc/nginx/nginx.pem
- ./_wildcard.localhost.pomerium.io-key.pem:/etc/nginx/nginx-key.pem
httpbin:
image: kennethreitz/httpbin:latest
expose:
- 80
pomerium:
image: pomerium/pomerium:latest
volumes:
- ./config.yaml:/pomerium/config.yaml:ro
expose:
- 80

View file

@ -0,0 +1,37 @@
# Protected application
server {
listen 443 ssl;
listen 80;
server_name httpbin.localhost.pomerium.io;
ssl_certificate /etc/nginx/nginx.pem;
ssl_certificate_key /etc/nginx/nginx-key.pem;
location / {
proxy_pass http://httpbin;
}
### External Authorization
# Send auth check to /authorize location.
auth_request /authorize;
# Set cookies we get back from the auth check
auth_request_set $saved_set_cookie $upstream_http_set_cookie;
add_header Set-Cookie $saved_set_cookie;
# If we get a 401, respond with a named location
error_page 401 = @error401;
# On 401, redirect the user to forward auth to start authentication flow
location @error401 {
return 302 https://fwdauth.localhost.pomerium.io/?uri=$scheme://$http_host$request_uri;
}
# The auth request must be a subpath of the server
location /authorize {
proxy_pass http://pomerium/verify?uri=$scheme://$http_host$request_uri;
proxy_set_header Host fwdauth.localhost.pomerium.io;
proxy_http_version 1.1;
}
### End External Authorization
}

View file

@ -0,0 +1,19 @@
# Pomerium endpoint
server {
listen 443 ssl;
server_name authenticate.localhost.pomerium.io fwdauth.localhost.pomerium.io;
ssl_certificate /etc/nginx/nginx.pem;
ssl_certificate_key /etc/nginx/nginx-key.pem;
location / {
proxy_pass http://pomerium;
proxy_set_header Host $http_host;
proxy_http_version 1.1;
}
}
# Define an upstream so that we don't need resolvers when we use variables in proxy_pass directives
# https://stackoverflow.com/questions/17685674/nginx-proxy-pass-with-remote-addr
upstream pomerium {
server pomerium;
}

View file

@ -0,0 +1,40 @@
-----BEGIN PRIVATE KEY-----
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
9k5AET80ZLKc7XYQ0NxI2yCf
-----END PRIVATE KEY-----

26
examples/nginx/rootCA.pem Normal file
View file

@ -0,0 +1,26 @@
-----BEGIN CERTIFICATE-----
MIIEWTCCAsGgAwIBAgIQBA3zYaPnHKhRmKC37lWvEjANBgkqhkiG9w0BAQsFADBF
MR4wHAYDVQQKExVta2NlcnQgZGV2ZWxvcG1lbnQgQ0ExDTALBgNVBAsTBHRlc3Qx
FDASBgNVBAMTC21rY2VydCB0ZXN0MB4XDTIwMDgyNDE5NDIwOVoXDTMwMDgyNDE5
NDIwOVowRTEeMBwGA1UEChMVbWtjZXJ0IGRldmVsb3BtZW50IENBMQ0wCwYDVQQL
EwR0ZXN0MRQwEgYDVQQDEwtta2NlcnQgdGVzdDCCAaIwDQYJKoZIhvcNAQEBBQAD
ggGPADCCAYoCggGBAK5vzHoxEjVpZlWTup+lCfsIrp8Ic1x4GFJAUwcEldAsQB7f
i42AXWH41AYzbNooNnyEixE1mrR1X+BfJ3sAwDkLwPLId+rOiIcl5NcqioYSaL8z
Jd+cevo3itCmgb3tJsAIph806H8wPTmAiDnUuttMrUbMXKDQBWe2y+abevc00e/8
EkpUpX7YdnHUPzfFwGy10sMA922ZTfNJPOLFBgNOXOzWBSsk98kCLWwAwz9FsMpO
aCxgminEANFiV04i9kRmo+u6kidSLi+IUSixvR2lJJ4eQoGBWXzVfauj5Yfi+B+h
4aSm7qaHrsV83VaWMx/rcTrI4QFyrET5Vz077Kyu44OeZrV34N9egehkidSHNQzu
dN1ux+2ZvQLlsUDe2zXpYZnWDbUeLuY0fYx1baEvJGeABT0AdNY5t0HFvgwGYFIX
lkgSVyx8sAGKUcbnTwvZlgz66o5vSJYAxxXKuWLsRoMQ4X+hS/tawMB6TAYop/L1
7F9aHDv7Kf5Rgbig9QIDAQABo0UwQzAOBgNVHQ8BAf8EBAMCAgQwEgYDVR0TAQH/
BAgwBgEB/wIBADAdBgNVHQ4EFgQU0t8UaNj7xry1h0qnTAm8Sxv69aMwDQYJKoZI
hvcNAQELBQADggGBAFZT6Zdg+tt+8t6Bo9Boe8uOKnqrCSuOCyMIajDLgijPRlHf
iJRggRjGT2Ig7c0nzL5SfeuExoMPMUmkfNAKki3VhK7cxLijDtn4fOmyyW5OO7AT
zwSmOyakHXq4ip3klysNGVPzxjwHBuK5rCdPa2X1WXN4PeM6NQvGZB34hQ1962om
1gad4YardZ81fVLJfOlCtIPD87TSreVGxiawUIAAGWgDuVMouN4PvqTUyEmorgxi
hSaiVDCSlS/nuW5fuOGzZ1Ko9UhbCsmO3bbLzXKcjuwKeyzgyjozHMyx5gUhhOFk
kqDIuIven3j+uLke0WAK++Z11vM8fVn0wB80RqubuTbqJzvH3w0R/PWVd0yAMFNu
Y2Z+AZ0OwMm9BtqfwoW5PZSIMF06q6IbLmuLEH/5dE9xDN0s5Ia8gn7ySYqso+62
yJjURRgGJeXLkrjfeSav39D0bg+JCB7J63Z7BCz6/Jv1TL45yWbeMmtqFPH6nS5t
25uIk/1regWTCajVMg==
-----END CERTIFICATE-----