proxy

Documentation

Overview

Package proxy implements a simple lightweight TLS termination proxy that uses Let's Encrypt to provide TLS encryption for any number of TCP and HTTP servers and server names concurrently on the same port.

It can also act as a reverse HTTP proxy with optional user authentication with SAML, OpenID Connect, and/or passkeys.

Index

• Constants
• type BWLimit
• type Backend
• type BackendSSO
• type ClientAuth
• type Config
  • func ReadConfig(filename string) (*Config, error)
  • func (cfg *Config) Check() error
• type ConfigOIDC
• type ConfigPKI
• type ConfigPasskey
• type ConfigSAML
• type LocalOIDCClient
• type LocalOIDCRewriteRule
• type LocalOIDCServer
• type LogFilter
• type PathOverride
• type Proxy
  • func New(cfg *Config, passphrase []byte) (*Proxy, error)
  • func NewTestProxy(cfg *Config) (*Proxy, error)
  • func (p *Proxy) Reconfigure(cfg *Config) error
  • func (p *Proxy) RevokeAllCertificates(ctx context.Context, reason string) error
  • func (p *Proxy) Shutdown(ctx context.Context)
  • func (p *Proxy) Start(ctx context.Context) error
  • func (p *Proxy) Stop()
• type TLSCertificate
• type WebSocketConfig

Constants

const (
	ModePlaintext      = "PLAINTEXT"
	ModeTCP            = "TCP"
	ModeTLS            = "TLS"
	ModeTLSPassthrough = "TLSPASSTHROUGH"
	ModeQUIC           = "QUIC"
	ModeHTTP           = "HTTP"
	ModeHTTPS          = "HTTPS"
	ModeLocal          = "LOCAL"
	ModeConsole        = "CONSOLE"
)

Types

type BWLimit

type BWLimit struct {
	// Name is the name of the group.
	Name string `yaml:"name"`
	// Ingress is the ingress limit, in bytes per second.
	Ingress float64 `yaml:"ingress"`
	// Egress is the engress limit, in bytes per second.
	Egress float64 `yaml:"egress"`
}

BWLimit is a named bandwidth limit configuration.

type Backend

