diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 08a1a2d30..77c7dd1c4 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -222,8 +222,7 @@ module.exports = { "/enterprise/install/helm", ], }, - "prometheus", - "service-accounts", + "metrics", { title: "Reference", type: "group", diff --git a/docs/.vuepress/public/_redirects b/docs/.vuepress/public/_redirects index 652bb3206..98c9f2a7b 100644 --- a/docs/.vuepress/public/_redirects +++ b/docs/.vuepress/public/_redirects @@ -53,6 +53,8 @@ /jobs/Backend-Engineer.html /careers/backend-engineer/ /enterprise/ / +/enterprise/service-accounts.html /enterprise/reference/configure.html#service-accounts +/enterprise/prometheus.html /enterprise/metrics.html /docs/installation.html / /docs/installation /docs/install diff --git a/docs/docs/topics/original-request-context.md b/docs/docs/topics/original-request-context.md index 18734ddca..a9a83c8be 100644 --- a/docs/docs/topics/original-request-context.md +++ b/docs/docs/topics/original-request-context.md @@ -51,7 +51,7 @@ routes: ``` - **App** is a user-facing application. Users connect to it through Pomerium. -- **API** is also accessed through it's Pomerium Route, but is only accessible by the **App**, using a [service account](/enterprise/service-accounts.md) to authenticate. +- **API** is also accessed through it's Pomerium Route, but is only accessible by the **App**, using a [service account](/enterprise/reference/configure.md#service-accounts) to authenticate. - The **API** service needs to know the user making the request to **App** in order to formulate the correct response. Both Routes include [`pass_identity_headers`](/reference/readme.md#pass-identity-headers), which provides (at minimum) the `X-Pomerium-Jwt-Assertion` header to the downstream application. diff --git a/docs/enterprise/about.md b/docs/enterprise/about.md index 44fc2681e..1df24a376 100644 --- a/docs/enterprise/about.md +++ b/docs/enterprise/about.md @@ -34,7 +34,7 @@ Easily define who can control access to what areas of your infrastructure. Our [ [User roles](/enterprise/concepts.md#rbac-for-enterprise-console-users) are granted along Namespace hierarchy, with 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. +Pomerium Enterprise uses teams and groups defined by your identity provider (**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. diff --git a/docs/enterprise/console-settings.yaml b/docs/enterprise/console-settings.yaml index ac84e5a60..90c3f2f92 100644 --- a/docs/enterprise/console-settings.yaml +++ b/docs/enterprise/console-settings.yaml @@ -181,7 +181,6 @@ settings: - name: "DNS Lookup Family" - name: "Log Level" - name: "Proxy Log Level" - - name: "Enable User Impersonation" - name: "Cookies" settings: - name: "HTTPS Only" @@ -227,7 +226,46 @@ settings: keys: ["set_response_headers"] - name: "Service Accounts" doc: | - See [Concepts: Service Accounts][service-accounts-concept]. + Service accounts offer a protected and standardized method of authenticating machine-to-machine communication between services protected by Pomerium. + + ::: tip + Before you begin, confirm you are in the correct Namespace. A service account can only be used in the Namespace it was created in, including its children Namespaces. + ::: + + 1. From the main menu, select **Service Accounts** under **CONFIGURE**. Click the **+ ADD SERVICE ACCOUNT** button: + + ![An empty Service Accounts page](../img/add-service-account.png) + + 1. Service accounts can be unique and exist only for Pomerium, or impersonate directory users from your IdP. + + ::::: tabs + :::: tab Unique + Give the user a unique ID. Consider referencing the Namespace you're creating it under, for easier reference later. Optionally set an expiration date: + + ![Adding a unique service account](../img/create-service-account.png) + + The user ID set here corresponds to the `User` criteria when editing a policy. + :::: + :::: tab Impersonated + You can find your User ID by going to the special endpoint `/.pomerium`, or selecting **Logout** under your user in the upper right hand corner (this will not immediately log you out): + + ![Session Details](../img/user-id.png) + + Copy the User ID and paste it into the **User ID** field in the **Add Service Account** modal. The lookahead search should show you the user name You can also optionally set an expiration date: + + ![Adding an impersonated service account](../img/create-impersonated-service-account.png) + :::: + ::::: + + 1. After you click **Submit**, the modal presents the Java Web Token (**JWT**) for the service account. Temporarily save it somewhere secure, as you will not be able to view it again: + + ![Service Account Added](../img/service-account-jwt.png) + + This JWT must be added to your application configuration to enable direct communication. + + 1. Edit or create policies to give the service account access to the internal service: + + ![An example policy for a service account](../img/service-account-policy.png) - name: "Namespaces" keys: ["namespace"] doc: | diff --git a/docs/enterprise/install/quickstart.md b/docs/enterprise/install/quickstart.md index 9b58b70f1..fba86ae84 100644 --- a/docs/enterprise/install/quickstart.md +++ b/docs/enterprise/install/quickstart.md @@ -211,7 +211,7 @@ audience: console.localhost.pomerium.com ## Next Steps -Pomerium Enterprise assumes access to a [Prometheus](https://prometheus.io/) data store for metrics. See [Prometheus Metrics](/enterprise/prometheus.md) to learn how to configure access. +Pomerium Enterprise assumes access to a [Prometheus](https://prometheus.io/) data store for metrics. See [Configure Metrics](/enterprise/metrics.md) to learn how to configure access. ## Troubleshooting diff --git a/docs/enterprise/prometheus.md b/docs/enterprise/metrics.md similarity index 93% rename from docs/enterprise/prometheus.md rename to docs/enterprise/metrics.md index d776b0caf..d69244c44 100644 --- a/docs/enterprise/prometheus.md +++ b/docs/enterprise/metrics.md @@ -1,13 +1,17 @@ --- -title: Prometheus +title: Metrics sidebarDepth: 1 description: Use Prometheus as a metrics data store. --- -# Prometheus Metrics +# Configure Metrics Pomerium Enterprise 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. +::: tip +For production deployments, we suggest using a dedicated Prometheus instance. +::: + ## Prepare Pomerium 1. In the Pomerium `config.yaml`, define the `metrics_address` key to a network interface and/or port. For example: diff --git a/docs/enterprise/reference/configure.md b/docs/enterprise/reference/configure.md index 74c9db4d7..517532e6a 100644 --- a/docs/enterprise/reference/configure.md +++ b/docs/enterprise/reference/configure.md @@ -134,9 +134,6 @@ Log level sets the global logging level for pomerium. Only logs of the desired l 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 @@ -248,7 +245,46 @@ Set Response Headers allows you to set static values for the given response head ## Service Accounts -See [Concepts: Service Accounts][service-accounts-concept]. +Service accounts offer a protected and standardized method of authenticating machine-to-machine communication between services protected by Pomerium. + +::: tip +Before you begin, confirm you are in the correct Namespace. A service account can only be used in the Namespace it was created in, including its children Namespaces. +::: + +1. From the main menu, select **Service Accounts** under **CONFIGURE**. Click the **+ ADD SERVICE ACCOUNT** button: + + ![An empty Service Accounts page](../img/add-service-account.png) + +1. Service accounts can be unique and exist only for Pomerium, or impersonate directory users from your IdP. + + ::::: tabs + :::: tab Unique + Give the user a unique ID. Consider referencing the Namespace you're creating it under, for easier reference later. Optionally set an expiration date: + + ![Adding a unique service account](../img/create-service-account.png) + + The user ID set here corresponds to the `User` criteria when editing a policy. + :::: + :::: tab Impersonated + You can find your User ID by going to the special endpoint `/.pomerium`, or selecting **Logout** under your user in the upper right hand corner (this will not immediately log you out): + + ![Session Details](../img/user-id.png) + + Copy the User ID and paste it into the **User ID** field in the **Add Service Account** modal. The lookahead search should show you the user name You can also optionally set an expiration date: + + ![Adding an impersonated service account](../img/create-impersonated-service-account.png) + :::: + ::::: + +1. After you click **Submit**, the modal presents the Java Web Token (**JWT**) for the service account. Temporarily save it somewhere secure, as you will not be able to view it again: + + ![Service Account Added](../img/service-account-jwt.png) + + This JWT must be added to your application configuration to enable direct communication. + +1. Edit or create policies to give the service account access to the internal service: + + ![An example policy for a service account](../img/service-account-policy.png) ## Namespaces @@ -260,7 +296,7 @@ A [Namespace][namespace-concept] is a collection of users, groups, routes, and p - 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.md#non-domain-users) for more information. +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. ::: diff --git a/docs/enterprise/service-accounts.md b/docs/enterprise/service-accounts.md deleted file mode 100644 index 362f877d5..000000000 --- a/docs/enterprise/service-accounts.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Service Accounts -sidebarDepth: 1 -description: Protect internal machine resources with service accounts. ---- - -# Service Accounts - -Service accounts offer a protected and standardized method of authenticating machine-to-machine communication between services protected by Pomerium. - -## Create a Service Account - -::: tip -Before you begin, confirm you are in the correct Namespace. A service account can only be used in the Namespace it was created in, including its children Namespaces. -::: - -1. From the main menu, select **Service Accounts** under **CONFIGURE**. Click the **+ ADD SERVICE ACCOUNT** button: - - ![An empty Service Accounts page](./img/add-service-account.png) - -1. Service accounts can be unique and exist only for Pomerium, or impersonate directory users from your IdP. - - ::::: tabs - :::: tab Unique - Give the user a unique ID. Consider referencing the Namespace you're creating it under, for easier reference later. Optionally set an expiration date: - - ![Adding a unique service account](./img/create-service-account.png) - - The user ID set here corresponds to the `User` criteria when editing a policy. - :::: - :::: tab Impersonated - You can find your User ID by going to the special endpoint `/.pomerium`, or selecting **Logout** under your user in the upper right hand corner (this will not immediately log you out): - - ![Session Details](./img/user-id.png) - - Copy the User ID and paste it into the **User ID** field in the **Add Service Account** modal. The lookahead search should show you the user name You can also optionally set an expiration date: - - ![Adding an impersonated service account](./img/create-impersonated-service-account.png) - :::: - ::::: - -1. After you click **Submit**, the modal presents the Java Web Token (**JWT**) for the service account. Temporarily save it somewhere secure, as you will not be able to view it again: - - ![Service Account Added](./img/service-account-jwt.png) - - This JWT must be added to your application configuration to enable direct communication. - -1. Edit or create policies to give the service account access to the internal service: - - ![An example policy for a service account](./img/service-account-policy.png) \ No newline at end of file diff --git a/docs/partials/generate-recovery-token.md b/docs/partials/generate-recovery-token.md index c3804c3c2..ee29d8153 100644 --- a/docs/partials/generate-recovery-token.md +++ b/docs/partials/generate-recovery-token.md @@ -1,8 +1,8 @@ -There could arise several situations that prevent Pomerium from authenticating users to Pomerium Enterprise. In these situations, you may be presented with the recovery sign in page: +In the event that you lose access to the console via delegated access (the policy defined in Pomerium), there exists a fallback procedure to gain regain access ot the console via a generated recovery token. ![Pomerium Enterprise Recovery Sign In](./img/recovery-token.png) -This page requires a recovery token. To generate a token, run the `pomerium-console generate-recovery token` with the following flags: +To generate a token, run the `pomerium-console generate-recovery token` command with the following flags: | Flag | Description | | --------------------------- | ----------- |