diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index d775db832..f5540c55a 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -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": { - pattern: "**/*.md", - }, - sitemap: { - hostname: "https://www.pomerium.com", - outFile: "docs/sitemap.xml", - }, - "@vuepress/google-analytics": { - ga: "UA-129872447-2", - }, - }, + plugins: [ + "vuepress-plugin-element-tabs", + [ + "check-md", + { + pattern: "**/*.md", + }, + ], + [ + "sitemap", + { + hostname: "https://www.pomerium.com", + outFile: "docs/sitemap.xml", + }, + ], + [ + "@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", + ], + }, + ], + }, + ], }, }, -} +}; diff --git a/docs/.vuepress/enhanceApp.js b/docs/.vuepress/enhanceApp.js new file mode 100644 index 000000000..a29e34880 --- /dev/null +++ b/docs/.vuepress/enhanceApp.js @@ -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); + }); + }); + } +} diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md index 67ab29ee6..9646882c2 100644 --- a/docs/docs/CHANGELOG.md +++ b/docs/docs/CHANGELOG.md @@ -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. diff --git a/docs/docs/install/binary.md b/docs/docs/install/binary.md index 862f549ca..4d02702a6 100644 --- a/docs/docs/install/binary.md +++ b/docs/docs/install/binary.md @@ -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 diff --git a/docs/docs/install/from-source.md b/docs/docs/install/from-source.md index 70914947c..dc8836534 100644 --- a/docs/docs/install/from-source.md +++ b/docs/docs/install/from-source.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 diff --git a/docs/docs/install/helm.md b/docs/docs/install/helm.md index 95241afd1..0a78486ff 100644 --- a/docs/docs/install/helm.md +++ b/docs/docs/install/helm.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. ![currently logged in user](./img/logged-in-as.png) -[./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 -[tls certificates]: ../topics/certificates.md +[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 \ No newline at end of file diff --git a/docs/docs/releases.md b/docs/docs/releases.md index 7b4ea77be..8729e4fcb 100644 --- a/docs/docs/releases.md +++ b/docs/docs/releases.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). diff --git a/docs/docs/topics/data-storage.md b/docs/docs/topics/data-storage.md index 17da96e57..bad5ca142 100644 --- a/docs/docs/topics/data-storage.md +++ b/docs/docs/topics/data-storage.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. diff --git a/docs/docs/topics/kubernetes-integration.md b/docs/docs/topics/kubernetes-integration.md index 4f293ff60..b025332e2 100644 --- a/docs/docs/topics/kubernetes-integration.md +++ b/docs/docs/topics/kubernetes-integration.md @@ -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: diff --git a/docs/docs/topics/production-deployment.md b/docs/docs/topics/production-deployment.md index 7130a73ba..755db86b8 100644 --- a/docs/docs/topics/production-deployment.md +++ b/docs/docs/topics/production-deployment.md @@ -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 diff --git a/docs/docs/topics/tcp-support.md b/docs/docs/topics/tcp-support.md index 86d95a902..00859fc19 100644 --- a/docs/docs/topics/tcp-support.md +++ b/docs/docs/topics/tcp-support.md @@ -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: - - 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 +routes: + - from: tcp+https://redis.corp.example.com:6379 + to: tcp://redis.internal.example.com:6379 + 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: diff --git a/docs/docs/upgrading.md b/docs/docs/upgrading.md index a289d4a1c..0f496b011 100644 --- a/docs/docs/upgrading.md +++ b/docs/docs/upgrading.md @@ -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 diff --git a/docs/enterprise/about.md b/docs/enterprise/about.md new file mode 100644 index 000000000..c02f1729d --- /dev/null +++ b/docs/enterprise/about.md @@ -0,0 +1,49 @@ +--- +title: About +sidebarDepth: 2 +description: What does the Pomerium Enterpise Console offer? +--- + +# Pomerium Enterprise + + + +## 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. + +![Overview animation of the Pomerium Enterprise Console](./img/console-overview.gif) + +### 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. + +![Pomerium Enterprise Console Session List](./img/console-session-list.png) + +### 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. + + + +## 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. diff --git a/docs/enterprise/concepts.md b/docs/enterprise/concepts.md new file mode 100644 index 000000000..5799a0e63 --- /dev/null +++ b/docs/enterprise/concepts.md @@ -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: + + ![The Session Details page, showing the "sub" data](./img/session-details.png) + +## 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 diff --git a/docs/enterprise/console-settings.yaml b/docs/enterprise/console-settings.yaml new file mode 100644 index 000000000..205b262e3 --- /dev/null +++ b/docs/enterprise/console-settings.yaml @@ -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. + + ![The Traffic page in Pomerium Enterprise](../img/traffic-fullpage.png) + - name: "Runtime" + doc: | + Monitor how many system resources Pomerium is consuming. Filter by date range, service, and instance. + + ![The Runtime Info page in Pomerium Enterprise](../img/runtime-fullpage.png) + - 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. + + ![The Sessions page in Pomerium Enterprise](../img/sessions-fullpage.png) + - 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 Events page in Pomerium Enterprise](../img/events-fullpage.png) + + 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: + + ![A screenshot showing the diff of a change to a route, adding a policy](../img/deployment-diff.png) + - 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. + + ![A policy being constructed in Pomerium Enterprise console allowing a single user access](../img/example-policy-single-user.png) + + ### Pomerium Policy Language + + From the **EDITOR** tab users can write policies in Pomerium Policy Language (**PPL**), a YAML-based notation. + + ![A policy as viewed from the editor tab](../img/example-policy-editor.png) + + 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 diff --git a/docs/enterprise/img/console-overview.gif b/docs/enterprise/img/console-overview.gif new file mode 100644 index 000000000..15b872748 Binary files /dev/null and b/docs/enterprise/img/console-overview.gif differ diff --git a/docs/enterprise/img/console-route-traffic.png b/docs/enterprise/img/console-route-traffic.png new file mode 100644 index 000000000..2e1ef189b Binary files /dev/null and b/docs/enterprise/img/console-route-traffic.png differ diff --git a/docs/enterprise/img/console-session-landing.png b/docs/enterprise/img/console-session-landing.png new file mode 100644 index 000000000..c6d60b4f7 Binary files /dev/null and b/docs/enterprise/img/console-session-landing.png differ diff --git a/docs/enterprise/img/console-session-list.png b/docs/enterprise/img/console-session-list.png new file mode 100644 index 000000000..76d95944e Binary files /dev/null and b/docs/enterprise/img/console-session-list.png differ diff --git a/docs/enterprise/img/deployment-diff.png b/docs/enterprise/img/deployment-diff.png new file mode 100644 index 000000000..d52992a94 Binary files /dev/null and b/docs/enterprise/img/deployment-diff.png differ diff --git a/docs/enterprise/img/events-fullpage.png b/docs/enterprise/img/events-fullpage.png new file mode 100644 index 000000000..cb9f3a545 Binary files /dev/null and b/docs/enterprise/img/events-fullpage.png differ diff --git a/docs/enterprise/img/example-policy-editor.png b/docs/enterprise/img/example-policy-editor.png new file mode 100644 index 000000000..97a3a5247 Binary files /dev/null and b/docs/enterprise/img/example-policy-editor.png differ diff --git a/docs/enterprise/img/example-policy-single-user.png b/docs/enterprise/img/example-policy-single-user.png new file mode 100644 index 000000000..fb6cc27a7 Binary files /dev/null and b/docs/enterprise/img/example-policy-single-user.png differ diff --git a/docs/enterprise/img/runtime-fullpage.png b/docs/enterprise/img/runtime-fullpage.png new file mode 100644 index 000000000..734d58588 Binary files /dev/null and b/docs/enterprise/img/runtime-fullpage.png differ diff --git a/docs/enterprise/img/session-details.png b/docs/enterprise/img/session-details.png new file mode 100644 index 000000000..db17149e4 Binary files /dev/null and b/docs/enterprise/img/session-details.png differ diff --git a/docs/enterprise/img/sessions-fullpage.png b/docs/enterprise/img/sessions-fullpage.png new file mode 100644 index 000000000..1cddc0ebe Binary files /dev/null and b/docs/enterprise/img/sessions-fullpage.png differ diff --git a/docs/enterprise/img/traffic-fullpage.png b/docs/enterprise/img/traffic-fullpage.png new file mode 100644 index 000000000..aabcb780e Binary files /dev/null and b/docs/enterprise/img/traffic-fullpage.png differ diff --git a/docs/enterprise/install/helm.md b/docs/enterprise/install/helm.md new file mode 100644 index 000000000..72354b43c --- /dev/null +++ b/docs/enterprise/install/helm.md @@ -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: + + ![The Session List page after installing Pomerium Enterprise Console](../img/console-session-landing.png) + +## 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/ \ No newline at end of file diff --git a/docs/enterprise/install/quickstart.md b/docs/enterprise/install/quickstart.md new file mode 100644 index 000000000..7eb1ca64a --- /dev/null +++ b/docs/enterprise/install/quickstart.md @@ -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. diff --git a/docs/enterprise/install/readme.md b/docs/enterprise/install/readme.md new file mode 100644 index 000000000..4c834515d --- /dev/null +++ b/docs/enterprise/install/readme.md @@ -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) \ No newline at end of file diff --git a/docs/enterprise/pomerium-console_serve.yaml b/docs/enterprise/pomerium-console_serve.yaml new file mode 100644 index 000000000..600845622 --- /dev/null +++ b/docs/enterprise/pomerium-console_serve.yaml @@ -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 diff --git a/docs/enterprise/prometheus.md b/docs/enterprise/prometheus.md new file mode 100644 index 000000000..15c93f671 --- /dev/null +++ b/docs/enterprise/prometheus.md @@ -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: + + ![Traffic Data in Pomerium Enterprise Console](./img/console-route-traffic.png) + +## 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). diff --git a/docs/enterprise/readme.md b/docs/enterprise/readme.md new file mode 100644 index 000000000..50a169c3a --- /dev/null +++ b/docs/enterprise/readme.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/enterprise/reference/config.md b/docs/enterprise/reference/config.md new file mode 100644 index 000000000..6e25a96e6 --- /dev/null +++ b/docs/enterprise/reference/config.md @@ -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` diff --git a/docs/enterprise/reference/configure.md b/docs/enterprise/reference/configure.md new file mode 100644 index 000000000..5f85609a6 --- /dev/null +++ b/docs/enterprise/reference/configure.md @@ -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 + +![pomerium forward auth request flow](./img/auth-flow-diagram.svg) + +#### 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 + +![jaeger example trace](./img/jaeger.png) + +### 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 diff --git a/docs/enterprise/reference/img b/docs/enterprise/reference/img new file mode 120000 index 000000000..5ff50db27 --- /dev/null +++ b/docs/enterprise/reference/img @@ -0,0 +1 @@ +../../reference/img \ No newline at end of file diff --git a/docs/enterprise/reference/manage.md b/docs/enterprise/reference/manage.md new file mode 100644 index 000000000..94dd90bed --- /dev/null +++ b/docs/enterprise/reference/manage.md @@ -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. + +![A policy being constructed in Pomerium Enterprise console allowing a single user access](../img/example-policy-single-user.png) + +### Pomerium Policy Language + +From the **EDITOR** tab users can write policies in Pomerium Policy Language (**PPL**), a YAML-based notation. + +![A policy as viewed from the editor tab](../img/example-policy-editor.png) + +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 diff --git a/docs/enterprise/reference/reports.md b/docs/enterprise/reference/reports.md new file mode 100644 index 000000000..f74536be8 --- /dev/null +++ b/docs/enterprise/reference/reports.md @@ -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. + +![The Traffic page in Pomerium Enterprise](../img/traffic-fullpage.png) + + +## Runtime + +Monitor how many system resources Pomerium is consuming. Filter by date range, service, and instance. + +![The Runtime Info page in Pomerium Enterprise](../img/runtime-fullpage.png) + + +## 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. + +![The Sessions page in Pomerium Enterprise](../img/sessions-fullpage.png) + + +## Events + +The events page displays the log output of Envoy as it process changes from Pomerium and applies updates to the underlying services. + +![The Events page in Pomerium Enterprise](../img/events-fullpage.png) + +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: + +![A screenshot showing the diff of a change to a route, adding a policy](../img/deployment-diff.png) + + +[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 diff --git a/docs/guides/ad-guard.md b/docs/guides/ad-guard.md index d5f0a8d21..65eeda0c8 100644 --- a/docs/guides/ad-guard.md +++ b/docs/guides/ad-guard.md @@ -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=== diff --git a/docs/guides/argo.md b/docs/guides/argo.md index fb343aa0d..dfc5986cf 100644 --- a/docs/guides/argo.md +++ b/docs/guides/argo.md @@ -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: diff --git a/docs/guides/code-server.md b/docs/guides/code-server.md index fe30e53ef..3d75b3d87 100644 --- a/docs/guides/code-server.md +++ b/docs/guides/code-server.md @@ -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]() 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 diff --git a/docs/guides/kubernetes-dashboard.md b/docs/guides/kubernetes-dashboard.md index 1a8c46692..bd4648080 100644 --- a/docs/guides/kubernetes-dashboard.md +++ b/docs/guides/kubernetes-dashboard.md @@ -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: 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" diff --git a/docs/guides/local-oidc.md b/docs/guides/local-oidc.md index 6b39075e6..36c4c2fb9 100644 --- a/docs/guides/local-oidc.md +++ b/docs/guides/local-oidc.md @@ -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= 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/ diff --git a/docs/guides/synology.md b/docs/guides/synology.md index 190b1ac10..c526512af 100644 --- a/docs/guides/synology.md +++ b/docs/guides/synology.md @@ -104,16 +104,19 @@ We'll also need a test application to manage access to. For this guide we'll use ![Synology download httpbin docker image](./img/synology-httpbin.png) -### 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 ![Synology done](./img/synology-step-4-unauthorized.png) -[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 diff --git a/docs/guides/tcp.md b/docs/guides/tcp.md index cbbb471fe..47b5e6a6b 100644 --- a/docs/guides/tcp.md +++ b/docs/guides/tcp.md @@ -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] diff --git a/docs/guides/tiddlywiki.md b/docs/guides/tiddlywiki.md index b4dc4e9d4..225952e55 100644 --- a/docs/guides/tiddlywiki.md +++ b/docs/guides/tiddlywiki.md @@ -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 diff --git a/docs/guides/transmission.md b/docs/guides/transmission.md index cea5e0200..e56c54fc5 100644 --- a/docs/guides/transmission.md +++ b/docs/guides/transmission.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:// # Replace with the domain you want to use to access Transmission to: http://: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: - - # 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: [""] # 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 `/.pomerium` to view and confirm your session details. [Transmission]: https://transmissionbt.com/ -[quick start]: ../docs/quick-start +[quick start]: /docs/install/readme.md \ No newline at end of file diff --git a/docs/readme.md b/docs/readme.md index bce08b424..f24978818 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,2 +1,7 @@ + + + \ No newline at end of file diff --git a/docs/reference/readme.md b/docs/reference/readme.md index 3bb46cd67..6950bde23 100644 --- a/docs/reference/readme.md +++ b/docs/reference/readme.md @@ -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). ![cloudflare blog on timeouts](https://blog.cloudflare.com/content/images/2016/06/Timeouts-001.png) @@ -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 diff --git a/docs/reference/settings.yaml b/docs/reference/settings.yaml index b11f85f6d..2d9ded733 100644 --- a/docs/reference/settings.yaml +++ b/docs/reference/settings.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). ![cloudflare blog on timeouts](https://blog.cloudflare.com/content/images/2016/06/Timeouts-001.png) @@ -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`. diff --git a/examples/config/config.example.env b/examples/config/config.example.env index 080249a1f..d68bb20e4 100644 --- a/examples/config/config.example.env +++ b/examples/config/config.example.env @@ -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` diff --git a/examples/config/config.example.yaml b/examples/config/config.example.yaml index 74d13880e..66031dc14 100644 --- a/examples/config/config.example.yaml +++ b/examples/config/config.example.yaml @@ -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"] diff --git a/examples/config/config.minimal.env b/examples/config/config.minimal.env index 7c1f97527..3b4099419 100644 --- a/examples/config/config.minimal.env +++ b/examples/config/config.minimal.env @@ -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 diff --git a/examples/config/config.minimal.yaml b/examples/config/config.minimal.yaml index 1f0af56ee..da10f3c0c 100644 --- a/examples/config/config.minimal.yaml +++ b/examples/config/config.minimal.yaml @@ -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 diff --git a/examples/config/policy.example.yaml b/examples/config/policy.example.yaml index b6ec7ffd0..fb1d5be51 100644 --- a/examples/config/policy.example.yaml +++ b/examples/config/policy.example.yaml @@ -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 diff --git a/examples/config/route.example.yaml b/examples/config/route.example.yaml new file mode 100644 index 000000000..32845c60d --- /dev/null +++ b/examples/config/route.example.yaml @@ -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"] diff --git a/examples/docker/basic.docker-compose.yml b/examples/docker/basic.docker-compose.yml index 739b60803..2d01a02dd 100644 --- a/examples/docker/basic.docker-compose.yml +++ b/examples/docker/basic.docker-compose.yml @@ -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 diff --git a/examples/docker/nginx.docker-compose.yml b/examples/docker/nginx.docker-compose.yml index 355a2b36d..83230170a 100644 --- a/examples/docker/nginx.docker-compose.yml +++ b/examples/docker/nginx.docker-compose.yml @@ -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: diff --git a/examples/helm/helm_gke.sh b/examples/helm/helm_gke.sh index fc30a26be..1bbedc5cc 100755 --- a/examples/helm/helm_gke.sh +++ b/examples/helm/helm_gke.sh @@ -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! diff --git a/examples/kubernetes/kubernetes-config.yaml b/examples/kubernetes/kubernetes-config.yaml index 9a8abb923..f29893110 100644 --- a/examples/kubernetes/kubernetes-config.yaml +++ b/examples/kubernetes/kubernetes-config.yaml @@ -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" diff --git a/examples/kubernetes/pomerium-certificates.yaml b/examples/kubernetes/pomerium-certificates.yaml new file mode 100644 index 000000000..7201753bf --- /dev/null +++ b/examples/kubernetes/pomerium-certificates.yaml @@ -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 diff --git a/examples/kubernetes/pomerium-console-certificate.yaml b/examples/kubernetes/pomerium-console-certificate.yaml new file mode 100644 index 000000000..1b5d7f2e6 --- /dev/null +++ b/examples/kubernetes/pomerium-console-certificate.yaml @@ -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 diff --git a/examples/kubernetes/pomerium-values.yaml b/examples/kubernetes/pomerium-values.yaml new file mode 100644 index 000000000..b8e565097 --- /dev/null +++ b/examples/kubernetes/pomerium-values.yaml @@ -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 diff --git a/examples/kubernetes/values.yaml b/examples/kubernetes/values.yaml index 9eb7603ca..217ea8489 100644 --- a/examples/kubernetes/values.yaml +++ b/examples/kubernetes/values.yaml @@ -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 diff --git a/examples/mutual-tls/README.md b/examples/mutual-tls/README.md index 33dfb8ee7..ef7aaef84 100644 --- a/examples/mutual-tls/README.md +++ b/examples/mutual-tls/README.md @@ -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 diff --git a/examples/mutual-tls/example.config.yaml b/examples/mutual-tls/example.config.yaml index 2dad53abf..c232d7527 100644 --- a/examples/mutual-tls/example.config.yaml +++ b/examples/mutual-tls/example.config.yaml @@ -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 diff --git a/examples/nginx/config.yaml b/examples/nginx/config.yaml index 30d519b34..a346a5be1 100644 --- a/examples/nginx/config.yaml +++ b/examples/nginx/config.yaml @@ -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 diff --git a/examples/tiddlywiki/REAME.md b/examples/tiddlywiki/REAME.md index 13c4e8800..d6fcdd332 100644 --- a/examples/tiddlywiki/REAME.md +++ b/examples/tiddlywiki/REAME.md @@ -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` diff --git a/examples/tiddlywiki/config.yaml b/examples/tiddlywiki/config.yaml index c7660333f..f59198e47 100644 --- a/examples/tiddlywiki/config.yaml +++ b/examples/tiddlywiki/config.yaml @@ -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 diff --git a/examples/traefik/config.yaml b/examples/traefik/config.yaml index 1f1a5dd1c..d069e3351 100644 --- a/examples/traefik/config.yaml +++ b/examples/traefik/config.yaml @@ -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 diff --git a/package.json b/package.json index f39e91406..13211513e 100644 --- a/package.json +++ b/package.json @@ -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" diff --git a/scripts/generate-console-pages.js b/scripts/generate-console-pages.js new file mode 100755 index 000000000..eed975bd2 --- /dev/null +++ b/scripts/generate-console-pages.js @@ -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); +});