type Backend struct {
	// ServerNames is the list of all the server names for this service,
	// e.g. example.com, www.example.com.
	// Internationalized names are converted to ascii using the IDNA2008
	// lookup standard as implemented by golang.org/x/net/idna.
	ServerNames []string `yaml:"serverNames"`
	// ClientAuth specifies that the TLS client's identity must be verified.
	ClientAuth *ClientAuth `yaml:"clientAuth,omitempty"`
	// AllowIPs specifies a list of IP network addresses to allow, in CIDR
	// format, e.g. 192.168.0.0/24.
	//
	// The rules are applied in this order:
	// * If DenyIPs is specified, the remote addr must not match any of the
	//   IP addresses in the list.
	// * If AllowIPs is specified, the remote addr must match at least one
	//   of the IP addresses on the list.
	//
	// If an IP address is blocked, the client receives a TLS "unrecognized
	// name" alert, as if it connected to an unknown server name.
	AllowIPs *[]string `yaml:"allowIPs,omitempty"`
	// DenyIPs specifies a list of IP network addresses to deny, in CIDR
	// format, e.g. 192.168.0.0/24. See AllowIPs.
	DenyIPs *[]string `yaml:"denyIPs,omitempty"`
	// SSO indicates that the backend requires user authentication, and
	// specifies which identity provider to use and who's allowed to
	// connect.
	SSO *BackendSSO `yaml:"sso,omitempty"`
	// ExportJWKS is the path where to export the proxy's JSON Web Key Set.
	// This should only be set when SSO is enabled and JSON Web Tokens are
	// generated for the users to authenticate with the backends.
	ExportJWKS string `yaml:"exportJwks,omitempty"`
	// ALPNProtos specifies the list of ALPN procotols supported by this
	// backend. The ACME acme-tls/1 protocol doesn't need to be specified.
	//
	// The default values are:
	//  * [h2, http/1.1] when QUIC is not enabled
	//  * [h3, h2, http/1.1] when QUIC is enabled and Mode is one of:
	//      HTTP, HTTPS, QUIC, LOCAL, CONSOLE
	//
	// Set the value to an empty slice [] to disable ALPN.
	// The negotiated protocol is forwarded to the backends that use TLS.
	//
	// https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
	ALPNProtos *[]string `yaml:"alpnProtos,flow,omitempty"`
	// BackendProto specifies which protocol to use when forwarding an HTTPS
	// request to the backend. This field is only valid in modes HTTP and
	// HTTPS.
	// The value should be an ALPN protocol, e.g.: http/1.1, h2, or h3. The default is http/1.1.
	// If the value is set explicitly to "", the same protocol used by the
	// client will be used with the backend.
	BackendProto *string `yaml:"backendProto,omitempty"`
	// Mode controls how the proxy communicates with the backend.
	// - PLAINTEXT: Use a plaintext, non-encrypted, TCP connection. This is
	// the the default mode.
	//        CLIENT --TLS--> PROXY ----> BACKEND SERVER
	// - TLS: Open a new TLS connection. Set ForwardServerName, ForwardRootCAs,
	//     and/or InsecureSkipVerify to verify the identity of the server.
	//        CLIENT --TLS--> PROXY --TLS--> BACKEND SERVER
	// - TLSPASSTHROUGH: Forward the whole TLS connection to the backend.
	//     In this mode, the proxy terminates the TCP connection, but not
	//     the TLS connection. The proxy uses the information from the TLS
	//     ClientHello message to route the TLS data to the right backend.
	//     It cannot see the plaintext data, and it cannot enforce client
	//     authentication & authorization.
	//                +-TCP-PROXY-TCP-+
	//        CLIENT -+------TLS------+-> BACKEND SERVER
	// - QUIC: Open a new QUIC connection. If the incoming connection is
	//     TLS, forward the data on a single bidirectional QUIC stream. If
	//     the incoming connection is QUIC, forward all streams.
	//        CLIENT --TLS---> PROXY --QUIC STREAM--> BACKEND SERVER
	//     Or
	//        CLIENT --QUIC--> PROXY --QUIC--> BACKEND SERVER
	// - HTTP: Parses the incoming connection as HTTPS and forwards the
	//     requests to the backends as HTTP requests.
	//        CLIENT --HTTPS--> PROXY --HTTP--> BACKEND SERVER
	// - HTTPS: Parses the incoming connection as HTTPS and forwards the
	//     requests to the backends as HTTPS requests.
	//        CLIENT --HTTPS--> PROXY --HTTPS--> BACKEND SERVER
	// - LOCAL: Behaves exactly like HTTP and HTTPS without backend
	//     addresses. This mode is intended for local handlers like Oauth2
	//     redirects.
	//        CLIENT --HTTPS--> PROXY
	// - CONSOLE: Indicates that this backend is handled by the proxy itself
	//     to report its status and metrics. It is strongly recommended
	//     to use it with ClientAuth and ACL. Otherwise, information from
	//     the proxy's configuration can be leaked to anyone who knows the
	//     backend's server name.
	//        CLIENT --TLS--> PROXY CONSOLE
	//
	// QUIC
	//
	// If the incoming connection is QUIC and Mode is TCP or TLS, each QUIC
	// stream is treated like an incoming TLS connection.
	//                               ,--STREAM1--> BACKEND SERVER
	//        CLIENT --QUIC--> PROXY +--STREAM2--> BACKEND SERVER
	//                               `--STREAM3--> BACKEND SERVER
	// If Mode is QUIC, all streams are forwards to the backend server.
	//        CLIENT --QUIC--> PROXY --QUIC--> BACKEND SERVER
	Mode string `yaml:"mode"`
	// DocumentRoot indicates local files should be served from this
	// directory. This option is only valid when Addresses is empty.
	DocumentRoot string `yaml:"documentRoot,omitempty"`
	// BWLimit is the name of the bandwidth limit policy to apply to this
	// backend. All backends using the same policy are subject to common
	// limits.
	BWLimit string `yaml:"bwLimit,omitempty"`
	// LogFilter specifies what gets logged for this backend. Values that
	// are not specified are inherited from the top level config.
	LogFilter LogFilter `yaml:"logFilter,omitempty"`
	// Addresses is a list of server addresses where requests are forwarded.
	// When more than one address are specified, requests are distributed
	// using a simple round robin.
	Addresses []string `yaml:"addresses,omitempty"`
	// InsecureSkipVerify disabled the verification of the backend server's
	// TLS certificate. See https://pkg.go.dev/crypto/tls#Config
	InsecureSkipVerify bool `yaml:"insecureSkipVerify,omitempty"`
	// ForwardRateLimit specifies how fast requests can be forwarded to the
	// backend servers. It applies to forwarding connections, and to
	// forwarding HTTP requests. The default value is 5 requests per second.
	ForwardRateLimit int `yaml:"forwardRateLimit"`
	// ForwardServerName is the ServerName to send in the TLS handshake with
	// the backend server. It is also used to verify the server's identify.
	// This is particularly useful when the addresses use IP addresses
	// instead of hostnames.
	ForwardServerName string `yaml:"forwardServerName,omitempty"`
	// ForwardRootCAs a list of:
	// - CA names defined in the PKI section,
	// - File names that contain PEM-encoded certificates, or
	// - PEM-encoded certificates.
	ForwardRootCAs []string `yaml:"forwardRootCAs,omitempty"`
	// ForwardTimeout is the connection timeout to backend servers. If
	// Addresses contains multiple addresses, this timeout indicates how
	// long to wait before trying the next address in the list. The default
	// value is 30 seconds.
	ForwardTimeout time.Duration `yaml:"forwardTimeout"`
	// ForwardHTTPHeaders is a list of HTTP headers to add to the forwarded
	// request. Headers that already exist are overwritten.
	ForwardHTTPHeaders map[string]string `yaml:"forwardHttpHeaders,omitempty"`

	// PathOverrides specifies different backend parameters for some path
	// prefixes.
	// Paths are matched by prefix in the order that they are listed here.
	PathOverrides []*PathOverride `yaml:"pathOverrides,omitempty"`
	// ProxyProtocolVersion enables the PROXY protocol on this backend. The
	// value is the version of the protocol to use, e.g. v1 or v2.
	// By default, the proxy protocol is not enabled.
	// See https://github.com/haproxy/haproxy/blob/master/doc/proxy-protocol.txt
	ProxyProtocolVersion string `yaml:"proxyProtocolVersion,omitempty"`
	// SanitizePath indicates that the request's path should be sanitized
	// before forwarding the request to the backend. The default is true.
	// The only reason to set this field is if the backend service somehow
	// depends on the unsanitized version of the path.
	//
	// Examples:
	//   // -> /
	//   /. -> /
	//   /foo/../bar -> /bar
	//   /../../ -> /
	SanitizePath *bool `yaml:"sanitizePath,omitempty"`

	// ServerCloseEndsConnection indicates that the proxy will close the
	// whole TCP connection when the server closes its end of it. The
	// default value is true.
	ServerCloseEndsConnection *bool `yaml:"serverCloseEndsConnection,omitempty"`
	// ClientCloseEndsConnection indicates that the proxy will close the
	// whole TCP connection when the client closes its end of it. The
	// default value is false.
	ClientCloseEndsConnection *bool `yaml:"clientCloseEndsConnection,omitempty"`
	// HalfCloseTimeout is the amount of time to keep the TCP connection
	// open when one stream is closed. The default value is 1 minute.
	HalfCloseTimeout *time.Duration `yaml:"halfCloseTimeout,omitempty"`
	// contains filtered or unexported fields
}

Backend encapsulates the data of one backend.

type BackendSSO

type BackendSSO struct {
	// Provider is the the name of an identity provider defined in
	// Config.OIDCProviders.
	Provider string `yaml:"provider"`
	// ForceReAuth is the time duration after which the user has to
	// authenticate again. By default, users don't have to authenticate
	// again until their token expires.
	ForceReAuth time.Duration `yaml:"forceReAuth,omitempty"`
	// ACL restricts which user identity can access this backend. It is a
	// list of email addresses and/or domains, e.g. "bob@example.com", or
	// "@example.com"
	// If ACL is nil, all identities are allowed. If ACL is an empty list,
	// nobody is allowed.
	ACL *[]string `yaml:"acl,omitempty"`
	// Paths lists the path prefixes for which this policy will be enforced.
	// If Paths is empty, the policy applies to all paths.
	Paths []string `yaml:"paths,omitempty"`
	// SetUserIDHeader indicates that the x-tlsproxy-user-id header should
	// be set with the email address of the user.
	//
	// This is equivalent to:
	//   ForwardHTTPHeaders: map[string]string{
	//       "x-tlsproxy-user-id": "${JWT:email}",
	//   }
	SetUserIDHeader bool `yaml:"setUserIdHeader,omitempty"`
	// GenerateIDTokens indicates that the proxy should generate ID tokens
	// for authenticated users.
	GenerateIDTokens bool `yaml:"generateIdTokens,omitempty"`
	// LocalOIDCServer is used to configure a local OpenID Provider to
	// authenticate users with backend services that support OpenID Connect.
	LocalOIDCServer *LocalOIDCServer `yaml:"localOIDCServer,omitempty"`
	// contains filtered or unexported fields
}

