From a1b1b74c2e6448f9e05efdbcf3e2b6920fe0c6a5 Mon Sep 17 00:00:00 2001 From: Jack Ussher-Smith Date: Tue, 6 Jul 2021 15:22:17 +0100 Subject: [PATCH] sso_*: various documentation additions (#315) * sso_*: documentation touch ups * sso_proxy: add some headings * fix indentation * typo alert --- docs/sso_config.md | 18 +++++--- docs/sso_proxy_config.md | 75 +++++++++++++++++++++++++++++++++ internal/proxy/configuration.go | 2 +- quickstart/docker-compose.yml | 2 +- 4 files changed, 88 insertions(+), 9 deletions(-) create mode 100644 docs/sso_proxy_config.md diff --git a/docs/sso_config.md b/docs/sso_config.md index 21be1df5..0c90b320 100644 --- a/docs/sso_config.md +++ b/docs/sso_config.md @@ -32,11 +32,11 @@ For example, the following config would have the following environment variables * **to** is the cname of the proxied service (this tells sso proxy where to proxy requests that come in on the from field) * **type** declares the type of route to use, right now there is just *simple* and *rewrite*. * **options** are a set of options that can be added to your configuration. - * **allowed groups** optional list of authorized google groups that can access the service. If not specified, anyone within an email domain is allowed to access the service. *Note*: We do not support nested group authentication at this time. Groups must be made up of email addresses associated with individual's accounts. See [#133](https://github.com/buzzfeed/sso/issues/133). - * **allowed_email_domains** optional list of authorized email domains that can access the service. - * **allowed_email_addresses** optional list of authorized email addresses that can access the service. + * **allowed_groups** optional list of authorized google groups that can access the service. *Note*: We do not support nested group authentication at this time. Groups must be made up of email addresses associated with individual's accounts. See [#133](https://github.com/buzzfeed/sso/issues/133). + * **allowed_email_domains** optional list of authorized email domains that can access the service. Set to `*` to allow any email domain. + * **allowed_email_addresses** optional list of authorized email addresses that can access the service. Set to `*` to allow any email address. * **flush_interval** sets an interval to periodically flush the buffered response to the client. If specified, SSO Proxy will not timeout requests to this upstream and will stream the response to the client. NOTE: Use with extreme caution. - * **header_overrides** overrides any heads set either by SSO proxy itself or upstream applications. Useful for modifying browser security headers. + * **header_overrides** overrides any headers set either by SSO proxy itself or upstream applications. Useful for modifying browser security headers. * **inject_request_headers** adds headers to the request before the request is sent to the proxied service. Useful for adding basic auth headers if needed. * **provider_slug** determines which identity provider this upstream will use. This provider must first be configured within `sso_auth`. * **skip_auth_regex** skips authentication for paths matching these regular expressions. NOTE: Use with extreme caution. @@ -45,6 +45,9 @@ For example, the following config would have the following environment variables from their parent routing config if not specified here (e.g. *options*). * **cluster name ** are cluster-specific settings. Any configuration specified in the default field can be override here with cluster specific configuration. +Note: From the perspective of request validations, if a request meets the requirements set in any of `allowed_groups`, `allowed_email_domains`, and `allowed_email_addresses`, +then it will be deemed valid. It need only pass _one_, not all of them. + ### Route Types There are currently two route types used by SSO to route requests, *simple* and *rewrite*. @@ -99,7 +102,7 @@ export SSO_CONFIG_FOOBAR_SIGNING_KEY="sha256:shared-secret-value" ``` would be the signing key for the `foobar` upstream service, use the sha256 with the `shared-secret-value` as it's signing key value. -This signs the request using defined signature headers found in https://github.com/buzzfeed/sso/blob/main/sso_proxy/oauthproxy.go#L25. +This signs the request using defined signature headers found in the `SignatureHeaders` variable at https://github.com/buzzfeed/sso/blob/main/internal/proxy/oauthproxy.go#L27-L39. Specific implementation details can be found at https://github.com/18F/hmacauth ### Headers @@ -120,7 +123,8 @@ Optional: #### Security Headers -`sso_proxy` adds the following headers to every outgoing request, to ensure a baseline level of browser security for every service that it protects. These headers _cannot_ be overridden by upstream services, but _can_ be overridden in the `HEADER_OVERRIDES` environment variable. +`sso_proxy` adds the following headers to every outgoing request, to ensure a baseline level of browser security for every service that it protects. +These headers _cannot_ be overridden by upstream services themselves, but _can_ be overridden in invdividual upstream configurations by setting the `header_overrides` variable. * `Strict-Transport-Security` * `X-Content-Type-Options` @@ -144,7 +148,7 @@ The **session\_ttl\_valid** option controls the amount of time it will take for will make an _internal request_ to `sso_auth` (i.e. invisible to the end user) to revalidate & refresh the session. -The **sessioni\_ttl\_lifetime** option controls the maximum lifetime of a +The **session\_ttl\_lifetime** option controls the maximum lifetime of a `sso_proxy` session, after which a user will be 301 redirected to `sso_auth` to go through the 3rd party OAuth2 flow again. diff --git a/docs/sso_proxy_config.md b/docs/sso_proxy_config.md new file mode 100644 index 00000000..fb576fe8 --- /dev/null +++ b/docs/sso_proxy_config.md @@ -0,0 +1,75 @@ +# Available Configuration Variables +We currently use environment variables to read configuration options, below is a list of environment variables and +their corresponding types that the sso proxy will read. + +Defaults for the below settings can be found here: https://github.com/buzzfeed/sso/blob/main/internal/proxy/configuration.go#L61-L105 + + +## Session and Server configuration + +### Session +``` +SESSION_COOKIE_NAME - string - name associated with the session cookie +SESSION_COOKIE_SECRET - string - seed string for secure cookies +SESSION_COOKIE_DOMAIN - string - cookie domain to force cookies to (ie: .yourcompany.com)* +SESSION_COOKIE_SECURE - bool - set secure (HTTPS) cookie flag +SESSION_COOKIE_HTTPONLY - bool - set 'httponly' cookie flag +SESSION_TTL_LIFETIME - time.Duration - 'time-to-live' of a session lifetime +SESSION_TTL_VALID - time.Duration - 'time-to-live' of a valid session +SESSION_TTL_GRACEPERIOD - time.Duration - time period in which session data can be reused while the provider is unavailable. +``` + +### Server +``` +SERVER_PORT - string - port the http server listens on +SERVER_TIMEOUT_SHUTDOWN - time.Duration - time to allow in-flight requests to complete before server shutdown +SERVER_TIMEOUT_READ - time.Duration - read request timeout +SERVER_TIMEOUT_WRITE - time.Duration - write request timeout +``` + +### Client +``` +CLIENT_ID - string - the OAuth Client ID: ie: "123456.apps.googleusercontent.com" +CLIENT_SECRET - string - the OAuth Client secret +``` + +### Request Signer +``` +REQUESTSIGNER_KEY - string - RSA private key used for digitally signing requests +``` + +## Upstream and Provider Configuration + +### Upstream +For further upstream configuration, see https://github.com/buzzfeed/sso/blob/main/docs/sso_config.md. +``` +UPSTREAM_DEFAULT_EMAIL_DOMAINS - []string - default setting for upstream `allowed_email_domains` variable +UPSTREAM_DEFAULT_EMAIL_ADDRESSES - []string - default setting for upstream `allowed_email_addresses` variable +UPSTREAM_DEFAULT_GROUPS - []string - default setting for upstream `allowed groups` variable +UPSTREAM_DEFAULT_TIMEOUT - time.Duration - default setting for upstream `timeout` variable +UPSTREAM_DEFAULT_TCP_RESET_DEADLINE - time.Duration - default time period to wait for a response from an upstream +UPSTREAM_DEFAULT_PROVIDER - string - default setting for the upstream `provider_slug` variable +UPSTREAM_CONFIGS_FILE - string - path to the file containing upstream configurations +UPSTREAM_SCHEME - string - the scheme used for upstreams (e.g. `https`) +UPSTREAM_CLUSTER - string - the cluster in which this is running, used within upstream configuration +``` + +## Provider +``` +PROVIDER_TYPE - string - string - the 'type' of upstream provider to use (at this time, only a provider type of 'sso' is supported) +PROVIDER_URL_EXTERNAL - string - the external URL for the upstream provider in this environment (e.g. "https://sso-auth.example.com") +PROVIDER_URL_INTERNAL - string - the internal URL for the upstream provider in this environment (e.g. "https://sso-auth-int.example.com") +PROVIDER_SCOPE - string - OAuth `scope` sent with provider requests +``` + +## Logging and Monitoring Configuration +### StatsD +``` +METRICS_STATSD_PORT - int - port that statsdclient listens on +METRICS_STATSD_HOST - string - hostname that statsd client uses +``` + +### Logging +``` +LOGGING_ENABLE - bool - enable request logging +``` diff --git a/internal/proxy/configuration.go b/internal/proxy/configuration.go index 82f6bf16..8c39e1a5 100644 --- a/internal/proxy/configuration.go +++ b/internal/proxy/configuration.go @@ -49,7 +49,7 @@ import ( // UPSTREAM_DEFAULT_TIMEOUT // UPSTREAM_DEFAULT_TCP_RESET_DEADLINE // UPSTREAM_DEFAULT_PROVIDER -// UPSTREAM_CONFIGS_FILE +// UPSTREAM_CONFIGFILE // UPSTREAM_SCHEME // UPSTREAM_CLUSTER // diff --git a/quickstart/docker-compose.yml b/quickstart/docker-compose.yml index b6dedf64..c76a7c14 100644 --- a/quickstart/docker-compose.yml +++ b/quickstart/docker-compose.yml @@ -34,7 +34,7 @@ services: # (Optional) Allow specific google email address to log in for demo purposes # - UPSTREAM_DEFAULT_EMAIL_ADDRESSES=* - - UPSTREAM_CONFIGSFILE=/sso/upstream_configs.yml + - UPSTREAM_CONFIGFILE=/sso/upstream_configs.yml - PROVIDER_URL_EXTERNAL=http://sso-auth.localtest.me - PROVIDER_URL_INTERNAL=http://host.docker.internal