mirror of
https://github.com/pomerium/pomerium.git
synced 2025-04-29 10:26:29 +02:00
fill out reports
This commit is contained in:
alexfornuto
parent
f13517d262
commit
57be5780e5
9 changed files with 297 additions and 223 deletions
|
|
@ -85,11 +85,15 @@ Routes define the connection pathway and configuration from the internet to your
|
|||
|
||||
### Protected Endpoints
|
||||
|
||||
This term refers to the system or service the route provides or restrics access to.
|
||||
This term refers to the system or service the route provides or restricts access to.
|
||||
|
||||
## Policies
|
||||
|
||||
In the Pomerium Enterprise Console, FILL ME IN
|
||||
A Policy defines what permissions a set of users or groups has.
|
||||
|
||||
Policies can be applied to [Routes](#routes) directly, or enforced within a [Namespace](#namespaces). This associates the set of permissions with a service or set of services, completing the authentication model.
|
||||
|
||||
To learn more about how to create Policies in Pomerium Enterprise Console, see [Reference: Policies].
|
||||
|
||||
## Access control
|
||||
|
||||
|
|
@ -117,3 +121,5 @@ Authorization is where Pomerium's value proposition really lies. With Pomerium:
|
|||
- authorization is identity and context aware; pomerium can be used to integrate data from any source into authorization policy decisions.
|
||||
- trust flows from identity, device-state, and context, not network location. Every device, user, and application's communication should be authenticated, authorized, and encrypted.
|
||||
- Pomerium provides detailed audit logs for all activity in your environment. Quickly detect anomalies to mitigate bad actors and revoke access with a click of a button. Simplify life-cycle management and access reviews.
|
||||
|
||||
[Reference: Policies]: /enterprise/reference/manage.md#policies-2
|
||||
|
|
@ -18,8 +18,20 @@ settings:
|
|||
|
||||
- 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 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 "Component reloaded" 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 the Pomerium Enterprise Console. 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:
|
||||
|
||||
|
||||
- name: "Manage"
|
||||
settings:
|
||||
- name: "Routes"
|
||||
|
|
@ -78,10 +90,6 @@ settings:
|
|||
doc: |
|
||||
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.
|
||||
|
||||
::: tip
|
||||
This is a separate concept from [policies](/reference/readme.md#policy) in the non-enterprise model. In open-source Pomerium, the `policy` block defines both routes and access.
|
||||
:::
|
||||
|
||||
Policies can be constructed three ways:
|
||||
|
||||
### Web UI
|
||||
|
|
@ -220,4 +228,5 @@ postamble: |
|
|||
[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
|
||||
[service-accounts-concept]: /enterprise/concepts.md#service-accounts
|
||||
[policy-reference]: /enterprise/reference/manage.md#policies-2
|
||||
BIN
docs/enterprise/img/deployment-diff.png
Normal file
BIN
docs/enterprise/img/deployment-diff.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
|
|
@ -360,3 +360,4 @@ A [Namespace][namespace-concept] is a collection of users, groups, routes, and p
|
|||
[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
|
||||
|
|
|
|||
|
|
@ -150,13 +150,6 @@ The substitution for your regex pattern, ex: `\\2/instance/\\1`.
|
|||
|
||||
#### Allow Websockets
|
||||
|
||||
If set, enables proxying of websocket connections.
|
||||
|
||||
:::warning
|
||||
|
||||
**Use with caution:** websockets are long-lived connections, so [global timeouts](/reference/readme.md#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](https://www.cloudflare.com/learning/ddos/ddos-attack-tools/slowloris/).
|
||||
|
||||
:::
|
||||
|
||||
#### Timeout
|
||||
|
||||
|
|
@ -262,10 +255,6 @@ Some policy types support additional [configuration](/reference/readme.md#load-b
|
|||
|
||||
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.
|
||||
|
||||
::: tip
|
||||
This is a separate concept from [policies](/reference/readme.md#policy) in the non-enterprise model. In open-source Pomerium, the `policy` block defines both routes and access.
|
||||
:::
|
||||
|
||||
Policies can be constructed three ways:
|
||||
|
||||
### Web UI
|
||||
|
|
@ -365,3 +354,4 @@ certificates:
|
|||
[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
|
||||
|
|
|
|||
|
|
@ -32,14 +32,27 @@ View active Sessions. From here you can revoke sessions, filter by session or us
|
|||
|
||||
## Events
|
||||
|
||||
The events page displays the log output of Envoy as it process changes from Pomerium and applies updates to the underlying services.
|
||||
|
||||
|
||||
|
||||
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 "Component reloaded" refers to when services are reloaded, usually due to a system update.
|
||||
|
||||
|
||||
## Deployments
|
||||
|
||||
From the **Deployment History** page administrators can review changes made to their Pomerium configuration.
|
||||
|
||||
The default view shows all changes made through the Pomerium Enterprise Console. 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:
|
||||
|
||||
|
||||
|
||||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -1073,6 +1073,13 @@ If set, the TLS connection to the storage backend will not be verified.
|
|||
- Type: [base64 encoded] `string` or inline policy structure in config file
|
||||
- **Required** However, pomerium will safely start without a policy configured, but will be unable to authorize or proxy traffic until the configuration is updated to contain a policy.
|
||||
|
||||
|
||||
::: warning
|
||||
The `policy` field as a top-level configuration key has been replaced with [`routes`](/reference.html#routes). Moving forward, define policies within each defined route.
|
||||
|
||||
Existing policy definitions will currently behave as expected, but are deprecated and will be removed in a future version of Pomerium.
|
||||
:::
|
||||
|
||||
Policy contains route specific settings, and access control details. If you are configuring via POLICY environment variable, just the contents of the policy needs to be passed. If you are configuring via file, the policy should be present under the policy key. For example,
|
||||
|
||||
<<< @/examples/config/policy.example.yaml
|
||||
|
|
@ -1092,7 +1099,7 @@ policy:
|
|||
|
||||
In this example, an incoming request with a path prefix of `/admin` would be handled by the first route (which is restricted to superusers). All other requests for `from.example.com` would be handled by the second route (which is open to the public).
|
||||
|
||||
A list of policy configuration variables follows.
|
||||
A list of configuration variables specific to `policy` follows Note that this also shares all configuration variables listed under [routes](/reference.html#routes), excluding `policy` and its child variables.
|
||||
|
||||
|
||||
### Allowed Domains
|
||||
|
|
@ -1157,6 +1164,101 @@ Claims are represented as a map of strings to a list of values:
|
|||
Allowed users is a collection of whitelisted users to authorize for a given route.
|
||||
|
||||
|
||||
## Authorize Service
|
||||
|
||||
### Authorize Service URL
|
||||
- Environmental Variable: `AUTHORIZE_SERVICE_URL` or `AUTHORIZE_SERVICE_URLS`
|
||||
- Config File Key: `authorize_service_url` or `authorize_service_urls`
|
||||
- Type: `URL`
|
||||
- Required
|
||||
- Example: `https://authorize.corp.example.com`
|
||||
|
||||
Authorize Service URL is the location of the internally accessible authorize service. Multiple URLs can be specified with `authorize_service_url`.
|
||||
|
||||
|
||||
### Google Cloud Serverless Authentication Service Account
|
||||
- Environmental Variable: `GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION_SERVICE_ACCOUNT`
|
||||
- Config File Key: `google_cloud_serverless_authentication_service_account`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Optional
|
||||
|
||||
Manually specify the service account credentials to support GCP's [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) format.
|
||||
|
||||
If unspecified:
|
||||
|
||||
- If [Identity Provider Name](#identity-provider-name) is set to `google`, will default to [Identity Provider Service Account](#identity-provider-service-account)
|
||||
- Otherwise, will default to ambient credentials in the default locations searched by the Google SDK. This includes GCE metadata server tokens.
|
||||
|
||||
|
||||
### Signing Key
|
||||
- Environmental Variable: `SIGNING_KEY`
|
||||
- Config File Key: `signing_key`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Optional
|
||||
|
||||
Signing Key is the private key used to sign a user's attestation JWT which can be consumed by upstream applications to pass along identifying user information like username, id, and groups.
|
||||
|
||||
If set, the signing key's public key will can retrieved by hitting Pomerium's `/.well-known/pomerium/jwks.json` endpoint which lives on the authenticate service. Otherwise, the endpoint will return an empty keyset.
|
||||
|
||||
For example, assuming you have [generated an ES256 key](https://github.com/pomerium/pomerium/blob/master/scripts/generate_self_signed_signing_key.sh) as follows.
|
||||
|
||||
```bash
|
||||
# Generates an P-256 (ES256) signing key
|
||||
openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
|
||||
# careful! this will output your private key in terminal
|
||||
cat ec_private.pem | base64
|
||||
```
|
||||
|
||||
That signing key can be accessed via the well-known jwks endpoint.
|
||||
|
||||
```bash
|
||||
$ curl https://authenticate.int.example.com/.well-known/pomerium/jwks.json | jq
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": [
|
||||
{
|
||||
"use": "sig",
|
||||
"kty": "EC",
|
||||
"kid": "ccc5bc9d835ff3c8f7075ed4a7510159cf440fd7bf7b517b5caeb1fa419ee6a1",
|
||||
"crv": "P-256",
|
||||
"alg": "ES256",
|
||||
"x": "QCN7adG2AmIK3UdHJvVJkldsUc6XeBRz83Z4rXX8Va4",
|
||||
"y": "PI95b-ary66nrvA55TpaiWADq8b3O1CYIbvjqIHpXCY"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If no certificate is specified, one will be generated and the base64'd public key will be added to the logs. Note, however, that this key be unique to each service, ephemeral, and will not be accessible via the authenticate service's `jwks_uri` endpoint.
|
||||
|
||||
|
||||
### Signing Key Algorithm
|
||||
- Environmental Variable: `SIGNING_KEY_ALGORITHM`
|
||||
- Config File Key: `signing_key_algorithm`
|
||||
- Type: `string`
|
||||
- Options: `ES256` or `EdDSA` or `RS256`
|
||||
- Default: `ES256`
|
||||
|
||||
This setting specifies which signing algorithm to use when signing the upstream attestation JWT. Cryptographic algorithm choice is subtle, and beyond the scope of this document, but we suggest sticking to the default `ES256` unless you have a good reason to use something else.
|
||||
|
||||
Be aware that any RSA based signature method may be an order of magnitude lower than [elliptic curve] variants like EdDSA (`ed25519`) and ECDSA (`ES256`). For more information, checkout [this article](https://www.scottbrady91.com/JOSE/JWTs-Which-Signing-Algorithm-Should-I-Use).
|
||||
|
||||
|
||||
## Routes
|
||||
- Environment Variable: `ROUTE`
|
||||
- Config File Key: `route`
|
||||
- Type: `string`
|
||||
- **Required** - While Pomerium will start without a route configured, it will not authorize or proxy any traffic until a route is defined. If configuring Pomerium for the Enterprise Console, define a route for the Console itself in Pomerium.
|
||||
|
||||
A route contains specific access and control definitions for a back-end service. Each route is a list item under the `routes` key.
|
||||
|
||||
Each route defines at minimum a `from` and `to` field, and a `policy` key defining authorization logic. Additional options are listed below.
|
||||
|
||||
<<< @/examples/config/route.example.yaml
|
||||
|
||||
|
||||
### CORS Preflight
|
||||
- `yaml`/`json` setting: `cors_allow_preflight`
|
||||
- Type: `bool`
|
||||
|
|
@ -1186,7 +1288,7 @@ Requires setting [Google Cloud Serverless Authentication Service Account](#googl
|
|||
|
||||
`From` is the externally accessible URL for the proxied request.
|
||||
|
||||
Specifying `tcp+https` for the scheme enables [TCP proxying](../docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
|
||||
Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
|
||||
|
||||
|
||||
### Kubernetes Service Account Token
|
||||
|
|
@ -1585,7 +1687,7 @@ When [`lb_policy`](#load-balancing-policy) is configured, you may further custom
|
|||
- [`ring_hash_lb_config`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#config-cluster-v3-cluster-ringhashlbconfig)
|
||||
- [`maglev_lb_config`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-msg-config-cluster-v3-cluster-maglevlbconfig)
|
||||
|
||||
See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.md#load-balancing-method)
|
||||
See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.html#load-balancing-method)
|
||||
|
||||
|
||||
### Health Checks
|
||||
|
|
@ -1605,104 +1707,10 @@ Only one of `http_health_check`, `tcp_health_check`, or `grpc_health_check` may
|
|||
- [HTTP](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck-httphealthcheck)
|
||||
- [GRPC](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck-grpchealthcheck)
|
||||
|
||||
See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.md#active-health-checks).
|
||||
See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.html#active-health-checks).
|
||||
|
||||
|
||||
### Websocket Connections
|
||||
- Config File Key: `allow_websockets`
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
|
||||
If set, enables proxying of websocket connections.
|
||||
|
||||
:::warning
|
||||
|
||||
**Use with caution:** websockets are long-lived connections, so [global timeouts](#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](https://www.cloudflare.com/learning/ddos/ddos-attack-tools/slowloris/).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
## Authorize Service
|
||||
|
||||
### Authorize Service URL
|
||||
- Environmental Variable: `AUTHORIZE_SERVICE_URL` or `AUTHORIZE_SERVICE_URLS`
|
||||
- Config File Key: `authorize_service_url` or `authorize_service_urls`
|
||||
- Type: `URL`
|
||||
- Required
|
||||
- Example: `https://authorize.corp.example.com`
|
||||
|
||||
Authorize Service URL is the location of the internally accessible authorize service. Multiple URLs can be specified with `authorize_service_url`.
|
||||
|
||||
|
||||
### Google Cloud Serverless Authentication Service Account
|
||||
- Environmental Variable: `GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION_SERVICE_ACCOUNT`
|
||||
- Config File Key: `google_cloud_serverless_authentication_service_account`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Optional
|
||||
|
||||
Manually specify the service account credentials to support GCP's [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) format.
|
||||
|
||||
If unspecified:
|
||||
|
||||
- If [Identity Provider Name](#identity-provider-name) is set to `google`, will default to [Identity Provider Service Account](#identity-provider-service-account)
|
||||
- Otherwise, will default to ambient credentials in the default locations searched by the Google SDK. This includes GCE metadata server tokens.
|
||||
|
||||
|
||||
### Signing Key
|
||||
- Environmental Variable: `SIGNING_KEY`
|
||||
- Config File Key: `signing_key`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Optional
|
||||
|
||||
Signing Key is the private key used to sign a user's attestation JWT which can be consumed by upstream applications to pass along identifying user information like username, id, and groups.
|
||||
|
||||
If set, the signing key's public key will can retrieved by hitting Pomerium's `/.well-known/pomerium/jwks.json` endpoint which lives on the authenticate service. Otherwise, the endpoint will return an empty keyset.
|
||||
|
||||
For example, assuming you have [generated an ES256 key](https://github.com/pomerium/pomerium/blob/master/scripts/generate_self_signed_signing_key.sh) as follows.
|
||||
|
||||
```bash
|
||||
# Generates an P-256 (ES256) signing key
|
||||
openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
|
||||
# careful! this will output your private key in terminal
|
||||
cat ec_private.pem | base64
|
||||
```
|
||||
|
||||
That signing key can be accessed via the well-known jwks endpoint.
|
||||
|
||||
```bash
|
||||
$ curl https://authenticate.int.example.com/.well-known/pomerium/jwks.json | jq
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": [
|
||||
{
|
||||
"use": "sig",
|
||||
"kty": "EC",
|
||||
"kid": "ccc5bc9d835ff3c8f7075ed4a7510159cf440fd7bf7b517b5caeb1fa419ee6a1",
|
||||
"crv": "P-256",
|
||||
"alg": "ES256",
|
||||
"x": "QCN7adG2AmIK3UdHJvVJkldsUc6XeBRz83Z4rXX8Va4",
|
||||
"y": "PI95b-ary66nrvA55TpaiWADq8b3O1CYIbvjqIHpXCY"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If no certificate is specified, one will be generated and the base64'd public key will be added to the logs. Note, however, that this key be unique to each service, ephemeral, and will not be accessible via the authenticate service's `jwks_uri` endpoint.
|
||||
|
||||
|
||||
### Signing Key Algorithm
|
||||
- Environmental Variable: `SIGNING_KEY_ALGORITHM`
|
||||
- Config File Key: `signing_key_algorithm`
|
||||
- Type: `string`
|
||||
- Options: `ES256` or `EdDSA` or `RS256`
|
||||
- Default: `ES256`
|
||||
|
||||
This setting specifies which signing algorithm to use when signing the upstream attestation JWT. Cryptographic algorithm choice is subtle, and beyond the scope of this document, but we suggest sticking to the default `ES256` unless you have a good reason to use something else.
|
||||
|
||||
Be aware that any RSA based signature method may be an order of magnitude lower than [elliptic curve] variants like EdDSA (`ed25519`) and ECDSA (`ES256`). For more information, checkout [this article](https://www.scottbrady91.com/JOSE/JWTs-Which-Signing-Algorithm-Should-I-Use).
|
||||
|
||||
|
||||
[base64 encoded]: https://en.wikipedia.org/wiki/Base64
|
||||
[elliptic curve]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations#Generating_EC_Keys_and_Parameters
|
||||
|
|
@ -1711,7 +1719,7 @@ Be aware that any RSA based signature method may be an order of magnitude lower
|
|||
[json]: https://en.wikipedia.org/wiki/JSON
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[oidc rfc]: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
|
||||
[okta]: /docs/identity-providers/okta.md
|
||||
[okta]: ../docs/identity-providers/okta.md
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[signed headers]: /docs/topics/getting-users-identity.md
|
||||
[toml]: https://en.wikipedia.org/wiki/TOML
|
||||
|
|
|
|||
|
|
@ -29,11 +29,11 @@ postamble: |
|
|||
[base64 encoded]: https://en.wikipedia.org/wiki/Base64
|
||||
[elliptic curve]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations#Generating_EC_Keys_and_Parameters
|
||||
[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
|
||||
[identity provider]: ../docs/identity-providers/
|
||||
[identity provider]: /docs/identity-providers/readme.md
|
||||
[json]: https://en.wikipedia.org/wiki/JSON
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[oidc rfc]: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
|
||||
[okta]: ../docs/identity-providers/okta.md
|
||||
[okta]: /docs/identity-providers/okta.md
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[signed headers]: ../docs/topics/getting-users-identity.md
|
||||
[toml]: https://en.wikipedia.org/wiki/TOML
|
||||
|
|
@ -1195,6 +1195,13 @@ settings:
|
|||
- Type: [base64 encoded] `string` or inline policy structure in config file
|
||||
- **Required** However, pomerium will safely start without a policy configured, but will be unable to authorize or proxy traffic until the configuration is updated to contain a policy.
|
||||
doc: |
|
||||
|
||||
::: warning
|
||||
The `policy` field as a top-level configuration key has been replaced with [`routes`](/reference.html#routes). Moving forward, define policies within each defined route.
|
||||
|
||||
Existing policy definitions will currently behave as expected, but are deprecated and will be removed in a future version of Pomerium.
|
||||
:::
|
||||
|
||||
Policy contains route specific settings, and access control details. If you are configuring via POLICY environment variable, just the contents of the policy needs to be passed. If you are configuring via file, the policy should be present under the policy key. For example,
|
||||
|
||||
<<< @/examples/config/policy.example.yaml
|
||||
|
|
@ -1214,7 +1221,7 @@ settings:
|
|||
|
||||
In this example, an incoming request with a path prefix of `/admin` would be handled by the first route (which is restricted to superusers). All other requests for `from.example.com` would be handled by the second route (which is open to the public).
|
||||
|
||||
A list of policy configuration variables follows.
|
||||
A list of configuration variables specific to `policy` follows Note that this also shares all configuration variables listed under [routes](/reference.html#routes), excluding `policy` and its child variables.
|
||||
settings:
|
||||
- name: "Allowed Domains"
|
||||
keys: ["allowed_domains"]
|
||||
|
|
@ -1271,7 +1278,6 @@ settings:
|
|||
|
||||
- Nested maps are flattened: `{ "a": { "b": ["c"] } }` becomes `{ "a.b": ["c"] }`
|
||||
- Values are always a list: `{ "a": "b" }` becomes `{ "a": ["b"] }`
|
||||
|
||||
- name: "Allowed Users"
|
||||
keys: ["allowed_users"]
|
||||
attributes: |
|
||||
|
|
@ -1281,6 +1287,108 @@ settings:
|
|||
- Example: `alice@pomerium.io` , `bob@contractor.co`
|
||||
doc: |
|
||||
Allowed users is a collection of whitelisted users to authorize for a given route.
|
||||
- name: "Authorize Service"
|
||||
settings:
|
||||
- name: "Authorize Service URL"
|
||||
keys: ["authorize_service_url"]
|
||||
attributes: |
|
||||
- Environmental Variable: `AUTHORIZE_SERVICE_URL` or `AUTHORIZE_SERVICE_URLS`
|
||||
- Config File Key: `authorize_service_url` or `authorize_service_urls`
|
||||
- Type: `URL`
|
||||
- Required
|
||||
- Example: `https://authorize.corp.example.com`
|
||||
doc: |
|
||||
Authorize Service URL is the location of the internally accessible authorize service. Multiple URLs can be specified with `authorize_service_url`.
|
||||
shortdoc: |
|
||||
Authorize Service URL is the location of the internally accessible authorize service.
|
||||
- name: "Google Cloud Serverless Authentication Service Account"
|
||||
keys: ["google_cloud_serverless_authentication_service_account"]
|
||||
attributes: |
|
||||
- Environmental Variable: `GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION_SERVICE_ACCOUNT`
|
||||
- Config File Key: `google_cloud_serverless_authentication_service_account`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Optional
|
||||
doc: |
|
||||
Manually specify the service account credentials to support GCP's [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) format.
|
||||
|
||||
If unspecified:
|
||||
|
||||
- If [Identity Provider Name](#identity-provider-name) is set to `google`, will default to [Identity Provider Service Account](#identity-provider-service-account)
|
||||
- Otherwise, will default to ambient credentials in the default locations searched by the Google SDK. This includes GCE metadata server tokens.
|
||||
- name: "Signing Key"
|
||||
keys: ["signing_key"]
|
||||
attributes: |
|
||||
- Environmental Variable: `SIGNING_KEY`
|
||||
- Config File Key: `signing_key`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Optional
|
||||
doc: |
|
||||
Signing Key is the private key used to sign a user's attestation JWT which can be consumed by upstream applications to pass along identifying user information like username, id, and groups.
|
||||
|
||||
If set, the signing key's public key will can retrieved by hitting Pomerium's `/.well-known/pomerium/jwks.json` endpoint which lives on the authenticate service. Otherwise, the endpoint will return an empty keyset.
|
||||
|
||||
For example, assuming you have [generated an ES256 key](https://github.com/pomerium/pomerium/blob/master/scripts/generate_self_signed_signing_key.sh) as follows.
|
||||
|
||||
```bash
|
||||
# Generates an P-256 (ES256) signing key
|
||||
openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
|
||||
# careful! this will output your private key in terminal
|
||||
cat ec_private.pem | base64
|
||||
```
|
||||
|
||||
That signing key can be accessed via the well-known jwks endpoint.
|
||||
|
||||
```bash
|
||||
$ curl https://authenticate.int.example.com/.well-known/pomerium/jwks.json | jq
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": [
|
||||
{
|
||||
"use": "sig",
|
||||
"kty": "EC",
|
||||
"kid": "ccc5bc9d835ff3c8f7075ed4a7510159cf440fd7bf7b517b5caeb1fa419ee6a1",
|
||||
"crv": "P-256",
|
||||
"alg": "ES256",
|
||||
"x": "QCN7adG2AmIK3UdHJvVJkldsUc6XeBRz83Z4rXX8Va4",
|
||||
"y": "PI95b-ary66nrvA55TpaiWADq8b3O1CYIbvjqIHpXCY"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If no certificate is specified, one will be generated and the base64'd public key will be added to the logs. Note, however, that this key be unique to each service, ephemeral, and will not be accessible via the authenticate service's `jwks_uri` endpoint.
|
||||
shortdoc: |
|
||||
Signing Key is the key used to sign a user's attestation JWT which can be consumed by upstream applications to pass along identifying user information like username, id, and groups.
|
||||
- name: "Signing Key Algorithm"
|
||||
keys: ["signing_key_algorithm"]
|
||||
attributes: |
|
||||
- Environmental Variable: `SIGNING_KEY_ALGORITHM`
|
||||
- Config File Key: `signing_key_algorithm`
|
||||
- Type: `string`
|
||||
- Options: `ES256` or `EdDSA` or `RS256`
|
||||
- Default: `ES256`
|
||||
doc: |
|
||||
This setting specifies which signing algorithm to use when signing the upstream attestation JWT. Cryptographic algorithm choice is subtle, and beyond the scope of this document, but we suggest sticking to the default `ES256` unless you have a good reason to use something else.
|
||||
|
||||
Be aware that any RSA based signature method may be an order of magnitude lower than [elliptic curve] variants like EdDSA (`ed25519`) and ECDSA (`ES256`). For more information, checkout [this article](https://www.scottbrady91.com/JOSE/JWTs-Which-Signing-Algorithm-Should-I-Use).
|
||||
shortdoc: |
|
||||
Signing Key Algorithm is the algorithm used to sign a user's attestation JWT.
|
||||
- name: "Routes"
|
||||
keys: ["routes"]
|
||||
attributes: |
|
||||
- Environment Variable: `ROUTE`
|
||||
- Config File Key: `route`
|
||||
- Type: `string`
|
||||
- **Required** - While Pomerium will start without a route configured, it will not authorize or proxy any traffic until a route is defined. If configuring Pomerium for the Enterprise Console, define a route for the Console itself in Pomerium.
|
||||
doc: |
|
||||
A route contains specific access and control definitions for a back-end service. Each route is a list item under the `routes` key.
|
||||
|
||||
Each route defines at minimum a `from` and `to` field, and a `policy` key defining authorization logic. Additional options are listed below.
|
||||
|
||||
<<< @/examples/config/route.example.yaml
|
||||
settings:
|
||||
- name: "CORS Preflight"
|
||||
keys: ["cors_allow_preflight"]
|
||||
attributes: |
|
||||
|
|
@ -1751,105 +1859,4 @@ settings:
|
|||
|
||||
See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.html#active-health-checks).
|
||||
|
||||
- name: "Websocket Connections"
|
||||
keys: ["allow_websockets"]
|
||||
attributes: |
|
||||
- Config File Key: `allow_websockets`
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
doc: |
|
||||
If set, enables proxying of websocket connections.
|
||||
|
||||
:::warning
|
||||
|
||||
**Use with caution:** websockets are long-lived connections, so [global timeouts](#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](https://www.cloudflare.com/learning/ddos/ddos-attack-tools/slowloris/).
|
||||
|
||||
:::
|
||||
- name: "Authorize Service"
|
||||
settings:
|
||||
- name: "Authorize Service URL"
|
||||
keys: ["authorize_service_url"]
|
||||
attributes: |
|
||||
- Environmental Variable: `AUTHORIZE_SERVICE_URL` or `AUTHORIZE_SERVICE_URLS`
|
||||
- Config File Key: `authorize_service_url` or `authorize_service_urls`
|
||||
- Type: `URL`
|
||||
- Required
|
||||
- Example: `https://authorize.corp.example.com`
|
||||
doc: |
|
||||
Authorize Service URL is the location of the internally accessible authorize service. Multiple URLs can be specified with `authorize_service_url`.
|
||||
shortdoc: |
|
||||
Authorize Service URL is the location of the internally accessible authorize service.
|
||||
- name: "Google Cloud Serverless Authentication Service Account"
|
||||
keys: ["google_cloud_serverless_authentication_service_account"]
|
||||
attributes: |
|
||||
- Environmental Variable: `GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION_SERVICE_ACCOUNT`
|
||||
- Config File Key: `google_cloud_serverless_authentication_service_account`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Optional
|
||||
doc: |
|
||||
Manually specify the service account credentials to support GCP's [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) format.
|
||||
|
||||
If unspecified:
|
||||
|
||||
- If [Identity Provider Name](#identity-provider-name) is set to `google`, will default to [Identity Provider Service Account](#identity-provider-service-account)
|
||||
- Otherwise, will default to ambient credentials in the default locations searched by the Google SDK. This includes GCE metadata server tokens.
|
||||
- name: "Signing Key"
|
||||
keys: ["signing_key"]
|
||||
attributes: |
|
||||
- Environmental Variable: `SIGNING_KEY`
|
||||
- Config File Key: `signing_key`
|
||||
- Type: [base64 encoded] `string`
|
||||
- Optional
|
||||
doc: |
|
||||
Signing Key is the private key used to sign a user's attestation JWT which can be consumed by upstream applications to pass along identifying user information like username, id, and groups.
|
||||
|
||||
If set, the signing key's public key will can retrieved by hitting Pomerium's `/.well-known/pomerium/jwks.json` endpoint which lives on the authenticate service. Otherwise, the endpoint will return an empty keyset.
|
||||
|
||||
For example, assuming you have [generated an ES256 key](https://github.com/pomerium/pomerium/blob/master/scripts/generate_self_signed_signing_key.sh) as follows.
|
||||
|
||||
```bash
|
||||
# Generates an P-256 (ES256) signing key
|
||||
openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
|
||||
# careful! this will output your private key in terminal
|
||||
cat ec_private.pem | base64
|
||||
```
|
||||
|
||||
That signing key can be accessed via the well-known jwks endpoint.
|
||||
|
||||
```bash
|
||||
$ curl https://authenticate.int.example.com/.well-known/pomerium/jwks.json | jq
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": [
|
||||
{
|
||||
"use": "sig",
|
||||
"kty": "EC",
|
||||
"kid": "ccc5bc9d835ff3c8f7075ed4a7510159cf440fd7bf7b517b5caeb1fa419ee6a1",
|
||||
"crv": "P-256",
|
||||
"alg": "ES256",
|
||||
"x": "QCN7adG2AmIK3UdHJvVJkldsUc6XeBRz83Z4rXX8Va4",
|
||||
"y": "PI95b-ary66nrvA55TpaiWADq8b3O1CYIbvjqIHpXCY"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If no certificate is specified, one will be generated and the base64'd public key will be added to the logs. Note, however, that this key be unique to each service, ephemeral, and will not be accessible via the authenticate service's `jwks_uri` endpoint.
|
||||
shortdoc: |
|
||||
Signing Key is the key used to sign a user's attestation JWT which can be consumed by upstream applications to pass along identifying user information like username, id, and groups.
|
||||
- name: "Signing Key Algorithm"
|
||||
keys: ["signing_key_algorithm"]
|
||||
attributes: |
|
||||
- Environmental Variable: `SIGNING_KEY_ALGORITHM`
|
||||
- Config File Key: `signing_key_algorithm`
|
||||
- Type: `string`
|
||||
- Options: `ES256` or `EdDSA` or `RS256`
|
||||
- Default: `ES256`
|
||||
doc: |
|
||||
This setting specifies which signing algorithm to use when signing the upstream attestation JWT. Cryptographic algorithm choice is subtle, and beyond the scope of this document, but we suggest sticking to the default `ES256` unless you have a good reason to use something else.
|
||||
|
||||
Be aware that any RSA based signature method may be an order of magnitude lower than [elliptic curve] variants like EdDSA (`ed25519`) and ECDSA (`ES256`). For more information, checkout [this article](https://www.scottbrady91.com/JOSE/JWTs-Which-Signing-Algorithm-Should-I-Use).
|
||||
shortdoc: |
|
||||
Signing Key Algorithm is the algorithm used to sign a user's attestation JWT.
|
||||
- name: "Websocket Connections"
|
||||
40
examples/config/route-example.yml
Normal file
40
examples/config/route-example.yml
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# This file contains only route and policy configuration details. Other
|
||||
# configuration settings required by pomerium are excluded for clarity.
|
||||
# See: https://www.pomerium.io/docs/reference/reference/
|
||||
#
|
||||
# For a complete self contained configuration see : config.example.yaml.
|
||||
# Or, mix and match a policy file (this) with env vars : config.example.env
|
||||
|
||||
routes:
|
||||
- from: https://verify.localhost.pomerium.io
|
||||
to: http://localhost:8000
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- domain:
|
||||
is: pomerium.io
|
||||
cors_allow_preflight: true
|
||||
timeout: 30s
|
||||
- from: https://external-verify.localhost.pomerium.io
|
||||
to: https://verify.pomerium.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- domain:
|
||||
is: gmail.com
|
||||
- from: https://weirdlyssl.localhost.pomerium.io
|
||||
to: http://neverssl.com
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
email:
|
||||
is: bdd@pomerium.io
|
||||
groups:
|
||||
has: ["admins", "developers"]
|
||||
- from: https://hello.localhost.pomerium.io
|
||||
to: http://localhost:8080
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- groups:
|
||||
has: ["admins@pomerium.io"]
|
||||
Loading…
Add table
Reference in a new issue