BackendSSO specifies the identity parameters to use for a backend.

type ClientAuth

type ClientAuth struct {
	// ACL optionally specifies which client identities are allowed to use
	// this service. A nil value disabled the authorization check and allows
	// any valid client certificate. Otherwise, the value is a slice of
	// Subject or Subject Alternate Name strings from the client X509
	// certificate, e.g. SUBJECT:CN=Bob or EMAIL:bob@example.com
	ACL *[]string `yaml:"acl,omitempty"`
	// RootCAs a list of:
	// - CA names defined in the PKI section,
	// - File names that contain PEM-encoded certificates, or
	// - PEM-encoded certificates.
	RootCAs []string `yaml:"rootCAs,omitempty"`
	// AddClientCertHeader indicates which fields of the HTTP
	// X-Forwarded-Client-Cert header should be added to the request when
	// Mode is HTTP or HTTPS.
	AddClientCertHeader []string `yaml:"addClientCertHeader,omitempty"`
}

ClientAuth specifies how to authenticate and authorize the TLS client's identity.

type Config

type Config struct {
	// Definitions is a section where yaml anchors can be defined. It is
	// otherwise ignored by the proxy.
	Definitions any `yaml:"definitions,omitempty"`

	// HTTPAddr must be reachable from the internet via port 80 for the
	// letsencrypt ACME http-01 challenge to work. If the httpAddr is empty,
	// the proxy will only use tls-alpn-01 and tlsAddr must be reachable on
	// port 443.
	// See https://letsencrypt.org/docs/challenge-types/
	HTTPAddr string `yaml:"httpAddr,omitempty"`
	// TLSAddr is the address where the proxy will receive TLS connections
	// and forward them to the backends.
	TLSAddr string `yaml:"tlsAddr"`
	// EnableQUIC specifies whether the QUIC protocol should be enabled.
	// The default is true if the binary is compiled with QUIC support.
	EnableQUIC *bool `yaml:"enableQUIC,omitempty"`
	// AcceptProxyHeaderFrom is a list of CIDRs. The PROXY protocol is
	// enabled for incoming TCP connections originating from IP addresses
	// within one of these CIDRs. By default, the proxy protocol is not
	// enabled for incoming connections.
	// See https://github.com/haproxy/haproxy/blob/master/doc/proxy-protocol.txt
	AcceptProxyHeaderFrom []string `yaml:"acceptProxyHeaderFrom,omitempty"`
	// HWBacked indicates that local data should be encrypted using
	// hardware-backed encryption keys, e.g. with a Trusted Platform Module
	// (TPM). When this option is true, the local data cannot be used or
	// recovered on a different device.
	//
	// This option cannot be changed without manually deleting the cache
	// directory.
	HWBacked bool `yaml:"hwBacked,omitempty"`
	// CacheDir is the directory where the proxy stores its data, e.g. TLS
	// certificates, OCSP responses, etc.
	CacheDir string `yaml:"cacheDir,omitempty"`
	// DefaultServerName is the server name to use when the TLS client
	// doesn't use the Server Name Indication (SNI) extension.
	DefaultServerName string `yaml:"defaultServerName,omitempty"`
	// LogFilter specifies what gets logged for this backend. Values can
	// be overridden on a per-backend basis.
	LogFilter LogFilter `yaml:"logFilter,omitempty"`
	// Backends is the list of service backends.
	Backends []*Backend `yaml:"backends"`
	// Email is optionally sent to Let's Encrypt when registering a new
	// account.
	Email string `yaml:"email,omitempty"`
	// RevokeUnusedCertificates indicates that unused certificates
	// should be revoked. The default is true.
	// See https://letsencrypt.org/docs/revoking/
	RevokeUnusedCertificates *bool `yaml:"revokeUnusedCertificates,omitempty"`
	// MaxOpen is the maximum number of open incoming connections.
	MaxOpen int `yaml:"maxOpen,omitempty"`
	// AcceptTOS indicates acceptance of the Let's Encrypt Terms of Service.
	// See https://letsencrypt.org/repository/
	AcceptTOS bool `yaml:"acceptTOS"`
	// OIDCProviders is the list of OIDC providers.
	OIDCProviders []*ConfigOIDC `yaml:"oidc,omitempty"`
	// SAMLProviders is the list of SAML providers.
	SAMLProviders []*ConfigSAML `yaml:"saml,omitempty"`
	// PasskeyProviders are identity providers that use OIDC or SAML for
	// the first authentication and to configure passkeys, and then rely
	// exclusively on passkeys.
	PasskeyProviders []*ConfigPasskey `yaml:"passkey,omitempty"`
	// PKI is a list of locally hosted and managed Certificate Authorities
	// that can be used to authenticate TLS clients and backend servers.
	PKI []*ConfigPKI `yaml:"pki,omitempty"`
	// TLSCertificates is a lists of TLS certificates that should be used
	// instead of Let's Encrypt. If a certificate is needed but there is no
	// match in this list, Let's Encrypt is used.
	TLSCertificates []*TLSCertificate `yaml:"tlsCertificates,omitempty"`
	// BWLimits is the list of named bandwidth limit groups.
	// Each backend can be associated with one group. The group's limits
	// are shared between all the backends associated with it.
	BWLimits []*BWLimit `yaml:"bwLimits,omitempty"`
	// WebSockets is a list of WebSocket endpoints and where they get
	// forwarded.
	// Incoming WebSocket requests are bridged to TCP connections. The
	// content of BinaryMessages are streamed to the TCP server, and
	// data received from the server is sent to the client also
	// as BinaryMessages.
	WebSockets []*WebSocketConfig `yaml:"webSockets,omitempty"`
	// contains filtered or unexported fields
}

Config is the TLS proxy configuration.

func ReadConfig

func ReadConfig(filename string) (*Config, error)

ReadConfig reads and validates a YAML config file.

func (*Config) Check

func (cfg *Config) Check() error

Check checks that the Config is valid, sets some default values, and initializes internal data structures.

type ConfigOIDC

type ConfigOIDC struct {
	// Name is the name of the provider. It is used internally only.
	Name string `yaml:"name"`
	// DiscoveryURL is the discovery URL of the OIDC provider. If set, it
	// is used to discover the values of AuthEndpoint and TokenEndpoint.
	DiscoveryURL string `yaml:"discoveryUrl,omitempty"`
	// AuthEndpoint is the authorization endpoint. It must be set only if
	// DiscoveryURL is not set.
	AuthEndpoint string `yaml:"authorizationEndpoint,omitempty"`
	// Scopes is the list of scopes to request. The default list ("openid",
	// "email") returns only the user's email address.
	// To get the user's name and picture, add the "profile" scope with
	// google, or the "public_profile" scope with facebook, i.e.
	// {"openid", "email", "profile"} or {"openid", "email",
	// "public_profile"}.
	Scopes []string `yaml:"scopes,flow,omitempty"`
	// HostedDomain specifies that the HD param should be used.
	// This parameter is used by Google is restrict the login process to
	// one hosted domain, e.g. example.com. An empty or unspecified value
	// means accounts from any domain will be accepted.
	// https://developers.google.com/identity/openid-connect/openid-connect#hd-param
	HostedDomain string `yaml:"hostedDomain,omitempty"`
	// TokenEndpoint is the token endpoint. It must be set only if
	// DiscoveryURL is not set.
	TokenEndpoint string `yaml:"tokenEndpoint,omitempty"`
	// UserinfoEndpoint is the userinfo endpoint. It must be set only if
	// DiscoveryURL is not set and the token endpoint doesn't return an
	// ID token.
	UserinfoEndpoint string `yaml:"userinfoEndpoint,omitempty"`
	// RedirectURL is the OAUTH2 redirect URL. It must be managed by the
	// proxy.
	RedirectURL string `yaml:"redirectUrl"`
	// ClientID is the Client ID.
	ClientID string `yaml:"clientId"`
	// ClientSecret is the Client Secret.
	ClientSecret string `yaml:"clientSecret"`
	// Domain, if set, determine the domain where the user identities will
	// be valid. Only set this if all host names in the domain are served
	// by this proxy.
	Domain string `yaml:"domain,omitempty"`
}

