additional docs - almost finished

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*.
@@ -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`

docs/sso_proxy_config.md

@@ -0,0 +1,70 @@
+# 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
+```
+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
+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 -
+PROVIDER_URL_EXTERNAL  - string - the external URL for the upstream provider in this envrironment (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
+```
+
+### 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
+```