Documentation ¶
Overview ¶
Package config is a configuration abstraction that facilitates enabling Pomerium settings forvarious encoding types (JSON/YAML/ENVARS) and methods.
Index ¶
- Constants
- Variables
- func IsAll(s string) bool
- func IsAuthenticate(s string) bool
- func IsAuthorize(s string) bool
- func IsCache(s string) bool
- func IsProxy(s string) bool
- func IsValidService(s string) bool
- func WatchChanges(configFile string, opt *Options, services []OptionsUpdater)
- type AutocertOptions
- type Options
- func (o *Options) Checksum() uint64
- func (o *Options) GetAuthenticateURL() *url.URL
- func (o *Options) GetAuthorizeURL() *url.URL
- func (o *Options) GetDataBrokerURL() *url.URL
- func (o *Options) GetForwardAuthURL() *url.URL
- func (o *Options) GetOauthOptions() oauth.Options
- func (o *Options) OnConfigChange(run func(in fsnotify.Event))
- func (o *Options) Validate() error
- type OptionsUpdater
- type Policy
- type StringURL
- type TracingOptions
Constants ¶
const ( // ServiceAll represents running all services in "all-in-one" mode ServiceAll = "all" // ServiceProxy represents running the proxy service component ServiceProxy = "proxy" // ServiceAuthorize represents running the authorize service component ServiceAuthorize = "authorize" // ServiceAuthenticate represents running the authenticate service component ServiceAuthenticate = "authenticate" // ServiceCache represents running the cache service component ServiceCache = "cache" )
const ( // JaegerTracingProviderName is the name of the tracing provider Jaeger. JaegerTracingProviderName = "jaeger" // ZipkinTracingProviderName is the name of the tracing provider Zipkin. ZipkinTracingProviderName = "zipkin" )
const DefaultAlternativeAddr = ":5443"
DefaultAlternativeAddr is the address used is two services are competing over the same listener. Typically this is invisible to the end user (e.g. localhost) gRPC server, or is used for healthchecks (authorize only service)
const DisableHeaderKey = "disable"
DisableHeaderKey is the key used to check whether to disable setting header
Variables ¶
var AutocertManager = newAutocertManager()
AutocertManager manages Let's Encrypt certificates based on configuration options.
var EnvoyAdminURL = &url.URL{Host: "localhost:9901", Scheme: "http"}
EnvoyAdminURL indicates where the envoy control plane is listening
var RedirectAndAutocertServer = newRedirectAndAutoCertServer()
RedirectAndAutocertServer is an HTTP server which handles redirecting to HTTPS and autocerts.
Functions ¶
func IsAuthenticate ¶
IsAuthenticate checks to see if we should be running the authenticate service
func IsAuthorize ¶
IsAuthorize checks to see if we should be running the authorize service
func IsValidService ¶
IsValidService checks to see if a service is a valid service mode
func WatchChanges ¶ added in v0.9.0
func WatchChanges(configFile string, opt *Options, services []OptionsUpdater)
WatchChanges takes a configuration file, an existing options struct, and updates each service in the services slice OptionsUpdater with a new set of options if any change is detected. It also periodically rechecks if any computed properties have changed.
Types ¶
type AutocertOptions ¶ added in v0.10.0
type AutocertOptions struct { // Enable enables fully automated certificate management including issuance // and renewal from LetsEncrypt. Must be used in conjunction with Folder. Enable bool `mapstructure:"autocert" yaml:"autocert,omitempty"` // UseStaging tells autocert to use Let's Encrypt's staging CA which // has less strict usage limits then the (default) production CA. // // https://letsencrypt.org/docs/staging-environment/ UseStaging bool `mapstructure:"autocert_use_staging" yaml:"autocert_use_staging,omitempty"` // MustStaple will cause autocert to request a certificate with // status_request extension. This will allow the TLS client (the browser) // to fail immediately if Pomerium failed to get an OCSP staple. // See also https://tools.ietf.org/html/rfc7633 // Only used when Enable is true. MustStaple bool `mapstructure:"autocert_must_staple" yaml:"autocert_must_staple,omitempty"` // Folder specifies the location to store, and load autocert managed // TLS certificates. // defaults to $XDG_DATA_HOME/pomerium Folder string `mapstructure:"autocert_dir" yaml:"autocert_dir,omitempty"` }
AutocertOptions contains the options to control the behavior of autocert.
type Options ¶
type Options struct { // Debug outputs human-readable logs to Stdout. Debug bool `mapstructure:"pomerium_debug" yaml:"pomerium_debug,omitempty"` // LogLevel sets the global override for log level. All Loggers will use at least this value. // Possible options are "info","warn","debug" and "error". Defaults to "info". LogLevel string `mapstructure:"log_level" yaml:"log_level,omitempty"` // ProxyLogLevel sets the log level for the proxy service. // Possible options are "info","warn", and "error". Defaults to the value of `LogLevel`. ProxyLogLevel string `mapstructure:"proxy_log_level" yaml:"proxy_log_level,omitempty"` // requests between services. SharedKey string `mapstructure:"shared_secret" yaml:"shared_secret,omitempty"` // Services is a list enabled service mode. If none are selected, "all" is used. // Available options are : "all", "authenticate", "proxy". Services string `mapstructure:"services" yaml:"services,omitempty"` // Addr specifies the host and port on which the server should serve // HTTPS requests. If empty, ":443" (localhost:443) is used. Addr string `mapstructure:"address" yaml:"address,omitempty"` // InsecureServer when enabled disables all transport security. // In this mode, Pomerium is susceptible to man-in-the-middle attacks. // This should be used only for testing. InsecureServer bool `mapstructure:"insecure_server" yaml:"insecure_server,omitempty"` CertificateFiles []certificateFilePair `mapstructure:"certificates" yaml:"certificates,omitempty"` // Cert and Key is the x509 certificate used to create the HTTPS server. Cert string `mapstructure:"certificate" yaml:"certificate,omitempty"` Key string `mapstructure:"certificate_key" yaml:"certificate_key,omitempty"` // CertFile and KeyFile is the x509 certificate used to hydrate TLSCertificate CertFile string `mapstructure:"certificate_file" yaml:"certificate_file,omitempty"` KeyFile string `mapstructure:"certificate_key_file" yaml:"certificate_key_file,omitempty"` Certificates []tls.Certificate `mapstructure:"-" yaml:"-"` // HttpRedirectAddr, if set, specifies the host and port to run the HTTP // to HTTPS redirect server on. If empty, no redirect server is started. HTTPRedirectAddr string `mapstructure:"http_redirect_addr" yaml:"http_redirect_addr,omitempty"` // Timeout settings : https://github.com/pomerium/pomerium/issues/40 ReadTimeout time.Duration `mapstructure:"timeout_read" yaml:"timeout_read,omitempty"` WriteTimeout time.Duration `mapstructure:"timeout_write" yaml:"timeout_write,omitempty"` IdleTimeout time.Duration `mapstructure:"timeout_idle" yaml:"timeout_idle,omitempty"` // Policies define per-route configuration and access control policies. Policies []Policy `yaml:"policy,omitempty"` PolicyEnv string `yaml:",omitempty"` PolicyFile string `mapstructure:"policy_file" yaml:"policy_file,omitempty"` // AuthenticateURL represents the externally accessible http endpoints // used for authentication requests and callbacks AuthenticateURLString string `mapstructure:"authenticate_service_url" yaml:"authenticate_service_url,omitempty"` AuthenticateURL *url.URL `yaml:"-,omitempty"` // AuthenticateCallbackPath is the path to the HTTP endpoint that will // receive the response from your identity provider. The value must exactly // match one of the authorized redirect URIs for the OAuth 2.0 client. // Defaults to: `/oauth2/callback` AuthenticateCallbackPath string `mapstructure:"authenticate_callback_path" yaml:"authenticate_callback_path,omitempty"` // Session/Cookie management // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie CookieName string `mapstructure:"cookie_name" yaml:"cookie_name,omitempty"` CookieSecret string `mapstructure:"cookie_secret" yaml:"cookie_secret,omitempty"` CookieDomain string `mapstructure:"cookie_domain" yaml:"cookie_domain,omitempty"` CookieSecure bool `mapstructure:"cookie_secure" yaml:"cookie_secure,omitempty"` CookieHTTPOnly bool `mapstructure:"cookie_http_only" yaml:"cookie_http_only,omitempty"` CookieExpire time.Duration `mapstructure:"cookie_expire" yaml:"cookie_expire,omitempty"` // Identity provider configuration variables as specified by RFC6749 // https://openid.net/specs/openid-connect-basic-1_0.html#RFC6749 ClientID string `mapstructure:"idp_client_id" yaml:"idp_client_id,omitempty"` ClientSecret string `mapstructure:"idp_client_secret" yaml:"idp_client_secret,omitempty"` Provider string `mapstructure:"idp_provider" yaml:"idp_provider,omitempty"` ProviderURL string `mapstructure:"idp_provider_url" yaml:"idp_provider_url,omitempty"` Scopes []string `mapstructure:"idp_scopes" yaml:"idp_scopes,omitempty"` ServiceAccount string `mapstructure:"idp_service_account" yaml:"idp_service_account,omitempty"` // RequestParams are custom request params added to the signin request as // part of an Oauth2 code flow. // // https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml // https://openid.net/specs/openid-connect-basic-1_0.html#RequestParameters RequestParams map[string]string `mapstructure:"idp_request_params" yaml:"idp_request_params,omitempty"` // Administrators contains a set of emails with users who have super user // (sudo) access including the ability to impersonate other users' access Administrators []string `mapstructure:"administrators" yaml:"administrators,omitempty"` // AuthorizeURL is the routable destination of the authorize service's // gRPC endpoint. NOTE: As many load balancers do not support // externally routed gRPC so this may be an internal location. AuthorizeURLString string `mapstructure:"authorize_service_url" yaml:"authorize_service_url,omitempty"` AuthorizeURL *url.URL `yaml:",omitempty"` // Settings to enable custom behind-the-ingress service communication OverrideCertificateName string `mapstructure:"override_certificate_name" yaml:"override_certificate_name,omitempty"` CA string `mapstructure:"certificate_authority" yaml:"certificate_authority,omitempty"` CAFile string `mapstructure:"certificate_authority_file" yaml:"certificate_authority_file,omitempty"` // SigningKey is the private key used to add a JWT-signature. // https://www.pomerium.io/docs/signed-headers.html SigningKey string `mapstructure:"signing_key" yaml:"signing_key,omitempty"` // Headers to set on all proxied requests. Add a 'disable' key map to turn off. HeadersEnv string `yaml:",omitempty"` Headers map[string]string `yaml:",omitempty"` // List of JWT claims to insert as x-pomerium-claim-* headers on proxied requests JWTClaimsHeaders []string `mapstructure:"jwt_claims_headers" yaml:"jwt_claims_headers,omitempty"` // RefreshCooldown limits the rate a user can refresh her session RefreshCooldown time.Duration `mapstructure:"refresh_cooldown" yaml:"refresh_cooldown,omitempty"` DefaultUpstreamTimeout time.Duration `mapstructure:"default_upstream_timeout" yaml:"default_upstream_timeout,omitempty"` // Address/Port to bind to for prometheus metrics MetricsAddr string `mapstructure:"metrics_address" yaml:"metrics_address,omitempty"` // Tracing shared settings TracingProvider string `mapstructure:"tracing_provider" yaml:"tracing_provider,omitempty"` TracingSampleRate float64 `mapstructure:"tracing_sample_rate" yaml:"tracing_sample_rate,omitempty"` // Jaeger // // CollectorEndpoint is the full url to the Jaeger HTTP Thrift collector. // For example, http://localhost:14268/api/traces TracingJaegerCollectorEndpoint string `mapstructure:"tracing_jaeger_collector_endpoint" yaml:"tracing_jaeger_collector_endpoint,omitempty"` // Zipkin // // ZipkinEndpoint configures the zipkin collector URI // Example: http://zipkin:9411/api/v2/spans TracingJaegerAgentEndpoint string `mapstructure:"tracing_jaeger_agent_endpoint" yaml:"tracing_jaeger_agent_endpoint,omitempty"` ZipkinEndpoint string `mapstructure:"tracing_zipkin_endpoint" yaml:"tracing_zipkin_endpoint"` // GRPCAddr specifies the host and port on which the server should serve // gRPC requests. If running in all-in-one mode, ":5443" (localhost:5443) is used. GRPCAddr string `mapstructure:"grpc_address" yaml:"grpc_address,omitempty"` // GRPCInsecure disables transport security. // If running in all-in-one mode, defaults to true. GRPCInsecure bool `mapstructure:"grpc_insecure" yaml:"grpc_insecure,omitempty"` GRPCClientTimeout time.Duration `mapstructure:"grpc_client_timeout" yaml:"grpc_client_timeout,omitempty"` GRPCClientDNSRoundRobin bool `mapstructure:"grpc_client_dns_roundrobin" yaml:"grpc_client_dns_roundrobin,omitempty"` //GRPCServerMaxConnectionAge sets MaxConnectionAge in the grpc ServerParameters used to create GRPC Services GRPCServerMaxConnectionAge time.Duration `mapstructure:"grpc_server_max_connection_age" yaml:"grpc_server_max_connection_age,omitempty"` //GRPCServerMaxConnectionAgeGrace sets MaxConnectionAgeGrace in the grpc ServerParameters used to create GRPC Services GRPCServerMaxConnectionAgeGrace time.Duration `mapstructure:"grpc_server_max_connection_age_grace,omitempty" yaml:"grpc_server_max_connection_age_grace,omitempty"` //nolint: lll // ForwardAuthEndpoint allows for a given route to be used as a forward-auth // endpoint instead of a reverse proxy. Some third-party proxies that do not // have rich access control capabilities (nginx, envoy, ambassador, traefik) // allow you to delegate and authenticate each request to your website // with an external server or service. Pomerium can be configured to accept // these requests with this switch ForwardAuthURLString string `mapstructure:"forward_auth_url" yaml:"forward_auth_url,omitempty"` ForwardAuthURL *url.URL `yaml:",omitempty"` // CacheURL is the routable destination of the cache service's // gRPC endpoint. NOTE: As many load balancers do not support // externally routed gRPC so this may be an internal location. // // TODO(BDD): Deprecate and remove in 0.11.0 CacheURLString string `mapstructure:"cache_service_url" yaml:"cache_service_url,omitempty"` CacheURL *url.URL `yaml:",omitempty"` // DataBrokerURL is the routable destination of the databroker service's gRPC endpiont. DataBrokerURLString string `mapstructure:"databroker_service_url" yaml:"databroker_service_url,omitempty"` DataBrokerURL *url.URL `yaml:",omitempty"` // ClientCA is the base64-encoded certificate authority to validate client mTLS certificates against. ClientCA string `mapstructure:"client_ca" yaml:"client_ca,omitempty"` // ClientCAFile points to a file that contains the certificate authority to validate client mTLS certificates against. ClientCAFile string `mapstructure:"client_ca_file" yaml:"client_ca_file,omitempty"` AutocertOptions `mapstructure:",squash" yaml:",inline"` // contains filtered or unexported fields }
Options are the global environmental flags used to set up pomerium's services. Use NewXXXOptions() methods for a safely initialized data structure.
func NewDefaultOptions ¶
func NewDefaultOptions() *Options
NewDefaultOptions returns a copy the default options. It's the caller's responsibility to do a follow up Validate call.
func NewOptionsFromConfig ¶
NewOptionsFromConfig builds the main binary's configuration options by parsing environmental variables and config file
func (*Options) GetAuthenticateURL ¶ added in v0.9.0
GetAuthenticateURL returns the AuthenticateURL in the options or localhost.
func (*Options) GetAuthorizeURL ¶ added in v0.9.0
GetAuthorizeURL returns the AuthorizeURL in the options or localhost:5443.
func (*Options) GetDataBrokerURL ¶ added in v0.10.0
GetDataBrokerURL returns the DataBrokerURL in the options or localhost:5443.
func (*Options) GetForwardAuthURL ¶ added in v0.9.0
GetForwardAuthURL returns the ForwardAuthURL in the options or localhost.
func (*Options) GetOauthOptions ¶ added in v0.10.0
GetOauthOptions gets the oauth.Options for the given config options.
func (*Options) OnConfigChange ¶
OnConfigChange starts a go routine and watches for any changes. If any are detected, via an fsnotify event the provided function is run.
type OptionsUpdater ¶
OptionsUpdater updates local state based on an Options struct
type Policy ¶
type Policy struct { From string `mapstructure:"from" yaml:"from"` To string `mapstructure:"to" yaml:"to"` // Identity related policy AllowedUsers []string `mapstructure:"allowed_users" yaml:"allowed_users,omitempty" json:"allowed_users,omitempty"` AllowedGroups []string `mapstructure:"allowed_groups" yaml:"allowed_groups,omitempty" json:"allowed_groups,omitempty"` AllowedDomains []string `mapstructure:"allowed_domains" yaml:"allowed_domains,omitempty" json:"allowed_domains,omitempty"` Source *StringURL `yaml:",omitempty" json:"source,omitempty" hash:"ignore"` Destination *url.URL `yaml:",omitempty" json:"destination,omitempty" hash:"ignore"` // Additional route matching options Prefix string `mapstructure:"prefix" yaml:"prefix,omitempty" json:"prefix,omitempty"` Path string `mapstructure:"path" yaml:"path,omitempty" json:"path,omitempty"` Regex string `mapstructure:"regex" yaml:"regex,omitempty" json:"regex,omitempty"` // Allow unauthenticated HTTP OPTIONS requests as per the CORS spec // https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Preflighted_requests CORSAllowPreflight bool `mapstructure:"cors_allow_preflight" yaml:"cors_allow_preflight,omitempty"` // Allow any public request to access this route. **Bypasses authentication** AllowPublicUnauthenticatedAccess bool `mapstructure:"allow_public_unauthenticated_access" yaml:"allow_public_unauthenticated_access,omitempty"` // UpstreamTimeout is the route specific timeout. Must be less than the global // timeout. If unset, route will fallback to the proxy's DefaultUpstreamTimeout. UpstreamTimeout time.Duration `mapstructure:"timeout" yaml:"timeout,omitempty"` // Enable proxying of websocket connections by removing the default timeout handler. // Caution: Enabling this feature could result in abuse via DOS attacks. AllowWebsockets bool `mapstructure:"allow_websockets" yaml:"allow_websockets,omitempty"` // TLSSkipVerify controls whether a client verifies the server's certificate // chain and host name. // If TLSSkipVerify is true, TLS accepts any certificate presented by the // server and any host name in that certificate. // In this mode, TLS is susceptible to man-in-the-middle attacks. // This should be used only for testing. TLSSkipVerify bool `mapstructure:"tls_skip_verify" yaml:"tls_skip_verify,omitempty"` // TLSServerName overrides the hostname in the `to` field. This is useful // if your backend is an HTTPS server with a valid certificate, but you // want to communicate to the backend with an internal hostname (e.g. // Docker container name). TLSServerName string `mapstructure:"tls_server_name" yaml:"tls_server_name,omitempty"` // TLSCustomCA defines the root certificate to use with a given // route when verifying server certificates. TLSCustomCA string `mapstructure:"tls_custom_ca" yaml:"tls_custom_ca,omitempty"` TLSCustomCAFile string `mapstructure:"tls_custom_ca_file" yaml:"tls_custom_ca_file,omitempty"` // Contains the x.509 client certificate to present to the downstream // host. TLSClientCert string `mapstructure:"tls_client_cert" yaml:"tls_client_cert,omitempty"` TLSClientKey string `mapstructure:"tls_client_key" yaml:"tls_client_key,omitempty"` TLSClientCertFile string `mapstructure:"tls_client_cert_file" yaml:"tls_client_cert_file,omitempty"` TLSClientKeyFile string `mapstructure:"tls_client_key_file" yaml:"tls_client_key_file,omitempty"` ClientCertificate *tls.Certificate `yaml:",omitempty" hash:"ignore"` // SetRequestHeaders adds a collection of headers to the downstream request // in the form of key value pairs. Note bene, this will overwrite the // value of any existing value of a given header key. SetRequestHeaders map[string]string `mapstructure:"set_request_headers" yaml:"set_request_headers,omitempty"` // RemoveRequestHeaders removes a collection of headers from a downstream request. // Note that this has lower priority than `SetRequestHeaders`, if you specify `X-Custom-Header` in both // `SetRequestHeaders` and `RemoveRequestHeaders`, then the header won't be removed. RemoveRequestHeaders []string `mapstructure:"remove_request_headers" yaml:"remove_request_headers,omitempty"` // PreserveHostHeader disables host header rewriting. // // This option only takes affect if the destination is a DNS name. If the destination is an IP address, // use SetRequestHeaders to explicitly set the "Host" header. // // https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header PreserveHostHeader bool `mapstructure:"preserve_host_header" yaml:"preserve_host_header,omitempty"` // PassIdentityHeaders controls whether to add a user's identity headers to the downstream request. // These includes: // // - X-Pomerium-Jwt-Assertion // - X-Pomerium-Claim-* // PassIdentityHeaders bool `mapstructure:"pass_identity_headers" yaml:"pass_identity_headers,omitempty"` }
Policy contains route specific configuration and access settings.
type StringURL ¶ added in v0.8.0
StringURL stores a URL as a string in json.
func (*StringURL) MarshalJSON ¶ added in v0.8.0
MarshalJSON returns the URLs host as json.
type TracingOptions ¶ added in v0.9.0
type TracingOptions struct { // Shared Provider string Service string Debug bool // CollectorEndpoint is the full url to the Jaeger HTTP Thrift collector. // For example, http://localhost:14268/api/traces JaegerCollectorEndpoint *url.URL // AgentEndpoint instructs exporter to send spans to jaeger-agent at this address. // For example, localhost:6831. JaegerAgentEndpoint string // ZipkinEndpoint configures the zipkin collector URI // Example: http://zipkin:9411/api/v2/spans ZipkinEndpoint *url.URL // SampleRate is percentage of requests which are sampled SampleRate float64 }
TracingOptions contains the configurations settings for a http server.
func NewTracingOptions ¶ added in v0.9.0
func NewTracingOptions(o *Options) (*TracingOptions, error)
NewTracingOptions builds a new TracingOptions from core Options
func (*TracingOptions) Enabled ¶ added in v0.9.0
func (t *TracingOptions) Enabled() bool
Enabled indicates whether tracing is enabled on a given TracingOptions