ConfigOIDC contains the parameters of an OIDC provider.

type ConfigPKI

type ConfigPKI struct {
	// Name is the name of the CA.
	Name string `yaml:"name"`
	// KeyType is type of cryptographic key to use with this CA. Valid
	// values are: ecdsa-p224, ecdsa-p256, ecdsa-p394, ecdsa-p521, ed25519,
	// rsa-2048, rsa-3072, and rsa-4096.
	KeyType string `yaml:"keyType,omitempty"`
	// IssuingCertificateURLs is a list of URLs that return the X509
	// certificate of the CA.
	IssuingCertificateURLs []string `yaml:"issuingCertificateUrls,omitempty"`
	// CRLDistributionPoints is a list of URLs that return the Certificate
	// Revocation List for this CA.
	CRLDistributionPoints []string `yaml:"crlDistributionPoints,omitempty"`
	// OCSPServer is a list of URLs that serve the Online Certificate Status
	// Protocol (OCSP) for this CA.
	// https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol
	OCSPServer []string `yaml:"ocspServers,omitempty"`
	// Endpoint is the URL where users can manage their certificates. It
	// should be on a backend with restricted access and/or forceReAuth
	// enabled.
	Endpoint string `yaml:"endpoint"`
	// Admins is a list of users who are allowed to perform administrative
	// tasks on the CA, e.g. revoke any certificate.
	Admins []string `yaml:"admins"`
}

ConfigPKI defines the parameters of a local Certificate Authority.

type ConfigPasskey

type ConfigPasskey struct {
	// Name is the name of the provider. It is used internally only.
	Name string `yaml:"name"`
	// IdentityProvider is the name of another identity provider that will
	// be used to authenticate the user before registering their first
	// passkey.
	IdentityProvider string `yaml:"identityProvider"`
	// RefreshInterval is the amount of time after which users must
	// re-authenticate with the other identity provider.
	// The value is a go duration, e.g. '500h'
	// The default value of 0 means no re-authentication is required.
	RefreshInterval time.Duration `yaml:"refreshInterval,omitempty"`
	// Endpoint is a URL on this proxy that will handle the passkey
	// authentication.
	Endpoint string `yaml:"endpoint"`
	// Domain, if set, determine the domain where the user identities will
	// be valid. Only set this if all host names in the domain are served
	// by this proxy.
	Domain string `yaml:"domain,omitempty"`
}

ConfigPasskey contains the parameters of a Passkey manager.

type ConfigSAML

type ConfigSAML struct {
	// Name is the name of the provider. It is used internally only.
	Name     string `yaml:"name"`
	SSOURL   string `yaml:"ssoUrl"`
	EntityID string `yaml:"entityId"`
	Certs    string `yaml:"certs"`
	ACSURL   string `yaml:"acsUrl"`
	// Domain, if set, determine the domain where the user identities will
	// be valid. Only set this if all host names in the domain are served
	// by this proxy.
	Domain string `yaml:"domain,omitempty"`
}

