3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-05-11 16:17:39 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: Add UUID to docs yaml blocks (#3251)

Browse source
This commit is contained in:
Travis Groth 2022-04-08 10:54:27 -04:00 • committed by GitHub
parent 5e836913ae
commit cbe90fd96d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 2445 additions and 2249 deletions
Download patch file Download diff file Expand all files Collapse all files

7
Makefile
View file

@ -138,6 +138,13 @@ yarn:
@echo "==> $@"
cd ui ; yarn install --network-timeout 120000
.PHONY: gen-docs
gen-docs:
@echo "==> $@"
pip3 install ruamel.yaml
python3 ./scripts/generate-settings-docs.py
node scripts/generate-console-pages.js
.PHONY: help
help:
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

711
docs/enterprise/console-settings.yaml
View file

@ -1,329 +1,406 @@
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 Pomerium Enterprise. 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](/enterprise/concepts.md#routes) 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.
When first installing Pomerium Enterprise, users may want to import existing routes from the open-source Pomerium core. The **Import Routes** button accepts the open-source `config.yaml` file and imports routes from it to Pomerium Enterprise.
From the main Routes page you can view and manage existing routes. From the table of routes you can:
- filter visible routes,
- delete one or more routes,
- move routes between Namespaces,
- export one or more route definitions to a CSV file,
- create a JSON-formatted policy report on one or more selected routes.
The sections below cover the options available when creating or editing a route.
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.
more: '/enterprise/reference/manage.html#name'
- name: "From"
- name: "Metrics Name"
doc: |
Once a Route is created, the Metric Name field will populate. You can use this name to scrape the Prometheus service for metrics on this Route when making custom dashboards.
- 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.
more: '/enterprise/reference/manage.html#policies-2'
- 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: "Allow SPDY"
keys: ["allow_spdy"]
- 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](/enterprise/concepts.md#policies) 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 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`
- `http_method`
- `http_path`
- `reject`
- `time_of_day`
- `user`
Some criteria also support a sub-path as part of the criterion name:
```yaml
- allow:
or:
- claim/family_name: 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**: Allow unauthenticated HTTP OPTIONS requests as per the CORS spec.
- **Public Access**: This setting allows complete, unrestricted access to an associated route. Use this setting with caution.
- name: "Certificates"
- name: "Devices"
doc: |
Introduced in v0.16.0, the **Manage Devices** page lets administrators manage user devices for policy-based authorization.
settings:
- name: "Manage Devices"
doc: |
From this page, administrators can manage new and existing device enrollments.
Device enrollment let's you create [policies](/docs/topics/ppl.md#device-matcher) that use [device identity](/docs/topics/device-identity.md).
- Users can [self-enroll](/guides/enroll-device.md) devices, which must then be approved in the **Devices List** for policies requiring approved devices.
- Administrators can use the **New Enrollment** button to create a link for the user to enroll a device as pre-approved. See our [Pre-Approved Device Enrollment](/guides/admin-enroll-device.md) guide for more information.
more: '/enterprise/reference/manage.html#manage-devices'
- name: "Devices List"
doc: |
Displays the currently enrolled devices for each user, along with their current approval status.
Administrators can inspect, approve, or delete registered devices from this table.
![List of user devices](./img/console-devices.png)
- name: "New Enrollment"
doc: |
The **New Enrollment** button allows administrators to create a custom link for a specific user to use to register a new device, which will automatically be approved.
This scheme is known as [Trust on First Use (TOFU)](https://en.wikipedia.org/wiki/Trust_on_first_use).
![Example device enrollment](./img/new-enrollment.png)
more: '/guides/admin-enroll-device.html'
settings:
- name: "Search Users"
doc: "New Enrollment URLs are only valid for the specified user."
more: '/guides/admin-enroll-device.html'
- name: "Redirect URL"
doc: "**Optional**: The URL the user will be taken to after device enrollment is successful."
more: '/guides/admin-enroll-device.html'
- name: "Enrollment Type"
doc: "Specify if the user can enroll any device identity, or restrict it to a [secure enclave](/docs/topics/device-identity.md#secure-enclaves)."
more: '/guides/admin-enroll-device.html'
- name: "Configure"
- name: Reports
settings:
- name: Traffic
doc: |
The **Configure** section of the Pomerium Enterprise Console houses settings that affect the entirety of the Console environment, i.e. across all Namespaces. Adjust these settings with care.
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)
uuid: fbf40372-9895-4ca7-95d3-5e18f8f56413
- 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)
uuid: 2edcf120-b62c-464b-a3a7-e5b14e3e6400
- 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)
uuid: d11acb05-65cc-4c65-9f92-4b1f08b622ef
- 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.
uuid: 219f8dd6-38d4-4dc3-98a6-98cca314c49e
- 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 Pomerium Enterprise. 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)
uuid: c812c87e-ec06-4091-b1fe-e206e43103d5
uuid: e15ae275-fa57-40d3-b2f7-ce24799ccf79
- name: Manage
settings:
- name: Routes
doc: |
A [Route](/enterprise/concepts.md#routes) 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.
When first installing Pomerium Enterprise, users may want to import existing routes from the open-source Pomerium core. The **Import Routes** button accepts the open-source `config.yaml` file and imports routes from it to Pomerium Enterprise.
From the main Routes page you can view and manage existing routes. From the table of routes you can:
- filter visible routes,
- delete one or more routes,
- move routes between Namespaces,
- export one or more route definitions to a CSV file,
- create a JSON-formatted policy report on one or more selected routes.
The sections below cover the options available when creating or editing a route.
settings:
- name: "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.
more: /enterprise/reference/manage.html#name
uuid: 3f59881a-24b4-41a0-b92f-1d36a69b76e8
- name: From
uuid: b9c54c4e-28ad-4a8b-aa65-3aa7f8b1f032
- name: Metrics Name
doc: |
The **Settings** section holds global settings that affect how the Pomerium Enterprise Console runs, logs, and communicates. Values set here are applied globally, except for settings documented to override global options.
settings:
- name: "Global"
settings:
- name: "Debug"
- name: "HTTP Redirect Address"
- name: "DNS Lookup Family"
- name: "Log Level"
- name: "Proxy Log Level"
- 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> (opens new window) 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"
doc: |
Tracing tracks the progression of a single user request as it is handled by Pomerium.
Each unit of 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.
settings:
- name: "Tracing Sample Rate"
doc: |
Percentage of requests to sample. Default is .01%.
Unlike the decimal value notion used for the `tracing_sample_rate` [key](/reference/readme.md#shared-tracing-settings) in open-source Pomerium, this value is a percentage, e.g. a value of `1` equates to 1%
- name: "Authenticate"
- name: "Proxy"
settings:
- name: "Certificate Authority"
keys: ["certificate_authority"]
- name: "Default Upstream Timeout"
- name: "JWT Claim Headers"
- name: "X-Forward-For HTTP Header"
keys: ["skip_xff_append"]
- name: "Response Headers"
keys: ["set_response_headers"]
- name: "Service Accounts"
Once a Route is created, the Metric Name field will populate. You can use this name to scrape the Prometheus service for metrics on this Route when making custom dashboards.
uuid: 7df15eef-3070-4353-822d-c2745386e0db
- name: To
uuid: 9c0201e0-b5fa-4027-a1e7-f115a3f70969
- name: Redirect
uuid: 72d885ce-8cd3-41a7-b7d0-0953ce49f8de
- name: Pass Identity Headers
uuid: 12e599f2-8bcc-4061-ba88-998c2671109c
- 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.
more: /enterprise/reference/manage.html#policies-2
uuid: c7340a01-2942-4ffe-bbf6-f97f0fec1e75
- name: Enable Google Cloud Serverless Authentication
uuid: 416405ec-74c3-47cb-899e-34bebaff26bf
uuid: fd86b6ea-fe73-4222-a675-5493c7dbd105
- name: Matchers
settings:
- name: Path
uuid: e5c805e5-4f7f-4fce-ba33-d3f1f47f5d35
- name: Prefix
uuid: 3a2bc400-d1bc-4249-a813-9777cfca7779
- name: Regex
uuid: 13dbfeb0-a8a0-4c97-9bb9-52aa3f22c7cc
uuid: 0bbff866-b7b9-4fdf-b8e5-b6d4f2475855
- name: Rewrite
settings:
- name: Prefix Rewrite
uuid: 3fb98409-89ae-47ae-b9ff-44f07f833492
- name: Regex Rewrite Pattern
keys: [regex_rewrite_pattern]
doc: |
[Service accounts](/enterprise/concepts.md#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:
![The Service Accounts page](./img/console-service-account.png)
1. Service accounts can be unique and exist only for Pomerium, or impersonate directory users from your IdP.
Give the user a unique ID, or select an existing user to impersonate. 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.
1. After you click **Submit**, the modal presents the JSON 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/create-policy-1.png)
---
![An example policy for a service account](./img/create-policy-2.png)
- name: "Namespaces"
keys: ["namespace"]
The pattern to match before rewriting, ex: `^/service/([^/]+)(/.*)$`.
uuid: 5cd03f7c-b474-45fd-aef0-c1ee15f2eaf2
- name: Regex Rewrite Substitution
keys: [regex_rewrite_substitution]
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.
The substitution for your regex pattern, ex: `\\2/instance/\\1`.
uuid: 71cdc7a9-d72e-407c-99f0-36e3a5ef1f41
uuid: b9ee5ae3-e90d-40f1-8df3-91d26ebe85cd
- name: Timeouts
settings:
- name: Allow Websockets
keys: [allow_websockets]
uuid: f42c273d-7c3d-471c-a28e-75b8c9e771f3
- name: Allow SPDY
keys: [allow_spdy]
uuid: ca7bf8ec-e123-4171-b22b-00c24a6a0d96
- name: Timeout
keys: [timeout]
uuid: 2b38fd23-24b0-4830-b924-0de802402191
- name: Idle Timeout
keys: [idle_timeout]
uuid: 25d0d973-9add-4efb-abaa-d526a41b3c4e
uuid: d93421db-ae13-4978-8d22-91561cc9eb61
- name: Headers
settings:
- name: Host Headers
keys: [host_rewrite]
uuid: 399e48ea-e6f3-4ab9-b007-714ed7428168
- name: Set Request Headers
uuid: 6acc6aa7-6cde-4849-b960-63103e3f00ee
- name: Remove Request Headers
uuid: c593bd77-b333-40c7-95bb-0ba41bf270e3
- name: Rewrite Response Headers
uuid: 1a9d6b6e-8d79-4ece-92c3-1d36d9c58af6
uuid: e8022486-c36d-4fad-970f-6412b7b156a2
- name: Load Balancer
settings:
- name: Load Balancing Policy
uuid: b4563876-813c-4eab-85e1-7c74efeb4412
uuid: ef865e68-a544-4482-b331-6acf5e723d3a
uuid: 99cab2ec-f8e6-4bcb-aa1d-2eba94948f49
- name: Policies
keys: [Policy]
doc: |
A [Policy](/enterprise/concepts.md#policies) 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 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.
Policies can be constructed three ways:
::: 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.
:::
### 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 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`
- `http_method`
- `http_path`
- `reject`
- `time_of_day`
- `user`
Some criteria also support a sub-path as part of the criterion name:
```yaml
- allow:
or:
- claim/family_name: 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**: Allow unauthenticated HTTP OPTIONS requests as per the CORS spec.
- **Public Access**: This setting allows complete, unrestricted access to an associated route. Use this setting with caution.
uuid: 1710a312-0562-4a18-b5a6-bedfc54873f6
- name: Certificates
uuid: bff9a877-7c35-4b9d-80d8-ca3b2d16a2fc
- name: Devices
doc: |
Introduced in v0.16.0, the **Manage Devices** page lets administrators manage user devices for policy-based authorization.
settings:
- name: Manage Devices
doc: |
From this page, administrators can manage new and existing device enrollments.
Device enrollment let's you create [policies](/docs/topics/ppl.md#device-matcher) that use [device identity](/docs/topics/device-identity.md).
- Users can [self-enroll](/guides/enroll-device.md) devices, which must then be approved in the **Devices List** for policies requiring approved devices.
- Administrators can use the **New Enrollment** button to create a link for the user to enroll a device as pre-approved. See our [Pre-Approved Device Enrollment](/guides/admin-enroll-device.md) guide for more information.
more: /enterprise/reference/manage.html#manage-devices
uuid: 742c64e4-9441-41b0-ac6e-677b6bfe6cbb
- name: Devices List
doc: |
Displays the currently enrolled devices for each user, along with their current approval status.
Administrators can inspect, approve, or delete registered devices from this table.
![List of user devices](./img/console-devices.png)
uuid: dd10552e-c7f8-4cca-8c31-3ed01f31b478
- name: New Enrollment
doc: |
The **New Enrollment** button allows administrators to create a custom link for a specific user to use to register a new device, which will automatically be approved.
This scheme is known as [Trust on First Use (TOFU)](https://en.wikipedia.org/wiki/Trust_on_first_use).
![Example device enrollment](./img/new-enrollment.png)
more: /guides/admin-enroll-device.html
settings:
- name: Search Users
doc: New Enrollment URLs are only valid for the specified user.
more: /guides/admin-enroll-device.html
uuid: 4d636f56-21e2-4c72-9a65-0fc9ff76823e
- name: Redirect URL
doc: '**Optional**: The URL the user will be taken to after device enrollment
is successful.'
more: /guides/admin-enroll-device.html
uuid: 79e3b000-79cd-4522-9336-cefb28906930
- name: Enrollment Type
doc: Specify if the user can enroll any device identity, or restrict it to
a [secure enclave](/docs/topics/device-identity.md#secure-enclaves).
more: /guides/admin-enroll-device.html
uuid: 69b7c84d-84aa-4a38-b830-55dfed8ad2a1
uuid: 4bdd0102-a593-420b-8999-51a461657dc4
uuid: d1eb6b9e-ab93-4beb-ab91-d1de6aa76498
uuid: e0dbd749-1a83-4d28-8fb9-e067f2d6daa4
- name: Configure
doc: |
The **Configure** section of the Pomerium Enterprise Console houses settings that affect the entirety of the Console environment, i.e. across all Namespaces. Adjust these settings with care.
settings:
- name: Settings
doc: |
The **Settings** section holds global settings that affect how the Pomerium Enterprise Console runs, logs, and communicates. Values set here are applied globally, except for settings documented to override global options.
settings:
- name: Global
settings:
- name: Debug
uuid: 6c058151-b21b-4b65-9abc-6ab884f946c0
- name: HTTP Redirect Address
uuid: 42459dde-ebb7-4e31-9cd1-1dbf01d7a440
- name: DNS Lookup Family
uuid: 206d37b5-9a6b-4043-8dae-68ca89640e2d
- name: Log Level
uuid: 1c13dfc6-6718-412a-8091-904f703c3014
- name: Proxy Log Level
uuid: c1f29676-7bf9-4feb-bb3b-246debd9c64b
uuid: 77e4a8cb-447e-4f79-b6b9-e752dcc53249
- name: Cookies
settings:
- name: HTTPS Only
keys: [cookie_secure]
uuid: 43d28fb7-69c3-4923-b095-b0f97ec88ed4
- name: Javascript Security
uuid: 9597b118-6fa1-4dd2-bf07-68b9f582f519
- name: Expires
keys: [cookie_expire]
uuid: e28156d0-5175-4cdc-8a39-dcb3735d1438
uuid: 378293b9-6068-4a97-9fa5-75a0fa155538
- name: Timeouts
doc: Timeouts set the global server timeouts. Timeouts can also be set for individual
routes.
uuid: 58a18216-744f-4ffc-aab5-aeabd74851f1
- 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> (opens new window) for details
uuid: 02d307d3-415f-4c0c-8d64-5f2fb96198cc
- 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
uuid: b49ffe89-5006-4f8e-841a-d6a12d00dbb3
uuid: f744ee07-7d41-4016-8621-3ead4e330a95
- name: Tracing
doc: |
Tracing tracks the progression of a single user request as it is handled by Pomerium.
Each unit of 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.
settings:
- name: Tracing Sample Rate
doc: |
Percentage of requests to sample. Default is .01%.
Unlike the decimal value notion used for the `tracing_sample_rate` [key](/reference/readme.md#shared-tracing-settings) in open-source Pomerium, this value is a percentage, e.g. a value of `1` equates to 1%
uuid: a214565d-9b77-4994-9c07-531bd9610dd0
uuid: bd62365e-1e08-4c45-9b3f-0eccbb0f8d80
- name: Authenticate
uuid: 5ce0bdf1-c73b-4994-988c-74a3c1743514
- name: Proxy
settings:
- name: Certificate Authority
keys: [certificate_authority]
uuid: 8b2127cd-b876-4296-b724-80101825be10
- name: Default Upstream Timeout
uuid: 11689429-03f1-4a75-9432-8c070c468ad7
- name: JWT Claim Headers
uuid: 01b24ad4-96dc-4885-b837-96ec1a5e826e
- name: X-Forward-For HTTP Header
keys: [skip_xff_append]
uuid: b1427fa5-4ddb-468b-a6c6-527634b374f6
- name: Response Headers
keys: [set_response_headers]
uuid: fe27b075-e5f0-40fe-8561-748b7ff9dae3
uuid: 9334d44c-919c-45af-8405-6acf19be1085
uuid: b0e3a449-e743-4cc2-a820-d5d470b752ab
- name: Service Accounts
doc: |
[Service accounts](/enterprise/concepts.md#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:
![The Service Accounts page](./img/console-service-account.png)
1. Service accounts can be unique and exist only for Pomerium, or impersonate directory users from your IdP.
Give the user a unique ID, or select an existing user to impersonate. 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.
1. After you click **Submit**, the modal presents the JSON 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/create-policy-1.png)
---
![An example policy for a service account](./img/create-policy-2.png)
uuid: f2a12f52-ea7a-4b44-8308-3500d653c122
- 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.md#non-domain-users) for more information.
:::
uuid: 3ffcbb2a-4c02-4c3f-b11e-0eef5c30f1bd
uuid: b1688ca0-aea8-4296-bc67-8c397ef969a6
postamble: |
[route-concept]: /enterprise/concepts.md#routes
[route-reference]: /enterprise/reference/manage.md#routes

4
docs/enterprise/reference/configure.md
View file

@ -151,7 +151,9 @@ Default Upstream Timeout is the default timeout applied to a proxied route when
The JWT Claim Headers setting allows you to pass specific user session data 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:
Additionally, this will add the claim to the `X-Pomerium-Jwt-Assertion` header provided by [`pass_identity_headers`](/reference/readme.md#pass-identity-headers), if not already present.
Any claim in the pomerium session JWT can be placed into a corresponding header and the JWT payload 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. Underscores will be replaced with dashes; e.g. `X-Pomerium-Claim-Given-Name`.

3935
docs/reference/settings.yaml
View file

File diff suppressed because it is too large Load diff

37
scripts/generate-settings-docs.py
View file

@ -1,7 +1,10 @@
#!/usr/bin/env python3
import os.path
import uuid
from typing import Any, IO
import yaml
from ruamel.yaml import YAML
yaml = YAML()
def main():
@ -10,9 +13,16 @@ def main():
d = os.path.normpath(d)
print(f"generating {d}/readme.md")
f = open(os.path.join(d, "settings.yaml"))
doc = yaml.full_load(f)
f.close()
settings_path = f"{d}/settings.yaml"
enterprise_settings_path = os.path.normpath(os.path.join(os.path.dirname(__file__), '..',
'docs', 'enterprise', 'console-settings.yaml'))
rewrite_settings_yaml(settings_path)
rewrite_settings_yaml(enterprise_settings_path)
with open(settings_path) as f:
doc = yaml.load(f)
f = open(os.path.join(os.path.dirname(__file__),
"..", "docs", "reference", "readme.md"), "w")
@ -22,6 +32,25 @@ def main():
f.close()
def rewrite_settings_yaml(path):
with open(path) as f:
doc = yaml.load(f)
add_uuid(doc['settings'])
with open(path, 'w') as f:
yaml.dump(doc, f)
def add_uuid(settings):
for setting in settings:
if not 'uuid' in setting:
setting['uuid'] = str(uuid.uuid4())
if 'settings' in setting:
add_uuid(setting['settings'])
def write_setting(w, depth, setting):
if 'name' in setting:
w.write(f"{'#' * depth} {setting.get('name', '')}\n")