3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-08-06 10:21:05 +02:00
Code Issues Projects Releases Packages Wiki Activity

deployment : add docker support, docker-compose example, & quick-start guide.

Browse source
This commit is contained in:
Bobby DeSimone 2019-01-17 00:22:10 -08:00 • committed by GitHub
commit 929a1ca7b0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 132 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

4
.gitignore vendored
View file

@ -1,4 +1,4 @@
.docker-compose.yml
pem pem
env env
coverage.txt coverage.txt
@ -16,7 +16,7 @@ _test
# Architecture specific extensions/prefixes # Architecture specific extensions/prefixes
*.[568vq] *.[568vq]
[568vq].out [568vq].out
*.cgo1.go *.cgo1.go
*.cgo2.c *.cgo2.c
_cgo_defun.c _cgo_defun.c

10
README.md
View file

@ -15,11 +15,11 @@ Use Pomerium to:
- deploy mutual authenticated encryption (mTLS). - deploy mutual authenticated encryption (mTLS).
- aggregate logging and telemetry data. - aggregate logging and telemetry data.
To learn more about the problems Pomerium attempts to address, check out this repository of [resources] covering zero-trust and BeyondCorp.
## Get started ## Get started
For instructions on getting started using Pomerium, see our [docs]. For instructions on getting started using Pomerium, see our [quick start guide].
To learn more about zero-trust and BeyondCorp, check out [awesome-zero-trust].
## Start developing ## Start developing
@ -33,6 +33,6 @@ $ source ./env # see env.example
$ ./bin/pomerium -debug $ ./bin/pomerium -debug
``` ```
[awesome-zero-trust]: https://github.com/pomerium/awesome-zero-trust [resources] : https://github.com/pomerium/awesome-zero-trust
[go environment]: https://golang.org/doc/install [go environment]: https://golang.org/doc/install
[docs]: https://www.pomerium.io [quick start guide]: https://www.pomerium.io/guide/

97
docker-compose.yml Normal file
View file

@ -0,0 +1,97 @@
# Example Pomerium configuration.
#
# NOTE! Change IDP_* settings to match your identity provider settings!
# NOTE! Generate new SHARED_SECRET and COOKIE_SECRET keys!
# 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
version: "3"
services:
# NGINX routes to pomerium's services depending on the request.
nginx-proxy:
image: jwilder/nginx-proxy:latest
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.
# 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
- /var/run/docker.sock:/tmp/docker.sock:ro
pomerium-authenticate:
image: pomerium/pomerium:latest
environment:
- SERVICES=authenticator
# auth settings
- REDIRECT_URL=https://sso-auth.corp.beyondperimeter.com/oauth2/callback
# Identity Provider Settings (Must be changed!)
- IDP_PROVIDER="google"
- IDP_PROVIDER_URL=https://accounts.google.com
- IDP_CLIENT_ID=851877082059-bfgkpj09noog7as3gpc3t7r6n9sjbgs6.apps.googleusercontent.com
- IDP_CLIENT_SECRET=P34wwijKRNP3skP5ag5I12kz
- SCOPE="openid email"
- PROXY_ROOT_DOMAIN=beyondperimeter.com
- ALLOWED_DOMAINS=*
# shared service settings
# Generate 256 bit random keys e.g. `head -c32 /dev/urandom | base64`
- SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
# if passing certs as files
# - CERTIFICATE_KEY=corp.beyondperimeter.com.crt
# - CERTIFICATE_KEY_FILE=corp.beyondperimeter.com.key
# Or, you can pass certifcates as bas64 encoded values. e.g. `base64 -i cert.pem`
# - CERTIFICATE=
# - CERTIFICATE_KEY=
# nginx settings
- VIRTUAL_PROTO=https
- VIRTUAL_HOST=sso-auth.corp.beyondperimeter.com
- VIRTUAL_PORT=443
volumes: # volumes is optional; used if passing certificates as files
- ./cert.pem:/pomerium/cert.pem:ro
- ./privkey.pem:/pomerium/privkey.pem:ro
expose:
- 443
pomerium-proxy:
image: pomerium/pomerium:latest
environment:
- SERVICES=proxy
# proxy settings
- AUTHENTICATE_SERVICE_URL=https://sso-auth.corp.beyondperimeter.com
- ROUTES=https://httpbin.corp.beyondperimeter.com=http://httpbin,https://hello.corp.beyondperimeter.com=http://hello-world/
# Generate 256 bit random keys e.g. `head -c32 /dev/urandom | base64`
- SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
# if passing certs as files
# - CERTIFICATE_KEY=corp.beyondperimeter.com.crt
# - CERTIFICATE_KEY_FILE=corp.beyondperimeter.com.key
# Or, you can pass certifcates as bas64 encoded values. e.g. `base64 -i cert.pem`
# - CERTIFICATE=
# - CERTIFICATE_KEY=
# nginx settings
- VIRTUAL_PROTO=https
- VIRTUAL_HOST=*.corp.beyondperimeter.com
- VIRTUAL_PORT=443
volumes: # volumes is optional; used if passing certificates as files
- ./cert.pem:/pomerium/cert.pem:ro
- ./privkey.pem:/pomerium/privkey.pem:ro
expose:
- 443
# https://httpbin.corp.beyondperimeter.com
httpbin:
image: kennethreitz/httpbin:latest
expose:
- 80
# Simple hello world
# https://hello.corp.beyondperimeter.com
hello-world:
image: tutum/hello-world:latest
expose:
- 80

30
docs/guide/identity-providers.md
View file