ConfigSAML contains the parameters of a SAML identity provider.

type LocalOIDCClient

type LocalOIDCClient struct {
	// ID is the OAUTH2 client ID. It should a unique string that's hard to
	// guess. See https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/
	ID string `yaml:"id"`
	// Secret is the OAUTH2 secret for the client. It should be a random
	// string generated with something like:
	//  dd if=/dev/random bs=32 count=1 | base64
	Secret string `yaml:"secret"`
	// RedirectURI is where the authorization endpoint will redirect the
	// user once the authorization code has been granted.
	RedirectURI []string `yaml:"redirectUri"`
}

LocalOIDCClient contains the parameters of one OIDC client that is allowed to connect to the local OIDC server. All the fields must be shared with the client application.

type LocalOIDCRewriteRule

type LocalOIDCRewriteRule struct {
	InputClaim  string `yaml:"inputClaim"`
	OutputClaim string `yaml:"outputClaim"`
	Regex       string `yaml:"regex"`
	Value       string `yaml:"value"`
}

LocalOIDCRewriteRule define how to rewrite existing claims or create new claims from existing ones. The following example uses the "email" claim to create a "preferred_username" claim by removing the domain name.

InputClaim: "email"
OutputClaim: "preferred_username"
Regex: "^([^@]+)@example.com$"
Value: "$1"

type LocalOIDCServer

type LocalOIDCServer struct {
	// PathPrefix specifies how the endpoint paths are constructed. It is
	// generally fine to leave it empty.
	PathPrefix string `yaml:"pathPrefix,omitempty"`
	// Clients is the list of all authorized clients and their
	// configurations.
	Clients []*LocalOIDCClient `yaml:"clients,omitempty"`
	// RewriteRules are used to rewrite existing claims or create new claims
	// from existing ones.
	RewriteRules []*LocalOIDCRewriteRule `yaml:"rewriteRules,omitempty"`
}

LocalOIDCServer is used to configure a local OpenID Provider to authenticate users with backend services that support OpenID Connect. When this is enabled, tlsproxy will add a few endpoints to this backend: - <PathPrefix>/.well-known/openid-configuration - <PathPrefix>/authorization - <PathPrefix>/token - <PathPrefix>/jwks

type LogFilter

type LogFilter struct {
	// Connections indicates that incoming connections are logged.
	Connections *bool `yaml:"connections,omitempty"`
	// Requests indicates that http requests are logged.
	Requests *bool `yaml:"requests,omitempty"`
	// Errors indicates that errors are logged.
	Errors *bool `yaml:"errors,omitempty"`
}

LogFilter specifies what to log.

type PathOverride

