mirror of
https://github.com/pomerium/pomerium.git
synced 2025-05-10 15:47:36 +02:00
v0.5.0 (#375)
This commit is contained in:
Bobby DeSimone
GitHub
parent
00c29f4e77
commit
ec9607d1d5
61 changed files with 894 additions and 468 deletions
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
v0.4.2
|
||||
v0.5.0
|
||||
|
|
@ -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/reference",
|
||||
// "reference/examples",
|
||||
"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"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
@ -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)"
|
||||
|
|
@ -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
|
||||
|
|
@ -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=
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
399
docs/configuration/img/auth-flow-diagram.svg
Normal file
399
docs/configuration/img/auth-flow-diagram.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 19 KiB |
BIN
docs/configuration/img/certificates-ssl-report.png
Normal file
BIN
docs/configuration/img/certificates-ssl-report.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
BIN
docs/configuration/img/certificates-valid-secure-certificate.png
Normal file
BIN
docs/configuration/img/certificates-valid-secure-certificate.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 210 KiB |
BIN
docs/configuration/img/jaeger.png
Normal file
BIN
docs/configuration/img/jaeger.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 223 KiB |
BIN
docs/configuration/img/pomerium-user-impersonation.mp4
Normal file
BIN
docs/configuration/img/pomerium-user-impersonation.mp4
Normal file
Binary file not shown.
BIN
docs/configuration/img/security-headers.png
Normal file
BIN
docs/configuration/img/security-headers.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
|
|
@ -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.
|
||||
|
||||
If you are coming from a kubernetes or docker background this should feel familiar. If not, check out the following primers.
|
||||
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.
|
||||
|
||||
- [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
|
|||
|
||||
 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
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
||||
|
Before Width: | Height: | Size: 84 KiB After Width: | Height: | Size: 84 KiB |
|
Before Width: | Height: | Size: 318 KiB After Width: | Height: | Size: 318 KiB |
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 78 KiB |
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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**.
|
||||
|
||||
|
||||
|
|
@ -104,8 +106,8 @@ IDP_CLIENT_ID="REPLACE-ME"
|
|||
IDP_CLIENT_SECRET="REPLACE-ME"
|
||||
```
|
||||
|
||||
[client id]: ../reference/reference.md#identity-provider-client-id
|
||||
[client secret]: ../reference/reference.md#identity-provider-client-secret
|
||||
[client id]: ../../configuration/readme.md#identity-provider-client-id
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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** |
|
||||
|
||||
|
||||
|
||||
1.Click **Save Application** to proceed.
|
||||
|
||||
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.
|
||||
|
||||
```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.
|
||||
|
||||
|
||||
|
||||
[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
|
||||
|
|
@ -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 secret]: ../reference/reference.md#identity-provider-client-secret
|
||||
[client id]: ../../configuration/readme.md#identity-provider-client-id
|
||||
[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
|
||||
|
|
|
|||
BIN
docs/docs/identity-providers/img/okta-api-token.png
Normal file
BIN
docs/docs/identity-providers/img/okta-api-token.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 346 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 266 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
|
|
@ -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
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
|
||||
Select your desired authorization server and navigate to the **claims tab**. Click **Add Claim** and configure the group claim for **ID Token** as follows.
|
||||
|
||||
|
||||
|
||||
| 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 |
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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_SECRET="xxxxxx"
|
||||
IDP_CLIENT_ID="REPLACE_ME"
|
||||
IDP_CLIENT_SECRET="REPLACE_ME"
|
||||
IDP_SERVICE_ACCOUNT="REPLACE_ME" # api token
|
||||
```
|
||||
|
||||
[client id]: ../reference/reference.md#identity-provider-client-id
|
||||
[client secret]: ../reference/reference.md#identity-provider-client-secret
|
||||
[client id]: ../../configuration/readme.md#identity-provider-client-id
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
@ -26,17 +28,11 @@ Under **Token Timeout settings** set **Refresh Token** to 60 minutes (or whateve
|
|||
|
||||
|
||||
|
||||
[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.
|
||||
|
||||
|
||||
|
||||
**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**
|
||||
|
||||
|
||||
|
||||
Finally, configure Pomerium with the identity provider settings retrieved in the previous steps. Your [environmental variables] should look something like this.
|
||||
## Pomerium Configuration
|
||||
|
||||
```bash
|
||||
IDP_PROVIDER="onelogin"
|
||||
|
|
@ -49,8 +45,8 @@ After reloading Pomerium, you should be able to see any login events from your O
|
|||
|
||||
|
||||
|
||||
[client id]: ../reference/reference.md#identity-provider-client-id
|
||||
[client secret]: ../reference/reference.md#identity-provider-client-secret
|
||||
[client id]: ../../configuration/readme.md#identity-provider-client-id
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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 secret]: ../reference/reference.md#identity-provider-client-secret
|
||||
[client id]: ../../configuration/readme.md#identity-provider-client-id
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
|
|||
|
|
@ -211,7 +211,7 @@ And just to be safe, try logging in from another google account to see what happ
|
|||
|
||||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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_authority]: ../reference/#certificate-authority
|
||||
[certificate_key]: ../reference/#certificate-key
|
||||
[override_certificate_name]: ../reference/#override-certificate-name
|
||||
[certificate]: ../../configuration/readme.md#certificate
|
||||
[certificate_authority]: ../../configuration/readme.md#certificate-authority
|
||||
[certificate_key]: ../../configuration/readme.md#certificate-key
|
||||
[override_certificate_name]: ../../configuration/readme.md#override-certificate-name
|
||||
[principles]: ../docs/#why
|
||||
[zero-trust]: ../docs/#why
|
||||
|
|
|
|||
|
|
@ -40,4 +40,4 @@ Here's what it looks like.
|
|||
Your browser does not support the video tag.
|
||||
</video>
|
||||
|
||||
[configuration settings]: ../reference/#administrators
|
||||
[configuration settings]: ../../configuration/readme.md#administrators
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Please also see [architecture](../#architecture) for information on component in
|
|||
|
||||
## 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
|
||||
|
||||
|
|
@ -27,8 +27,7 @@ In more complicated deployments, you may also choose to share aspects of the con
|
|||
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
|
||||
|
||||
|
|
@ -64,7 +63,6 @@ You should provide a TCP or HTTP(s) load balancer between end users and the Prox
|
|||
|
||||
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.
|
||||
|
|
@ -80,11 +78,11 @@ By default, the Proxy will automatically connect to all IPs returned by a DNS qu
|
|||
**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
|
||||
- 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.
|
||||
|
|
@ -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 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
|
||||
|
|
@ -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)
|
||||
- [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)
|
||||
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.
|
||||
|
||||
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).
|
||||
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.
|
||||
### Callback handler
|
||||
|
||||
### 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.
|
||||
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.
|
||||
### Refresh API
|
||||
|
||||
### 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.
|
||||
|
||||
### Python
|
||||
Please consider see the following minimal but complete python example.
|
||||
|
||||
```bash
|
||||
python scripts/programmatic_access.py --client-secret REPLACE_ME \
|
||||
--client-id 851877082059-85tfqg9hlm8j9km5d9uripd0dvk72mvk.apps.googleusercontent.com \
|
||||
--pomerium-client-id 851877082059-bfgkpj09noog7as3gpc3t7r6n9sjbgs6.apps.googleusercontent.com
|
||||
python3 scripts/programmatic_access.py \
|
||||
--dst https://httpbin.example.com/headers \
|
||||
--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
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
|
|||
|
|
@ -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's group membership is now determined by the globally unique and immutable ID field.
|
||||
- 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. 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
|
||||
[authenticate internal service url]: ./reference/reference.md#authenticate-service-url
|
||||
[policy]: ./configuration/readme.md#policy
|
||||
[authenticate internal service url]: ./configuration/readme.md#authenticate-service-url
|
||||
|
|
|
|||
|
|
@ -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?
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue