sso_*: various documentation additions (buzzfeed#315)

* sso_*: documentation touch ups

* sso_proxy: add some headings

* fix indentation

* typo alert

Author: Jusshersmith

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 <identifier>** 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.
 

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
+```

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
 //

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