type PathOverride struct {
	// Paths is the list of path prefixes for which these parameters apply.
	Paths []string `yaml:"paths"`
	// Addresses is a list of server addresses where requests are forwarded.
	// When more than one address are specified, requests are distributed
	// using a simple round robin.
	Addresses []string `yaml:"addresses,omitempty"`
	// Mode is either HTTP or HTTPS.
	Mode string `yaml:"mode"`
	// DocumentRoot indicates local files should be served from this
	// directory. This option is only valid when Addresses is empty.
	DocumentRoot string `yaml:"documentRoot,omitempty"`
	// BackendProto specifies which protocol to use when forwarding an HTTPS
	// request to the backend. This field is only valid in modes HTTP and
	// HTTPS.
	// The value should be an ALPN protocol, e.g.: http/1.1, h2, or h3.
	// If the value is set explicitly to "", the same protocol used by the
	//  client will be used with the backend.
	BackendProto *string `yaml:"backendProto,omitempty"`
	// InsecureSkipVerify disabled the verification of the backend server's
	// TLS certificate. See https://pkg.go.dev/crypto/tls#Config
	InsecureSkipVerify bool `yaml:"insecureSkipVerify,omitempty"`
	// ForwardServerName is the ServerName to send in the TLS handshake with
	// the backend server. It is also used to verify the server's identify.
	// This is particularly useful when the addresses use IP addresses
	// instead of hostnames.
	ForwardServerName string `yaml:"forwardServerName,omitempty"`
	// ForwardRootCAs a list of:
	// - CA names defined in the PKI section,
	// - File names that contain PEM-encoded certificates, or
	// - PEM-encoded certificates.
	ForwardRootCAs []string `yaml:"forwardRootCAs,omitempty"`
	// ForwardTimeout is the connection timeout to backend servers. If
	// Addresses contains multiple addresses, this timeout indicates how
	// long to wait before trying the next address in the list. The default
	// value is 30 seconds.
	ForwardTimeout time.Duration `yaml:"forwardTimeout"`
	// ProxyProtocolVersion enables the PROXY protocol on this backend. The
	// value is the version of the protocol to use, e.g. v1 or v2.
	// By default, the proxy protocol is not enabled.
	// See https://www.haproxy.org/download/2.3/doc/proxy-protocol.txt
	ProxyProtocolVersion string `yaml:"proxyProtocolVersion,omitempty"`
	// ForwardHTTPHeaders is a list of HTTP headers to add to the forwarded
	// request. Headers that already exist are overwritten.
	//
	// Special keywords are automatically expanded from the header values:
	//   ${NETWORK} is either tcp or udp.
	//   ${LOCAL_ADDR} is the local address of the network connection.
	//   ${REMOTE_ADDR} is the remote address of the network connection.
	//   ${LOCAL_IP} is the local IP address of the network connection.
	//   ${REMOTE_IP} is the remote IP address of the network connection.
	//   ${SERVER_NAME} is the server name requested by the client.
	//   ${JWT:xxxx} expands to the value of claim xxxx from the ID token.
	ForwardHTTPHeaders *map[string]string `yaml:"forwardHttpHeaders,omitempty"`
	// SanitizePath indicates that the request's path should be sanitized
	// before forwarding the request to the backend.
	SanitizePath *bool `yaml:"sanitizePath,omitempty"`
	// contains filtered or unexported fields
}

PathOverride specifies different backend parameters for some path prefixes.

type Proxy

type Proxy struct {
	// contains filtered or unexported fields
}

Proxy receives TLS connections and forwards them to the configured backends.

func New

func New(cfg *Config, passphrase []byte) (*Proxy, error)

New returns a new initialized Proxy.

func NewTestProxy

func NewTestProxy(cfg *Config) (*Proxy, error)

NewTestProxy returns a test Proxy that uses an internal certificate manager instead of letsencrypt.

func (*Proxy) Reconfigure

func (p *Proxy) Reconfigure(cfg *Config) error

Reconfigure updates the proxy's configuration. Some parameters cannot be changed after Start has been called, e.g. HTTPAddr, TLSAddr, CacheDir.

func (*Proxy) RevokeAllCertificates

func (p *Proxy) RevokeAllCertificates(ctx context.Context, reason string) error

RevokeAllCertificates revokes all the certificates in the cache.

func (*Proxy) Shutdown

func (p *Proxy) Shutdown(ctx context.Context)

Shutdown gracefully shuts down the proxy, waiting for all existing connections to close or ctx to be canceled.

func (*Proxy) Start

func (p *Proxy) Start(ctx context.Context) error

Start starts a TLS proxy with the given configuration. The proxy runs in background until the context is canceled.

func (*Proxy) Stop

func (p *Proxy) Stop()

Stop closes all connections and stops all goroutines.

type TLSCertificate

type TLSCertificate struct {
	// ServerNames is a list of server names for which this certificate
	// should be used.
	ServerNames []string `yaml:"serverNames"`
	// KeyFile is the name of the file that contains the private key.
	KeyFile string `yaml:"key"`
	// CertFile is the name of the file that contains the X.509 certificate
	// chain.
	CertFile string `yaml:"cert"`
}

TLSCertificate specifies TLS keys and certificates to use for given server names.

type WebSocketConfig

type WebSocketConfig struct {
	Endpoint string `yaml:"endpoint"`
	Address  string `yaml:"address,omitempty"`
}

WebSocketConfig specifies a WebSocket endpoint.