3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-07-05 19:08:03 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: document service account requirements (#999)

Browse source
This commit is contained in:
Travis Groth 2020-06-25 19:32:36 -04:00 • committed by GitHub
parent 917d8ec61b
commit c049d87362
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 59 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/configuration/examples/config/config.example.env
View file

@ -40,10 +40,6 @@ export COOKIE_SECRET="$(head -c32 /dev/urandom | base64)"
export IDP_PROVIDER="google" export IDP_PROVIDER="google"
export IDP_PROVIDER_URL="https://accounts.google.com" # optional for google export IDP_PROVIDER_URL="https://accounts.google.com" # optional for google
# IF GSUITE and you want to get user groups you will need to set a service account
# see identity provider docs for gooogle for more info :
# export IDP_SERVICE_ACCOUNT=$(echo '{"impersonate_user": "bdd@pomerium.io"}' | base64)
# OKTA # OKTA
# export IDP_PROVIDER="okta" # export IDP_PROVIDER="okta"
# export IDP_CLIENT_ID="REPLACEME" # export IDP_CLIENT_ID="REPLACEME"
@ -62,3 +58,7 @@ export IDP_PROVIDER_URL="https://accounts.google.com" # optional for google
# directly as a base64 encoded yaml/json file, or as the policy key in the configuration # directly as a base64 encoded yaml/json file, or as the policy key in the configuration
# file # file
export POLICY="$(base64 ./docs/configuration/examples/config/policy.example.yaml)" export POLICY="$(base64 ./docs/configuration/examples/config/policy.example.yaml)"
# For Group data you must set an IDP_SERVICE_ACCOUNT
# https://www.pomerium.com/configuration/#identity-provider-service-account
# export IDP_SERVICE_ACCOUNT=$( echo YOUR_SERVICE_ACCOUNT | base64)

3
docs/configuration/examples/config/config.example.yaml
View file

@ -64,6 +64,9 @@ authenticate_service_url: https://authenticate.corp.beyondperimeter.com
# scope: "openid email" # generally, you want the default OIDC scopes # scope: "openid email" # generally, you want the default OIDC scopes
# For Group data you must set an IDP_SERVICE_ACCOUNT
# idp_service_account: YOUR_SERVICE_ACCOUNT
# Proxied routes and per-route policies are defined in a policy block # Proxied routes and per-route policies are defined in a policy block
policy: policy:
- from: https://httpbin.corp.beyondperimeter.com - from: https://httpbin.corp.beyondperimeter.com

3
docs/configuration/examples/kubernetes/kubernetes-config.yaml
View file

@ -13,6 +13,9 @@ override_certificate_name: "*.corp.beyondperimeter.com"
idp_provider: google idp_provider: google
idp_client_id: REPLACE_ME.apps.googleusercontent.com idp_client_id: REPLACE_ME.apps.googleusercontent.com
idp_client_secret: "REPLACE_ME" idp_client_secret: "REPLACE_ME"
# Required for group data
# https://www.pomerium.com/configuration/#identity-provider-service-account
idp_service_account: YOUR_SERVICE_ACCOUNT
policy: policy:
- from: https://httpbin.corp.beyondperimeter.com - from: https://httpbin.corp.beyondperimeter.com

3
docs/configuration/examples/kubernetes/values.yaml
View file

@ -3,6 +3,9 @@ authenticate:
provider: "google" provider: "google"
clientID: YOUR_CLIENT_ID clientID: YOUR_CLIENT_ID
clientSecret: YOUR_SECRET clientSecret: YOUR_SECRET
# Required for group data
# https://www.pomerium.com/configuration/#identity-provider-service-account
serviceAccount: YOUR_SERVICE_ACCOUNT
service: service:
annotations: annotations:
cloud.google.com/app-protocols: '{"https":"HTTPS"}' cloud.google.com/app-protocols: '{"https":"HTTPS"}'

72
docs/configuration/readme.md
View file

@ -456,28 +456,28 @@ Expose a prometheus format HTTP endpoint on the specified port. Disabled by defa
#### Pomerium Metrics Tracked #### Pomerium Metrics Tracked
Name | Type | Description | Name | Type | Description |
--------------------------------------------- | --------- | ----------------------------------------------------------------------- | --------------------------------------------- | --------- | ----------------------------------------------------------------------- |
grpc_client_request_duration_ms | Histogram | GRPC client request duration by service | grpc_client_request_duration_ms | Histogram | GRPC client request duration by service |
grpc_client_request_size_bytes | Histogram | GRPC client request size by service | grpc_client_request_size_bytes | Histogram | GRPC client request size by service |
grpc_client_requests_total | Counter | Total GRPC client requests made by service | grpc_client_requests_total | Counter | Total GRPC client requests made by service |
grpc_client_response_size_bytes | Histogram | GRPC client response size by service | grpc_client_response_size_bytes | Histogram | GRPC client response size by service |
grpc_server_request_duration_ms | Histogram | GRPC server request duration by service | grpc_server_request_duration_ms | Histogram | GRPC server request duration by service |
grpc_server_request_size_bytes | Histogram | GRPC server request size by service | grpc_server_request_size_bytes | Histogram | GRPC server request size by service |
grpc_server_requests_total | Counter | Total GRPC server requests made by service | grpc_server_requests_total | Counter | Total GRPC server requests made by service |
grpc_server_response_size_bytes | Histogram | GRPC server response size by service | grpc_server_response_size_bytes | Histogram | GRPC server response size by service |
http_client_request_duration_ms | Histogram | HTTP client request duration by service | http_client_request_duration_ms | Histogram | HTTP client request duration by service |
http_client_request_size_bytes | Histogram | HTTP client request size by service | http_client_request_size_bytes | Histogram | HTTP client request size by service |
http_client_requests_total | Counter | Total HTTP client requests made by service | http_client_requests_total | Counter | Total HTTP client requests made by service |
http_client_response_size_bytes | Histogram | HTTP client response size by service | http_client_response_size_bytes | Histogram | HTTP client response size by service |
http_server_request_duration_ms | Histogram | HTTP server request duration by service | http_server_request_duration_ms | Histogram | HTTP server request duration by service |
http_server_request_size_bytes | Histogram | HTTP server request size by service | http_server_request_size_bytes | Histogram | HTTP server request size by service |
http_server_requests_total | Counter | Total HTTP server requests handled by service | http_server_requests_total | Counter | Total HTTP server requests handled by service |
http_server_response_size_bytes | Histogram | HTTP server response size by service | http_server_response_size_bytes | Histogram | HTTP server response size by service |
pomerium_build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion | pomerium_build_info | Gauge | Pomerium build metadata by git revision, service, version and goversion |
pomerium_config_checksum_int64 | Gauge | Currently loaded configuration checksum by service | pomerium_config_checksum_int64 | Gauge | Currently loaded configuration checksum by service |
pomerium_config_last_reload_success | Gauge | Whether the last configuration reload succeeded by service | pomerium_config_last_reload_success | Gauge | Whether the last configuration reload succeeded by service |
pomerium_config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service | pomerium_config_last_reload_success_timestamp | Gauge | The timestamp of the last successful configuration reload by service |
#### Envoy Proxy Metrics #### Envoy Proxy Metrics
@ -526,10 +526,10 @@ Each unit work is called a Span in a trace. Spans include metadata about the wor
#### Shared Tracing Settings #### Shared Tracing Settings
Config Key | Description | Required | Config Key | Description | Required |
:------------------ | :----------------------------------------------------------------------------------- | -------- | :------------------ | :----------------------------------------------------------------------------------- | -------- |
tracing_provider | The name of the tracing provider. (e.g. jaeger, zipkin) | ✅ | tracing_provider | The name of the tracing provider. (e.g. jaeger, zipkin) | ✅ |
tracing_sample_rate | Percentage of requests to sample in decimal notation. Default is `0.0001`, or `.01%` | ❌ | tracing_sample_rate | Percentage of requests to sample in decimal notation. Default is `0.0001`, or `.01%` | ❌ |
#### Jaeger (partial) #### Jaeger (partial)
@ -543,10 +543,10 @@ tracing_sample_rate | Percentage of requests to sample in decimal notation. Defa
- Service dependency analysis - Service dependency analysis
- Performance / latency optimization - Performance / latency optimization
Config Key | Description | Required | Config Key | Description | Required |
:-------------------------------- | :------------------------------------------ | -------- | :-------------------------------- | :------------------------------------------ | -------- |
tracing_jaeger_collector_endpoint | Url to the Jaeger HTTP Thrift collector. | ✅ | tracing_jaeger_collector_endpoint | Url to the Jaeger HTTP Thrift collector. | ✅ |
tracing_jaeger_agent_endpoint | Send spans to jaeger-agent at this address. | ✅ | tracing_jaeger_agent_endpoint | Send spans to jaeger-agent at this address. | ✅ |
#### Zipkin #### Zipkin
@ -554,9 +554,9 @@ Zipkin is an open source distributed tracing system and protocol.
Many tracing backends support zipkin either directly or through intermediary agents, including Jaeger. For full tracing support, we recommend using the Zipkin tracing protocol. Many tracing backends support zipkin either directly or through intermediary agents, including Jaeger. For full tracing support, we recommend using the Zipkin tracing protocol.
Config Key | Description | Required | Config Key | Description | Required |
:---------------------- | :------------------------------- | -------- | :---------------------- | :------------------------------- | -------- |
tracing_zipkin_endpoint | Url to the Zipkin HTTP endpoint. | ✅ | tracing_zipkin_endpoint | Url to the Zipkin HTTP endpoint. | ✅ |
#### Example #### Example
@ -637,9 +637,11 @@ Identity provider scopes correspond to access privilege scopes as defined in Sec
- Environmental Variable: `IDP_SERVICE_ACCOUNT` - Environmental Variable: `IDP_SERVICE_ACCOUNT`
- Config File Key: `idp_service_account` - Config File Key: `idp_service_account`
- Type: `string` - Type: `string`
- Required, depending on provider - Required for group based policies
Identity Provider Service Account is field used to configure any additional user account or access-token that may be required for querying additional user information during authentication. For a concrete example, Google an additional service account and to make a follow-up request to query a user's group membership. For more information, refer to the [identity provider] docs to see if your provider requires this setting. Identity Provider Service Account is field used to configure any additional user account or access-token that may be required for querying additional user information during authentication.
**All group membership from an IdP is queried via service account.**
### Identity Provider URL ### Identity Provider URL

11
docs/docs/identity-providers/readme.md
View file

@ -16,11 +16,18 @@ In this guide we'll cover how to do the following for each identity provider:
1. Set a **[Redirect URL](https://www.oauth.com/oauth2-servers/redirect-uris/)** pointing back to Pomerium. For example, `https://${authenticate_service_url}/oauth2/callback`. 1. Set a **[Redirect URL](https://www.oauth.com/oauth2-servers/redirect-uris/)** pointing back to Pomerium. For example, `https://${authenticate_service_url}/oauth2/callback`.
2. Generate a **[Client ID]** and **[Client Secret]**. 2. Generate a **[Client ID]** and **[Client Secret]**.
3. Configure Pomerium to use the **[Client ID]** and **[Client Secret]** keys. 3. Generate a **[Service Account]** for additional IdP Data.
4. Configure Pomerium to synchronize directory data from your identity provider (e.g. groups membership), by setting a service account. 4. Configure Pomerium to use the **[Client ID]** and **[Client Secret]** keys.
5. Configure Pomerium to synchronize directory data from your identity provider (e.g. groups membership), by setting a service account.
:::warning
You must configure an IdP **[Service Account]** to write policy against group membership, or any other data that does not uniquely identify an end-user.
[client id]: ../../configuration/readme.md#identity-provider-client-id [client id]: ../../configuration/readme.md#identity-provider-client-id
[client secret]: ../../configuration/readme.md#identity-provider-client-secret [client secret]: ../../configuration/readme.md#identity-provider-client-secret
[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
[oauth2]: https://oauth.net/2/ [oauth2]: https://oauth.net/2/
[openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect
[service account]: ../../configuration/#identity-provider-service-account