pomerium/docs/enterprise/console-settings.yaml

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.
        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: "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`
          - `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: "Configure"
    settings:
      - name: "Settings"
        settings:
          - name: "Global"
            settings:
              - name: "Debug"
              - name: "Forward Auth"
              - 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 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"
        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:

             ![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: |
          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.
          :::

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