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) 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: 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: | 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: | The pattern to match before rewriting, ex: `^/service/([^/]+)(/.*)$`. uuid: 5cd03f7c-b474-45fd-aef0-c1ee15f2eaf2 - name: Regex Rewrite Substitution keys: [regex_rewrite_substitution] doc: | 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 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. ::: ::: details Example Rego Policy This example policy compares the `given_name` claim from a user's session against a list of popular first names, and only allows the 100 most popular first names. ```rego package pomerium.policy session = s { s = gset_databroker_record("type.googleapis.com/user.ServiceAccount", input.session.id) s != null } else = s { s = get_databroker_record("type.googleapis.com/session.Session", input.session.id) s != null } else = {} { true } user = u { u = get_databroker_record("type.googleapis.com/user.User", session.user_id) } else = {} { true } allow = [true, {"custom-rego-authorized"}] { # grab all the claims from the user and session objects session_claims := object.get(session, "claims", {}) user_claims := object.get(user, "claims", {}) all_claims := object.union(session_claims, user_claims) # get the given_name claim. claim values are always an array of strings given_names := object.get(all_claims, "given_name", []) # query a JSON dump of the most popular baby names from 2020 response := http.send({ "method": "GET", "url": "https://raw.githubusercontent.com/aruljohn/popular-baby-names/master/2020/boy_names_2020.json", "force_json_decode": true, }) # only include the top 100 names all_names := response.body.names popular_names := array.slice(all_names, 0, 99) # check that there's a given name in the popular names some i some j popular_names[i] == given_names[j] } else = [false, {"custom-rego-unauthorized"}] { session.id != "" } else = [false, {"user-unauthenticated"}] { true } ``` This example pulls session data from the Databroker service using `type.googleapis.com/session.Session` for users and `type.googleapis.com/user.ServiceAccount` for service accounts. ::: ### 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 (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 (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 [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