mirror of
https://github.com/pomerium/pomerium.git
synced 2025-04-28 18:06:34 +02:00
docs: add configuration variables (#52)
This commit is contained in:
Bobby DeSimone
GitHub
parent
7b1e832b45
commit
a31721a239
5 changed files with 246 additions and 14 deletions
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
# Pomerium
|
||||
|
||||
[](https://travis-ci.org/pomerium/pomerium) [](https://goreportcard.com/report/github.com/pomerium/pomerium) [][godocs] [](https://github.com/pomerium/pomerium/blob/master/LICENSE)[](https://codecov.io/gh/pomerium/pomerium)
|
||||
[](https://travis-ci.org/pomerium/pomerium) [](https://goreportcard.com/report/github.com/pomerium/pomerium) [][godocs] [](https://github.com/pomerium/pomerium/blob/master/LICENSE) [](https://codecov.io/gh/pomerium/pomerium)
|
||||
|
||||
Pomerium is a tool for managing secure access to internal applications and resources.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,6 @@ module.exports = {
|
|||
sidebar: {
|
||||
"/guide/": guideSidebar("Quick Start"),
|
||||
"/docs/": docsSidebar("Documentation")
|
||||
|
||||
}
|
||||
}
|
||||
};
|
||||
|
|
@ -34,7 +33,7 @@ function docsSidebar(title) {
|
|||
{
|
||||
title,
|
||||
collapsable: false,
|
||||
children: ["", "identity-providers", "signed-headers", "examples"]
|
||||
children: ["", "identity-providers", "signed-headers", "examples","config-reference"]
|
||||
}
|
||||
];
|
||||
}
|
||||
|
|
|
|||
242
docs/docs/config-reference.md
Normal file
242
docs/docs/config-reference.md
Normal file
|
|
@ -0,0 +1,242 @@
|
|||
---
|
||||
sidebar: auto
|
||||
---
|
||||
|
||||
# Configuration Variables
|
||||
|
||||
Pomerium primarily uses [environmental variables] to set configuration settings. If you are coming from kubernetes or docker based deployment this should feel very 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/)
|
||||
- [Docker: Environment variables](https://docs.docker.com/compose/environment-variables/)
|
||||
|
||||
## Global settings
|
||||
|
||||
Global settings are configuration variables that are shared by all services.
|
||||
|
||||
### Service Mode
|
||||
|
||||
- Environmental Variable: `SERVICES`
|
||||
- Type: `string`
|
||||
- Default: `all`
|
||||
- Options: `all` `authenticate` or `proxy`
|
||||
|
||||
Service mode sets the pomerium service(s) to run. For example, if you are just testing pomerium, you may want to use `all` and run in all-in-one mode. Alternatively, in production, you probably want to have several instances of each service running for scalability and high availability.
|
||||
|
||||
### Address
|
||||
|
||||
- Environmental Variable: `ADDRESS`
|
||||
- Type: `string`
|
||||
- Default: `:https`
|
||||
|
||||
Address specifies the host and port to serve HTTPS and gRPC requests from. If empty, `:https` is used.
|
||||
|
||||
### Shared Secret
|
||||
|
||||
- Environmental Variable: `SHARED_SECRET`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Required
|
||||
|
||||
Shared Secret is the base64 encoded random 256-bit key used to mutually authenticate requests between services. It's critical to store safely and recommended to use secure key-management system where available. Otherwise, `/dev/urandom` can be used to generate a the key. For example:
|
||||
|
||||
```
|
||||
head -c32 /dev/urandom | base64
|
||||
```
|
||||
|
||||
### Debug
|
||||
|
||||
- Environmental Variable: `POMERIUM_DEBUG`
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
|
||||
By default, JSON encoded logs are produced. Debug enables human-readable and more verbose logging to [standard out](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)). For production, it's recommended to be set to `false`.
|
||||
|
||||
For example, if true.
|
||||
|
||||
```
|
||||
10:37AM INF cmd/pomerium version=v0.0.1-dirty+ede4124
|
||||
10:37AM INF proxy: new route from=httpbin.corp.beyondperimeter.com to=https://httpbin.org
|
||||
10:37AM INF proxy: new route from=ssl.corp.beyondperimeter.com to=http://neverssl.com
|
||||
10:37AM INF proxy/authenticator: grpc connection OverrideCertificateName= addr=auth.corp.beyondperimeter.com:443
|
||||
```
|
||||
|
||||
If false:
|
||||
|
||||
```
|
||||
{"level":"info","version":"v0.0.1-dirty+ede4124","time":"2019-02-18T10:41:03-08:00","message":"cmd/pomerium"}
|
||||
{"level":"info","from":"httpbin.corp.beyondperimeter.com","to":"https://httpbin.org","time":"2019-02-18T10:41:03-08:00","message":"proxy: new route"}
|
||||
{"level":"info","from":"ssl.corp.beyondperimeter.com","to":"http://neverssl.com","time":"2019-02-18T10:41:03-08:00","message":"proxy: new route"}
|
||||
{"level":"info","OverrideCertificateName":"","addr":"auth.corp.beyondperimeter.com:443","time":"2019-02-18T10:41:03-08:00","message":"proxy/authenticator: grpc connection"}
|
||||
```
|
||||
|
||||
### Certificate
|
||||
|
||||
- Environmental Variable: either `CERTIFICATE` or `CERTIFICATE_FILE`
|
||||
- Type: [base64 encoded] `string` or relative file location
|
||||
- Required
|
||||
|
||||
Certificate is the x509 _public-key_ used to establish secure HTTP and gRPC connections. If unset, pomerium will attempt to find and use `./cert.pem`.
|
||||
|
||||
### Certificate Key
|
||||
|
||||
- Environmental Variable: either `CERTIFICATE_KEY` or `CERTIFICATE_KEY_FILE`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Required
|
||||
|
||||
Certificate key is the x509 _private-key_ used to establish secure HTTP and gRPC connections. If unset, pomerium will attempt to find and use `./privkey.pem`.
|
||||
|
||||
## Authenticate Service
|
||||
|
||||
### Redirect URL
|
||||
|
||||
- Environmental Variable: `REDIRECT_URL`
|
||||
- Type: `URL`
|
||||
- Required
|
||||
- Example: `https://auth.corp.example.com/oauth2/callback`
|
||||
|
||||
Redirect URL is the url the user will be redirected to following authentication with a third-party identity provider (IdP). Note the URL ends with `/oauth2/callback`. This setting will mirror the URL set when configuring your [identity provider]. Typically, on the provider side, this is called an _authorized callback url_.
|
||||
|
||||
### Allowed Email Domains
|
||||
|
||||
::: warning
|
||||
This setting will be deprecated with the upcoming release of authorization service module.
|
||||
:::
|
||||
|
||||
- Environmental Variable: `ALLOWED_DOMAINS`
|
||||
- Type: `[]string` (e.g. comma separated list of string)
|
||||
- Required
|
||||
- Example: `engineering.corp-b.com,devops.corp-a.com`
|
||||
|
||||
The allowed email domains settings dictates which email domains are valid for access. If an authenticated user has a domain email ending in a non-whitelisted domain, an error will be returned.
|
||||
|
||||
|
||||
|
||||
### Proxy Root Domains
|
||||
|
||||
- Environmental Variable: `PROXY_ROOT_DOMAIN`
|
||||
- Type: `[]string` (e.g. comma separated list of string)
|
||||
- Required
|
||||
|
||||
Proxy Root Domains specifies the domains that are allowed to proxy access from. If a proxy service attempts to authenticate a user from a non-whitelisted domain, an error will be returned. For example, `httpbin.corp.example.com` would be a valid domain under the proxy root domain `corp.example.com`.
|
||||
|
||||
### Identity Provider Name
|
||||
|
||||
- Environmental Variable: `IDP_PROVIDER`
|
||||
- Type: `string`
|
||||
- Required
|
||||
- Options: `azure` `google` `okta` `gitlab` or `oidc`
|
||||
|
||||
Provider is short-hand-name of the built-in OpenID Connect (oidc) identity provider to use to authenticate user requests. To use a generic provider, set to `oidc`. See [identity provider] for details.
|
||||
|
||||
### Identity Provider Client ID
|
||||
|
||||
- Environmental Variable: `IDP_CLIENT_ID`
|
||||
- Type: `string`
|
||||
- Required
|
||||
|
||||
Client ID is the OAuth 2.0 Client Identifier retrieved from your identity provider. For a detailed explanation of an OpenID Connect Request, see the [OIDC RFC] or your identity provider's documentation. See [identity provider] for details.
|
||||
|
||||
### Identity Provider Client Secret
|
||||
|
||||
- Environmental Variable: `IDP_CLIENT_SECRET`
|
||||
- Type: `string`
|
||||
- Required
|
||||
|
||||
Client ID is the OAuth 2.0 Secret Identifier retrieved from your identity provider. For a detailed explanation of an OpenID Client Secret, see the [OIDC RFC Section 9](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) or your identity provider's documentation. See [identity provider] for details.
|
||||
|
||||
### Identity Provider URL
|
||||
|
||||
- Environmental Variable: `IDP_PROVIDER_URL`
|
||||
- Type: `string`
|
||||
- Optional if your identity provider is a built-in IDP and has a static URL.
|
||||
|
||||
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 URL](https://accounts.google.com/.well-known/openid-configuration).
|
||||
|
||||
### Identity Provider Scopes
|
||||
|
||||
- Environmental Variable: `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.
|
||||
|
||||
## Proxy Service
|
||||
|
||||
### Routes
|
||||
|
||||
- Environmental Variable: `ROUTES`
|
||||
- Type: `map[string]string` comma separated mapping of gatewayed (reverse-proxied) entities.
|
||||
- Required
|
||||
- Example: `https://httpbin.corp.example.com=http://httpbin,https://hello.corp.example.com=http://hello:8080/`
|
||||
|
||||
Routes contains a mapping of routes to be managed by pomerium.
|
||||
|
||||
### Signing Key
|
||||
|
||||
- Environmental Variable: `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`
|
||||
- Type: `URL`
|
||||
- Required
|
||||
- Example: `https://auth.corp.example.com`
|
||||
|
||||
Authenticate Service URL is the externally accessible URL for the authenticate service.
|
||||
|
||||
### Authenticate Internal Service URL
|
||||
|
||||
- Environmental Variable: `AUTHENTICATE_INTERNAL_URL`
|
||||
- Type: `string`
|
||||
- Optional
|
||||
- Example: `pomerium-authenticate-service.pomerium.svc.cluster.local`
|
||||
|
||||
Authenticate Service URL is the internal hostname for the authenticate service. Used in place of the authenticate service url for "behind-the-ingress communication. Setting is required for ingresses and load balancers that do not support HTTPS/2 or gRPC termination.
|
||||
|
||||
### Authenticate Internal Service Address
|
||||
|
||||
- Environmental Variable: `AUTHENTICATE_INTERNAL_URL`
|
||||
- Type: `string`
|
||||
- Optional
|
||||
- Example: `pomerium-authenticate-service.pomerium.svc.cluster.local`
|
||||
|
||||
Authenticate Internal Service Address is the target location of the authenticate service. Used for "behind-the-ingress communication. Setting is required for ingresses and load balancers that do not support HTTPS/2 or gRPC termination.
|
||||
|
||||
### Authenticate Service Port
|
||||
|
||||
- Environmental Variable: `AUTHENTICATE_SERVICE_PORT`
|
||||
- Type: `int`
|
||||
- Optional
|
||||
- Default: `443`
|
||||
- Example: `8443`
|
||||
|
||||
Authenticate Service Port is used to set the port value for authenticate service communication.
|
||||
|
||||
### Override Certificate Name
|
||||
|
||||
- Environmental Variable: `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`
|
||||
|
||||
When Authenticate Internal Service Address is set, secure service communication can fail because the external certificate name will not match the internally provided URL. This setting allows you to override that check. Should be set to value of the external certificate name.
|
||||
|
||||
### Certificate Authority
|
||||
|
||||
- Environmental Variable: `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.
|
||||
|
||||
[base64 encoded]: https://en.wikipedia.org/wiki/Base64
|
||||
[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
|
||||
[identity provider]: ./identity-providers.md
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[oidc rfc]: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
|
|
@ -3,7 +3,7 @@ import (
|
|||
"fmt"
|
||||
"time"
|
||||
|
||||
"gopkg.in/square/go-jose.v2"
|
||||
jose "gopkg.in/square/go-jose.v2"
|
||||
"gopkg.in/square/go-jose.v2/jwt"
|
||||
)
|
||||
|
||||
|
|
@ -40,7 +40,7 @@ type ES256Signer struct {
|
|||
signer jose.Signer
|
||||
}
|
||||
|
||||
// NewES256Signer creates an Eliptic Curve, NIST P-256 (aka secp256r1 aka prime256v1) JWT signer.
|
||||
// NewES256Signer creates an Elliptic Curve, NIST P-256 (aka secp256r1 aka prime256v1) JWT signer.
|
||||
//
|
||||
// RSA is not supported due to performance considerations of needing to sign each request.
|
||||
// Go's P-256 is constant-time and SHA-256 is faster on 64-bit machines and immune
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
{
|
||||
"scripts": {
|
||||
"docs:dev": "vuepress dev docs",
|
||||
"docs:build": "vuepress build docs"
|
||||
},
|
||||
"dependencies": {
|
||||
"firebase-tools": "^6.2.2"
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Reference in a new issue