@ -41,11 +41,11 @@ Your `Client ID` and `Client Secret` will be displayed:
Set `Client ID` and `Client Secret` in Pomerium's settings. Your [environmental variables] should look something like this. Set `Client ID` and `Client Secret` in Pomerium's settings. Your [environmental variables] should look something like this.
```bash ```bash
export REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback" REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
export IDP_PROVIDER="google" IDP_PROVIDER="google"
export IDP_PROVIDER_URL="https://accounts.google.com" IDP_PROVIDER_URL="https://accounts.google.com"
export IDP_CLIENT_ID="yyyy.apps.googleusercontent.com" IDP_CLIENT_ID="yyyy.apps.googleusercontent.com"
export IDP_CLIENT_SECRET="xxxxxx" IDP_CLIENT_SECRET="xxxxxx"
``` ```
## Okta ## Okta
@ -78,11 +78,11 @@ Go to the **General** page of your app and scroll down to the **Client Credentia
At this point, you will configure the integration from the Pomerium side. Your [environmental variables] should look something like this. At this point, you will configure the integration from the Pomerium side. Your [environmental variables] should look something like this.
```bash ```bash
export REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback" REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
export IDP_PROVIDER="okta" IDP_PROVIDER="okta"
export IDP_PROVIDER_URL="https://dev-108295-admin.oktapreview.com/" IDP_PROVIDER_URL="https://dev-108295-admin.oktapreview.com/"
export IDP_CLIENT_ID="0oairksnr0C0fEJ7l0h7" IDP_CLIENT_ID="0oairksnr0C0fEJ7l0h7"
export IDP_CLIENT_SECRET="xxxxxx" IDP_CLIENT_SECRET="xxxxxx"
``` ```
## Azure ## Azure
@ -151,11 +151,11 @@ At this point, you will configure the integration from the Pomerium side. Your [
```bash ```bash
# Azure # Azure
export REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback" REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
export IDP_PROVIDER="azure" IDP_PROVIDER="azure"
export IDP_PROVIDER_URL="https://login.microsoftonline.com/{REPLACE-ME-SEE-ABOVE}/v2.0" IDP_PROVIDER_URL="https://login.microsoftonline.com/{REPLACE-ME-SEE-ABOVE}/v2.0"
export IDP_CLIENT_ID="REPLACE-ME" IDP_CLIENT_ID="REPLACE-ME"
export IDP_CLIENT_SECRET="REPLACE-ME" IDP_CLIENT_SECRET="REPLACE-ME"
``` ```

49
docs/guide/readme.md
View file

@ -1,47 +1,24 @@
# Quick start # Quick start
1. [Download] pre-built binaries or build Pomerium from source.
1. Generate a wild-card certificate for a test domain like `corp.example.com`. For convenience, an included [script] can generate a free one using LetsEncrypt and [certbot].
Once complete, move the generated public and private keys (`cert.pem`/`privkey.pem`) next to the pomerium binary. Certificates can also be set as environmental variables or dynamically with a [KMS]. ## Using Docker
1. Next, set configure your [identity provider](./identity-providers.md) by generating an OAuth **Client ID** and **Client Secret** as well as setting a **Redirect URL** endpoint. The Redirect URL endpoint will be called by the identity provider following user authentication. * Install [docker](https://docs.docker.com/install/).
* Install [docker-compose](https://docs.docker.com/compose/install/).
* Save Pomerium's example [`docker-compose.yml`]().
* Inspect the `docker-compose.yml` file. In addition to specifying Pomerium's configuration settings, and services, you'll see that there are other included services to give you a feel for how pomerium works.
* Update the compose file with your [identity provider] settings.
* Copy your subdomain's wild-card TLS certificate next to the compose file. See included [script] to generate one from LetsEncrypt.
* Run docker compose by runnig the command `$ docker-compose up`.
* If you navigate to `https://hello.corp.beyondperimeter.com` or `https://httpbin.corp.beyondperimeter.com` where "corp.beyondperimeter.com" is your subdomain in your browser, you should see something like the following in your browser and in your terminal.
1. Pomerium is configured using [environmental variables]. A minimal configuration is as follows. ![Getting started](./get-started.gif)
```bash [![asciicast](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg.svg)](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg)
# file : env
# The URL that the identity provider will call back after authenticating the user
export REDIRECT_URL="https://sso-auth.corp.example.com/oauth2/callback"
# Generate 256 bit random keys e.g. `head -c32 /dev/urandom | base64`
export SHARED_SECRET=REPLACE_ME
export COOKIE_SECRET=REPLACE_ME
# Allow users with emails from the following domain post-fix (e.g. example.com)
export ALLOWED_DOMAINS=*
## Identity Provider Settings
export IDP_PROVIDER="google"
export IDP_PROVIDER_URL="https://accounts.google.com" # optional for google
export IDP_CLIENT_ID="YOU_GOT_THIS_FROM_STEP-3.apps.googleusercontent.com"
export IDP_CLIENT_SECRET="YOU_GOT_THIS_FROM_STEP-3"
# key/value list of simple routes.
export ROUTES='http.corp.example.com=httpbin.org'
```
You can also view the [env.example] configuration file for a more comprehensive list of options.
1. For a first run, I suggest setting the debug flag which provides user friendly logging.
```bash
source ./env
./pomerium -debug
```
1. You should now get the following when you try to access one of your `corp` routes.
![Getting started](./get-started.gif)
[download]: https://github.com/pomerium/pomerium/releases [download]: https://github.com/pomerium/pomerium/releases
[environmental variables]: https://12factor.net/config
[env.example]: https://github.com/pomerium/pomerium/blob/master/env.example
[kms]: https://en.wikipedia.org/wiki/Key_management [kms]: https://en.wikipedia.org/wiki/Key_management
[certbot]: https://certbot.eff.org/docs/install.html [certbot]: https://certbot.eff.org/docs/install.html
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh [script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
[source]: https://github.com/pomerium/pomerium#start-developing
[identity provider]: ./identity-providers.md