mirror of
https://github.com/pomerium/pomerium.git
synced 2025-05-10 15:47:36 +02:00
Enterprise Docs (#2390)
* install VuePress Plugin Tabs https://www.npmjs.com/package/vuepress-plugin-tabs * init Enterprise documentation section * replace Vuepress tab plugin now using https://github.com/superbiger/vuepress-plugin-tabs * init Enterprise Quickstart * block of enterprise doc updates * Helm Quickstart Update (#2380) * removed/fixed redundant or incorrect config And some small copy edits * Update docs/docs/quick-start/helm.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * init console with helm doc * squash me * codeblock fix * init about page * updates to Enterprise section * consolidate on Postgres * WIP helm updates * update and align OS and Enterprise helm docs * Enterprise settings docs (#2397) * init console-specific reference docs files * remove shortdoc for name * init Enterprise Reference doc * expanding Enterprise Reference * init JS script for reference subpages When reviewing please remember that I'm not a developer, be kind * update script and apply * remove errant dep * document script and expand for CLI help output * import pomerium-console_serve.yaml In future iterations, this file should be sourced at build time as an artifact from the pomerium-console repo * init new output file * update script call and output * fix anchor links * BROKEN - import content from settings.yaml when dupe is true * filtering WiP * fix dupe script, more content * replace if dupe with if not docs * squash me * squash me! * add docs about PPL (#2404) * squash meeeeee * Update docs/enterprise/install/quickstart.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * symlink img dir from docs/reference * squash mee * update install reqs * Fixed links throughout * Update docs/enterprise/install/quickstart.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * Update docs/enterprise/install/quickstart.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * remove internal note * - format python with black - format js with prettier Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * optimize images with imageOptim Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * run prettier on config.js Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * concepts.md Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * update concepts Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * copy edits * typo * symlink img dir from docs/reference * modify TLS section in quick-start * rm whitespace * add common links postamble * block of updates * block of updates * updates with @travisgroth * turtles all the way down * more content * import all the things * fill out reports * fill out reports * fix file extension * fix links * crosslink PPL ref * document embedded prometheus * expand example * update reqs * document non-directory users * typo fix * update metrics_address * fix broken links in example configs * update examples for route syntax * replaced required with deprecated Note that I didn't link to the route reference because I'm unsure what link formats are accepted when this file is used elsewhere. The warning block below includes a link. * update enterprise/about * Update docs/enterprise/console-settings.yaml Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/console-settings.yaml Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * remove commented config lines * update non-domain user section in concepts * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/about.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * add console route to OSS conf * update enterprise settings copy from source file * Update docs/enterprise/concepts.md * Update reports reference * merge conflict resolution * update sourced doc content, fix whitespace Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> Co-authored-by: Caleb Doxsey <cdoxsey@pomerium.com> Co-authored-by: Bobby DeSimone <bobbydesimone@gmail.com> Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
This commit is contained in:
Alex Fornuto
GitHub
parent
0b9f06b5ae
commit
5332a752d0
72 changed files with 2775 additions and 217 deletions
|
|
@ -3,18 +3,28 @@ module.exports = {
|
|||
title: "Pomerium",
|
||||
description:
|
||||
"Pomerium is a beyond-corp inspired, zero trust, open source identity-aware access proxy.",
|
||||
plugins: {
|
||||
"check-md": {
|
||||
plugins: [
|
||||
"vuepress-plugin-element-tabs",
|
||||
[
|
||||
"check-md",
|
||||
{
|
||||
pattern: "**/*.md",
|
||||
},
|
||||
sitemap: {
|
||||
],
|
||||
[
|
||||
"sitemap",
|
||||
{
|
||||
hostname: "https://www.pomerium.com",
|
||||
outFile: "docs/sitemap.xml",
|
||||
},
|
||||
"@vuepress/google-analytics": {
|
||||
],
|
||||
[
|
||||
"@vuepress/google-analytics",
|
||||
{
|
||||
ga: "UA-129872447-2",
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
markdown: {
|
||||
externalLinkSymbol: false,
|
||||
},
|
||||
|
|
@ -32,9 +42,7 @@ module.exports = {
|
|||
{ text: "Guides", link: "/guides/" },
|
||||
{
|
||||
text: "Enterprise",
|
||||
link: "https://www.pomerium.com/",
|
||||
target: "_self",
|
||||
rel: "",
|
||||
link: "/enterprise/about/",
|
||||
},
|
||||
{
|
||||
text: "v0.14.x", // current tagged version
|
||||
|
|
@ -181,6 +189,43 @@ module.exports = {
|
|||
children: [""],
|
||||
},
|
||||
],
|
||||
"/enterprise/": [
|
||||
{
|
||||
title: "Enterprise",
|
||||
type: "group",
|
||||
collapsable: false,
|
||||
sidebarDepth: 2,
|
||||
children: [
|
||||
"about",
|
||||
"concepts",
|
||||
{
|
||||
title: "Install",
|
||||
type: "group",
|
||||
collapsable: false,
|
||||
path: "/enterprise/install/",
|
||||
sidebarDepth: 2,
|
||||
children: [
|
||||
"/enterprise/install/quickstart",
|
||||
"/enterprise/install/helm",
|
||||
],
|
||||
},
|
||||
"prometheus",
|
||||
{
|
||||
title: "Reference",
|
||||
type: "group",
|
||||
collapsable: false,
|
||||
path: "/enterprise/reference/configure",
|
||||
sidebarDepth: 2,
|
||||
children: [
|
||||
"/enterprise/reference/config.md",
|
||||
"/enterprise/reference/reports",
|
||||
"/enterprise/reference/manage",
|
||||
"/enterprise/reference/configure",
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
}
|
||||
};
|
||||
|
|
|
|||
18
docs/.vuepress/enhanceApp.js
Normal file
18
docs/.vuepress/enhanceApp.js
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
export default ({ router }) => {
|
||||
if(typeof process === 'undefined' || process.env.VUE_ENV !== 'server') {
|
||||
router.onReady(() => {
|
||||
const { app } = router;
|
||||
|
||||
app.$once("hook:mounted", () => {
|
||||
setTimeout(() => {
|
||||
const { hash } = document.location;
|
||||
if (hash.length > 1) {
|
||||
const id = decodeURIComponent(hash.substring(1));
|
||||
const element = document.getElementById(id);
|
||||
if (element) element.scrollIntoView();
|
||||
}
|
||||
}, 500);
|
||||
});
|
||||
});
|
||||
}
|
||||
}
|
||||
|
|
@ -2187,7 +2187,7 @@ There were no changes in the v0.7.1 release, but we updated the build process sl
|
|||
|
||||
- Azure AD identity provider now uses globally unique and immutable `ID` for [group membership](https://docs.microsoft.com/en-us/graph/api/group-get?view=graph-rest-1.0&tabs=http).
|
||||
- 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).
|
||||
- Okta now requires an additional set of credentials to be used to query for group membership set as a [service account](https://www.pomerium.com/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.
|
||||
|
||||
|
|
@ -2412,7 +2412,7 @@ There were no changes in the v0.7.1 release, but we updated the build process sl
|
|||
### FEATURES
|
||||
|
||||
- **Authorization** : The authorization module adds support for per-route access policy. In this release we support the most common forms of identity based access policy: `allowed_users`, `allowed_groups`, and `allowed_domains`. In future versions, the authorization module will also support context and device based authorization policy and decisions. See website documentation for more details.
|
||||
- **Group Support** : The authenticate service now retrieves a user's group membership information during authentication and refresh. This change may require additional identity provider configuration; all of which are described in the [updated docs](https://www.pomerium.io/docs/identity-providers.html). A brief summary of the requirements for each IdP are as follows:
|
||||
- **Group Support** : The authenticate service now retrieves a user's group membership information during authentication and refresh. This change may require additional identity provider configuration; all of which are described in the [updated docs](https://www.pomerium.com/docs/identity-providers.html). A brief summary of the requirements for each IdP are as follows:
|
||||
|
||||
- Google requires the [Admin SDK](https://developers.google.com/admin-sdk/directory/) to enabled, a service account with properly delegated access, and `IDP_SERVICE_ACCOUNT` to be set to the base64 encoded value of the service account's key file.
|
||||
- Okta requires a `groups` claim to be added to both the `id_token` and `access_token`. No additional API calls are made.
|
||||
|
|
|
|||
|
|
@ -41,8 +41,8 @@ Finally, source the configuration `env` file and run pomerium specifying the `co
|
|||
|
||||
Browse to `external-verify.your.domain.example`. Connections between you and [verify] will now be proxied and managed by Pomerium.
|
||||
|
||||
[configuration variables]: ../../reference/readme.md
|
||||
[configuration variables]: /reference/readme.md
|
||||
[download]: https://github.com/pomerium/pomerium/releases
|
||||
[verify]: https://verify.pomerium.com/
|
||||
[identity provider]: ../identity-providers/
|
||||
[tls certificates]: ../topics/certificates.md
|
||||
[identity provider]: /docs/identity-providers/readme.md
|
||||
[tls certificates]: /docs/topics/certificates.md
|
||||
|
|
|
|||
|
|
@ -71,8 +71,8 @@ make && ./bin/pomerium -config config.yaml
|
|||
|
||||
Browse to `verify.localhost.pomerium.io`. Connections between you and [verify] will now be proxied and managed by Pomerium.
|
||||
|
||||
[configuration variables]: ../../reference/readme.md
|
||||
[configuration variables]: /reference/readme.md
|
||||
[verify]: https://verify.pomerium.com/
|
||||
[identity provider]: ../identity-providers/
|
||||
[identity provider]: /docs/identity-providers/readme.md
|
||||
[make]: https://en.wikipedia.org/wiki/Make_(software)
|
||||
[tls certificates]: ../topics/certificates.md
|
||||
[tls certificates]: /docs/topics/certificates.md
|
||||
|
|
|
|||
|
|
@ -8,54 +8,217 @@ meta:
|
|||
|
||||
# Pomerium using Helm
|
||||
|
||||
This quick-start will show you how to deploy Pomerium with [Helm](https://helm.sh) on [Kubernetes](https://kubernetes.io).
|
||||
This quick-start will show you how to deploy Pomerium with [Helm] on [Kubernetes].
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A [Google Cloud Account](https://console.cloud.google.com/)
|
||||
- A configured [identity provider]
|
||||
- Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
|
||||
- Install the [Google Cloud SDK](https://cloud.google.com/kubernetes-engine/docs/quickstart)
|
||||
- Install [helm](https://helm.sh/docs/using_helm/)
|
||||
- [TLS certificates]
|
||||
- [Install kubectl].
|
||||
- [Install helm].
|
||||
- A Kubernetes provider.
|
||||
- A cluster, with your local `kubectl` authorized to interact with it. The cluster configuration and node pool will depend on your provider and the scope of your project.
|
||||
- Export the configuration file from your Kubernetes host and export it to your `KUBECONFIG` environment variable (usually by placing it in `~/.kube`).
|
||||
|
||||
Though there are [many ways](https://unofficial-kubernetes.readthedocs.io/en/latest/setup/pick-right-solution/) to work with Kubernetes, for the purpose of this guide, we will be using Google's [Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). That said, most of the following steps should be very similar using any other provider.
|
||||
See [Organizing Cluster Access Using kubeconfig Files] for more information.
|
||||
- A namespace in the cluster for Pomerium. This document assumes the namespace `pomerium`.
|
||||
- A configured [identity provider].
|
||||
- [TLS certificates]. If you don't yet have a production environment with trusted certificates, this page will cover using [mkcert] to create locally trusted certificates, and [cert-manager] to manage them in the cluster.
|
||||
|
||||
In addition to sharing many of the same features as the Kubernetes quickstart guide, the default helm deployment script also includes a bootstrapped certificate authority enabling mutually authenticated and encrypted communication between services that does not depend on the external LetsEncrypt certificates. Having the external domain certificate de-coupled makes it easier to renew external certificates.
|
||||
::: tip
|
||||
This configuration installs Redis as the data broker service. While this isn't strictly required when running Pomerium by itself, it is necessary for Pomerium Enterprise, and still highly recommended if not.
|
||||
:::
|
||||
|
||||
## Configure
|
||||
## Certificates
|
||||
|
||||
Download and modify the following helm_gke.sh script and values file to match your [identity provider] and [TLS certificates] settings.
|
||||
This setup uses [mkcert] to generate certificates that are trusted by your local web browser for testing, and cert-manager to manage them. If you already have a certificate solution, you can skip the steps below and move on to [the next stage](#install-pomerium).
|
||||
|
||||
<<<@/examples/helm/helm_gke.sh
|
||||
### Install mkcert
|
||||
|
||||
<<<@/examples/kubernetes/values.yaml
|
||||
|
||||
## Run
|
||||
|
||||
Run [./scripts/helm_gke.sh] which will:
|
||||
|
||||
1. Provision a new cluster.
|
||||
2. Create authenticate, authorize, and proxy [deployments](https://cloud.google.com/kubernetes-engine/docs/concepts/deployment).
|
||||
3. Provision and apply authenticate, authorize, and proxy [services](https://cloud.google.com/kubernetes-engine/docs/concepts/service).
|
||||
4. Configure an ingress, Google's default load balancer.
|
||||
After [installing mkcert], confirm the presence and names of your local CA files:
|
||||
|
||||
```bash
|
||||
./scripts/helm_gke.sh
|
||||
mkcert -install
|
||||
The local CA is already installed in the system trust store! 👍
|
||||
The local CA is already installed in the Firefox and/or Chrome/Chromium trust store! 👍
|
||||
|
||||
ls $(mkcert -CAROOT)
|
||||
rootCA-key.pem rootCA.pem
|
||||
```
|
||||
|
||||
The output of `mkcert -install` may vary depending on you operating system.
|
||||
|
||||
## Install and Configure cert-manager
|
||||
|
||||
If you haven't already, install cert-manager and create a CA issuer. You can follow their docs (listed below) or use the steps provided:
|
||||
|
||||
- [cert-manager: Installing with Helm]
|
||||
- [cert-manager: CA]
|
||||
|
||||
1. Create a namespace for cert-manager:
|
||||
|
||||
```bash
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Add the jetstack.io repository and update Helm:
|
||||
|
||||
```bash
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Install cert-manager to your cluster:
|
||||
|
||||
```bash
|
||||
helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace \
|
||||
--version v1.4.0 --set installCRDs=true
|
||||
```
|
||||
|
||||
1. Confirm deployment with `kubectl get pods --namespace cert-manager`:
|
||||
|
||||
```bash
|
||||
kubectl get pods --namespace cert-manager
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
cert-manager-5d7f97b46d-8g942 1/1 Running 0 33s
|
||||
cert-manager-cainjector-69d885bf55-6x5v2 1/1 Running 0 33s
|
||||
cert-manager-webhook-8d7495f4-s5s6p 1/1 Running 0 33s
|
||||
```
|
||||
|
||||
1. In your Pomerium namespace, create a Kubernetes secret for the rootCA-key file in your local CA root:
|
||||
|
||||
```bash
|
||||
kubectl create secret tls pomerium-tls-ca --namespace=pomerium \
|
||||
--cert=$(mkcert -CAROOT)/rootCA.pem --key=$(mkcert -CAROOT)/rootCA-key.pem
|
||||
```
|
||||
|
||||
1. Define an Issuer configuration in `issuer.yaml`:
|
||||
|
||||
```yaml
|
||||
apiVersion: cert-manager.io/v1
|
||||
kind: Issuer
|
||||
metadata:
|
||||
name: pomerium-issuer
|
||||
namespace: pomerium
|
||||
spec:
|
||||
ca:
|
||||
secretName: pomerium-tls-ca
|
||||
```
|
||||
|
||||
1. Apply and confirm:
|
||||
|
||||
```bash
|
||||
kubectl apply -f issuer.yaml
|
||||
issuer.cert-manager.io/pomerium-issuer created
|
||||
|
||||
kubectl get issuers.cert-manager.io --namespace pomerium
|
||||
NAME READY AGE
|
||||
pomerium-issuer True 10s
|
||||
```
|
||||
|
||||
## Install Pomerium
|
||||
|
||||
1. Set your `kubectl` context to the Pomerium namespace:
|
||||
|
||||
```bash
|
||||
kubectl config set-context --current --namespace=pomerium
|
||||
```
|
||||
|
||||
1. Create certificate configurations for Pomerium. Our example is named `pomerium-certificates.yaml`, to differentiate from a configuration file for Pomerium Enterprise, if you choose to install it later:
|
||||
|
||||
<<< @/examples/kubernetes/pomerium-certificates.yaml
|
||||
|
||||
::: tip
|
||||
If you already have a domain space for Pomerium with a certificate solution, use it in place of `*.localhost.pomerium.io`.
|
||||
:::
|
||||
|
||||
1. Apply the certificate configuration, and confirm:
|
||||
|
||||
```bash
|
||||
kubectl apply -f pomerium-certificates.yaml
|
||||
```
|
||||
|
||||
```bash
|
||||
kubectl get certificate
|
||||
NAME READY SECRET AGE
|
||||
pomerium-cert True pomerium-tls 10s
|
||||
pomerium-redis-cert True pomerium-redis-tls 10s
|
||||
```
|
||||
|
||||
1. Create a values file for Helm to use when installing Pomerium. Our example is named `pomerium-values.yaml`.
|
||||
|
||||
<<< @/examples/kubernetes/pomerium-values.yaml
|
||||
|
||||
::: tip
|
||||
The options required in the `authenticate.idp` block will vary depending on your [identity provider].
|
||||
|
||||
If you changed the `*.localhost.pomerium.io` value in `pomerium-certificates.yaml` update `config.rootDomain` to match, omitting the `*`.
|
||||
:::
|
||||
|
||||
1. Add Pomerium's Helm repo:
|
||||
|
||||
```bash
|
||||
helm repo add pomerium https://helm.pomerium.io
|
||||
```
|
||||
|
||||
1. So that we can create a valid test route, add Bitnami's Helm repo to pull nginx from:
|
||||
|
||||
```bash
|
||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||
```
|
||||
|
||||
1. Update Helm:
|
||||
|
||||
```bash
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Install nginx to the cluster:
|
||||
|
||||
```bash
|
||||
helm upgrade --install nginx bitnami/nginx --set service.type=ClusterIP
|
||||
```
|
||||
|
||||
1. Install Pomerium to the cluster:
|
||||
|
||||
```bash
|
||||
helm upgrade --install pomerium pomerium/pomerium --values ./pomerium-values.yaml
|
||||
```
|
||||
|
||||
## Navigate
|
||||
|
||||
Open a browser and navigate to `verify.your.domain.example`.
|
||||
If you are installing Pomerium with a valid domain name and certificates, update your DNS records to point to the external IP address of the `pomerium-proxy` service:
|
||||
|
||||
You can also navigate to the special pomerium endpoint `verify.your.domain.example/.pomerium/` to see your current user details.
|
||||
```none
|
||||
kubectl get svc pomerium-proxy
|
||||
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
pomerium-proxy LoadBalancer 10.128.117.25 192.0.2.20 443:30006/TCP,9090:30707/TCP 2m37s
|
||||
```
|
||||
|
||||
For development and testing, you can use `kubectl` to create a local proxy:
|
||||
|
||||
```bash
|
||||
sudo -E kubectl --namespace pomerium port-forward service/pomerium-proxy 443:443
|
||||
```
|
||||
|
||||
Open a browser and navigate to `hello.localhost.pomerium.com`.
|
||||
|
||||
You can also navigate to the special pomerium endpoint `hello.localhost.pomerium.com/.pomerium/` to see your current user details.
|
||||
|
||||
|
||||
|
||||
[./scripts/helm_gke.sh]: https://github.com/pomerium/pomerium/tree/master/examples
|
||||
[./scripts/kubernetes_gke.sh]: https://github.com/pomerium/pomerium/tree/master/examples
|
||||
[example kubernetes files]: https://github.com/pomerium/pomerium/tree/master/examples
|
||||
## Next Steps
|
||||
|
||||
Congratulations on installing Pomerium to your Kubernetes cluster! If you're installing Pomerium Enterprise next, see [Install Pomerium Enterprise Console in Helm]. If not, check our our [guides](/guides/readme.md) to install common services behind Pomerium.
|
||||
|
||||
[cert-manager]: https://cert-manager.io/docs/
|
||||
[cert-manager: CA]: https://cert-manager.io/docs/configuration/ca/
|
||||
[cert-manager: Installing with Helm]: https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm
|
||||
[Helm]: https://helm.sh
|
||||
[Install helm]: https://helm.sh/docs/using_helm/
|
||||
[identity provider]: ../identity-providers/readme.md
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[Install Pomerium Enterprise Console in Helm]: /enterprise/install/helm.md
|
||||
[installing mkcert]: https://github.com/FiloSottile/mkcert#installation
|
||||
[Install kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
|
||||
[Kubernetes]: https://kubernetes.io
|
||||
[mkcert]: https://github.com/FiloSottile/mkcert
|
||||
[Organizing Cluster Access Using kubeconfig Files]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/
|
||||
[tls certificates]: ../topics/certificates.md
|
||||
|
|
@ -8,7 +8,7 @@ description: This article describes various ways to install pomerium
|
|||
|
||||
Pomerium is shipped in multiple formats and architectures to suit a variety of deployment patterns. There are two binaries:
|
||||
|
||||
- `pomerium` is the primary server component. It is a monolithic binary that can perform the function of any [services mode](/reference/#service-mode).
|
||||
- `pomerium` is the primary server component. It is a monolithic binary that can perform the function of any [services mode](/reference/readme.md#service-mode).
|
||||
- `pomerium-cli` (optional) is a command-line client for working with Pomerium. Functions include acting as an authentication helper for tools like [kubtctl](topics/kubernetes-integration.md).
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ To prevent early session loss in production deployments, persistent storage back
|
|||
|
||||
## Backends
|
||||
|
||||
Configuration options for each backend are detailed in [databroker configuration reference](/reference/#databroker-service).
|
||||
Configuration options for each backend are detailed in [databroker configuration reference](/reference/readme.md#data-broker-service).
|
||||
|
||||
In all backends, Pomerium encrypts record values. This ensures security of all records at rest, regardless of data store capabilities. While this prevents many classes of attack vector, additional security measures should always be taken to secure data in transit and minimize access to the backends themselves.
|
||||
|
||||
|
|
|
|||
|
|
@ -43,14 +43,14 @@ Pomerium can be leveraged as a proxy for user requests to the API Server.
|
|||
Building on top of a standard Kubernetes and Pomerium deployment:
|
||||
|
||||
1. Pomerium is given access to a Kubernetes service account with [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) permissions
|
||||
2. A [policy route](/reference/#policy) is created for the API server and [configured](/reference/#kubernetes-service-account-token) to use the service account token
|
||||
2. A [policy route](/reference/readme.md#policy) is created for the API server and [configured](/reference/readme.md#kubernetes-service-account-token) to use the service account token
|
||||
3. Kubernetes RoleBindings operate against IdP Users and Group subjects
|
||||
4. Users access the protected cluster through their standard tools, using [pomerium-cli](/docs/installation.md#pomerium-cli) as an auth provider in `~/.kube/config`
|
||||
4. Users access the protected cluster through their standard tools, using [pomerium-cli](/docs/releases.md#pomerium-cli) as an auth provider in `~/.kube/config`
|
||||
5. Pomerium authorizes requests and passes the user identity to the API server for fine grained RBAC
|
||||
|
||||
## Kubeconfig Setup
|
||||
|
||||
After installing the [pomerium-cli](/docs/installation.md#pomerium-cli), you must configure your `kubeconfig` for authentication.
|
||||
After installing the [pomerium-cli](/docs/releases.md#pomerium-cli), you must configure your `kubeconfig` for authentication.
|
||||
|
||||
Substitute `mycluster.pomerium.io` with your own API Server's `from` in Pomerium's policy:
|
||||
|
||||
|
|
|
|||
|
|
@ -6,13 +6,13 @@ description: >-
|
|||
|
||||
# Production Deployment
|
||||
|
||||
This page covers the topic of running Pomerium in a production configuration. See the [quick start section](../install/quickstart/) for canned example configurations.
|
||||
This page covers the topic of running Pomerium in a production configuration. See the [quick start section](/docs/install/readme.md) for canned example configurations.
|
||||
|
||||
Please also see [architecture](../#architecture) for information on component interactions.
|
||||
Please also see [architecture](/docs/architecture.md) for information on component interactions.
|
||||
|
||||
## Service Mode
|
||||
|
||||
For configuration of the service mode, see [Service Mode](../../reference/readme.md#service-mode).
|
||||
For configuration of the service mode, see [Service Mode](/reference/readme.md#service-mode).
|
||||
|
||||
### All in One
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ meta:
|
|||
|
||||
Operations and engineering teams frequently require access to lower level administrative and data protocols such as SSH, RDP, Postgres, MySQL, Redis, etc.
|
||||
|
||||
In addition to managing HTTP based applications, Pomerium can be used to protect non-HTTP systems with the same consistent authorization policy. This is achieved by tunneling TCP over HTTP with the help of a client side command built into [`pomerium-cli`](/docs/installation.md#pomerium-cli).
|
||||
In addition to managing HTTP based applications, Pomerium can be used to protect non-HTTP systems with the same consistent authorization policy. This is achieved by tunneling TCP over HTTP with the help of a client side command built into [`pomerium-cli`](/docs/releases.md#pomerium-cli).
|
||||
|
||||
|
||||
Internally, Pomerium uses the [`CONNECT` method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT) to establish the TCP tunnel.
|
||||
|
|
@ -26,17 +26,20 @@ Otherwise, the HTTP proxy in front of Pomerium must know how to properly handle
|
|||
|
||||
## Configuring
|
||||
|
||||
TCP configuration is simple. Just specify the correct scheme and ports in your policy [`to`](/reference/#to) and [`from`](/reference/#from) fields.
|
||||
TCP configuration is simple. Just specify the correct scheme and ports in your route [`to`](/reference/readme.md#to) and [`from`](/reference/readme.md#from) fields.
|
||||
|
||||
Example:
|
||||
```yaml
|
||||
policy:
|
||||
routes:
|
||||
- from: tcp+https://redis.corp.example.com:6379
|
||||
to: tcp://redis.internal.example.com:6379
|
||||
allowed_users:
|
||||
- contractor@not-example.com
|
||||
allowed_groups:
|
||||
- datascience@example.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: contractor@not-example.com
|
||||
- groups:
|
||||
has: ["datascience@example.com"]
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
|
@ -47,7 +50,7 @@ Notes:
|
|||
|
||||
## Using
|
||||
|
||||
While HTTP routes can be consumed with just a normal browser, `pomerium-cli` must serve as a proxy for TCP routes. It is [available](/docs/installation.md#pomerium-cli) for a variety of platforms in various formats.
|
||||
While HTTP routes can be consumed with just a normal browser, `pomerium-cli` must serve as a proxy for TCP routes. It is [available](/docs/releases.md#pomerium-cli) for a variety of platforms in various formats.
|
||||
|
||||
To connect, you normally need just the external hostname and port of your TCP route:
|
||||
|
||||
|
|
|
|||
|
|
@ -68,11 +68,11 @@ To update your policies for v0.14, please remove any identity provider prefix.
|
|||
|
||||
### Upstream load balancing
|
||||
|
||||
With the v0.13 release, routes may contain [multiple `to` URLs](/reference/#to), and Pomerium will load balance between the endpoints. This allows Pomerium to fill the role of an edge proxy without the need for additional HTTP load balancers.
|
||||
With the v0.13 release, routes may contain [multiple `to` URLs](/reference/readme.md#to), and Pomerium will load balance between the endpoints. This allows Pomerium to fill the role of an edge proxy without the need for additional HTTP load balancers.
|
||||
|
||||
- Active [health checks](/reference/#health-checks) and passive [outlier detection](/reference/#outlier-detection)
|
||||
- Configurable [load balancing policies](/reference/#load-balancing-policy)
|
||||
- Configurable [load balancing weight](/reference/#to)
|
||||
- Active [health checks](/reference/readme.md#health-checks) and passive [outlier detection](/reference/readme.md#outlier-detection)
|
||||
- Configurable [load balancing policies](/reference/readme.md#load-balancing-policy)
|
||||
- Configurable [load balancing weight](/reference/readme.md#to)
|
||||
|
||||
See [Load Balancing](/docs/topics/load-balancing) for more information on using this feature set.
|
||||
|
||||
|
|
@ -82,7 +82,7 @@ With the v0.13 release, all TLS files referenced from Pomerium's configuration a
|
|||
|
||||
### Proxy Protocol support
|
||||
|
||||
The Pomerium HTTP listener now [supports](/reference/#use-proxy-protocol) HAPROXY's [proxy protocol](https://www.haproxy.org/download/1.9/doc/proxy-protocol.txt) to update `X-Forwarded-For` accurately when behind another proxy service.
|
||||
The Pomerium HTTP listener now [supports](/reference/readme.md#use-proxy-protocol) HAPROXY's [proxy protocol](https://www.haproxy.org/download/1.9/doc/proxy-protocol.txt) to update `X-Forwarded-For` accurately when behind another proxy service.
|
||||
|
||||
## Breaking
|
||||
|
||||
|
|
@ -113,7 +113,7 @@ Pomerium can now be used for non-HTTP services. See [documentation](/docs/topic
|
|||
|
||||
### Datadog Tracing
|
||||
|
||||
Datadog has been added as a natively supported [tracing backend](/reference/#datadog)
|
||||
Datadog has been added as a natively supported [tracing backend](/reference/readme.md#datadog)
|
||||
|
||||
# Since 0.10.0
|
||||
|
||||
|
|
@ -335,7 +335,7 @@ Please see the updated examples, and [cache service docs] as a reference and for
|
|||
|
||||
- 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).
|
||||
- Okta now requires an additional set of credentials to be used to query for group membership set as a [service account](/reference/readme.md#identity-provider-service-account).
|
||||
|
||||
### OneLogin
|
||||
|
||||
|
|
@ -347,7 +347,7 @@ Force refresh has been removed from the dashboard. Logging out and back in again
|
|||
|
||||
### Programmatic Access API changed
|
||||
|
||||
Previous programmatic authentication endpoints (`/api/v1/token`) has been removed and has been replaced by a per-route, oauth2 based auth flow. Please see updated [programmatic documentation](https://www.pomerium.io/docs/reference/programmatic-access.html) how to use the new programmatic access api.
|
||||
Previous programmatic authentication endpoints (`/api/v1/token`) has been removed and has been replaced by a per-route, oauth2 based auth flow. Please see updated [programmatic documentation](/docs/topics/programmatic-access.md) how to use the new programmatic access api.
|
||||
|
||||
### Forward-auth route change
|
||||
|
||||
|
|
@ -498,9 +498,9 @@ 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.
|
||||
|
||||
[authenticate internal service url]: ../reference/readme.md#authenticate-service-url
|
||||
[cache service docs]: ../reference/readme.md#cache-service
|
||||
[identity provider service account]: ../reference/readme.md#identity-provider-service-account
|
||||
[policy]: ../reference/readme.md#policy
|
||||
[storage backend configuration here]: ../reference/readme.md#cache-service
|
||||
[storage backend types]: ../reference/readme.md#data-broker-storage-type
|
||||
[authenticate internal service url]: /reference/readme.md#authenticate-service-url
|
||||
[cache service docs]: /reference/readme.md#data-broker-service
|
||||
[identity provider service account]: /reference/readme.md#identity-provider-service-account
|
||||
[policy]: /reference/readme.md#policy
|
||||
[storage backend configuration here]: /reference/readme.md#data-broker-service
|
||||
[storage backend types]: /reference/readme.md#data-broker-storage-type
|
||||
|
|
|
|||
49
docs/enterprise/about.md
Normal file
49
docs/enterprise/about.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: About
|
||||
sidebarDepth: 2
|
||||
description: What does the Pomerium Enterpise Console offer?
|
||||
---
|
||||
|
||||
# Pomerium Enterprise
|
||||
|
||||
<!-- This paragraph introduces what Pomerium Enterprise is. -->
|
||||
|
||||
## Features
|
||||
|
||||
In addition to the capabilities provided by open-source Pomerium, Pomerium Enterprise provides:
|
||||
|
||||
### Management GUI
|
||||
|
||||
The Pomerium Enterprise Console lets you view traffic and logs, define routes and policies, and organize your service access all from an intuitive web interface.
|
||||
|
||||
|
||||
|
||||
### Programmatic API
|
||||
|
||||
Integrate Pomerium into your workflows by managing configuration from the programming language or infrastructure management tool of your choice.
|
||||
|
||||
### Session management
|
||||
|
||||
Quickly view who is logged in your infrastructure, with easy access to revoke sessions.
|
||||
|
||||
|
||||
|
||||
### Self-Service, and Access Controls
|
||||
|
||||
Easily define who can control access to what areas of your infrastructure. Our [Namespaces](/enterprise/concepts.md#namespaces) make it easy to allow teams to self-manage access to the infrastructure they build from or depend on.
|
||||
|
||||
[User roles](/enterprise/concepts.md#rbac-for-enterprise-console-users) are granted along Namespace hierarchy, with in inheritance from parents.
|
||||
|
||||
Pomerium Enterprise uses teams and groups defined by your IdP, so you can build stable policies that don't need to be adjusted as your company changes.
|
||||
|
||||
See [Concepts: Self-Service Capabilities](./concepts.md#self-service-capabilities) for more information.
|
||||
|
||||
### Deployment History & Audit Logs
|
||||
|
||||
View and export change and access logs from the web UI. Pomerium Enterprise Console gives you a complete view of who's using it and how access is adjusted.
|
||||
|
||||
<!-- This is a start, but a weak one. -->
|
||||
|
||||
## Sign up
|
||||
|
||||
Review our [Pricing](https://www.pomerium.com/pricing/) page, or [Contact Sales](https://www.pomerium.com/contact-sales/) When you're ready to get started.
|
||||
144
docs/enterprise/concepts.md
Normal file
144
docs/enterprise/concepts.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
---
|
||||
title: Concepts
|
||||
sidebarDepth: 2
|
||||
description: Learn how the Pomerium Enterprise Console works.
|
||||
---
|
||||
|
||||
# Concepts
|
||||
|
||||
## Namespaces
|
||||
|
||||
In the Pomerium Enterprise Console, a **Namespace** is a cornerstone organization unit. They are container objects that behave similar to a unix directory structure.
|
||||
|
||||
In each Namespace, administrators can create organizational units where users and groups can be added. Namespaces enable fine-grained role based access control and management. The structure and hierarchy of namespaces empower teams to self-service the routes and policies pertinent to them. Namespaces can can also be used to optionally or mandatorily inherit from their parent permission or policies.
|
||||
|
||||
Namespaces enable:
|
||||
|
||||
- Self-Service.
|
||||
- Hierarchical policy enforcement (both enforced, and optional),
|
||||
- Policy organization.
|
||||
- [RBAC](https://en.wikipedia.org/wiki/Role-based_access_control) for the Enterprise Console itself.
|
||||
|
||||
Each of these sub-concepts are related and build on each other to form a unified security model.
|
||||
|
||||
### Self-Service Capabilities
|
||||
|
||||
One of the benefits of an identity-aware access proxy is that, once in place, developers and owners of enterprise applications have an incentive to configure their services to be accessible via the proxy.
|
||||
|
||||
Self-service has [several benefits](https://www.usenix.org/system/files/login/articles/login_winter16_05_cittadini.pdf):
|
||||
|
||||
- Frees global administrators from continuously modifying the configuration per user requests
|
||||
- Encourages service owners to own their own route configuration and policy
|
||||
- Ensures a reasonable compromise between development velocity and security controls
|
||||
|
||||
Unlike with a VPN, or network driven access control mechanisms, application owners (with limited access permissions managed through namespaces) can maintain route and policy configuration for their own services, while higher level operations, security, and identity teams are able to enforce higher level authorization and access policies.
|
||||
|
||||
### Hierarchical Policy Enforcement
|
||||
|
||||
Hierarchical policy lets administrators enforce high level authorization policy. Policies can be optional (self-select), or mandatory.
|
||||
|
||||
Identities and their group memberships are defined by your Identity Provider (**IdP**). Pomerium looks to your IdP for identity information, so policies defined using groups are always up-to-date with the access management defined upstream.
|
||||
|
||||
Consider this scenario: you want to enable your security team to manage high level corporate policy while enabling application owners to set finer grained user access to their specific applications. Pomerium can help you do that!
|
||||
|
||||
Your security team can enact top level security policies to ensure, everyone:
|
||||
|
||||
- has a `yourcompany.com` email account,
|
||||
- isn't coming from a known bad actor IP address,
|
||||
|
||||
From there, the security team delegates management of child [Namespaces](#namespaces) to application teams, providing flexibility to self-manage their own application [Routes](#routes) and [Policies](#policies).
|
||||
|
||||
For example, a developer group can be given control to determine who has access to their Namespace, and create or edit Routes within it. They can provide authentication and authorization to their WiP app without writing new authorization code.
|
||||
|
||||
Meanwhile, the CFO is given [manager](#manager) permissions over the "Accounting" Namespace, and can set enforced or optional policies for the services within.
|
||||
|
||||
### RBAC for Enterprise Console Users
|
||||
|
||||
- Namespaces are also used to achieve Role Based Access Control (**RBAC**) in the console itself.
|
||||
- There are three different roles:
|
||||
|
||||
#### Guest (no role)
|
||||
|
||||
Users who are authenticated by your IdP but do not have a role assigned in the Pomerium Console can still view the list of Namespaces, but nothing else.
|
||||
|
||||
#### Viewer
|
||||
|
||||
A user with the Viewer role can:
|
||||
|
||||
- view all resources in a Namespace (Routes, Policies, Certificates), including child Namespaces
|
||||
- view traffic dashboard for routes in the Namespace, including child Namespaces
|
||||
- view the activity log for a namespace.
|
||||
|
||||
#### Manager
|
||||
|
||||
In addition to the access provided by the Viewer role, a Manager can create, read, update, and delete routes, policies, and certificates in a Namespace (as well as its children). A Manager may also reference policies and certificates in the parent Namespace.
|
||||
|
||||
#### Admin
|
||||
|
||||
An Admin user has permissions across all Namespaces. They can manage global settings, sessions, and service accounts, as well as view events and runtime data.
|
||||
|
||||
## Users and Groups
|
||||
|
||||
Pomerium populates users and groups from your IdP. This data is cached to prevent hitting API rate-limits, ensure policy enforcement performance, and provides look-ahead support when adding users or groups to [Namespaces](#namespaces) and [Policies](#policies).
|
||||
|
||||
### Non-Domain Users
|
||||
|
||||
You may encounter a situation where you may want to add users that are not directly associated with your corporate identity provider service. For example, if you have a corporate GSuite account and want to add a contractor with a gmail account. In this case, there are two workarounds:
|
||||
|
||||
- Create a group within your identity provider directly with the non-domain users in it. This group can be found and added to Namespaces and Policies.
|
||||
- Manually add the user's unique ID. Identify the ID from a user's Session Details page, or the [Sessions](/enterprise/reference/reports.html#sessions) page in Pomerium Enterprise Console.
|
||||
|
||||
A user can see their session ID by navigating to the special `/.pomerium` URL endpoint from any Pomerium managed route. The unique ID is listed as "sub" under User Claims:
|
||||
|
||||
|
||||
|
||||
## Service Accounts
|
||||
|
||||
Service accounts provides bearer token based authentication for machine-to-machine communication through Pomerium to your protected endpoints. They can provide auth for monitoring services, create API integrations, and other non-human driven scripts or services.
|
||||
|
||||
A service account identity can either be based on a user entry in your IdP Directory, or exist as a custom identity managed in a Pomerium Console [Namespace](#namespaces).
|
||||
|
||||
## Routes
|
||||
|
||||
Routes define the connection pathway and configuration from the internet to your internal service. As a very basic level, a route sends traffic from `external-address.company.com` to `internalService-address.localdomain`, restricted by the policies associated with it, and encrypted by your TLS certificates. But more advanced configurations allow identity header pass-through, path and prefix rewrites, request and response header modification, load balancer services, and more.
|
||||
|
||||
### Protected Endpoints
|
||||
|
||||
This term refers to the system or service the route provides or restricts access to.
|
||||
|
||||
## Policies
|
||||
|
||||
A Policy defines who has access to what based on the identity of the user, their device, and the associated request context.
|
||||
|
||||
Policies can be applied to [Routes](#routes) directly, or enforced within a [Namespace](#namespaces). Policies allow operators to add authorization and access control to a single, or collection of routes.
|
||||
|
||||
To learn more about how to create Policies in Pomerium Enterprise Console, see [Reference: Policies].
|
||||
|
||||
## Access control
|
||||
|
||||
Authentication and authorization are similar concepts that are often used interchangeably.
|
||||
|
||||
**Authentication** is the process of determining if you are who you say you are.
|
||||
|
||||
**Authorization** is the process of determining if you are allowed to do the thing you are trying to do.
|
||||
|
||||
Pomerium provides a standardized interface to add access control, regardless if an application itself has authorization or authentication baked in, so developers can focus on their app's functionality, not reinventing access control.
|
||||
|
||||
### Authentication
|
||||
|
||||
Pomerium provides authentication via your existing identity provider (Pomerium supports all major [single sign-on](/docs/identity-providers/) providers (Okta, G Suite, Azure, AD, Ping, Github and so on).
|
||||
|
||||
### Authorization
|
||||
|
||||
Authorization policy can be expressed in a high-level, [declarative language](/enterprise/reference/manage.html#pomerium-policy-language) or [as code](/enterprise/reference/manage.html#rego) that can be used to enforce ABAC, RBAC, or any other governance policy controls. Pomerium can make holistic policy and authorization decisions using external data and request context factors such as user groups, roles, time, day, location and vulnerability status.
|
||||
|
||||
Trust flows from identity, device-state, and context, not network location. Every device, user, and application's communication should be authenticated, authorized, and encrypted.
|
||||
|
||||
With Pomerium:
|
||||
|
||||
- requests are continuously re-evaluated on a per-request basis.
|
||||
- authorization is identity and context aware; pomerium can be used to integrate data from any source into authorization policy decisions.
|
||||
- trust flows from identity, device-state, and context, not network location. Every device, user, and application's communication should be authenticated, authorized, and encrypted.
|
||||
- Pomerium provides detailed audit logs for all activity in your environment. Quickly detect anomalies to mitigate bad actors and revoke access with a click of a button. Simplify life-cycle management and access reviews.
|
||||
|
||||
[Reference: Policies]: /enterprise/reference/manage.md#policies-2
|
||||
246
docs/enterprise/console-settings.yaml
Normal file
246
docs/enterprise/console-settings.yaml
Normal file
|
|
@ -0,0 +1,246 @@
|
|||
settings:
|
||||
- name: "Reports"
|
||||
settings:
|
||||
- name: "Traffic"
|
||||
doc: |
|
||||
View the traffic running through Pomerium. Filter by [Route][route-concept] name, or date range.
|
||||
|
||||
|
||||
- name: "Runtime"
|
||||
doc: |
|
||||
Monitor how many system resources Pomerium is consuming. Filter by date range, service, and instance.
|
||||
|
||||
|
||||
- name: "Sessions"
|
||||
doc: |
|
||||
View active Sessions. From here you can revoke sessions, filter by session or user information, or revoke one or multiple sessions. You can also export the data.
|
||||
|
||||
|
||||
- name: "Events"
|
||||
doc: |
|
||||
The events page displays the log output of Envoy as it process changes from Pomerium and applies updates to the underlying services.
|
||||
|
||||
|
||||
|
||||
The most common updates are to Pomerium Proxy services, which are updated every time a Route or Policy is created or updated.
|
||||
|
||||
The value under **Resource ID** will usually match the resource ID of a [Policy][policy-reference], visible in the Policy under **Change History** or in the URL. A value of "Pomerium Restarted" refers to when services are reloaded, usually due to a system update.
|
||||
- name: "Deployments"
|
||||
doc: |
|
||||
From the **Deployment History** page administrators can review changes made to their Pomerium configuration.
|
||||
|
||||
The default view shows all changes made through the Pomerium Enterprise Console. Use the **COMPARE** button next to an entry to filter to only changes that affected that resource. Select two versions of that resource, then **DIFF** to see what changed:
|
||||
|
||||
|
||||
- name: "Manage"
|
||||
settings:
|
||||
- name: "Routes"
|
||||
doc: |
|
||||
A Route defines how to access a service running behind Pomerium. This includes authentication (both for Pomerium and passed through to the service), rewrites, header management, load balancing, etc.
|
||||
settings:
|
||||
- name: "General"
|
||||
doc: |
|
||||
The **General** tab defines the route path, both from the internet and to the internal service, and the policies attached. Note that policies enforced on a [Namespace][namespace-reference] the route resides in will also be applied.
|
||||
settings:
|
||||
- name: "Name"
|
||||
doc: This value is only visible in the Console UI.
|
||||
- name: "From"
|
||||
- name: "To"
|
||||
- name: "Redirect"
|
||||
- name: "Pass Identity Headers"
|
||||
- name: "Policies"
|
||||
doc: Add or remove Policies to be applied to the Route. Note that Policies enforced in the Route's Namespace will be applied automatically.
|
||||
- name: "Enable Google Cloud Serverless Authentication"
|
||||
- name: "Matchers"
|
||||
settings:
|
||||
- name: Path
|
||||
- name: Prefix
|
||||
- name: Regex
|
||||
- name: "Rewrite"
|
||||
settings:
|
||||
- name: "Prefix Rewrite"
|
||||
- name: "Regex Rewrite Pattern"
|
||||
keys: ["regex_rewrite_pattern"]
|
||||
doc: |
|
||||
The pattern to match before rewriting, ex: `^/service/([^/]+)(/.*)$`.
|
||||
- name: "Regex Rewrite Substitution"
|
||||
keys: ["regex_rewrite_substitution"]
|
||||
doc: |
|
||||
The substitution for your regex pattern, ex: `\\2/instance/\\1`.
|
||||
- name: "Timeouts"
|
||||
settings:
|
||||
- name: "Allow Websockets"
|
||||
keys: ["allow_websockets"]
|
||||
- name: "Timeout"
|
||||
keys: ["timeout"]
|
||||
- name: "Idle Timeout"
|
||||
keys: ["idle_timeout"]
|
||||
- name: "Headers"
|
||||
settings:
|
||||
- name: "Host Headers"
|
||||
keys: ["host_rewrite"]
|
||||
- name: "Set Request Headers"
|
||||
- name: "Remove Request Headers"
|
||||
- name: "Rewrite Response Headers"
|
||||
- name: "Load Balancer"
|
||||
settings:
|
||||
- name: "Load Balancing Policy"
|
||||
- name: "Policies"
|
||||
keys: ["Policy"]
|
||||
doc: |
|
||||
A Policy defines what permissions a set of users or groups has. Policies are applied to Namespaces or Routes to associate the set of permissions with a service or set of service, completing the authentication model.
|
||||
|
||||
Policies can be constructed three ways:
|
||||
|
||||
### Web UI
|
||||
|
||||
From the **BUILDER** tab, users can add allow or deny blocks to a policy, containing and/or/not/nor logic to allow or deny sets of users and groups.
|
||||
|
||||
|
||||
|
||||
### Pomerium Policy Language
|
||||
|
||||
From the **EDITOR** tab users can write policies in Pomerium Policy Language (**PPL**), a YAML-based notation.
|
||||
|
||||
|
||||
|
||||
PPL documents contain one or more rules. Each rule has a corresponding action and one or more logical operators.
|
||||
Each logical operator contains criteria and each criterion has a name and corresponding data.
|
||||
|
||||
PPL documents are defined via YAML:
|
||||
|
||||
```yaml
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: x@example.com
|
||||
- email:
|
||||
is: y@example.com
|
||||
```
|
||||
|
||||
The available rule actions are:
|
||||
|
||||
- `allow`
|
||||
- `deny`
|
||||
|
||||
The available logical operators are:
|
||||
|
||||
- `and`
|
||||
- `or`
|
||||
- `not`
|
||||
- `nor`
|
||||
|
||||
The available criteria types are:
|
||||
|
||||
- `accept`
|
||||
- `authenticated_user`
|
||||
- `claim`
|
||||
- `date`
|
||||
- `day_of_week`
|
||||
- `domain`
|
||||
- `email`
|
||||
- `groups`
|
||||
- `reject`
|
||||
- `time_of_day`
|
||||
- `user`
|
||||
|
||||
Some criteria also support a sub-path as part of the criterion name:
|
||||
|
||||
```yaml
|
||||
- allow:
|
||||
or:
|
||||
- claim/family_name:
|
||||
is: Smith
|
||||
```
|
||||
|
||||
### Rego
|
||||
|
||||
For those using [OPA](https://www.openpolicyagent.org/), the **REGO** tab will accept policies written in Rego.
|
||||
|
||||
::: tip
|
||||
A policy can only support PPL or Rego. Once one is set, the other tab is disabled.
|
||||
:::
|
||||
|
||||
### Overrides
|
||||
|
||||
- **Any Authenticated User**: This setting will allow access to a route with this policy attached to any user who can authenticate to your Identity Provider (**IdP**).
|
||||
- **CORS Preflight**:
|
||||
- **Public Access**: This setting allows complete, unrestricted access to an associated route. Use this setting with caution.
|
||||
- name: "Certificates"
|
||||
- name: "Configure"
|
||||
settings:
|
||||
- name: "Settings"
|
||||
settings:
|
||||
- name: "Global"
|
||||
settings:
|
||||
- name: "Administrators"
|
||||
doc: A list of users with full access to the Pomerium Enterprise Console
|
||||
- name: "Debug"
|
||||
- name: "Forward Auth"
|
||||
- name: "HTTP Redirect Address"
|
||||
- name: "DNS Lookup Family"
|
||||
- name: "Log Level"
|
||||
- name: "Proxy Log Level"
|
||||
- name: "Enable User Impersonation"
|
||||
- name: "Cookies"
|
||||
settings:
|
||||
- name: "HTTPS Only"
|
||||
keys: ["cookie_secure"]
|
||||
- name: "Javascript Security"
|
||||
- name: "Expires"
|
||||
keys: ["cookie_expire"]
|
||||
- name: "Timeouts"
|
||||
doc: "Timeouts set the global server timeouts. Timeouts can also be set for individual routes."
|
||||
- name: "GRPC"
|
||||
settings:
|
||||
- name: "GRPC Server Max Connection Age"
|
||||
doc: |
|
||||
Set max connection age for GRPC servers. After this interval, servers ask clients to reconnect and perform any rediscovery for new/updated endpoints from DNS.
|
||||
|
||||
See https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters for details
|
||||
- name: "GRPC Server Max Connection Age Grace"
|
||||
doc: |
|
||||
Additive period with grpc_server_max_connection_age, after which servers will force connections to close.
|
||||
|
||||
See https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters (opens new window)for details
|
||||
- name: "Tracing"
|
||||
- name: "Authenticate"
|
||||
- name: "Authorize"
|
||||
settings:
|
||||
- name: "Signing Key"
|
||||
- name: "Signing Key Algorithm"
|
||||
- name: "Proxy"
|
||||
settings:
|
||||
- name: "Certificate Authority"
|
||||
keys: ["certificate_authority"]
|
||||
- name: "Default Upstream Timeout"
|
||||
- name: "JWT Claim Headers"
|
||||
- name: "Override Certificate Name"
|
||||
- name: "Refresh Cooldown"
|
||||
- name: "X-Forward-For HTTP Header"
|
||||
keys: ["skip_xff_append"]
|
||||
- name: "Response Headers"
|
||||
keys: ["set_response_headers"]
|
||||
- name: "Service Accounts"
|
||||
doc: |
|
||||
See [Concepts: Service Accounts][service-accounts-concept].
|
||||
- name: "Namespaces"
|
||||
keys: ["namespace"]
|
||||
doc: |
|
||||
A [Namespace][namespace-concept] is a collection of users, groups, routes, and policies that allows system administrators to organize, manage, and delegate permissions across their infrastructure.
|
||||
|
||||
- Policies can be optional or enforced on a Namespace.
|
||||
- Enforced policies are also enforced on child Namespaces, and optional policies are available to them as well.
|
||||
- Users or groups can be granted permission to edit access to routes within a Namespace, allowing them self-serve access to the routes critical to their work.
|
||||
|
||||
::: tip
|
||||
When using an IdP without directory sync or when working with non-domain users, they will not show up in the look-ahead search. See [Non-Domain Users](/enterprise/concepts.html#non-domain-users) for more information.
|
||||
:::
|
||||
|
||||
postamble: |
|
||||
[route-concept]: /enterprise/concepts.md#routes
|
||||
[route-reference]: /enterprise/reference/manage.md#routes
|
||||
[namespace-concept]: /enterprise/concepts.md#namespaces
|
||||
[namespace-reference]: /enterprise/reference/configure.md#namespaces
|
||||
[service-accounts-concept]: /enterprise/concepts.md#service-accounts
|
||||
[policy-reference]: /enterprise/reference/manage.md#policies-2
|
||||
BIN
docs/enterprise/img/console-overview.gif
Normal file
BIN
docs/enterprise/img/console-overview.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 518 KiB |
BIN
docs/enterprise/img/console-route-traffic.png
Normal file
BIN
docs/enterprise/img/console-route-traffic.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
BIN
docs/enterprise/img/console-session-landing.png
Normal file
BIN
docs/enterprise/img/console-session-landing.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
BIN
docs/enterprise/img/console-session-list.png
Normal file
BIN
docs/enterprise/img/console-session-list.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
docs/enterprise/img/deployment-diff.png
Normal file
BIN
docs/enterprise/img/deployment-diff.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
BIN
docs/enterprise/img/events-fullpage.png
Normal file
BIN
docs/enterprise/img/events-fullpage.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
BIN
docs/enterprise/img/example-policy-editor.png
Normal file
BIN
docs/enterprise/img/example-policy-editor.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
BIN
docs/enterprise/img/example-policy-single-user.png
Normal file
BIN
docs/enterprise/img/example-policy-single-user.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
BIN
docs/enterprise/img/runtime-fullpage.png
Normal file
BIN
docs/enterprise/img/runtime-fullpage.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
BIN
docs/enterprise/img/session-details.png
Normal file
BIN
docs/enterprise/img/session-details.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
BIN
docs/enterprise/img/sessions-fullpage.png
Normal file
BIN
docs/enterprise/img/sessions-fullpage.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
BIN
docs/enterprise/img/traffic-fullpage.png
Normal file
BIN
docs/enterprise/img/traffic-fullpage.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 81 KiB |
145
docs/enterprise/install/helm.md
Normal file
145
docs/enterprise/install/helm.md
Normal file
|
|
@ -0,0 +1,145 @@
|
|||
---
|
||||
title: Helm
|
||||
sidebarDepth: 1
|
||||
description: Install Pomerium Enterprise in Kubernetes with Helm
|
||||
---
|
||||
|
||||
# Install Pomerium Enterprise Console in Helm
|
||||
|
||||
This document covers installing Pomerium Enterprise Console into your existing helm-managed Kubernetes cluster. It's designed to work with an existing cluster running Pomerium, as described im [Pomerium using Helm]. Follow that document before continuing here.
|
||||
|
||||
## Before You Begin
|
||||
|
||||
The Pomerium Enterprise Console requires:
|
||||
|
||||
- An accessible RDBMS. We support PostgreSQL 9+.
|
||||
- A database and user with full permissions for it.
|
||||
- A certificate management solution. This page will assume a store of certificates using [cert-manager] as the solution. If you use another certificate solution, adjust the steps accordingly.
|
||||
- An existing Pomerium installation. If you don't already have the open-source Pomerium installed in your cluster, see [Pomerium using Helm] before you continue.
|
||||
|
||||
|
||||
## System Requirements
|
||||
|
||||
One of the advantages of a Kubernetes deployment is automatic scaling, but if your database or redis solution is outside of your k8s configuration, refer to the requirements below:
|
||||
|
||||
- Each Postgres instance should have at least:
|
||||
- 4 vCPUs
|
||||
- 8G RAM
|
||||
- 20G for data files
|
||||
- Each Redis instance should have at least:
|
||||
- 2 vCPUs
|
||||
- 4G RAM
|
||||
- 20G for data files
|
||||
|
||||
## Issue a Certificate
|
||||
|
||||
This setup assumes an existing certificate solution using cert-manager, as described in [Pomerium using Helm]. If you already have a different certificate solution, create and implement a certificate for `pomerium-console.pomerium.svc.cluster.local`. Then you can move on to [the next stage](#update-pomerium).
|
||||
|
||||
|
||||
1. Create a certificate configuration file for Pomerium Enterprise Our example is named `pomerium-console-certificate.yaml`:
|
||||
|
||||
<<< @/examples/kubernetes/pomerium-console-certificate.yaml
|
||||
|
||||
1. Apply the required certificate configurations, and confirm:
|
||||
|
||||
```bash
|
||||
kubectl apply -f pomerium-console-certificate.yaml
|
||||
```
|
||||
|
||||
```bash
|
||||
kubectl get certificate
|
||||
NAME READY SECRET AGE
|
||||
pomerium-cert True pomerium-tls 92m
|
||||
pomerium-console-cert True pomerium-console-tls 6s
|
||||
pomerium-redis-cert True pomerium-redis-tls 92m
|
||||
```
|
||||
|
||||
## Update Pomerium
|
||||
|
||||
1. Set your local context to your Pomerium namespace:
|
||||
|
||||
```bash
|
||||
kubectl config set-context --current --namespace=pomerium
|
||||
```
|
||||
|
||||
1. Open your pomerium values file. If you followed [Pomerium Using Helm], the file is named `pomerium-values.yaml`. In the `config` section, set a list item in the `routes` block for the Enterprise Console:
|
||||
|
||||
```yaml
|
||||
routes:
|
||||
- from: https://console.localhost.pomerium.com
|
||||
to: https://pomerium-console.pomerium.svc.cluster.local
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- domain:
|
||||
is: companydomain.com
|
||||
pass_identity_headers: true
|
||||
```
|
||||
|
||||
1. Use Helm to update your Pomerium installation:
|
||||
|
||||
```bash
|
||||
helm upgrade --install pomerium pomerium/pomerium --values=./pomerium-values.yaml
|
||||
```
|
||||
|
||||
## Install Pomerium Enterprise Console
|
||||
|
||||
1. Create `pomerium-console-values.yaml` as shown below, replacing placeholder values:
|
||||
|
||||
```yaml
|
||||
database:
|
||||
type: pg
|
||||
username: pomeriumDbUser
|
||||
password: IAMASTRONGPASSWORDLOOKATME
|
||||
host: 198.51.100.53
|
||||
name: pomeriumDbName
|
||||
sslmode: require
|
||||
config:
|
||||
sharedSecret: #Shared with Pomerium
|
||||
databaseEncryptionKey: #Generate from "head -c32 /dev/urandom | base64"
|
||||
administrators: "youruser@yourcompany.com" #This is a hard-coded access, remove once setup is complete
|
||||
tls:
|
||||
existingCASecret: pomerium-tls
|
||||
caSecretKey: ca.crt
|
||||
existingSecret: pomerium-console-tls
|
||||
generate: false
|
||||
image:
|
||||
pullUsername: pomerium/enterprise
|
||||
pullPassword: your-access-key
|
||||
```
|
||||
|
||||
1. Add the Pomerium Enterprise repository to your Helm configuration:
|
||||
|
||||
```bash
|
||||
helm repo add pomerium-enterprise https://releases.pomerium.com
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Install Pomerium Enterprise:
|
||||
|
||||
```bash
|
||||
helm install pomerium-console pomerium-enterprise/pomerium-console --values=pomerium-console-values.yaml
|
||||
```
|
||||
|
||||
1. If you haven't configured a public DNS record for your Pomerium domain space, you can use `kubectl` to generate a local proxy:
|
||||
|
||||
```bash
|
||||
sudo -E kubectl --namespace pomerium port-forward service/pomerium-proxy 443:443
|
||||
```
|
||||
|
||||
1. When visiting `https://console.localhost.pomerium.io`, you should se the Session List page:
|
||||
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Updating Service Types:
|
||||
|
||||
If, while updating the open-source Pomerium values, you change any block's `service.type` you may need to manually delete corresponding service before applying the new configuration. For example:
|
||||
|
||||
```bash
|
||||
kubectl delete svc pomerium-proxy
|
||||
```
|
||||
|
||||
[Pomerium using Helm]: /docs/install/helm.md
|
||||
[cert-manager]: https://cert-manager.io/docs/
|
||||
182
docs/enterprise/install/quickstart.md
Normal file
182
docs/enterprise/install/quickstart.md
Normal file
|
|
@ -0,0 +1,182 @@
|
|||
---
|
||||
title: Quickstart
|
||||
sidebarDepth: 1
|
||||
description: Demo Pomerium Enterprise
|
||||
---
|
||||
|
||||
# Pomerium Enterprise Quickstart
|
||||
|
||||
## Before You Begin
|
||||
|
||||
This document assumes:
|
||||
|
||||
- A non-containerized environment, either your local computer or a virtual machine (**vm**). While Pomerium is designed to scale with your production environment, we'll leave containerization and infrastructure as code (**IaC**) out for now, to focus on learning how Pomerium Enterprise works.
|
||||
- `root` or `sudo` privileges on the host.
|
||||
- You already have the open-source Pomerium base installed. If not, follow [this doc](/docs/install/binary.md) before you continue.
|
||||
- While an existing route is not required, we suggest implementing one test route to validate your identity provider (**IdP**) configuration.
|
||||
- Pomerium Enterprise requires a relational database. PostgreSQL 9+ is supported.
|
||||
- Securing the database connection with TLS may not be required, especially for a local installation, but is strongly recommended for production deployments. Therefor, this guide will assume a TLS-secured database connection.
|
||||
- A supported data broker backend. Currently we support Redis.
|
||||
- As with the database, TLS encryption is strongly recommended for production deployments.
|
||||
|
||||
## Requirements
|
||||
|
||||
- The Pomerium Enterprise Console requires Linux amd64/x86_64. It can manage Pomerium instances on other platforms, however.
|
||||
- Each Console instance should have at least:
|
||||
- 4 vCPUs
|
||||
- 8G RAM
|
||||
- 100G of disk wherever logs are stored
|
||||
- Each Postgres instance should have at least:
|
||||
- 4 vCPUs
|
||||
- 8G RAM
|
||||
- 20G for data files
|
||||
- Each Redis instance should have at least:
|
||||
- 2 vCPUs
|
||||
- 4G RAM
|
||||
- 20G for data files
|
||||
|
||||
## Install Pomerium Enterprise Console
|
||||
|
||||
Pomerium publishes standard OS packages for RPM and DEB based systems. The repositories require authentication via username and access key. These credentials will be issued to you during the onboarding process.
|
||||
|
||||
:::: tabs
|
||||
|
||||
::: tab deb
|
||||
|
||||
1. To automatically configure the repository for Debian and Ubuntu distributions, run the following command replacing `[access-key]`:
|
||||
|
||||
```bash
|
||||
curl -1sLf \
|
||||
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.deb.sh' \
|
||||
| sudo -E bash
|
||||
```
|
||||
|
||||
Or to manually configure, you can manually import the apt key, then create a new `.list` file in `/etc/apt/source.list.d`. Make sure to replace the distro and version:
|
||||
|
||||
```bash
|
||||
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key' | apt-key add -
|
||||
|
||||
echo "deb https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/deb/debian buster main" | sudo tee /apt/sources.list.d/pomerium-console.list
|
||||
```
|
||||
|
||||
1. Update `apt` and install the Pomerium Enterprise Console:
|
||||
|
||||
```bash
|
||||
sudo apt update; sudo apt install pomerium-console
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
|
||||
::: tab yum
|
||||
|
||||
1. To automatically configure the repository for RHEL based distributions, run the following command replacing `[access-key]`:
|
||||
|
||||
```bash
|
||||
curl -1sLf \
|
||||
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.rpm.sh' \
|
||||
| sudo -E bash
|
||||
```
|
||||
|
||||
Or to manually configure:
|
||||
|
||||
```bash
|
||||
yum install yum-utils pygpgme
|
||||
rpm --import 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key'
|
||||
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/config.rpm.txt?distro=el&codename=8' > /tmp/pomerium-enterprise.repo
|
||||
yum-config-manager --add-repo '/tmp/pomerium-enterprise.repo'
|
||||
yum -q makecache -y --disablerepo='*' --enablerepo='pomerium-enterprise'
|
||||
```
|
||||
|
||||
1. Update refresh and install:
|
||||
|
||||
```bash
|
||||
yum -y install pomerium-console
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
::::
|
||||
|
||||
### System Service
|
||||
|
||||
Once the package is installed, enable and start the system service:
|
||||
|
||||
```bash
|
||||
sudo systemctl enable --now pomerium-console
|
||||
```
|
||||
|
||||
## Initial Configuration
|
||||
|
||||
Like the open-source Pomerium base, Pomerium Enterprise Console is configured through a single config file, located at `/etc/pomerium-console/config.yaml`.
|
||||
|
||||
### External Services
|
||||
|
||||
First configure the Console to communicate with the database and databroker service:
|
||||
|
||||
```yaml
|
||||
database_url: pg://user:pass@dbhost.internal.mydomain.com/pomerium?sslmode=require
|
||||
databroker_service_url: https://pomerium-cache.internal.mydomain.com
|
||||
shared_secret: XXXXXXXXXXXXXXXXXXX
|
||||
database_encryption_key: YYYYYYYYYYYYYYYYYYYYYY
|
||||
```
|
||||
|
||||
For database uri options (especially TLS settings) see the [PostgreSQL SSL Support](https://www.postgresql.org/docs/9.1/libpq-ssl.html) documentation.
|
||||
|
||||
### Administrators
|
||||
|
||||
As a first-time setup step, you must also configure at least one administrator for console access. This user (or users) can then configure additional administrators in the console UI.
|
||||
|
||||
```yaml
|
||||
administrators: you@mydomain.com
|
||||
```
|
||||
|
||||
Once you have set permissions in the console UI, you should remove this configuration.
|
||||
|
||||
### TLS
|
||||
|
||||
If your open-source Pomerium installation is already configured to use TLS to secure back-end communication, you can do the same for the Pomerium Enterprise Console by providing it a certificate, key, and optional custom CA file to validate the `databroker_service_url` connection:
|
||||
|
||||
```yaml
|
||||
tls_ca_file: /etc/pomerium-console/ca.pem
|
||||
tls_cert_file: /etc/pomerium-console/cert.pem
|
||||
tls_key_file: /etc/pomerium-console/key.pem
|
||||
```
|
||||
|
||||
For proof-of-concept installations in the same local system, this is not required.
|
||||
|
||||
Once complete, your `/etc/pomerium-console/config.yaml` file should look something like this:
|
||||
|
||||
```yaml
|
||||
database_url: pg://user:pass@dbhost.internal.mydomain.com/pomerium?sslmode=require
|
||||
databroker_service_url: https://pomerium-cache.internal.mydomain.com
|
||||
shared_secret: XXXXXXXXXXXXXXXXXXX
|
||||
database_encryption_key: YYYYYYYYYYYYYYYYYYYYYY
|
||||
|
||||
# change / remove this after initial setup
|
||||
administrators: you@mydomain.com
|
||||
|
||||
tls_ca_file: /etc/pomerium-console/ca.pem
|
||||
tls_cert_file: /etc/pomerium-console/cert.pem
|
||||
tls_key_file: /etc/pomerium-console/key.pem
|
||||
```
|
||||
|
||||
### Update Pomerium
|
||||
|
||||
Open your Pomerium config file, `/etc/pomerium/config.yaml`. Add a list item in the `routes` block for the Enterprise Console:
|
||||
|
||||
```yaml
|
||||
routes:
|
||||
- from: https://console.localhost.pomerium.com
|
||||
to: https://pomerium-console.pomerium.svc.cluster.local
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- domain:
|
||||
is: companydomain.com
|
||||
pass_identity_headers: true
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
The Pomerium Enterprise Console assumes access to a [Prometheus](https://prometheus.io/) data store for metrics. See [Prometheus Metrics](/enterprise/prometheus.md) to learn how to configure access.
|
||||
14
docs/enterprise/install/readme.md
Normal file
14
docs/enterprise/install/readme.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
---
|
||||
title: Install
|
||||
lang: en-US
|
||||
meta:
|
||||
- name: keywords
|
||||
content: pomerium identity-access-proxy oidc docker reverse-proxy containers install enterprise console
|
||||
---
|
||||
|
||||
There are several ways to install Pomerium Enterprise, to suite your organization's needs. We provide open-source Pomerium and the Pomerium Enterprise Console as deb and rpm packages from an upstream repository, and as Docker images, and Helm charts. You can also build Pomerium from source.
|
||||
|
||||
Our docs are updated frequently, so check back if you don't see your preferred installation method here.
|
||||
|
||||
- [Quickstart](/enterprise/install/quickstart.md) (using deb or rpm packages)
|
||||
- [Kubernetes with Helm](/enterprise/install/helm.md)
|
||||
82
docs/enterprise/pomerium-console_serve.yaml
Normal file
82
docs/enterprise/pomerium-console_serve.yaml
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
name: pomerium-console serve
|
||||
usage: pomerium-console serve [flags]
|
||||
options:
|
||||
- name: administrators
|
||||
usage: |
|
||||
a list of user ids, names or emails to make administrators, useful for bootstrapping
|
||||
- name: bind-addr
|
||||
default_value: :8701
|
||||
usage: the address to listen on
|
||||
- name: customer-id
|
||||
usage: the customer id
|
||||
- name: database-encryption-key
|
||||
usage: |
|
||||
base64-encoded encryption key for encrypting sensitive data in the database
|
||||
- name: database-url
|
||||
default_value: |
|
||||
postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable
|
||||
usage: the database to connect to
|
||||
- name: databroker-service-url
|
||||
default_value: http://localhost:5443
|
||||
usage: the databroker service url
|
||||
- name: disable-validation
|
||||
default_value: "false"
|
||||
usage: disable config validation
|
||||
- name: enable-remote-diagnostics
|
||||
default_value: "false"
|
||||
usage: enable remote diagnostics
|
||||
- name: grpc-addr
|
||||
default_value: :8702
|
||||
usage: the address to listen for gRPC on
|
||||
- name: help
|
||||
shorthand: h
|
||||
default_value: "false"
|
||||
usage: help for serve
|
||||
- name: license
|
||||
usage: license JWT
|
||||
- name: override-certificate-name
|
||||
usage: |
|
||||
override the certificate name used for the databroker connection
|
||||
- name: prometheus-data-dir
|
||||
usage: path to prometheus data
|
||||
- name: prometheus-listen-addr
|
||||
default_value: 127.0.0.1:9090
|
||||
usage: embedded prometheus listen address as host:port
|
||||
- name: prometheus-scrape-interval
|
||||
default_value: 10s
|
||||
usage: prometheus scrape frequency
|
||||
- name: prometheus-url
|
||||
usage: url to access prometheus metrics server
|
||||
- name: shared-secret
|
||||
usage: base64-encoded shared secret for signing JWTs
|
||||
- name: signing-key
|
||||
usage: |
|
||||
base64-encoded signing key (public or private) for verifying JWTs
|
||||
- name: tls-ca
|
||||
usage: base64-encoded string of tls-ca
|
||||
- name: tls-ca-file
|
||||
usage: file storing tls-ca
|
||||
- name: tls-cert
|
||||
usage: base64-encoded string of tls-cert
|
||||
- name: tls-cert-file
|
||||
usage: file storing tls-cert
|
||||
- name: tls-insecure-skip-verify
|
||||
default_value: "false"
|
||||
usage: |
|
||||
disable remote hosts TLS certificate chain and hostname check
|
||||
- name: tls-key
|
||||
usage: base64-encoded string of tls-key
|
||||
- name: tls-key-file
|
||||
usage: file storing tls-key
|
||||
- name: use-static-assets
|
||||
default_value: "true"
|
||||
usage: when false, forward static requests to localhost:3000
|
||||
inherited_options:
|
||||
- name: config
|
||||
usage: Set configuration file path
|
||||
- name: version
|
||||
default_value: "false"
|
||||
usage: view the version information
|
||||
see_also:
|
||||
- 'pomerium-console - '
|
||||
- migrate - migrate the dashboard database up or down
|
||||
58
docs/enterprise/prometheus.md
Normal file
58
docs/enterprise/prometheus.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
title: Prometheus
|
||||
sidebarDepth: 1
|
||||
description: Use Prometheus as a metrics data store.
|
||||
---
|
||||
|
||||
# Prometheus Metrics
|
||||
|
||||
The Pomerium Enterprise Console uses Prometheus as a metrics collection back-end. You can configure Pomerium and the Console to talk to an existing Prometheus server, or configure the embedded Prometheus backend.
|
||||
|
||||
## Prepare Pomerium
|
||||
|
||||
1. In the Pomerium `config.yaml`, define the `metrics_address` key to a network interface and/or port. For example:
|
||||
|
||||
```yaml
|
||||
metrics_address: 0.0.0.0:9999
|
||||
```
|
||||
|
||||
The example above has Pomerium providing metrics at port `9999` on all network interfaces.
|
||||
|
||||
## External Prometheus
|
||||
|
||||
1. Add the listener to your Prometheus configuration, usually via `prometheus.yml`:
|
||||
|
||||
```yaml
|
||||
- job_name: 'Pomerium'
|
||||
scrape_interval: 30s
|
||||
scrape_timeout: 5s
|
||||
static_configs:
|
||||
- targets: ['192.0.2.10:9999']
|
||||
|
||||
```
|
||||
|
||||
1. [Reload](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#configuration) the Prometheus configuration:
|
||||
|
||||
```bash
|
||||
curl -i -XPOST path.to.prometheus:port/-/reload
|
||||
```
|
||||
|
||||
1. In the Pomerium Enterprise Console `config.yaml` file, define the `prometheus_url` key to point to your Prometheus instance(s):
|
||||
|
||||
```yaml
|
||||
prometheus_url: http://192.168.122.50:9090
|
||||
```
|
||||
|
||||
1. Restart the Pomerium and Pomerium Enterprise Console services. You should now see route traffic data in the Enterprise Console:
|
||||
|
||||
|
||||
|
||||
## Embedded Prometheus
|
||||
|
||||
To take advantage of Prometheus embedded in Pomerium Enterprise Console, edit `/etc/pomerium-console/config.yaml`:
|
||||
|
||||
```yaml
|
||||
prometheus_data_dir: /var/lib/pomerium-console/tsdb
|
||||
```
|
||||
|
||||
The directory path can be any location that the `pomerium` system user can write to. The example above uses the default location created by the [OS packages](/enterprise/install/quickstart).
|
||||
1
docs/enterprise/readme.md
Normal file
1
docs/enterprise/readme.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
<Redirect to="/enterprise/about/" />
|
||||
173
docs/enterprise/reference/config.md
Normal file
173
docs/enterprise/reference/config.md
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
---
|
||||
title: Environment Variables
|
||||
lang: en-US
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
# Pomerium Console Environment Variables
|
||||
|
||||
The keys listed below can be applied in Pomerium Console's `config.yaml` file, or applied as environment variables (in uppercase, replacing `-` with `_`).
|
||||
|
||||
## administrators
|
||||
|
||||
a list of user ids, names or emails to make administrators, useful for bootstrapping
|
||||
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## bind-addr
|
||||
|
||||
the address to listen on
|
||||
|
||||
**Default value:** `:8701`
|
||||
|
||||
## customer-id
|
||||
|
||||
the customer id
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## database-encryption-key
|
||||
|
||||
base64-encoded encryption key for encrypting sensitive data in the database
|
||||
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## database-url
|
||||
|
||||
the database to connect to
|
||||
|
||||
**Default value:** `postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable
|
||||
`
|
||||
|
||||
## databroker-service-url
|
||||
|
||||
the databroker service url
|
||||
|
||||
**Default value:** `http://localhost:5443`
|
||||
|
||||
## disable-validation
|
||||
|
||||
disable config validation
|
||||
|
||||
**Default value:** `false`
|
||||
|
||||
## enable-remote-diagnostics
|
||||
|
||||
enable remote diagnostics
|
||||
|
||||
**Default value:** `false`
|
||||
|
||||
## grpc-addr
|
||||
|
||||
the address to listen for gRPC on
|
||||
|
||||
**Default value:** `:8702`
|
||||
|
||||
## help
|
||||
|
||||
help for serve
|
||||
|
||||
**Default value:** `false`
|
||||
|
||||
## license
|
||||
|
||||
license JWT
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## override-certificate-name
|
||||
|
||||
override the certificate name used for the databroker connection
|
||||
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## prometheus-data-dir
|
||||
|
||||
path to prometheus data
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## prometheus-listen-addr
|
||||
|
||||
embedded prometheus listen address as host:port
|
||||
|
||||
**Default value:** `127.0.0.1:9090`
|
||||
|
||||
## prometheus-scrape-interval
|
||||
|
||||
prometheus scrape frequency
|
||||
|
||||
**Default value:** `10s`
|
||||
|
||||
## prometheus-url
|
||||
|
||||
url to access prometheus metrics server
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## shared-secret
|
||||
|
||||
base64-encoded shared secret for signing JWTs
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## signing-key
|
||||
|
||||
base64-encoded signing key (public or private) for verifying JWTs
|
||||
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## tls-ca
|
||||
|
||||
base64-encoded string of tls-ca
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## tls-ca-file
|
||||
|
||||
file storing tls-ca
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## tls-cert
|
||||
|
||||
base64-encoded string of tls-cert
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## tls-cert-file
|
||||
|
||||
file storing tls-cert
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## tls-insecure-skip-verify
|
||||
|
||||
disable remote hosts TLS certificate chain and hostname check
|
||||
|
||||
|
||||
**Default value:** `false`
|
||||
|
||||
## tls-key
|
||||
|
||||
base64-encoded string of tls-key
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## tls-key-file
|
||||
|
||||
file storing tls-key
|
||||
|
||||
**Default value:** `none`
|
||||
|
||||
## use-static-assets
|
||||
|
||||
when false, forward static requests to localhost:3000
|
||||
|
||||
**Default value:** `true`
|
||||
370
docs/enterprise/reference/configure.md
Normal file
370
docs/enterprise/reference/configure.md
Normal file
|
|
@ -0,0 +1,370 @@
|
|||
---
|
||||
title: Configure
|
||||
lang: en-US
|
||||
sidebarDepth: 2
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
# Configure
|
||||
|
||||
## Settings
|
||||
|
||||
|
||||
### Global
|
||||
|
||||
|
||||
#### Administrators
|
||||
|
||||
A list of users with full access to the Pomerium Enterprise Console
|
||||
|
||||
#### Debug
|
||||
|
||||
::: danger
|
||||
|
||||
Enabling the debug flag could result in sensitive information being logged!!!
|
||||
|
||||
:::
|
||||
|
||||
By default, JSON encoded logs are produced. Debug enables colored, human-readable logs to be streamed to [standard out](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)>>>). In production, it is 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=verify.localhost.pomerium.io to=https://verify.pomerium.com
|
||||
10:37AM INF proxy: new route from=ssl.localhost.pomerium.io to=http://neverssl.com
|
||||
10:37AM INF proxy/authenticator: grpc connection OverrideCertificateName= addr=auth.localhost.pomerium.io: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":"verify.localhost.pomerium.io","to":"https://verify.pomerium.com","time":"2019-02-18T10:41:03-08:00","message":"proxy: new route"}
|
||||
{"level":"info","from":"ssl.localhost.pomerium.io","to":"http://neverssl.com","time":"2019-02-18T10:41:03-08:00","message":"proxy: new route"}
|
||||
{"level":"info","OverrideCertificateName":"","addr":"auth.localhost.pomerium.io:443","time":"2019-02-18T10:41:03-08:00","message":"proxy/authenticator: grpc connection"}
|
||||
```
|
||||
|
||||
#### Forward Auth
|
||||
|
||||
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 allows you to delegate authentication and authorization for each request to Pomerium.
|
||||
|
||||
#### Request flow
|
||||
|
||||
|
||||
|
||||
#### Examples
|
||||
|
||||
##### 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.
|
||||
|
||||
```yaml
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: verify
|
||||
annotations:
|
||||
kubernetes.io/ingress.class: "nginx"
|
||||
certmanager.k8s.io/issuer: "letsencrypt-prod"
|
||||
nginx.ingress.kubernetes.io/auth-url: https://forwardauth.corp.example.com/verify?uri=$scheme://$host$request_uri
|
||||
nginx.ingress.kubernetes.io/auth-signin: "https://forwardauth.corp.example.com/?uri=$scheme://$host$request_uri"
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
- verify.corp.example.com
|
||||
secretName: quickstart-example-tls
|
||||
rules:
|
||||
- host: verify.corp.example.com
|
||||
http:
|
||||
paths:
|
||||
- path: /
|
||||
backend:
|
||||
serviceName: verify
|
||||
servicePort: 80
|
||||
```
|
||||
|
||||
#### Traefik docker-compose
|
||||
|
||||
If the `forward_auth_url` is also handled by Traefik, you will need to configure Traefik to trust the `X-Forwarded-*` headers as described in [the documentation](https://docs.traefik.io/v2.2/routing/entrypoints/#forwarded-headers).
|
||||
|
||||
```yml
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
traefik:
|
||||
# The official v2.2 Traefik docker image
|
||||
image: traefik:v2.2
|
||||
# Enables the web UI and tells Traefik to listen to docker
|
||||
command:
|
||||
- "--api.insecure=true"
|
||||
- "--providers.docker=true"
|
||||
- "--entrypoints.web.address=:80"
|
||||
- "--entrypoints.web.forwardedheaders.insecure=true"
|
||||
ports:
|
||||
# The HTTP port
|
||||
- "80:80"
|
||||
# The Web UI (enabled by --api.insecure=true)
|
||||
- "8080:8080"
|
||||
volumes:
|
||||
# So that Traefik can listen to the Docker events
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
verify:
|
||||
# A container that exposes an API to show its IP address
|
||||
image: pomerium/verify:latest
|
||||
labels:
|
||||
- "traefik.http.routers.verify.rule=Host(`verify.corp.example.com`)"
|
||||
# Create a middleware named `foo-add-prefix`
|
||||
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Pomerium-Authenticated-User-Email,x-pomerium-authenticated-user-id,x-pomerium-authenticated-user-groups,x-pomerium-jwt-assertion"
|
||||
- "traefik.http.middlewares.test-auth.forwardauth.address=http://forwardauth.corp.example.com/?uri=https://verify.corp.example.com"
|
||||
- "traefik.http.routers.verify.middlewares=test-auth@docker"
|
||||
```
|
||||
|
||||
#### HTTP Redirect Address
|
||||
|
||||
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.
|
||||
|
||||
#### DNS Lookup Family
|
||||
|
||||
The DNS IP address resolution policy. If not specified, the value defaults to `AUTO`.
|
||||
|
||||
#### Log Level
|
||||
|
||||
Log level sets the global logging level for pomerium. Only logs of the desired level and above will be logged.
|
||||
|
||||
#### Proxy Log Level
|
||||
|
||||
Proxy log level sets the logging level for the pomerium proxy service access logs. Only logs of the desired level and above will be logged.
|
||||
|
||||
#### Enable User Impersonation
|
||||
|
||||
|
||||
### Cookies
|
||||
|
||||
|
||||
#### HTTPS Only
|
||||
|
||||
If true, instructs browsers to only send user session cookies over HTTPS.
|
||||
|
||||
:::warning
|
||||
|
||||
Setting this to false may result in session cookies being sent in cleartext.
|
||||
|
||||
:::
|
||||
|
||||
#### Javascript Security
|
||||
|
||||
If true, prevents javascript in browsers from reading user session cookies.
|
||||
|
||||
:::warning
|
||||
|
||||
Setting this to false enables hostile javascript to steal session cookies and impersonate users.
|
||||
|
||||
:::
|
||||
|
||||
#### Expires
|
||||
|
||||
Sets the lifetime of session cookies. After this interval, users must reauthenticate.
|
||||
|
||||
### Timeouts
|
||||
|
||||
Timeouts set the global server timeouts. Timeouts can also be set for individual routes.
|
||||
|
||||
### GRPC
|
||||
|
||||
|
||||
#### GRPC Server Max Connection Age
|
||||
|
||||
Set max connection age for GRPC servers. After this interval, servers ask clients to reconnect and perform any rediscovery for new/updated endpoints from DNS.
|
||||
|
||||
See https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters for details
|
||||
|
||||
|
||||
#### GRPC Server Max Connection Age Grace
|
||||
|
||||
Additive period with grpc_server_max_connection_age, after which servers will force connections to close.
|
||||
|
||||
See https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters (opens new window)for details
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
Config Key | Description | Required
|
||||
:------------------ | :----------------------------------------------------------------------------------- | --------
|
||||
tracing_provider | The name of the tracing provider. (e.g. jaeger, zipkin) | ✅
|
||||
tracing_sample_rate | Percentage of requests to sample in decimal notation. Default is `0.0001`, or `.01%` | ❌
|
||||
|
||||
#### Datadog
|
||||
|
||||
Datadog is a real-time monitoring system that supports distributed tracing and monitoring.
|
||||
|
||||
Config Key | Description | Required
|
||||
:---------------------- | :--------------------------------------------------------------------------- | --------
|
||||
tracing_datadog_address | `host:port` address of the Datadog Trace Agent. Defaults to `localhost:8126` | ❌
|
||||
|
||||
#### Jaeger (partial)
|
||||
|
||||
**Warning** At this time, Jaeger protocol does not capture spans inside the proxy service. Please use Zipkin protocol with Jaeger for full support.
|
||||
|
||||
[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:
|
||||
|
||||
- Distributed context propagation
|
||||
- Distributed transaction monitoring
|
||||
- Root cause analysis
|
||||
- Service dependency analysis
|
||||
- Performance / latency optimization
|
||||
|
||||
Config Key | Description | Required
|
||||
:-------------------------------- | :------------------------------------------ | --------
|
||||
tracing_jaeger_collector_endpoint | Url to the Jaeger HTTP Thrift collector. | ✅
|
||||
tracing_jaeger_agent_endpoint | Send spans to jaeger-agent at this address. | ✅
|
||||
|
||||
#### Zipkin
|
||||
|
||||
Zipkin is an open source distributed tracing system and protocol.
|
||||
|
||||
Many tracing backends support zipkin either directly or through intermediary agents, including Jaeger. For full tracing support, we recommend using the Zipkin tracing protocol.
|
||||
|
||||
Config Key | Description | Required
|
||||
:---------------------- | :------------------------------- | --------
|
||||
tracing_zipkin_endpoint | Url to the Zipkin HTTP endpoint. | ✅
|
||||
|
||||
#### Example
|
||||
|
||||
|
||||
|
||||
### Authenticate
|
||||
|
||||
|
||||
### Authorize
|
||||
|
||||
|
||||
#### Signing Key
|
||||
|
||||
Signing Key is the private key used to sign a user's attestation JWT which can be consumed by upstream applications to pass along identifying user information like username, id, and groups.
|
||||
|
||||
If set, the signing key's public key will can retrieved by hitting Pomerium's `/.well-known/pomerium/jwks.json` endpoint which lives on the authenticate service. Otherwise, the endpoint will return an empty keyset.
|
||||
|
||||
For example, assuming you have [generated an ES256 key](https://github.com/pomerium/pomerium/blob/master/scripts/generate_self_signed_signing_key.sh) as follows.
|
||||
|
||||
```bash
|
||||
# Generates an P-256 (ES256) signing key
|
||||
openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
|
||||
# careful! this will output your private key in terminal
|
||||
cat ec_private.pem | base64
|
||||
```
|
||||
|
||||
That signing key can be accessed via the well-known jwks endpoint.
|
||||
|
||||
```bash
|
||||
$ curl https://authenticate.int.example.com/.well-known/pomerium/jwks.json | jq
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": [
|
||||
{
|
||||
"use": "sig",
|
||||
"kty": "EC",
|
||||
"kid": "ccc5bc9d835ff3c8f7075ed4a7510159cf440fd7bf7b517b5caeb1fa419ee6a1",
|
||||
"crv": "P-256",
|
||||
"alg": "ES256",
|
||||
"x": "QCN7adG2AmIK3UdHJvVJkldsUc6XeBRz83Z4rXX8Va4",
|
||||
"y": "PI95b-ary66nrvA55TpaiWADq8b3O1CYIbvjqIHpXCY"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If no certificate is specified, one will be generated and the base64'd public key will be added to the logs. Note, however, that this key be unique to each service, ephemeral, and will not be accessible via the authenticate service's `jwks_uri` endpoint.
|
||||
|
||||
#### Signing Key Algorithm
|
||||
|
||||
This setting specifies which signing algorithm to use when signing the upstream attestation JWT. Cryptographic algorithm choice is subtle, and beyond the scope of this document, but we suggest sticking to the default `ES256` unless you have a good reason to use something else.
|
||||
|
||||
Be aware that any RSA based signature method may be an order of magnitude lower than [elliptic curve] variants like ECDSA (`ES256`). For more information, checkout [this article](https://www.scottbrady91.com/JOSE/JWTs-Which-Signing-Algorithm-Should-I-Use).
|
||||
|
||||
### Proxy
|
||||
|
||||
|
||||
#### Certificate Authority
|
||||
|
||||
Certificate Authority is set when behind-the-ingress service communication uses custom or self-signed certificates.
|
||||
|
||||
:::warning
|
||||
|
||||
Be sure to include the intermediary certificate.
|
||||
|
||||
:::
|
||||
|
||||
#### Default Upstream Timeout
|
||||
|
||||
Default Upstream Timeout is the default timeout applied to a proxied route when no `timeout` key is specified by the policy.
|
||||
|
||||
#### JWT Claim Headers
|
||||
|
||||
The JWT Claim Headers setting allows you to pass specific user session data down to upstream applications as HTTP request headers. Note, unlike the header `x-pomerium-jwt-assertion` these values are not signed by the authorization service.
|
||||
|
||||
Any claim in the pomerium session JWT can be placed into a corresponding header for upstream consumption. This claim information is sourced from your Identity Provider (IdP) and Pomerium's own session metadata. The header will have the following format:
|
||||
|
||||
`X-Pomerium-Claim-{Name}` where `{Name}` is the name of the claim requested.
|
||||
|
||||
This option also supports a nested object to customize the header name. For example:
|
||||
|
||||
```yaml
|
||||
jwt_claims_headers:
|
||||
X-Email: email
|
||||
```
|
||||
|
||||
Will add an `X-Email` header with a value of the `email` claim.
|
||||
|
||||
Use this option if you previously relied on `x-pomerium-authenticated-user-{email|user-id|groups}`.
|
||||
|
||||
#### Override Certificate Name
|
||||
|
||||
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.
|
||||
|
||||
#### Refresh Cooldown
|
||||
|
||||
Refresh cooldown is the minimum amount of time between allowed manually refreshed sessions.
|
||||
|
||||
#### X-Forward-For HTTP Header
|
||||
|
||||
Do not append proxy IP address to `x-forwarded-for` HTTP header. See [Envoy](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=skip_xff_append#x-forwarded-for) docs for more detail.
|
||||
|
||||
#### Response Headers
|
||||
|
||||
Set Response Headers allows you to set static values for the given response headers. These headers will take precedence over the global `set_response_headers`.
|
||||
|
||||
## Service Accounts
|
||||
|
||||
See [Concepts: Service Accounts][service-accounts-concept].
|
||||
|
||||
|
||||
## Namespaces
|
||||
|
||||
A [Namespace][namespace-concept] is a collection of users, groups, routes, and policies that allows system administrators to organize, manage, and delegate permissions across their infrastructure.
|
||||
|
||||
- Policies can be optional or enforced on a Namespace.
|
||||
- Enforced policies are also enforced on child Namespaces, and optional policies are available to them as well.
|
||||
- Users or groups can be granted permission to edit access to routes within a Namespace, allowing them self-serve access to the routes critical to their work.
|
||||
|
||||
::: tip
|
||||
When using an IdP without directory sync or when working with non-domain users, they will not show up in the look-ahead search. See [Non-Domain Users](/enterprise/concepts.html#non-domain-users) for more information.
|
||||
:::
|
||||
|
||||
|
||||
[route-concept]: /enterprise/concepts.md#routes
|
||||
[route-reference]: /enterprise/reference/manage.md#routes
|
||||
[namespace-concept]: /enterprise/concepts.md#namespaces
|
||||
[namespace-reference]: /enterprise/reference/configure.md#namespaces
|
||||
[service-accounts-concept]: /enterprise/concepts.md#service-accounts
|
||||
[policy-reference]: /enterprise/reference/manage.md#policies-2
|
||||
1
docs/enterprise/reference/img
Symbolic link
1
docs/enterprise/reference/img
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
../../reference/img
|
||||
376
docs/enterprise/reference/manage.md
Normal file
376
docs/enterprise/reference/manage.md
Normal file
|
|
@ -0,0 +1,376 @@
|
|||
---
|
||||
title: Manage
|
||||
lang: en-US
|
||||
sidebarDepth: 2
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
# Manage
|
||||
|
||||
## Routes
|
||||
|
||||
A Route defines how to access a service running behind Pomerium. This includes authentication (both for Pomerium and passed through to the service), rewrites, header management, load balancing, etc.
|
||||
|
||||
|
||||
### General
|
||||
|
||||
The **General** tab defines the route path, both from the internet and to the internal service, and the policies attached. Note that policies enforced on a [Namespace][namespace-reference] the route resides in will also be applied.
|
||||
|
||||
|
||||
#### Name
|
||||
|
||||
This value is only visible in the Console UI.
|
||||
|
||||
#### From
|
||||
|
||||
`From` is the externally accessible URL for the proxied request.
|
||||
|
||||
Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
|
||||
|
||||
:::warning
|
||||
|
||||
Only secure schemes (`https` and `tcp+https`) are supported.
|
||||
|
||||
:::
|
||||
|
||||
#### To
|
||||
|
||||
`To` is the destination(s) of a proxied request. It can be an internal resource, or an external resource. Multiple upstream resources can be targeted by using a list instead of a single URL:
|
||||
|
||||
```yaml
|
||||
- from: https://example.com
|
||||
to:
|
||||
- https://a.example.com
|
||||
- https://b.example.com
|
||||
```
|
||||
|
||||
A load balancing weight may be associated with a particular upstream by appending `,[weight]` to the URL. The exact behavior depends on your [`lb_policy`](/reference/readme.md#load-balancing-policy) setting. See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.md#load-balancing-weight).
|
||||
|
||||
Must be `tcp` if `from` is `tcp+https`.
|
||||
|
||||
:::warning
|
||||
|
||||
Be careful with trailing slash.
|
||||
|
||||
With rule:
|
||||
|
||||
```yaml
|
||||
- from: https://verify.corp.example.com
|
||||
to: https://verify.pomerium.com/anything
|
||||
```
|
||||
|
||||
Requests to `https://verify.corp.example.com` will be forwarded to `https://verify.pomerium.com/anything`, while requests to `https://verify.corp.example.com/foo` will be forwarded to `https://verify.pomerium.com/anythingfoo`.To make the request forwarded to `https://httbin.org/anything/foo`, you can use double slashes in your request `https://httbin.corp.example.com//foo`.
|
||||
|
||||
While the rule:
|
||||
|
||||
```yaml
|
||||
- from: https://verify.corp.example.com
|
||||
to: https://verify.pomerium.com/anything/
|
||||
```
|
||||
|
||||
All requests to `https://verify.corp.example.com/*` will be forwarded to `https://verify.pomerium.com/anything/*`. That means accessing to `https://verify.corp.example.com` will be forwarded to `https://verify.pomerium.com/anything/`. That said, if your application does not handle trailing slash, the request will end up with 404 not found.
|
||||
|
||||
Either `redirect` or `to` must be set.
|
||||
|
||||
:::
|
||||
|
||||
#### Redirect
|
||||
|
||||
`Redirect` is used to redirect incoming requests to a new URL. The `redirect` field is an object with several possible
|
||||
options:
|
||||
|
||||
- `https_redirect` (boolean): the incoming scheme will be swapped with "https".
|
||||
- `scheme_redirect` (string): the incoming scheme will be swapped with the given value.
|
||||
- `host_redirect` (string): the incoming host will be swapped with the given value.
|
||||
- `port_redirect` (integer): the incoming port will be swapped with the given value.
|
||||
- `path_redirect` (string): the incoming path portion of the URL will be swapped with the given value.
|
||||
- `prefix_rewrite` (string): the incoming matched prefix will be swapped with the given value.
|
||||
- `response_code` (integer): the response code to use for the redirect. Defaults to 301.
|
||||
- `strip_query` (boolean): indicates that during redirection, the query portion of the URL will be removed. Defaults to false.
|
||||
|
||||
Either `redirect` or `to` must be set.
|
||||
|
||||
#### Pass Identity Headers
|
||||
|
||||
When enabled, this option will pass identity headers to upstream applications. These headers include:
|
||||
|
||||
- X-Pomerium-Jwt-Assertion
|
||||
- X-Pomerium-Claim-*
|
||||
|
||||
#### Policies
|
||||
|
||||
Add or remove Policies to be applied to the Route. Note that Policies enforced in the Route's Namespace will be applied automatically.
|
||||
|
||||
#### Enable Google Cloud Serverless Authentication
|
||||
|
||||
Enable sending a signed [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) to upstream GCP services.
|
||||
|
||||
Requires setting [Google Cloud Serverless Authentication Service Account](/reference/readme.md#google-cloud-serverless-authentication-service-account) or running Pomerium in an environment with a GCP service account present in default locations.
|
||||
|
||||
### Matchers
|
||||
|
||||
|
||||
#### Path
|
||||
|
||||
If set, the route will only match incoming requests with a path that is an exact match for the specified path.
|
||||
|
||||
#### Prefix
|
||||
|
||||
If set, the route will only match incoming requests with a path that begins with the specified prefix.
|
||||
|
||||
#### Regex
|
||||
|
||||
If set, the route will only match incoming requests with a path that matches the specified regular expression. The supported syntax is the same as the Go [regexp package](https://golang.org/pkg/regexp/) which is based on [re2](https://github.com/google/re2/wiki/Syntax).
|
||||
|
||||
### Rewrite
|
||||
|
||||
|
||||
#### Prefix Rewrite
|
||||
|
||||
If set, indicates that during forwarding, the matched prefix (or path) should be swapped with this value.
|
||||
For example, given this policy:
|
||||
|
||||
```yaml
|
||||
from: https://from.example.com
|
||||
to: https://to.example.com
|
||||
prefix: /admin
|
||||
prefix_rewrite: /
|
||||
```
|
||||
|
||||
A request to `https://from.example.com/admin` would be forwarded to `https://to.example.com/`.
|
||||
|
||||
#### Regex Rewrite Pattern
|
||||
|
||||
The pattern to match before rewriting, ex: `^/service/([^/]+)(/.*)$`.
|
||||
|
||||
|
||||
#### Regex Rewrite Substitution
|
||||
|
||||
The substitution for your regex pattern, ex: `\\2/instance/\\1`.
|
||||
|
||||
|
||||
### Timeouts
|
||||
|
||||
|
||||
#### Allow Websockets
|
||||
|
||||
If set, enables proxying of websocket connections.
|
||||
|
||||
:::warning
|
||||
|
||||
**Use with caution:** websockets are long-lived connections, so [global timeouts](/reference/readme.md#global-timeouts) are not enforced (though the policy-specific `timeout` is enforced). Allowing websocket connections to the proxy could result in abuse via [DOS attacks](https://www.cloudflare.com/learning/ddos/ddos-attack-tools/slowloris/).
|
||||
|
||||
:::
|
||||
|
||||
#### Timeout
|
||||
|
||||
Policy timeout establishes the per-route timeout value. Cannot exceed global timeout values.
|
||||
|
||||
#### Idle Timeout
|
||||
|
||||
If you are proxying long-lived requests that employ streaming calls such as websockets or gRPC,
|
||||
set this to either a maximum value there may be no data exchange over a connection (recommended),
|
||||
or set it to unlimited (`0s`). If `idle_timeout` is specified, and `timeout` is not
|
||||
explicitly set, then `timeout` would be unlimited (`0s`). You still may specify maximum lifetime
|
||||
of the connection using `timeout` value (i.e. to 1 day).
|
||||
|
||||
### Headers
|
||||
|
||||
|
||||
#### Host Headers
|
||||
|
||||
The `host` header can be preserved via the `preserve_host_header` setting or customized via 3 mutually exclusive options:
|
||||
|
||||
1. `preserve_host_header` when enabled, this option will pass the host header from the incoming request to the proxied host, instead of the destination hostname. It's an optional parameter of type `bool` that defaults to `false`.
|
||||
See [ProxyPreserveHost](http://httpd.apache.org/docs/2.0/mod/mod_proxy.html#proxypreservehost).
|
||||
2. `host_rewrite` which will rewrite the host to a new literal value.
|
||||
3. `host_rewrite_header` which will rewrite the host to match an incoming header value.
|
||||
4. `host_path_regex_rewrite_pattern`, `host_path_regex_rewrite_substitution` which will rewrite the host according to a regex matching the path. For example with the following config:
|
||||
|
||||
```yaml
|
||||
host_path_regex_rewrite_pattern: "^/(.+)/.+$"
|
||||
host_path_regex_rewrite_substitution: \1
|
||||
```
|
||||
|
||||
Would rewrite the host header to `example.com` given the path `/example.com/some/path`.
|
||||
|
||||
The 2nd, 3rd and 4th options correspond to the envoy route action host related options, which can be found [here](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-routeaction).
|
||||
|
||||
#### Set Request Headers
|
||||
|
||||
Set Request Headers allows you to set static values for given request headers. This can be useful if you want to pass along additional information to downstream applications as headers, or set authentication header to the request. For example:
|
||||
|
||||
```yaml
|
||||
- from: https://verify.corp.example.com
|
||||
to: https://verify.pomerium.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
set_request_headers:
|
||||
# works auto-magically!
|
||||
# https://verify.corp.example.com/basic-auth/root/hunter42
|
||||
Authorization: Basic cm9vdDpodW50ZXI0Mg==
|
||||
X-Your-favorite-authenticating-Proxy: "Pomerium"
|
||||
```
|
||||
|
||||
#### Remove Request Headers
|
||||
|
||||
Remove Request Headers allows you to remove given request headers. This can be useful if you want to prevent privacy information from being passed to downstream applications. For example:
|
||||
|
||||
```yaml
|
||||
- from: https://verify.corp.example.com
|
||||
to: https://verify.pomerium.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
remove_request_headers:
|
||||
- X-Email
|
||||
- X-Username
|
||||
```
|
||||
|
||||
#### Rewrite Response Headers
|
||||
|
||||
Rewrite Response Headers allows you to modify response headers before they are returned to the client. The `header` field will match the HTTP header name, and `prefix` will be replaced with `value`. For example, if the downstream server returns a header:
|
||||
|
||||
```text
|
||||
Location: http://localhost:8000/two/some/path/
|
||||
```
|
||||
|
||||
And the policy has this config:
|
||||
|
||||
```yaml
|
||||
rewrite_response_headers:
|
||||
- header: Location
|
||||
prefix: http://localhost:8000/two/
|
||||
value: http://frontend/one/
|
||||
```
|
||||
|
||||
The browser would be redirected to: `http://frontend/one/some/path/`. This is similar to nginx's [`proxy_redirect` option](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect), but can be used for any header.
|
||||
|
||||
### Load Balancer
|
||||
|
||||
|
||||
#### Load Balancing Policy
|
||||
|
||||
In presence of multiple upstreams, defines load balancing strategy between them.
|
||||
|
||||
See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-enum-config-cluster-v3-cluster-lbpolicy) for more details.
|
||||
|
||||
- [`ROUND_ROBIN`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#weighted-round-robin) (default)
|
||||
- [`LEAST_REQUEST`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#weighted-least-request) and may be further configured using [`least_request_lb_config`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-msg-config-cluster-v3-cluster-leastrequestlbconfig)
|
||||
- [`RING_HASH`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#ring-hash) and may be further configured using [`ring_hash_lb_config`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#config-cluster-v3-cluster-ringhashlbconfig) option
|
||||
- [`RANDOM`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#random)
|
||||
- [`MAGLEV`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#maglev) and may be further configured using [`maglev_lb_config`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-msg-config-cluster-v3-cluster-maglevlbconfig) option
|
||||
|
||||
Some policy types support additional [configuration](/reference/readme.md#load-balancing-policy-config).
|
||||
|
||||
## Policies
|
||||
|
||||
A Policy defines what permissions a set of users or groups has. Policies are applied to Namespaces or Routes to associate the set of permissions with a service or set of service, completing the authentication model.
|
||||
|
||||
Policies can be constructed three ways:
|
||||
|
||||
### Web UI
|
||||
|
||||
From the **BUILDER** tab, users can add allow or deny blocks to a policy, containing and/or/not/nor logic to allow or deny sets of users and groups.
|
||||
|
||||
|
||||
|
||||
### Pomerium Policy Language
|
||||
|
||||
From the **EDITOR** tab users can write policies in Pomerium Policy Language (**PPL**), a YAML-based notation.
|
||||
|
||||
|
||||
|
||||
PPL documents contain one or more rules. Each rule has a corresponding action and one or more logical operators.
|
||||
Each logical operator contains criteria and each criterion has a name and corresponding data.
|
||||
|
||||
PPL documents are defined via YAML:
|
||||
|
||||
```yaml
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: x@example.com
|
||||
- email:
|
||||
is: y@example.com
|
||||
```
|
||||
|
||||
The available rule actions are:
|
||||
|
||||
- `allow`
|
||||
- `deny`
|
||||
|
||||
The available logical operators are:
|
||||
|
||||
- `and`
|
||||
- `or`
|
||||
- `not`
|
||||
- `nor`
|
||||
|
||||
The available criteria types are:
|
||||
|
||||
- `accept`
|
||||
- `authenticated_user`
|
||||
- `claim`
|
||||
- `date`
|
||||
- `day_of_week`
|
||||
- `domain`
|
||||
- `email`
|
||||
- `groups`
|
||||
- `reject`
|
||||
- `time_of_day`
|
||||
- `user`
|
||||
|
||||
Some criteria also support a sub-path as part of the criterion name:
|
||||
|
||||
```yaml
|
||||
- allow:
|
||||
or:
|
||||
- claim/family_name:
|
||||
is: Smith
|
||||
```
|
||||
|
||||
### Rego
|
||||
|
||||
For those using [OPA](https://www.openpolicyagent.org/), the **REGO** tab will accept policies written in Rego.
|
||||
|
||||
::: tip
|
||||
A policy can only support PPL or Rego. Once one is set, the other tab is disabled.
|
||||
:::
|
||||
|
||||
### Overrides
|
||||
|
||||
- **Any Authenticated User**: This setting will allow access to a route with this policy attached to any user who can authenticate to your Identity Provider (**IdP**).
|
||||
- **CORS Preflight**:
|
||||
- **Public Access**: This setting allows complete, unrestricted access to an associated route. Use this setting with caution.
|
||||
|
||||
|
||||
## Certificates
|
||||
|
||||
Certificates are the x509 _public-key_ and _private-key_ used to establish secure HTTP and gRPC connections. Any combination of the above can be used together, and are additive. You can also use any of these settings in conjunction with `Autocert` to get OCSP stapling.
|
||||
|
||||
For example, if specifying multiple certificates at once:
|
||||
|
||||
```yaml
|
||||
certificates:
|
||||
- cert: "$HOME/.acme.sh/authenticate.example.com_ecc/fullchain.cer"
|
||||
key: "$HOME/.acme.sh/authenticate.example.com_ecc/authenticate.example.com.key"
|
||||
- cert: "$HOME/.acme.sh/verify.example.com_ecc/fullchain.cer"
|
||||
key: "$HOME/.acme.sh/verify.example.com_ecc/verify.example.com.key"
|
||||
- cert: "$HOME/.acme.sh/prometheus.example.com_ecc/fullchain.cer"
|
||||
key: "$HOME/.acme.sh/prometheus.example.com_ecc/prometheus.example.com.key"
|
||||
```
|
||||
|
||||
[route-concept]: /enterprise/concepts.md#routes
|
||||
[route-reference]: /enterprise/reference/manage.md#routes
|
||||
[namespace-concept]: /enterprise/concepts.md#namespaces
|
||||
[namespace-reference]: /enterprise/reference/configure.md#namespaces
|
||||
[service-accounts-concept]: /enterprise/concepts.md#service-accounts
|
||||
[policy-reference]: /enterprise/reference/manage.md#policies-2
|
||||
58
docs/enterprise/reference/reports.md
Normal file
58
docs/enterprise/reference/reports.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
title: Reports
|
||||
lang: en-US
|
||||
sidebarDepth: 2
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
# Reports
|
||||
|
||||
## Traffic
|
||||
|
||||
View the traffic running through Pomerium. Filter by [Route][route-concept] name, or date range.
|
||||
|
||||
|
||||
|
||||
|
||||
## Runtime
|
||||
|
||||
Monitor how many system resources Pomerium is consuming. Filter by date range, service, and instance.
|
||||
|
||||
|
||||
|
||||
|
||||
## Sessions
|
||||
|
||||
View active Sessions. From here you can revoke sessions, filter by session or user information, or revoke one or multiple sessions. You can also export the data.
|
||||
|
||||
|
||||
|
||||
|
||||
## Events
|
||||
|
||||
The events page displays the log output of Envoy as it process changes from Pomerium and applies updates to the underlying services.
|
||||
|
||||
|
||||
|
||||
The most common updates are to Pomerium Proxy services, which are updated every time a Route or Policy is created or updated.
|
||||
|
||||
The value under **Resource ID** will usually match the resource ID of a [Policy][policy-reference], visible in the Policy under **Change History** or in the URL. A value of "Pomerium Restarted" refers to when services are reloaded, usually due to a system update.
|
||||
|
||||
|
||||
## Deployments
|
||||
|
||||
From the **Deployment History** page administrators can review changes made to their Pomerium configuration.
|
||||
|
||||
The default view shows all changes made through the Pomerium Enterprise Console. Use the **COMPARE** button next to an entry to filter to only changes that affected that resource. Select two versions of that resource, then **DIFF** to see what changed:
|
||||
|
||||
|
||||
|
||||
|
||||
[route-concept]: /enterprise/concepts.md#routes
|
||||
[route-reference]: /enterprise/reference/manage.md#routes
|
||||
[namespace-concept]: /enterprise/concepts.md#namespaces
|
||||
[namespace-reference]: /enterprise/reference/configure.md#namespaces
|
||||
[service-accounts-concept]: /enterprise/concepts.md#service-accounts
|
||||
[policy-reference]: /enterprise/reference/manage.md#policies-2
|
||||
|
|
@ -33,8 +33,11 @@ This guide assumes you have already completed one of the [quick start] guides, a
|
|||
# config.yaml
|
||||
- from: https://adguard.domain.example
|
||||
to: http://adguard
|
||||
allowed_users:
|
||||
- user@example.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: user@example.com
|
||||
set_request_headers:
|
||||
# https://www.blitter.se/utils/basic-authentication-header-generator/
|
||||
Authorization: Basic dXNlcjpwYXNzd29yZA===
|
||||
|
|
|
|||
|
|
@ -64,15 +64,18 @@ helm install --namespace kube-system ingress-nginx ingress-nginx/ingress-nginx
|
|||
|
||||
## Install Pomerium
|
||||
|
||||
Like with Argo we will install Pomerium using the [Helm chart](https://github.com/pomerium/pomerium-helm). First create a `values.yaml` file (replacing the `allowed_users` and IDP `provider`/`clientID`/`clientSecret` with your own):
|
||||
Like with Argo we will install Pomerium using the [Helm chart](https://github.com/pomerium/pomerium-helm). First create a `values.yaml` file (replacing the `email.is` and IDP `provider`/`clientID`/`clientSecret` with your own):
|
||||
|
||||
```yaml
|
||||
config:
|
||||
policy:
|
||||
routes:
|
||||
- from: https://argo.localhost.pomerium.io
|
||||
to: http://argo-server.kube-system.svc.cluster.local:2746
|
||||
allowed_users:
|
||||
- REPLACE_ME
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
|
||||
authenticate:
|
||||
idp:
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ This guide covers using Pomerium to secure an instance of [code-server]. Pomeriu
|
|||
|
||||
[Visual Studio Code] is an open source code editor by Microsoft that has become [incredibly popular](https://insights.stackoverflow.com/survey/2019#technology-_-most-popular-development-environments) in the last few years. For many developers, [Visual Studio Code] hits the sweet spot between no frills editors like vim/emacs and full feature IDE's like Eclipse and IntelliJ. VS Code offers some of the creature comforts like intellisense, git integration, and plugins, while staying relatively lightweight.
|
||||
|
||||
One of the interesting attributes of [Visual Studio Code] is that it is built on the [Electron](<https://en.wikipedia.org/wiki/Electron_(software_framework)>) framework which uses a headless instance of Chrome rendered as a desktop application. It didn't take long for folks to realize that if we already had this great IDE written in Javascript, it may be possible to make [Visual Studio Code] run remotely.
|
||||
One of the interesting attributes of [Visual Studio Code] is that it is built on the [Electron](https://en.wikipedia.org/wiki/Electron_(software_framework)) framework which uses a headless instance of Chrome rendered as a desktop application. It didn't take long for folks to realize that if we already had this great IDE written in Javascript, it may be possible to make [Visual Studio Code] run remotely.
|
||||
|
||||
> "Any application that can be written in JavaScript, will eventually be written in JavaScript." -- [Jeff Atwood](https://blog.codinghorror.com/the-principle-of-least-power/)
|
||||
|
||||
|
|
@ -33,7 +33,7 @@ One of the interesting attributes of [Visual Studio Code] is that it is built on
|
|||
|
||||
## Pre-requisites
|
||||
|
||||
This guide assumes you have already completed one of the [quick start] guides, and have a working instance of Pomerium up and running. For purpose of this guide, I'm going to use docker-compose, though any other deployment method would work equally well.
|
||||
This guide assumes you have already completed one of the [install] guides, and have a working instance of Pomerium up and running. For purpose of this guide, I'm going to use docker-compose, though any other deployment method would work equally well.
|
||||
|
||||
## Configure
|
||||
|
||||
|
|
@ -41,19 +41,23 @@ This guide assumes you have already completed one of the [quick start] guides, a
|
|||
|
||||
```
|
||||
# config.yaml
|
||||
# See detailed configuration settings : https://www.pomerium.io/docs/reference/reference/
|
||||
# See detailed configuration settings : https://www.pomerium.com/docs/reference/
|
||||
|
||||
authenticate_service_url: https://authenticate.corp.domain.example
|
||||
|
||||
# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
|
||||
# identity provider settings : https://www.pomerium.com/docs/identity-providers.html
|
||||
idp_provider: google
|
||||
idp_client_id: REPLACE_ME
|
||||
idp_client_secret: REPLACE_ME
|
||||
|
||||
policy:
|
||||
routes:
|
||||
- from: https://code.corp.domain.example
|
||||
to: http://codeserver:8080
|
||||
allowed_users:
|
||||
- some.user@domain.example
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: user@example.com
|
||||
allow_websockets: true
|
||||
```
|
||||
|
||||
|
|
@ -129,7 +133,7 @@ When the code-server container is rebuilt, any files outside of `/home/coder/pro
|
|||
|
||||
[integrated terminal]: https://code.visualstudio.com/docs/editor/integrated-terminal
|
||||
[path]: https://en.wikipedia.org/wiki/PATH_(variable)
|
||||
[quick start]: ../docs/quick-start
|
||||
[synology nas]: ./synology.md
|
||||
[install]: /docs/install/readme.md
|
||||
[synology nas]: /guides/synology.md
|
||||
[visual studio code]: https://code.visualstudio.com/
|
||||
[code-server]: https://github.com/cdr/code-server
|
||||
|
|
|
|||
|
|
@ -226,7 +226,8 @@ We can retrieve the token to add to our proxied policy's authorization header as
|
|||
$ kubectl describe secret helm-dashboard
|
||||
```
|
||||
|
||||
```Name: dashboard-kubernetes-dashboard-token-bv9jq
|
||||
```bash
|
||||
Name: dashboard-kubernetes-dashboard-token-bv9jq
|
||||
Namespace: default
|
||||
Labels: <none>
|
||||
Annotations: kubernetes.io/service-account.name: dashboard-kubernetes-dashboard
|
||||
|
|
@ -259,12 +260,15 @@ config:
|
|||
sharedSecret: YOUR_SHARED_SECRET
|
||||
cookieSecret: YOUR_COOKIE_SECRET
|
||||
|
||||
policy:
|
||||
routes:
|
||||
# this route is directly proxied by pomerium & injects the authorization header
|
||||
- from: https://dashboard-proxied.domain.example
|
||||
to: https://helm-dashboard-kubernetes-dashboard
|
||||
allowed_users:
|
||||
- user@domain.example
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: user@domain.example
|
||||
tls_skip_verify: true # dashboard uses self-signed certificates in its default configuration
|
||||
set_request_headers:
|
||||
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.....
|
||||
|
|
@ -272,8 +276,11 @@ config:
|
|||
# this route is indirectly checked for access using forward-auth
|
||||
- from: https://dashboard-forwardauth.domain.example
|
||||
to: https://helm-dashboard-kubernetes-dashboard
|
||||
allowed_users:
|
||||
- user@domain.example
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: user@domain.example
|
||||
ingress:
|
||||
annotations:
|
||||
kubernetes.io/ingress.class: "nginx"
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ description: >-
|
|||
|
||||
# Local OIDC Provider
|
||||
|
||||
You can use the same below configs for other supported [identity providers](/docs/identity-providers).
|
||||
You can use the same below configs for other supported [identity providers](/docs/identity-providers/readme.md).
|
||||
|
||||
## Configure
|
||||
### Docker-compose
|
||||
|
|
@ -24,10 +24,11 @@ services:
|
|||
# Generate new secret keys. e.g. `head -c32 /dev/urandom | base64`
|
||||
- COOKIE_SECRET=<reducted>
|
||||
volumes:
|
||||
# Mount your domain's certificates : https://www.pomerium.io/docs/reference/certificates
|
||||
# Mount your domain's certificates : https://www.pomerium.com/docs/reference/certificates
|
||||
- ./_wildcard.localhost.pomerium.io-key.pem:/pomerium/privkey.pem:ro
|
||||
- ./_wildcard.localhost.pomerium.io.pem:/pomerium/cert.pem:ro
|
||||
# Mount your config file : https://www.pomerium.io/docs/reference/reference/
|
||||
# Mount your config file : https://www.pomerium.com/docs/reference/
|
||||
|
||||
- ./config.yaml:/pomerium/config.yaml
|
||||
ports:
|
||||
- 443:443
|
||||
|
|
@ -53,13 +54,14 @@ services:
|
|||
- 9000:9000
|
||||
```
|
||||
|
||||
You can generate certificates for `*.localhost.pomerium.io` using [this instruction](https://www.pomerium.io/docs/reference/certificates.html#certificates-2)
|
||||
You can generate certificates for `*.localhost.pomerium.io` using [this instruction](/docs/topics/certificates.md#certificates-2)
|
||||
|
||||
### Pomerium config
|
||||
|
||||
```yaml
|
||||
# config.yaml
|
||||
# See detailed configuration settings : https://www.pomerium.io/docs/reference/reference/
|
||||
# See detailed configuration settings : https://www.pomerium.com/docs/reference/
|
||||
|
||||
authenticate_service_url: https://authenticate.localhost.pomerium.io
|
||||
|
||||
autocert: false
|
||||
|
|
@ -151,5 +153,5 @@ $ docker-compose up -d
|
|||
|
||||
Now accessing to `https://verify.localhost.pomerium.io` and you will be redireted to OIDC server for authentication.
|
||||
|
||||
[identity provider]: ../docs/identity-providers/
|
||||
[identity provider]: ../docs/identity-providers/readme.md
|
||||
[qlik/simple-oidc-provider]: https://hub.docker.com/r/qlik/simple-oidc-provider/
|
||||
|
|
|
|||
|
|
@ -104,16 +104,19 @@ We'll also need a test application to manage access to. For this guide we'll use
|
|||
|
||||
|
||||
|
||||
### Policy
|
||||
### Route
|
||||
|
||||
We will create an extremely basic policy where `httpbin.int.nas.example` is replaced with the subdomain you want to use for the httpbin service, and `your.email.address@gmail.com` is replaced with your email address. All other users will be denied, and all other routes will be `404`.
|
||||
We will create an extremely basic route where `httpbin.int.nas.example` is replaced with the subdomain you want to use for the httpbin service, and `your.email.address@gmail.com` is replaced with your email address. All other users will be denied, and all other routes will be `404`.
|
||||
|
||||
```yaml
|
||||
# policy.yaml
|
||||
# route.yaml
|
||||
- from: https://httpbin.int.nas.example
|
||||
to: http://httpbin
|
||||
allowed_users:
|
||||
- your.email.address@gmail.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: your.email.address@gmail.com
|
||||
```
|
||||
|
||||
### Configure
|
||||
|
|
@ -215,12 +218,12 @@ And just to be safe, try logging in from another google account to see what happ
|
|||
|
||||
|
||||
|
||||
[certificate documentation]: ../topics/certificates.md
|
||||
[configuration variable docs]: ../../reference/readme.md
|
||||
[certificate documentation]: /docs/topics/certificates.md
|
||||
[configuration variable docs]: /reference/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
|
||||
[identity provider]: ../identity-providers/readme.md
|
||||
[identity provider]: /docs/identity-providers/readme.md
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[nginx]: https://www.nginx.com
|
||||
[self-hosted apps]: https://github.com/Kickball/awesome-selfhosted
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ description: >-
|
|||
|
||||
# Securing TCP based services
|
||||
|
||||
The following guide demonstrates how to use Pomerium's [TCP Proxying](/topics/tcp-support.md) support with various TCP services such as databases and other non-HTTP protocols. It also covers integration points with them when possible.
|
||||
The following guide demonstrates how to use Pomerium's [TCP Proxying](/docs/topics/tcp-support.md) support with various TCP services such as databases and other non-HTTP protocols. It also covers integration points with them when possible.
|
||||
|
||||
The source files from this guide can be found on [GitHub](https://github.com/pomerium/pomerium/tree/master/examples/tcp/).
|
||||
|
||||
|
|
@ -25,7 +25,7 @@ Important notes:
|
|||
|
||||
## How it works
|
||||
|
||||
* Create a standard Pomerium configuration for your [identity provider (IdP)](/docs/identity-providers/)
|
||||
* Create a standard Pomerium configuration for your [identity provider (IdP)](/docs/identity-providers/readme.md)
|
||||
* `pomerium-cli` runs on your workstation, listening on loopback for TCP connections
|
||||
* When an inbound connection is made, `pomerium-cli` proxies the connection through `pomerium`, authenticating the user if needed
|
||||
* Pomerium authorizes the connection and forwards it to the upstream service
|
||||
|
|
@ -39,7 +39,7 @@ This recipe is designed to run on a local docker-compose instance. The included
|
|||
* docker-compose
|
||||
* A copy of the [example repo](https://github.com/pomerium/pomerium/tree/master/examples/tcp/) checked out
|
||||
* Valid credentials for your OIDC provider
|
||||
* The [Pomerium Client](/docs/installation.md#pomerium-cli) installed
|
||||
* The [Pomerium Client](/docs/releases.md#pomerium-cli) installed
|
||||
* (Optional) `mkcert` to generate locally trusted certificates
|
||||
|
||||
## Certificates (optional)
|
||||
|
|
@ -82,7 +82,7 @@ Included in our compose file:
|
|||
|
||||
## Connect
|
||||
|
||||
To connect to your service, ensure [`pomerium-cli`](/docs/installation.md#pomerium-cli) is in your `$PATH` and run the `tcp` command, specifying the service you wish to reach.
|
||||
To connect to your service, ensure [`pomerium-cli`](/docs/releases.md#pomerium-cli) is in your `$PATH` and run the `tcp` command, specifying the service you wish to reach.
|
||||
|
||||
```bash
|
||||
pomerium-cli tcp [hostname]:[port]
|
||||
|
|
|
|||
|
|
@ -38,9 +38,13 @@ jwt_claims_headers: email
|
|||
policy:
|
||||
- from: https://wiki.example.local
|
||||
to: http://tiddlywiki:8080
|
||||
allowed_users:
|
||||
- reader1@example.com
|
||||
- writer1@example.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: reader1@example.com
|
||||
- email:
|
||||
is: writer1@example.com
|
||||
```
|
||||
### Docker-compose
|
||||
|
||||
|
|
@ -56,4 +60,4 @@ Navigate to your TiddlyWiki instance (e.g. `https://wiki.example.local`) and log
|
|||
|
||||
* as another email: pomerium displays a permission denied error.
|
||||
|
||||
[quick start]: ../docs/quick-start
|
||||
[quick start]: /docs/install/readme.md
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ While there are software clients available to interact with the daemon over RPC,
|
|||
::: warning
|
||||
Because RPC traffic to and from a Transmission daemon is unencrypted, we strongly suggest you only communicate from Pomerium to Transmission on a trusted private network. Note that some cloud hosting providers differentiate "private networking" (which is visible to all hosts in a data center) from "VLANS" which are only visible to your hosts. While you can configure a local proxy on your Transmission host to provide TLS encryption, that configuration is outside of the scope of this guide.
|
||||
|
||||
Running Pomerium and Transmission on the same host, using [docker](../docs/quick-start) for example, negates this concern.
|
||||
Running Pomerium and Transmission on the same host, using [docker](/docs/install/readme.md) for example, negates this concern.
|
||||
:::
|
||||
|
||||
## Before You Begin
|
||||
|
|
@ -43,10 +43,13 @@ Edit your `config.yaml` file to add the following policy. Note that `<>` denotes
|
|||
policy:
|
||||
- from: https://<transmission.mydomain.com> # Replace with the domain you want to use to access Transmission
|
||||
to: http://<private.ip.address>:9091 # Replace with the private network address of the Transmission host, or `localhost` if running on the same host.
|
||||
allowed_users:
|
||||
- myUser@mydomain.com # Replace with authorized user(s), or remove if using group permissions only.
|
||||
allowed_groups:
|
||||
- <transmission-users> # Replace with authorized user group(s), or remove if using user permissions only.
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: myUser@mydomain.com # Replace with authorized user(s), or remove if using group permissions only.
|
||||
- groups:
|
||||
has: ["<transmission-users>"] # Replace with authorized user group(s), or remove if using user permissions only.
|
||||
```
|
||||
Remember to restart the Pomerium instance after saving your changes.
|
||||
|
||||
|
|
@ -109,4 +112,4 @@ You should now be able to authenticate and access your Transmission daemon remot
|
|||
In addition to the lock symbol in your browser's address bar, you can go to `<transmission.mydomain.com>/.pomerium` to view and confirm your session details.
|
||||
|
||||
[Transmission]: https://transmissionbt.com/
|
||||
[quick start]: ../docs/quick-start
|
||||
[quick start]: /docs/install/readme.md
|
||||
|
|
@ -1,2 +1,7 @@
|
|||
<!-- Simply redirect back to docs! -->
|
||||
<Redirect to="/docs/" />
|
||||
|
||||
|
||||
<!--
|
||||
The docs project is currently only confirmed to work with Node version 14.17.3 (LTS).
|
||||
-->
|
||||
|
|
@ -46,7 +46,7 @@ Address specifies the host and port to serve HTTP requests from. If empty, `:443
|
|||
- Type: `bool`
|
||||
- Optional
|
||||
|
||||
Turning on autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS certificates from [Let's Encrypt][letsencrypt] which includes managed routes and the authenticate service. [Autocert Directory](./#autocert-directory) must be used with Autocert must have a place to persist, and share certificate data between services. Note that autocert also provides [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).
|
||||
Turning on autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS certificates from [Let's Encrypt][letsencrypt] which includes managed routes and the authenticate service. [Autocert Directory](#autocert-directory) must be used with Autocert must have a place to persist, and share certificate data between services. Note that autocert also provides [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).
|
||||
|
||||
This setting can be useful in situations where you may not have Pomerium behind a TLS terminating ingress or proxy that is already handling your public certificates on your behalf.
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ Autocert requires that ports `80`/`443` be accessible from the internet in order
|
|||
- Type: `bool`
|
||||
- Optional
|
||||
|
||||
If true, force autocert to request a certificate with the `status_request` extension (commonly called `Must-Staple`). This allows the TLS client (_id est_ the browser) to fail immediately if the TLS handshake doesn't include OCSP stapling information. This setting is only used when [Autocert](./#autocert) is true.
|
||||
If true, force autocert to request a certificate with the `status_request` extension (commonly called `Must-Staple`). This allows the TLS client (_id est_ the browser) to fail immediately if the TLS handshake doesn't include OCSP stapling information. This setting is only used when [Autocert](#autocert) is true.
|
||||
|
||||
:::tip
|
||||
|
||||
|
|
@ -84,7 +84,7 @@ For more details, please see [RFC7633](https://tools.ietf.org/html/rfc7633) .
|
|||
- Environmental Variable: either `AUTOCERT_DIR`
|
||||
- Config File Key: `autocert_dir`
|
||||
- Type: `string` pointing to the path of the directory
|
||||
- Required if using [Autocert](./#autocert) setting
|
||||
- Required if using [Autocert](#autocert) setting
|
||||
- Default:
|
||||
|
||||
- `/data/autocert` in published Pomerium docker images
|
||||
|
|
@ -339,7 +339,7 @@ services:
|
|||
- Example: `TIMEOUT_READ=30s`
|
||||
- Defaults: `TIMEOUT_READ=30s` `TIMEOUT_WRITE=0` `TIMEOUT_IDLE=5m`
|
||||
|
||||
Timeouts set the global server timeouts. Timeouts can also be set for individual [routes](./#policy).
|
||||
Timeouts set the global server timeouts. Timeouts can also be set for individual [routes](#policy).
|
||||
|
||||
|
||||
|
||||
|
|
@ -710,7 +710,7 @@ Some providers, like Amazon Cognito, _do not_ support the `offline_access` scope
|
|||
- Type: `string`
|
||||
- **Required** for group based policies (most configurations)
|
||||
|
||||
The identity provider service account setting is used to query associated identity information from your identity provider.
|
||||
The identity provider service account setting is used to query associated identity information from your identity provider. This is a provider specific value and is not required for all providers. For example, when using Okta this value will be an Okta API key, and for an OIDC provider that provides groups as a claim, this value will be empty.
|
||||
|
||||
:::warning
|
||||
|
||||
|
|
@ -1049,7 +1049,14 @@ If set, the TLS connection to the storage backend will not be verified.
|
|||
- Environmental Variable: `POLICY`
|
||||
- Config File Key: `policy`
|
||||
- Type: [base64 encoded] `string` or inline policy structure in config file
|
||||
- **Required** However, pomerium will safely start without a policy configured, but will be unable to authorize or proxy traffic until the configuration is updated to contain a policy.
|
||||
- **Deprecated**: This key has been replaced with `route`.
|
||||
|
||||
|
||||
::: warning
|
||||
The `policy` field as a top-level configuration key has been replaced with [`routes`](/reference/readme.md#routes). Moving forward, define policies within each defined route.
|
||||
|
||||
Existing policy definitions will currently behave as expected, but are deprecated and will be removed in a future version of Pomerium.
|
||||
:::
|
||||
|
||||
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,
|
||||
|
||||
|
|
@ -1070,7 +1077,7 @@ policy:
|
|||
|
||||
In this example, an incoming request with a path prefix of `/admin` would be handled by the first route (which is restricted to superusers). All other requests for `from.example.com` would be handled by the second route (which is open to the public).
|
||||
|
||||
A list of policy configuration variables follows.
|
||||
A list of configuration variables specific to `policy` follows Note that this also shares all configuration variables listed under [routes](/reference/readme.md#routes), excluding `policy` and its child variables.
|
||||
|
||||
|
||||
### Allowed Domains
|
||||
|
|
@ -1135,6 +1142,19 @@ Claims are represented as a map of strings to a list of values:
|
|||
Allowed users is a collection of whitelisted users to authorize for a given route.
|
||||
|
||||
|
||||
## Routes
|
||||
- Environment Variable: `ROUTE`
|
||||
- Config File Key: `route`
|
||||
- Type: `string`
|
||||
- **Required** - While Pomerium will start without a route configured, it will not authorize or proxy any traffic until a route is defined. If configuring Pomerium for the Enterprise Console, define a route for the Console itself in Pomerium.
|
||||
|
||||
A route contains specific access and control definitions for a back-end service. Each route is a list item under the `routes` key.
|
||||
|
||||
Each route defines at minimum a `from` and `to` field, and a `policy` key defining authorization logic. Policies are defined using [Pomerium Policy Language](/enterprise/reference/manage.md#pomerium-policy-language) (**PPL**). Additional options are listed below.
|
||||
|
||||
<<< @/examples/config/route.example.yaml
|
||||
|
||||
|
||||
### CORS Preflight
|
||||
- `yaml`/`json` setting: `cors_allow_preflight`
|
||||
- Type: `bool`
|
||||
|
|
@ -1152,7 +1172,7 @@ Allow unauthenticated HTTP OPTIONS requests as [per the CORS spec](https://devel
|
|||
|
||||
Enable sending a signed [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) to upstream GCP services.
|
||||
|
||||
Requires setting [Google Cloud Serverless Authentication Service Account](./#google-cloud-serverless-authentication-service-account) or running Pomerium in an environment with a GCP service account present in default locations.
|
||||
Requires setting [Google Cloud Serverless Authentication Service Account](#google-cloud-serverless-authentication-service-account) or running Pomerium in an environment with a GCP service account present in default locations.
|
||||
|
||||
|
||||
### From
|
||||
|
|
@ -1164,7 +1184,7 @@ Requires setting [Google Cloud Serverless Authentication Service Account](./#goo
|
|||
|
||||
`From` is the externally accessible URL for the proxied request.
|
||||
|
||||
Specifying `tcp+https` for the scheme enables [TCP proxying](../docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
|
||||
Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
|
||||
|
||||
:::warning
|
||||
|
||||
|
|
@ -1341,8 +1361,11 @@ Set Request Headers allows you to set static values for given request headers. T
|
|||
```yaml
|
||||
- from: https://verify.corp.example.com
|
||||
to: https://verify.pomerium.com
|
||||
allowed_users:
|
||||
- bdd@pomerium.io
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
set_request_headers:
|
||||
# works auto-magically!
|
||||
# https://verify.corp.example.com/basic-auth/root/hunter42
|
||||
|
|
@ -1361,8 +1384,11 @@ Remove Request Headers allows you to remove given request headers. This can be u
|
|||
```yaml
|
||||
- from: https://verify.corp.example.com
|
||||
to: https://verify.pomerium.com
|
||||
allowed_users:
|
||||
- bdd@pomerium.io
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
remove_request_headers:
|
||||
- X-Email
|
||||
- X-Username
|
||||
|
|
@ -1438,7 +1464,7 @@ Either `redirect` or `to` must be set.
|
|||
- https://b.example.com
|
||||
```
|
||||
|
||||
A load balancing weight may be associated with a particular upstream by appending `,[weight]` to the URL. The exact behavior depends on your [`lb_policy`](#load-balancing-policy) setting. See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.html#load-balancing-weight).
|
||||
A load balancing weight may be associated with a particular upstream by appending `,[weight]` to the URL. The exact behavior depends on your [`lb_policy`](#load-balancing-policy) setting. See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.md#load-balancing-weight).
|
||||
|
||||
Must be `tcp` if `from` is `tcp+https`.
|
||||
|
||||
|
|
@ -1691,12 +1717,12 @@ Be aware that any RSA based signature method may be an order of magnitude lower
|
|||
[base64 encoded]: https://en.wikipedia.org/wiki/Base64
|
||||
[elliptic curve]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations#Generating_EC_Keys_and_Parameters
|
||||
[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
|
||||
[identity provider]: ../docs/identity-providers/
|
||||
[identity provider]: /docs/identity-providers/readme.md
|
||||
[json]: https://en.wikipedia.org/wiki/JSON
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[oidc rfc]: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
|
||||
[okta]: ../docs/identity-providers/okta.md
|
||||
[okta]: /docs/identity-providers/okta.md
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[signed headers]: ../docs/topics/getting-users-identity.md
|
||||
[signed headers]: /docs/topics/getting-users-identity.md
|
||||
[toml]: https://en.wikipedia.org/wiki/TOML
|
||||
[yaml]: https://en.wikipedia.org/wiki/YAML
|
||||
|
|
|
|||
|
|
@ -29,13 +29,13 @@ postamble: |
|
|||
[base64 encoded]: https://en.wikipedia.org/wiki/Base64
|
||||
[elliptic curve]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations#Generating_EC_Keys_and_Parameters
|
||||
[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
|
||||
[identity provider]: ../docs/identity-providers/
|
||||
[identity provider]: /docs/identity-providers/readme.md
|
||||
[json]: https://en.wikipedia.org/wiki/JSON
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[oidc rfc]: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
|
||||
[okta]: ../docs/identity-providers/okta.md
|
||||
[okta]: /docs/identity-providers/okta.md
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[signed headers]: ../docs/topics/getting-users-identity.md
|
||||
[signed headers]: /docs/topics/getting-users-identity.md
|
||||
[toml]: https://en.wikipedia.org/wiki/TOML
|
||||
[yaml]: https://en.wikipedia.org/wiki/YAML
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ settings:
|
|||
- Type: `bool`
|
||||
- Optional
|
||||
doc: |
|
||||
Turning on autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS certificates from [Let's Encrypt][letsencrypt] which includes managed routes and the authenticate service. [Autocert Directory](./#autocert-directory) must be used with Autocert must have a place to persist, and share certificate data between services. Note that autocert also provides [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).
|
||||
Turning on autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS certificates from [Let's Encrypt][letsencrypt] which includes managed routes and the authenticate service. [Autocert Directory](#autocert-directory) must be used with Autocert must have a place to persist, and share certificate data between services. Note that autocert also provides [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).
|
||||
|
||||
This setting can be useful in situations where you may not have Pomerium behind a TLS terminating ingress or proxy that is already handling your public certificates on your behalf.
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ settings:
|
|||
- Type: `bool`
|
||||
- Optional
|
||||
doc: |
|
||||
If true, force autocert to request a certificate with the `status_request` extension (commonly called `Must-Staple`). This allows the TLS client (_id est_ the browser) to fail immediately if the TLS handshake doesn't include OCSP stapling information. This setting is only used when [Autocert](./#autocert) is true.
|
||||
If true, force autocert to request a certificate with the `status_request` extension (commonly called `Must-Staple`). This allows the TLS client (_id est_ the browser) to fail immediately if the TLS handshake doesn't include OCSP stapling information. This setting is only used when [Autocert](#autocert) is true.
|
||||
|
||||
:::tip
|
||||
|
||||
|
|
@ -105,7 +105,7 @@ settings:
|
|||
- Environmental Variable: either `AUTOCERT_DIR`
|
||||
- Config File Key: `autocert_dir`
|
||||
- Type: `string` pointing to the path of the directory
|
||||
- Required if using [Autocert](./#autocert) setting
|
||||
- Required if using [Autocert](#autocert) setting
|
||||
- Default:
|
||||
|
||||
- `/data/autocert` in published Pomerium docker images
|
||||
|
|
@ -387,7 +387,7 @@ settings:
|
|||
- Example: `TIMEOUT_READ=30s`
|
||||
- Defaults: `TIMEOUT_READ=30s` `TIMEOUT_WRITE=0` `TIMEOUT_IDLE=5m`
|
||||
doc: |
|
||||
Timeouts set the global server timeouts. Timeouts can also be set for individual [routes](./#policy).
|
||||
Timeouts set the global server timeouts. Timeouts can also be set for individual [routes](#policy).
|
||||
|
||||
|
||||
|
||||
|
|
@ -1167,8 +1167,15 @@ settings:
|
|||
- Environmental Variable: `POLICY`
|
||||
- Config File Key: `policy`
|
||||
- Type: [base64 encoded] `string` or inline policy structure in config file
|
||||
- **Required** However, pomerium will safely start without a policy configured, but will be unable to authorize or proxy traffic until the configuration is updated to contain a policy.
|
||||
- **Deprecated**: This key has been replaced with `route`.
|
||||
doc: |
|
||||
|
||||
::: warning
|
||||
The `policy` field as a top-level configuration key has been replaced with [`routes`](/reference/readme.md#routes). Moving forward, define policies within each defined route.
|
||||
|
||||
Existing policy definitions will currently behave as expected, but are deprecated and will be removed in a future version of Pomerium.
|
||||
:::
|
||||
|
||||
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,
|
||||
|
||||
<<< @/examples/config/policy.example.yaml
|
||||
|
|
@ -1188,7 +1195,7 @@ settings:
|
|||
|
||||
In this example, an incoming request with a path prefix of `/admin` would be handled by the first route (which is restricted to superusers). All other requests for `from.example.com` would be handled by the second route (which is open to the public).
|
||||
|
||||
A list of policy configuration variables follows.
|
||||
A list of configuration variables specific to `policy` follows Note that this also shares all configuration variables listed under [routes](/reference/readme.md#routes), excluding `policy` and its child variables.
|
||||
settings:
|
||||
- name: "Allowed Domains"
|
||||
keys: ["allowed_domains"]
|
||||
|
|
@ -1245,7 +1252,6 @@ settings:
|
|||
|
||||
- Nested maps are flattened: `{ "a": { "b": ["c"] } }` becomes `{ "a.b": ["c"] }`
|
||||
- Values are always a list: `{ "a": "b" }` becomes `{ "a": ["b"] }`
|
||||
|
||||
- name: "Allowed Users"
|
||||
keys: ["allowed_users"]
|
||||
attributes: |
|
||||
|
|
@ -1255,6 +1261,20 @@ settings:
|
|||
- Example: `alice@pomerium.io` , `bob@contractor.co`
|
||||
doc: |
|
||||
Allowed users is a collection of whitelisted users to authorize for a given route.
|
||||
- name: "Routes"
|
||||
keys: ["routes"]
|
||||
attributes: |
|
||||
- Environment Variable: `ROUTE`
|
||||
- Config File Key: `route`
|
||||
- Type: `string`
|
||||
- **Required** - While Pomerium will start without a route configured, it will not authorize or proxy any traffic until a route is defined. If configuring Pomerium for the Enterprise Console, define a route for the Console itself in Pomerium.
|
||||
doc: |
|
||||
A route contains specific access and control definitions for a back-end service. Each route is a list item under the `routes` key.
|
||||
|
||||
Each route defines at minimum a `from` and `to` field, and a `policy` key defining authorization logic. Policies are defined using [Pomerium Policy Language](/enterprise/reference/manage.md#pomerium-policy-language) (**PPL**). Additional options are listed below.
|
||||
|
||||
<<< @/examples/config/route.example.yaml
|
||||
settings:
|
||||
- name: "CORS Preflight"
|
||||
keys: ["cors_allow_preflight"]
|
||||
attributes: |
|
||||
|
|
@ -1274,7 +1294,7 @@ settings:
|
|||
doc: |
|
||||
Enable sending a signed [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) to upstream GCP services.
|
||||
|
||||
Requires setting [Google Cloud Serverless Authentication Service Account](./#google-cloud-serverless-authentication-service-account) or running Pomerium in an environment with a GCP service account present in default locations.
|
||||
Requires setting [Google Cloud Serverless Authentication Service Account](#google-cloud-serverless-authentication-service-account) or running Pomerium in an environment with a GCP service account present in default locations.
|
||||
- name: "From"
|
||||
keys: ["from"]
|
||||
attributes: |
|
||||
|
|
@ -1286,7 +1306,7 @@ settings:
|
|||
doc: |
|
||||
`From` is the externally accessible URL for the proxied request.
|
||||
|
||||
Specifying `tcp+https` for the scheme enables [TCP proxying](../docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
|
||||
Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
|
||||
|
||||
:::warning
|
||||
|
||||
|
|
@ -1474,8 +1494,11 @@ settings:
|
|||
```yaml
|
||||
- from: https://verify.corp.example.com
|
||||
to: https://verify.pomerium.com
|
||||
allowed_users:
|
||||
- bdd@pomerium.io
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
set_request_headers:
|
||||
# works auto-magically!
|
||||
# https://verify.corp.example.com/basic-auth/root/hunter42
|
||||
|
|
@ -1494,8 +1517,11 @@ settings:
|
|||
```yaml
|
||||
- from: https://verify.corp.example.com
|
||||
to: https://verify.pomerium.com
|
||||
allowed_users:
|
||||
- bdd@pomerium.io
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
remove_request_headers:
|
||||
- X-Email
|
||||
- X-Username
|
||||
|
|
@ -1571,7 +1597,7 @@ settings:
|
|||
- https://b.example.com
|
||||
```
|
||||
|
||||
A load balancing weight may be associated with a particular upstream by appending `,[weight]` to the URL. The exact behavior depends on your [`lb_policy`](#load-balancing-policy) setting. See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.html#load-balancing-weight).
|
||||
A load balancing weight may be associated with a particular upstream by appending `,[weight]` to the URL. The exact behavior depends on your [`lb_policy`](#load-balancing-policy) setting. See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.md#load-balancing-weight).
|
||||
|
||||
Must be `tcp` if `from` is `tcp+https`.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
#!/bin/bash
|
||||
# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
|
||||
# Main configuration flags : https://www.pomerium.com/docs/reference/
|
||||
|
||||
|
||||
# Main configuration flags
|
||||
# export ADDRESS=":8443" # optional, default is 443
|
||||
|
|
@ -14,7 +15,7 @@ export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com
|
|||
# export DATABROKER_SERVICE_URL=https://pomerium-databroker-service.default.svc.cluster.local
|
||||
|
||||
# Certificates can be loaded as files or base64 encoded bytes.
|
||||
# See : https://www.pomerium.io/docs/reference/certificates
|
||||
# See : https://www.pomerium.com/docs/reference/certificates
|
||||
export AUTOCERT=TRUE # Use Let's Encrypt to fetch certs. Port 80/443 must be internet accessible.
|
||||
# export AUTOCERT_DIR="./certs" # The path where you want to place your certificates
|
||||
# export CERTIFICATE_FILE="xxxx" # optional, defaults to `./cert.pem`
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
|
||||
# Main configuration flags : https://www.pomerium.com/docs/reference/
|
||||
|
||||
#
|
||||
# address: ":8443" # optional, default is 443
|
||||
# pomerium_debug: true # optional, default is false
|
||||
|
|
@ -73,24 +74,37 @@ authenticate_service_url: https://authenticate.localhost.pomerium.io
|
|||
# For Group data you must set an IDP_SERVICE_ACCOUNT
|
||||
# idp_service_account: YOUR_SERVICE_ACCOUNT
|
||||
|
||||
# Proxied routes and per-route policies are defined in a policy block
|
||||
policy:
|
||||
# Proxied routes and per-route policies are defined in a routes block
|
||||
routes:
|
||||
- from: https://verify.localhost.pomerium.io
|
||||
to: http://httpbin
|
||||
allowed_domains:
|
||||
- pomerium.io
|
||||
to: http://localhost:8000
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- domain:
|
||||
is: pomerium.io
|
||||
cors_allow_preflight: true
|
||||
timeout: 30s
|
||||
pass_identity_headers: true
|
||||
|
||||
- from: https://external-verify.localhost.pomerium.io
|
||||
to: https://verify.pomerium.com
|
||||
allowed_domains:
|
||||
- gmail.com
|
||||
pass_identity_headers: true
|
||||
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- domain:
|
||||
is: gmail.com
|
||||
- from: https://weirdlyssl.localhost.pomerium.io
|
||||
to: http://neverssl.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
- groups:
|
||||
has: ["admins", "developers"]
|
||||
- from: https://hello.localhost.pomerium.io
|
||||
to: http://hello:8080
|
||||
allowed_groups:
|
||||
- admins@pomerium.io
|
||||
pass_identity_headers: true
|
||||
to: http://localhost:8080
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- groups:
|
||||
has: ["admins@pomerium.io"]
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
#!/bin/bash
|
||||
|
||||
# See : https://www.pomerium.io/docs/reference/certificates
|
||||
# See : https://www.pomerium.com/docs/reference/certificates
|
||||
export AUTOCERT=TRUE # Use Let's Encrypt to fetch certs. Port 80/443 must be internet accessible.
|
||||
|
||||
# 256 bit random keys
|
||||
|
|
|
|||
|
|
@ -1,15 +1,16 @@
|
|||
# See detailed configuration settings : https://www.pomerium.io/docs/reference/reference/
|
||||
# See detailed configuration settings : https://www.pomerium.com/docs/reference/
|
||||
|
||||
|
||||
# this is the domain the identity provider will callback after a user authenticates
|
||||
authenticate_service_url: https://authenticate.localhost.pomerium.io
|
||||
|
||||
# certificate settings: https://www.pomerium.io/docs/reference/certificates.html
|
||||
# certificate settings: https://www.pomerium.com/docs/reference/certificates.html
|
||||
autocert: true
|
||||
|
||||
# REMOVE FOR PRODUCTION
|
||||
autocert_use_staging: true
|
||||
|
||||
# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
|
||||
# identity provider settings : https://www.pomerium.com/docs/identity-providers.html
|
||||
idp_provider: google
|
||||
idp_client_id: REPLACE_ME
|
||||
idp_client_secret: REPLACE_ME
|
||||
|
|
@ -21,6 +22,9 @@ cookie_secret: WwMtDXWaRDMBQCylle8OJ+w4kLIDIGd8W3cB4/zFFtg=
|
|||
policy:
|
||||
- from: https://verify.localhost.pomerium.io
|
||||
to: https://verify.pomerium.com
|
||||
allowed_users:
|
||||
- bdd@pomerium.io
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
pass_identity_headers: true
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
# This file contains only policy and route configuration details. Other
|
||||
# configuration settings required by pomerium are excluded for clarity.
|
||||
# See: https://www.pomerium.io/docs/reference/reference/
|
||||
# See: https://www.pomerium.com/docs/reference/
|
||||
|
||||
#
|
||||
# For a complete self contained configuration see : config.example.yaml.
|
||||
# Or, mix and match a policy file (this) with env vars : config.example.env
|
||||
|
|
|
|||
41
examples/config/route.example.yaml
Normal file
41
examples/config/route.example.yaml
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# This file contains only route and policy configuration details. Other
|
||||
# configuration settings required by pomerium are excluded for clarity.
|
||||
# See: https://www.pomerium.io/docs/reference/
|
||||
|
||||
#
|
||||
# For a complete self contained configuration see : config.example.yaml.
|
||||
# Or, mix and match a policy file (this) with env vars : config.example.env
|
||||
|
||||
routes:
|
||||
- from: https://verify.localhost.pomerium.io
|
||||
to: http://localhost:8000
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- domain:
|
||||
is: pomerium.io
|
||||
cors_allow_preflight: true
|
||||
timeout: 30s
|
||||
- from: https://external-verify.localhost.pomerium.io
|
||||
to: https://verify.pomerium.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- domain:
|
||||
is: gmail.com
|
||||
- from: https://weirdlyssl.localhost.pomerium.io
|
||||
to: http://neverssl.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: bdd@pomerium.io
|
||||
- groups:
|
||||
has: ["admins", "developers"]
|
||||
- from: https://hello.localhost.pomerium.io
|
||||
to: http://localhost:8080
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- groups:
|
||||
has: ["admins@pomerium.io"]
|
||||
|
|
@ -6,10 +6,11 @@ services:
|
|||
# Generate new secret keys. e.g. `head -c32 /dev/urandom | base64`
|
||||
- COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
|
||||
volumes:
|
||||
# Mount your domain's certificates : https://www.pomerium.io/docs/reference/certificates
|
||||
# Mount your domain's certificates : https://www.pomerium.com/docs/reference/certificates
|
||||
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
|
||||
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
|
||||
# Mount your config file : https://www.pomerium.io/docs/reference/reference/
|
||||
# Mount your config file : https://www.pomerium.com/docs/reference/
|
||||
|
||||
- ../config/config.minimal.yaml:/pomerium/config.yaml:ro
|
||||
ports:
|
||||
- 443:443
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ services:
|
|||
environment:
|
||||
- SERVICES=authenticate
|
||||
- INSECURE_SERVER=TRUE
|
||||
# NOTE!: Replace with your identity provider settings https://www.pomerium.io/docs/identity-providers.html
|
||||
# NOTE!: Replace with your identity provider settings https://www.pomerium.com/docs/identity-providers.html
|
||||
# - IDP_PROVIDER=google
|
||||
# - IDP_PROVIDER_URL=https://accounts.google.com
|
||||
# - IDP_CLIENT_ID=REPLACE_ME
|
||||
|
|
@ -70,7 +70,8 @@ services:
|
|||
- GRPC_ADDRESS=:443
|
||||
|
||||
volumes:
|
||||
# Retrieve non-secret config keys from the config file : https://www.pomerium.io/docs/reference/reference/
|
||||
# Retrieve non-secret config keys from the config file : https://www.pomerium.com/docs/reference/
|
||||
|
||||
# See `config.example.yaml` and modify to fit your needs.
|
||||
- ../config/config.example.yaml:/pomerium/config.yaml:ro
|
||||
expose:
|
||||
|
|
@ -85,7 +86,8 @@ services:
|
|||
- GRPC_INSECURE=TRUE
|
||||
- GRPC_ADDRESS=:443
|
||||
volumes:
|
||||
# Retrieve non-secret config keys from the config file : https://www.pomerium.io/docs/reference/reference/
|
||||
# Retrieve non-secret config keys from the config file : https://www.pomerium.com/docs/reference/
|
||||
|
||||
# See `config.example.yaml` and modify to fit your needs.
|
||||
- ../config/config.example.yaml:/pomerium/config.yaml:ro
|
||||
expose:
|
||||
|
|
|
|||
|
|
@ -28,13 +28,8 @@ echo "=> install pomerium with helm"
|
|||
helm install \
|
||||
pomerium \
|
||||
pomerium/pomerium \
|
||||
--set proxy.service.type="NodePort" \
|
||||
--set authenticate.service.type="NodePort" \
|
||||
--set config.sharedSecret=$(head -c32 /dev/urandom | base64) \
|
||||
--set config.cookieSecret=$(head -c32 /dev/urandom | base64) \
|
||||
--set ingress.secret.name="pomerium-tls" \
|
||||
--set ingress.secret.cert=$(base64 -i "$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer") \
|
||||
--set ingress.secret.key=$(base64 -i "$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key") \
|
||||
--set ingress.secret.cert="$(base64 -i $HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer)" \
|
||||
--set ingress.secret.key="$(base64 -i $HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key)" \
|
||||
--values docs/configuration/examples/kubernetes/values.yaml
|
||||
|
||||
# When done, clean up by deleting the cluster!
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
|
||||
# Main configuration flags : https://www.pomerium.com/docs/reference/
|
||||
|
||||
insecure_server: true
|
||||
grpc_insecure: true
|
||||
address: ":80"
|
||||
|
|
|
|||
35
examples/kubernetes/pomerium-certificates.yaml
Normal file
35
examples/kubernetes/pomerium-certificates.yaml
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
apiVersion: cert-manager.io/v1
|
||||
kind: Certificate
|
||||
metadata:
|
||||
name: pomerium-cert
|
||||
namespace: pomerium
|
||||
spec:
|
||||
secretName: pomerium-tls
|
||||
issuerRef:
|
||||
name: pomerium-issuer
|
||||
kind: Issuer
|
||||
usages:
|
||||
- server auth
|
||||
- client auth
|
||||
dnsNames:
|
||||
- pomerium-proxy.pomerium.svc.cluster.local
|
||||
- pomerium-authorize.pomerium.svc.cluster.local
|
||||
- pomerium-databroker.pomerium.svc.cluster.local
|
||||
- pomerium-authenticate.pomerium.svc.cluster.local
|
||||
# TODO - Replace the following entry with your domain space.
|
||||
- "*.localhost.pomerium.io" # Quotes are required to escape the wildcard
|
||||
---
|
||||
apiVersion: cert-manager.io/v1
|
||||
kind: Certificate
|
||||
metadata:
|
||||
name: pomerium-redis-cert
|
||||
namespace: pomerium
|
||||
spec:
|
||||
secretName: pomerium-redis-tls
|
||||
issuerRef:
|
||||
name: pomerium-issuer
|
||||
kind: Issuer
|
||||
dnsNames:
|
||||
- pomerium-redis-master.pomerium.svc.cluster.local
|
||||
- pomerium-redis-headless.pomerium.svc.cluster.local
|
||||
- pomerium-redis-replicas.pomerium.svc.cluster.local
|
||||
13
examples/kubernetes/pomerium-console-certificate.yaml
Normal file
13
examples/kubernetes/pomerium-console-certificate.yaml
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
apiVersion: cert-manager.io/v1
|
||||
kind: Certificate
|
||||
metadata:
|
||||
name: pomerium-console-cert
|
||||
namespace: pomerium
|
||||
spec:
|
||||
secretName: pomerium-console-tls
|
||||
issuerRef:
|
||||
name: pomerium-issuer
|
||||
kind: Issuer
|
||||
dnsNames:
|
||||
- pomerium-console.pomerium.svc.cluster.local
|
||||
54
examples/kubernetes/pomerium-values.yaml
Normal file
54
examples/kubernetes/pomerium-values.yaml
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
authenticate:
|
||||
existingTLSSecret: pomerium-tls
|
||||
idp:
|
||||
provider: "google"
|
||||
clientID: YOUR_CLIENT_ID
|
||||
clientSecret: YOUR_SECRET
|
||||
serviceAccount: YOUR_SERVICE_ACCOUNT
|
||||
proxied: false
|
||||
|
||||
proxy:
|
||||
existingTLSSecret: pomerium-tls
|
||||
service:
|
||||
type: LoadBalancer
|
||||
|
||||
databroker:
|
||||
existingTLSSecret: pomerium-tls
|
||||
storage:
|
||||
connectionString: rediss://pomerium-redis-master.pomerium.svc.cluster.local
|
||||
type: redis
|
||||
clientTLS:
|
||||
existingSecretName: pomerium-tls
|
||||
existingCASecretKey: ca.crt
|
||||
|
||||
authorize:
|
||||
existingTLSSecret: pomerium-tls
|
||||
|
||||
redis:
|
||||
enabled: true
|
||||
auth:
|
||||
enabled: false
|
||||
usePassword: false
|
||||
generateTLS: false
|
||||
tls:
|
||||
certificateSecret: pomerium-redis-tls
|
||||
|
||||
ingress:
|
||||
enabled: false
|
||||
|
||||
config:
|
||||
sharedSecret: YOURSHAREDSECRET # You can use "head -c32 /dev/urandom | base64" to generate.
|
||||
cookieSecret: YOURCOOKIESECRET # You can use "head -c32 /dev/urandom | base64" to generate.
|
||||
rootDomain: localhost.pomerium.io
|
||||
existingCASecret: pomerium-tls
|
||||
generateTLS: false # On by default, disabled when cert-manager or another solution is in place.
|
||||
policy:
|
||||
# This will be our testing app, to confirm that Pomerium is authenticating and routing traffic.
|
||||
- from: https://hello.localhost.pomerium.io
|
||||
to: http://nginx.pomerium.svc.cluster.local:80
|
||||
allowed_domains:
|
||||
- companydomain.com # Use the domain your company email address uses.
|
||||
- from: https://authenticate.localhost.pomerium.io
|
||||
to: https://pomerium-authenticate.pomerium.svc.cluster.local
|
||||
preserve_host_header: true
|
||||
allow_public_unauthenticated_access: true
|
||||
|
|
@ -18,6 +18,7 @@ proxy:
|
|||
cloud.google.com/app-protocols: '{"https":"HTTPS"}'
|
||||
|
||||
config:
|
||||
rootDomain: localhost.pomerium.io
|
||||
policy:
|
||||
- from: https://hello.localhost.pomerium.io
|
||||
to: http://nginx.default.svc.cluster.local:80
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ A tiny go http server that enforces client certificates and can be used to test
|
|||
authenticate_service_url: https://authenticate.corp.domain.example
|
||||
authorize_service_url: https://authorize.corp.domain.example
|
||||
|
||||
# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
|
||||
# identity provider settings : https://www.pomerium.com/docs/identity-providers.html
|
||||
idp_provider: google
|
||||
idp_client_id: REPLACE_ME
|
||||
idp_client_secret: REPLACE_ME
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
authenticate_service_url: https://authenticate.corp.domain.example
|
||||
authorize_service_url: https://authorize.corp.domain.example
|
||||
|
||||
# identity provider settings : https://www.pomerium.io/docs/identity-providers.html
|
||||
# identity provider settings : https://www.pomerium.com/docs/identity-providers.html
|
||||
idp_provider: google
|
||||
idp_client_id: REPLACE_ME
|
||||
idp_client_secret: REPLACE_ME
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
|
||||
# Main configuration flags : https://www.pomerium.com/docs/reference/
|
||||
|
||||
|
||||
pomerium_debug: true
|
||||
address: :80
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Run this demo locally on your docker-compose capable workstation, or replace `lo
|
|||
|
||||
- Update `config.yaml` for your e-mail address, if not using gmail/google.
|
||||
- Replace secrets in `config.yaml`.
|
||||
- Replace allowed_users in `config.yaml`
|
||||
- Replace `email.is` in `config.yaml`
|
||||
- Configure read-only or writer users by changing readers and writers parameter of tiddlywiki in `docker-compose.yaml`.
|
||||
- Run `docker-compose up` from this directory.
|
||||
- Navigate to `https://wiki.localhost.pomerium.io`
|
||||
|
|
|
|||
|
|
@ -11,6 +11,10 @@ jwt_claims_headers: email
|
|||
policy:
|
||||
- from: https://wiki.localhost.pomerium.io
|
||||
to: http://tiddlywiki:8080
|
||||
allowed_users:
|
||||
- writer1@example.com
|
||||
- reader1@example.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: writer1@example.com
|
||||
- email:
|
||||
is: reader1@example.com
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
|
||||
# Main configuration flags : https://www.pomerium.com/docs/reference/
|
||||
|
||||
|
||||
pomerium_debug: true
|
||||
address: :80
|
||||
|
|
|
|||
|
|
@ -1,14 +1,17 @@
|
|||
{
|
||||
"devDependencies": {
|
||||
"@vuepress/plugin-google-analytics": "1.8.2",
|
||||
"js-yaml": "^4.1.0",
|
||||
"vuepress": "1.8.2",
|
||||
"vuepress-plugin-check-md": "0.0.2",
|
||||
"vuepress-plugin-element-tabs": "^0.2.8",
|
||||
"vuepress-plugin-sitemap": "2.3.1"
|
||||
},
|
||||
"scripts": {
|
||||
"docs:dev": "vuepress dev docs",
|
||||
"docs:build": "vuepress build docs",
|
||||
"docs:check-md": "vuepress check-md"
|
||||
"docs:check-md": "vuepress check-md",
|
||||
"console:buildref": "node scripts/generate-console-pages.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"esm": "3.2.25"
|
||||
|
|
|
|||
172
scripts/generate-console-pages.js
Executable file
172
scripts/generate-console-pages.js
Executable file
|
|
@ -0,0 +1,172 @@
|
|||
// generate-console-pages.js
|
||||
|
||||
const fs = require("fs");
|
||||
const yaml = require("js-yaml");
|
||||
|
||||
/**
|
||||
* This helper script, run by the technical writers, (re)generates markdown
|
||||
* documents for the Enterprise reference section. It assumes the existence
|
||||
* of `console-settings.yaml`, to be sourced as a build artifact from
|
||||
* pomerium/pomerium-console, and `pomerium-console_serve.yaml`, sourced from
|
||||
* running `pomerium-console gendocs.
|
||||
*/
|
||||
|
||||
// Functions
|
||||
|
||||
/**
|
||||
*
|
||||
* Import content from /docs/reference/settings.yaml when needed.
|
||||
*/
|
||||
const fromOSSettings = (name, keys) => {
|
||||
//console.log(keys)
|
||||
const asMap = Object.values(OSSettings.settings).map((section) => {
|
||||
const subSections = Object.values(section.settings)
|
||||
return subSections
|
||||
} )
|
||||
let result = ''
|
||||
for (let i = 0; i < asMap.length; i++ ) {
|
||||
for (j = 0; j < asMap[i].length; j++){
|
||||
const fixAnchorLinksRegex = /\(\#/g
|
||||
const fixHTMLLinksRegex = /\(\/(.+?).html/g
|
||||
if (asMap[i][j].name === name) {
|
||||
result = asMap[i][j].doc.replace(fixAnchorLinksRegex, "(/reference/readme.md#").replace(fixHTMLLinksRegex, "(/$1.md")
|
||||
}
|
||||
else if (keys !== null && asMap[i][j].keys && keys.some( key => asMap[i][j].keys.indexOf(key) >= 0)) {
|
||||
result = asMap[i][j].doc.replace(fixAnchorLinksRegex, "(/reference/readme.md#").replace(fixHTMLLinksRegex, "(/$1.md")
|
||||
} else {
|
||||
if (asMap[i][j].settings) {
|
||||
for (k = 0; k < asMap[i][j].settings.length; k++) {
|
||||
if (asMap[i][j].settings[k].name === name && asMap[i][j].settings[k].doc) {
|
||||
result = asMap[i][j].settings[k].doc.replace(fixAnchorLinksRegex, "(/reference/readme.md#").replace(fixHTMLLinksRegex, "(/$1.md")
|
||||
}
|
||||
else if (keys !== null && asMap[i][j].settings[k].keys && keys.some( key => asMap[i][j].settings[k].keys.indexOf(key) >= 0) && asMap[i][j].settings[k].doc) {
|
||||
result = asMap[i][j].settings[k].doc.replace(fixAnchorLinksRegex, "(/reference/readme.md#").replace(fixHTMLLinksRegex, "(/$1.md")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Import console environment/config options from `pomerium-console_serve.yaml`
|
||||
*/
|
||||
const writeConfigPage = (src) => {
|
||||
//console.log(`keys from src file: ` + JSON.stringify(src)) // For Debugging
|
||||
let path = "./docs/enterprise/reference/config.md";
|
||||
console.log(`Generating environment variable docs...\n`);
|
||||
let frontmatter = `---
|
||||
title: Environment Variables
|
||||
lang: en-US
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
# Pomerium Console Environment Variables
|
||||
|
||||
The keys listed below can be applied in Pomerium Console's \`config.yaml\` file, or applied as environment variables (in uppercase, replacing \`-\` with \`_\`).
|
||||
|
||||
`;
|
||||
const keySection = (obj) => {
|
||||
//console.log(JSON.stringify(obj.name)) // For Debugging
|
||||
let header = `## ` + obj.name + "\n\n";
|
||||
let body = `${obj.usage}
|
||||
|
||||
**Default value:** \`${obj.default_value ? obj.default_value : `none`}\`
|
||||
`;
|
||||
return header + body;
|
||||
};
|
||||
|
||||
let content =
|
||||
frontmatter + src.options.map((section) => keySection(section)).join("\n");
|
||||
fs.writeFileSync(path, content);
|
||||
};
|
||||
|
||||
/**
|
||||
* Read `console-settings.yaml` and write
|
||||
* markdown pages under `docs/enterprise/reference`.
|
||||
*/
|
||||
const writePage = (setting) => {
|
||||
let path =
|
||||
"./docs/enterprise/reference/" +
|
||||
setting.name.replace(/\s/g, "-").toLowerCase() +
|
||||
".md";
|
||||
console.log("Generating", path, "page");
|
||||
|
||||
let frontmatter = `---
|
||||
title: ${setting.name}
|
||||
lang: en-US
|
||||
sidebarDepth: 2
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
`;
|
||||
|
||||
let header = "# " + setting.name + "\n" + "\n";
|
||||
let body = setting.doc ? setting.doc.toString() + "\n" : "";
|
||||
let moreBody = setting.settings
|
||||
? setting.settings
|
||||
.map((subsection) => writeSubsection(subsection, 2))
|
||||
.join("")
|
||||
: "";
|
||||
let content = frontmatter + header + body + moreBody + postamble;
|
||||
|
||||
fs.writeFileSync(path, content);
|
||||
};
|
||||
|
||||
/**
|
||||
* Called by writePage, this function
|
||||
* handles nested settings objects.
|
||||
*/
|
||||
const writeSubsection = (subsection, depth) => {
|
||||
let subContent = "";
|
||||
if (!subsection.name) {
|
||||
return;
|
||||
}
|
||||
if (!subsection.doc) {
|
||||
//console.log(subsection)
|
||||
//console.log(subsection.keys || "no key")
|
||||
subContent =
|
||||
fromOSSettings(subsection.name, subsection.keys || null) + "\n";
|
||||
}
|
||||
let header = "#".repeat(depth) + " " + subsection.name + "\n" + "\n";
|
||||
subContent =
|
||||
subContent + (subsection.doc ? subsection.doc.toString() + "\n\n" : "");
|
||||
subsection.attributes
|
||||
? (subContent = subContent + subsection.attributes.toString())
|
||||
: null;
|
||||
subsection.settings
|
||||
? (subContent =
|
||||
subContent +
|
||||
subsection.settings
|
||||
.map((turtles) => writeSubsection(turtles, depth + 1))
|
||||
.join(""))
|
||||
: "";
|
||||
return header + subContent;
|
||||
};
|
||||
|
||||
// Main
|
||||
|
||||
console.log("Reading console-settings.yaml");
|
||||
|
||||
let docs = yaml.load(
|
||||
fs.readFileSync("./docs/enterprise/console-settings.yaml", "utf8")
|
||||
);
|
||||
let keysFile = yaml.load(
|
||||
fs.readFileSync("./docs/enterprise/pomerium-console_serve.yaml", "utf8")
|
||||
);
|
||||
let OSSettings = yaml.load(
|
||||
fs.readFileSync("./docs/reference/settings.yaml", "utf8")
|
||||
);
|
||||
let postamble = docs.postamble
|
||||
|
||||
writeConfigPage(keysFile);
|
||||
|
||||
docs.settings.map((setting) => {
|
||||
writePage(setting);
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue