From 11602c42d52801e87ac14eada2ea685d27b396e8 Mon Sep 17 00:00:00 2001 From: Jusshersmith Date: Wed, 7 Aug 2019 14:03:48 +0100 Subject: [PATCH] docs: add sso_auth env var list and update google docs --- docs/google_provider_setup.md | 5 +- docs/sso_authenticator_config.md | 93 ++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 docs/sso_authenticator_config.md diff --git a/docs/google_provider_setup.md b/docs/google_provider_setup.md index db5bb1a8..dc53bdd5 100644 --- a/docs/google_provider_setup.md +++ b/docs/google_provider_setup.md @@ -127,8 +127,9 @@ variables together for any one provider. This can be changed to an identifier th sense for your individual use case. If following the quickstart, make sure this identifier matches what you used there. -- **`PROVIDER_GOOGLEQUICKSTART_GOOGLE_IMPERSONATE`**: An administrative email address on your organization's +- **`PROVIDER_GOOGLEQUICKSTART_GOOGLE_IMPERSONATE`**: (string) An administrative email address on your organization's domain, the identity of which can be assumed by `sso`. -- **`PROVIDER_GOOGLEQUICKSTART_GOOGLE_CREDENTIALS`**: The path to the JSON file downloaded at the time of +- **`PROVIDER_GOOGLEQUICKSTART_GOOGLE_CREDENTIALS`**: (string) The path to the JSON file downloaded at the time of service account creation above. There is no reason why this file should ever be accessed by any person or service other than `sso`; ensure that file permissions are set accordingly. +- **`PROVIDER_GOOGLEQUICKSTART_GROUPCACHE_INTERVAL_REFRESH`**: (time.Duration - default: `10m`) The interval the group cache should refresh at. #TODO:set default/test? diff --git a/docs/sso_authenticator_config.md b/docs/sso_authenticator_config.md new file mode 100644 index 00000000..d3b2361e --- /dev/null +++ b/docs/sso_authenticator_config.md @@ -0,0 +1,93 @@ +# 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 authenticator will read. + +Defaults for the below settings can be found here: https://github.com/buzzfeed/sso/blob/master/internal/auth/configuration.go#L66-L111 + + +## 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_KEY - string - seed string for secure auth codes +SESSION_COOKIE_SECURE - bool - set secure (HTTPS) cookie flag +SESSION_COOKIE_HTTPONLY - bool - set 'httponly' cookie flag +SESSION_COOKIE_REFRESH - time.Duration - duration to refresh the cookie after +SESSION_COOKIE_EXPIRE - time.Duration - duration that cookie is valid for +SESSION_LIFETIME - time.Duration - the session TTL +``` + + +### Client (sso proxy related) + +``` +CLIENT_PROXY_ID - string - Client ID matching the SSO Proxy client ID +CLIENT_PROXY_SECRET - string - Client secret matching the SSO Proxy client secret +``` + + +### Server +``` +SERVER_SCHEME - string - scheme the server will use, e.g. `https` +SERVER_HOST - string - host header that's required on incoming requests +SERVER_PORT - string - port the http server listens on +SERVER_TIMEOUT_REQUEST - time.Duration - overall request timeout +SERVER_TIMEOUT_WRITE - time.Duration - write request timeout +SERVER_TIMEOUT_READ - time.Duration - read request timeout +``` + + +### Authorization +``` +AUTHORIZE_PROXY_DOMAINS - []string - only redirect to the specified proxy domains. +AUTHORIZE_EMAIL_DOMAINS - []string - authenticate emails with the specified domains. Use `*` to authenticate any email +AUTHORIZE_EMAIL_ADDRESSES - []string - authenticate emails with the specified email addresses. Use `*` to authenticate any email +``` + +## 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 +LOGGING_LEVEL - string - level at which to log at, e.g. 'INFO' +``` + +## Provider configuration + +`*` in the below variables acts as a logical idendifier to group configuration variables together for any one provider. +This should be changed to an identifier that makes sense for your use case. +``` +PROVIDER_*_TYPE - string - determines the type of provider (supported options: google, okta) +PROVIDER_*_SLUG - string - unique provider 'slug' that is used to separate and create routes to individual providers. +PROVIDER_*_CLIENT_ID - string - OAuth Client ID +PROVIDER_*_CLIENT_SECRET - string - OAuth Client secret +PROVIDER_*_SCOPE - string - OAuth scopes the provider will use. Default standard set of scopes pre-set in individual provider +files; which this configuration variable overrides. +``` + +### Google provider specific +``` +PROVIDER_*_GOOGLE_CREDENTIALS - string - the path to the Google account's json credential file +PROVIDER_*_GOOGLE_IMPERSONATE - string - the Google account to impersonate for API calls +``` + +### Okta provider specific +``` +PROVIDER_*_OKTA_URL - string - the URL for your Okta domain, e.g. `.okta.com` +PROVIDER_*_OKTA_SERVER - string - the authorisation server ID +``` + +### Group refresh and caching +``` +PROVIDER_*_GROUPCACHE_INTERVAL_REFRESH - time.Duration - cache TTL for the groups fillcache mechanism used to preemptively fill group caches +PROVIDER_*_GROUPCACHE_INTERVAL_PROVIDER - time.Duration - cache TTL for the group cache provider used for on demand group caching +``` +```