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.
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 the route resides in will also be applied.
This value is only visible in the Console UI.
From is the externally accessible URL for the proxied request.
tcp+https for the scheme enables TCP proxying support for the route. You may map more than one port through the same hostname by specifying a different
:port in the URL.
Only secure schemes (
tcp+https) are supported.
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:
- 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 setting. See Load Balancing for example configurations.
Be careful with trailing slash.
- from: https://verify.corp.example.com to: https://verify.pomerium.com/anything
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
While the rule:
- 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.
to must be set.
Redirect is used to redirect incoming requests to a new URL. The
redirect field is an object with several possible
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.
to must be set.
# Pass Identity Headers
When enabled, this option will pass identity headers to upstream applications. These headers include:
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 (opens new window) to upstream GCP services.
Requires setting Google Cloud Serverless Authentication Service Account or running Pomerium in an environment with a GCP service account present in default locations.
If set, the route will only match incoming requests with a path that is an exact match for the specified path.
If set, the route will only match incoming requests with a path that begins with the specified prefix.
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 (opens new window) which is based on re2 (opens new window).
# Prefix Rewrite
If set, indicates that during forwarding, the matched prefix (or path) should be swapped with this value. For example, given this policy:
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
# Regex Rewrite Pattern
The pattern to match before rewriting, ex:
# Regex Rewrite Substitution
The substitution for your regex pattern, ex:
# Allow Websockets
If set, enables proxying of websocket connections.
Use with caution: websockets are long-lived connections, so 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 (opens new window).
# Allow SPDY
If set, enables proxying of SPDY protocol upgrades.
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 (
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).
# Host Headers
host header can be preserved via the
preserve_host_header setting or customized via 3 mutually exclusive options:
preserve_host_headerwhen 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
boolthat defaults to
false. See ProxyPreserveHost (opens new window).
host_rewritewhich will rewrite the host to a new literal value.
host_rewrite_headerwhich will rewrite the host to match an incoming header value.
host_path_regex_rewrite_substitutionwhich will rewrite the host according to a regex matching the path. For example with the following config:
host_path_regex_rewrite_pattern: "^/(.+)/.+$" host_path_regex_rewrite_substitution: \1
Would rewrite the host header to
example.comgiven the path
The 2nd, 3rd and 4th options correspond to the envoy route action host related options, which can be found here (opens new window).
# 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:
- from: https://verify.corp.example.com to: https://verify.pomerium.com policy: - allow: or: - email: is: firstname.lastname@example.org set_request_headers: # works auto-magically! # https://verify.corp.example.com/basic-auth/root/hunter42 Authorization: Basic cm9vdDpodW50ZXI0Mg== X-Your-favorite-authenticating-Proxy: "Pomerium"
:-prefixed pseudo-headers nor the
Host: header may be modified via this mechanism. Those headers may instead be modified via mechanisms such as
# 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:
- from: https://verify.corp.example.com to: https://verify.pomerium.com policy: - allow: or: - email: is: email@example.com 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:
And the policy has this config:
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 (opens new window), 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 (opens new window) for more details.
ROUND_ROBIN(opens new window) (default)
LEAST_REQUEST(opens new window) and may be further configured using
least_request_lb_config(opens new window)
RING_HASH(opens new window) and may be further configured using
ring_hash_lb_config(opens new window) option
RANDOM(opens new window)
MAGLEV(opens new window) and may be further configured using
maglev_lb_config(opens new window) option
Some policy types support additional configuration.
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.
# Pomerium Policy Language
From the EDITOR tab users can write policies in Pomerium Policy Language (PPL), a YAML-based notation.
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:
- allow: or: - email: is: firstname.lastname@example.org - email: is: email@example.com
The available rule actions are:
The available logical operators are:
The available criteria types are:
Some criteria also support a sub-path as part of the criterion name:
- allow: or: - claim/family_name: Smith
For those using OPA (opens new window), the REGO tab will accept policies written in Rego.
A policy can only support PPL or Rego. Once one is set, the other tab is disabled.
- 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.
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:
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"