docs: document all accepted config variables

[weeco]

Is your feature request related to a problem? Please describe. I saw a couple available environment variables with only a small description about what they are good for. One doesn't really know about all the options the SSO application offers

Describe the solution you'd like A complete table like this in your README.md:

Environment variable	Description	Default value
COOKIE_SECURE	Whether to store cookies as https only (requires SSL and valid certs)	true

For instance: What is the environment variable CLUSTER used for? Is it only used as template value for your upstream config and someone may not use this value at all?

[loganmeetsworld]

Thanks @weeco, a table is a great suggestion. We'll put this on our radar and get a PR out for it soon.

[mccutchen]

This feels a bit related to https://github.com/buzzfeed/sso/issues/34, too!

[asdptkt]

These are the configurations that is currently available in master branch:

For sso-proxy:

// Options are configuration options that can be set by Environment Variables
// Port - int -  port to listen on for HTTP clients
// ProviderURLString - the URL for the provider in this environment: "https://sso-auth.example.com"
// ProxyProviderURLString - the internal URL for the provider in this environment: "https://sso-auth-int.example.com"
// UpstreamConfigsFile - the path to upstream configs file
// Cluster - the cluster in which this is running, used for upstream configs
// Scheme - the default scheme, used for upstream configs
// SkipAuthPreflight - will skip authentication for OPTIONS requests, default false
// EmailDomains - csv list of emails with the specified domain to authenticate. Use * to authenticate any email
// ClientID - the OAuth Client ID: ie: "123456.apps.googleusercontent.com"
// ClientSecret - The OAuth Client Secret
// DefaultUpstreamTimeout - the default time period to wait for a response from an upstream
// TCPWriteTimeout - http server tcp write timeout
// TCPReadTimeout - http server tcp read timeout
// CookieName - name of the cookie
// CookieSecret - the seed string for secure cookies (optionally base64 encoded)
// CookieDomain - an optional cookie domain to force cookies to (ie: .yourcompany.com)*
// CookieExpire - expire timeframe for cookie
// CookieSecure - set secure (HTTPS) cookie flag
// CookieHTTPOnly - set HttpOnly cookie flag
// Provider - OAuth provider
// Scope - OAuth scope specification
// SessionLifetimeTTL - time to live for a session lifetime
// SessionValidTTL - time to live for a valid session
// GracePeriodTTL - time to reuse session data when provider unavailable
// RequestLoging - boolean whether or not to log requests
// StatsdHost - host addr for statsd client to listen on
// StatsdPort - port for statsdclient to listen on
type Options struct {
	Port int `envconfig:"PORT" default:"4180"`

	ProviderURLString      string `envconfig:"PROVIDER_URL"`
	ProxyProviderURLString string `envconfig:"PROXY_PROVIDER_URL"`
	UpstreamConfigsFile    string `envconfig:"UPSTREAM_CONFIGS"`
	Cluster                string `envconfig:"CLUSTER"`
	Scheme                 string `envconfig:"SCHEME" default:"https"`

	SkipAuthPreflight bool `envconfig:"SKIP_AUTH_PREFLIGHT"`

	EmailDomains []string `envconfig:"EMAIL_DOMAIN"`
	ClientID     string   `envconfig:"CLIENT_ID"`
	ClientSecret string   `envconfig:"CLIENT_SECRET"`

	DefaultUpstreamTimeout time.Duration `envconfig:"DEFAULT_UPSTREAM_TIMEOUT" default:"10s"`

	TCPWriteTimeout time.Duration `envconfig:"TCP_WRITE_TIMEOUT" default:"30s"`
	TCPReadTimeout  time.Duration `envconfig:"TCP_READ_TIMEOUT" default:"30s"`

	CookieName     string
	CookieSecret   string        `envconfig:"COOKIE_SECRET"`
	CookieDomain   string        `envconfig:"COOKIE_DOMAIN"`
	CookieExpire   time.Duration `envconfig:"COOKIE_EXPIRE" default:"168h"`
	CookieSecure   bool          `envconfig:"COOKIE_SECURE" default:"true"`
	CookieHTTPOnly bool          `envconfig:"COOKIE_HTTP_ONLY"`

	// These options allow for other providers besides Google, with potential overrides.
	Provider string `envconfig:"PROVIDER" default:"google"`
	Scope    string `envconfig:"SCOPE"`

	SessionLifetimeTTL time.Duration `envconfig:"SESSION_LIFETIME_TTL" default:"720h"`
	SessionValidTTL    time.Duration `envconfig:"SESSION_VALID_TTL" default:"1m"`
	GracePeriodTTL     time.Duration `envconfig:"GRACE_PERIOD_TTL" default:"3h"`

	RequestLogging bool `envconfig:"REQUEST_LOGGING" default:"true"`

	StatsdHost string `envconfig:"STATSD_HOST"`
	StatsdPort int    `envconfig:"STATSD_PORT"`

	StatsdClient *statsd.Client

	// This is an override for supplying template vars at test time
	testTemplateVars map[string]string

	// internal values that are set after config validation
	upstreamConfigs     []*UpstreamConfig
	providerURL         *url.URL
	provider            providers.Provider
	decodedCookieSecret []byte
}

For sso-auth:

// Options are config options that can be set by environment variables
// RedirectURL 	string - the OAuth Redirect URL. ie: \"https://internalapp.yourcompany.com/oauth2/callback\
// ClientID - 	string - the OAuth ClientID ie "123456.apps.googleusercontent.com"
// ClientSecret string - the OAuth Client Secret
// ProxyClientID - string - the client id that matches the sso proxy client id
// ProxyClientSecret - string - the client secret that matches the sso proxy client secret
// Host - string - The host that is in the header that is required on incoming requests
// Port - string - Port to listen on
// EmailDomains - []string - authenticate emails with the specified domain (may be given multiple times). Use * to authenticate any email
// ProxyRootDomains - []string - only redirect to specified proxy domains (may be given multiple times)
// GoogleAdminEmail - string - the google admin to impersonate for api calls
// GoogleServiceAccountJSON - string - the path to the service account json credentials
// Footer - string custom footer string. Use \"-\" to disable default footer.
// CookieSecret - string - the seed string for secure cookies (optionally base64 encoded)
// CookieDomain - string - an optional cookie domain to force cookies to (ie: .yourcompany.com)*
// CookieExpire - duration - expire timeframe for cookie, defaults at 168 hours
// CookieRefresh - duration - refresh the cookie after this duration default 0
// CookieSecure - bool - set secure (HTTPS) cookie flag
// CookieHTTPOnly - bool - set httponly cookie flag
// RequestTimeout - duration - overall request timeout
// AuthCodeSecret - string - the seed string for secure auth codes (optionally base64 encoded)
// PassHostHeader - bool - pass the request Host Header to upstream (default true)
// SkipProviderButton - bool - if true, will skip sign-in-page to directly reach the next step: oauth/start
// PassUserHeaders - bool (default true) - pass X-Forwarded-User and X-Forwarded-Email information to upstream
// SetXAuthRequest - set X-Auth-Request-User and X-Auth-Request-Email response headers (useful in Nginx auth_request mode)
// Provider - provider name
// SignInURL - provider sign in endpoint
// RedeemURL - provider token redemption endpoint
// ProfileURL - provider profile access endpoint
// ValidateURL - access token validation endpoint
// Scope - Oauth scope specification
// ApprovalPrompt - OAuth approval prompt
// RequestLogging - bool to log requests
// StatsdPort - port where statsd client listens
// StatsdHost - host where statsd client listens
type Options struct {
	RedirectURL       string `envconfig:"REDIRECT_URL" `
	ClientID          string `envconfig:"CLIENT_ID"`
	ClientSecret      string `envconfig:"CLIENT_SECRET"`
	ProxyClientID     string `envconfig:"PROXY_CLIENT_ID"`
	ProxyClientSecret string `envconfig:"PROXY_CLIENT_SECRET"`

	Host string `envconfig:"HOST"`
	Port int    `envconfig:"PORT" default:"4180"`

	EmailDomains     []string `envconfig:"SSO_EMAIL_DOMAIN"`
	ProxyRootDomains []string `envconfig:"PROXY_ROOT_DOMAIN"`

	GoogleAdminEmail         string `envconfig:"GOOGLE_ADMIN_EMAIL"`
	GoogleServiceAccountJSON string `envconfig:"GOOGLE_SERVICE_ACCOUNT_JSON"`

	Footer string `envconfig:"FOOTER"`

	CookieName     string
	CookieSecret   string        `envconfig:"COOKIE_SECRET"`
	CookieDomain   string        `envconfig:"COOKIE_DOMAIN"`
	CookieExpire   time.Duration `envconfig:"COOKIE_EXPIRE" default:"168h"`
	CookieRefresh  time.Duration `envconfig:"COOKIE_REFRESH" default:"1h"`
	CookieSecure   bool          `envconfig:"COOKIE_SECURE" default:"true"`
	CookieHTTPOnly bool          `envconfig:"COOKIE_HTTP_ONLY" default:"true"`

	RequestTimeout  time.Duration `envconfig:"REQUEST_TIMEOUT" default:"2s"`
	TCPWriteTimeout time.Duration `envconfig:"TCP_WRITE_TIMEOUT" default:"30s"`
	TCPReadTimeout  time.Duration `envconfig:"TCP_READ_TIMEOUT" default:"30s"`

	AuthCodeSecret string `envconfig:"AUTH_CODE_SECRET"`

	GroupsCacheRefreshTTL time.Duration `envconfig:"GROUPS_CACHE_REFRESH_TTL" default:"10m"`
	SessionLifetimeTTL    time.Duration `envconfig:"SESSION_LIFETIME_TTL" default:"720h"`

	PassHostHeader     bool `envconfig:"PASS_HOST_HEADER" default:"true"`
	SkipProviderButton bool `envconfig:"SKIP_PROVIDER_BUTTON"`
	PassUserHeaders    bool `envconfig:"PASS_USER_HEADERS" default:"true"`
	SetXAuthRequest    bool `envconfig:"SET_XAUTHREQUEST" default:"false"`

	// These options allow for other providers besides Google, with potential overrides.
	Provider       string `envconfig:"PROVIDER" default:"google"`
	SignInURL      string `envconfig:"SIGNIN_URL"`
	RedeemURL      string `envconfig:"REDEEM_URL"`
	ProfileURL     string `envconfig:"PROFILE_URL"`
	ValidateURL    string `envconfig:"VALIDATE_URL"`
	Scope          string `envconfig:"SCOPE"`
	ApprovalPrompt string `envconfig:"APPROVAL_PROMPT" default:"force"`

	RequestLogging bool `envconfig:"REQUEST_LOGGING" default:"true"`

	StatsdPort int    `envconfig:"STATSD_PORT"`
	StatsdHost string `envconfig:"STATSD_HOST"`

	// internal values that are set after config validation
	redirectURL         *url.URL
	decodedCookieSecret []byte
	GroupsCacheStopFunc func()
}

[kim0]

I came here to understand What is the environment variable CLUSTER used for? .. I still don't understand if this has any effect on my deploying sso through the helm chart or not. Any advice is appreciated. Thanks!

[sporkmonger]

Also, with the new config changes, there's a couple spots where the config structs accept arrays of strings but examples only ever provide a single value, so it's not obvious how to provide multiple values.