feat: Extended Root CA for client TLS connections (#181)

.schema/config.schema.json

@@ -1212,6 +1212,52 @@
             "timeout": {
               "$ref": "#/definitions/serverTimeout"
             },
+            "client_tls": {
+              "type": "object",
+              "title": "Client TLS",
+              "additionalProperties": false,
+              "properties": {
+                "trusted_certificates": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "default": null,
+                  "examples": [
+                    [
+                      "./self-signed.crt"
+                    ]
+                  ],
+                  "title": "Trusted Certificates",
+                  "description": "The array of files containing the certificates to trust when opening new TLS connections."
+                },
+                "cache": {
+                  "type": "object",
+                  "title": "Certificates Cache",
+                  "additionalProperties": false,
+                  "properties": {
+                    "refresh_frequency": {
+                      "type": "integer",
+                      "default": 1000,
+                      "title": "Refresh Frequency",
+                      "description": "Test if transport needs certificate refresh once every 1000 requests."
+                    },
+                    "ttl": {
+                      "type": "string",
+                      "title": "Expire After",
+                      "description": "Sets the time-to-live of the certificate cache.",
+                      "pattern": "^[0-9]+(ns|us|ms|s|m|h)$",
+                      "default": "5m",
+                      "examples": [
+                        "1h",
+                        "1m",
+                        "30s"
+                      ]
+                    }
+                  }
+                }
+              }
+            },
             "cors": {
               "$ref": "#/definitions/cors"
             },

docs/docs/api-access-rules.md

@@ -234,6 +234,40 @@ authenticators:
 }
 ```
 
+## Client TLS Transport
+
+In case you want to enable TLS connections to services protected by a
+self-signed certificate you will very likely need to setup your own custom
+certificates. Through the `client_tls` configuration you can set custom
+certificates that will be used by oathkeeper to connect to other services such
+as the upstream service, authorizers, authenticators, and mutators. The
+certificates are cached in memory to reduce latency, you can set the cache
+expiration conditions through the `cache` configuration or disable caching
+entirely. NOTE: Caching is enabled by default.
+
+Use the `cache.refresh_frequency` to test once every `1000` requests for a
+certificate file size or modification timestamp change. Setting the value to 0
+will disable the refresh on a frequency functionality, but retrain the update on
+file path change functionality.
+
+Use the `cache.ttl` to force the refresh of certificates once every `5m`
+regardless of the cache status. Setting this value to 0 will disable forced
+cache eviction due to an expired time-to-live.
+
+**oathkeeper.yml**
+
+```yaml
+serve:
+  proxy:
+    client_tls:
+      trusted_certificates:
+        - /my-certs/certificate-to-append.crt
+        - /my-certs/another-certificate.crt
+      cache:
+        refresh_frequency: 1000
+        ttl: 5m
+```
+
 ## Scoped Credentials
 
 Some credentials are scoped. For example, OAuth 2.0 Access Tokens usually are

docs/docs/reference/configuration.md

@@ -1538,6 +1538,63 @@ serve:
       #
       read: 5s
 
+    ## Client TLS Transport ##
+    #
+    # Control the client TLS transport.
+    #
+    client_tls:
+      ## Trusted Root CA Certificates ##
+      #
+      # The path to a certificate files to append to the Root Certificate Authority for TLS connections. Use this to accept self-signed certificates while keeping the host system certificate authority unaltered.
+      #
+      # Default value: ""
+      #
+      # Examples:
+      # - self-signed.crt
+      #
+      # Set this value using environment variables on
+      # - Linux/macOS:
+      #    $ export SERVE_PROXY_CLIENT_TLS_TRUSTED_CERTIFICATES=<value>
+      # - Windows Command Line (CMD):
+      #    > set SERVE_PROXY_CLIENT_TLS_TRUSTED_CERTIFICATES=<value>
+      #
+      trusted_certificates:
+        - /my-certs/certificate-to-append.crt
+        - /my-certs/another-certificate.crt
+
+      ## cache ##
+      #
+      cache:
+        ## Refresh Frequency ##
+        #
+        # The interval at which to test if the upstream transport certificates changed. Use 0 to disable test.
+        #
+        # Default value: 1000
+        #
+        # Examples:
+        # - 1000
+        # - 0
+        #
+        # Set this value using environment variables on
+        # - Linux/macOS:
+        #    $ export SERVE_PROXY_CLIENT_TLS_CACHE_REFRESH_FREQUENCY=<value>
+        # - Windows Command Line (CMD):
+        #    > set SERVE_PROXY_CLIENT_TLS_CACHE_REFRESH_FREQUENCY=<value>
+        #
+        refresh_frequency: 1000
+
+        ## Refresh Frequency ##
+        #
+        # Sets the time-to-live of the certificate cache. Use 0 to disable cache expiration.
+        #
+        # Set this value using environment variables on
+        # - Linux/macOS:
+        #    $ export SERVE_PROXY_CLIENT_TLS_CACHE_TTL=<value>
+        # - Windows Command Line (CMD):
+        #    > set SERVE_PROXY_CLIENT_TLS_CACHE_TTL=<value>
+        #
+        ttl: 5m
+
     ## Cross Origin Resource Sharing (CORS) ##
     #
     # Configure [Cross Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/) using the following options.

driver/configuration/provider.go

@@ -5,7 +5,8 @@ import (
 	"net/url"
 	"time"
 
-	"github.com/gobuffalo/packr/v2"
+	packr "github.com/gobuffalo/packr/v2"
+
 	"github.com/ory/fosite"
 	"github.com/ory/x/tracing"
 
@@ -40,6 +41,9 @@ type Provider interface {
 	ProxyReadTimeout() time.Duration
 	ProxyWriteTimeout() time.Duration
 	ProxyIdleTimeout() time.Duration
+	ProxyServeClientTLSTrustedCerts() []string
+	ProxyServeClientTLSCacheRefreshFrequency() int
+	ProxyServeClientTLSCacheTimeToLive() time.Duration
 
 	APIReadTimeout() time.Duration
 	APIWriteTimeout() time.Duration

driver/configuration/provider_viper.go

@@ -43,6 +43,9 @@ const (
 	ViperKeyProxyIdleTimeout                    = "serve.proxy.timeout.idle"
 	ViperKeyProxyServeAddressHost               = "serve.proxy.host"
 	ViperKeyProxyServeAddressPort               = "serve.proxy.port"
+	ViperKeyProxyClientTLSTrustedCerts          = "serve.proxy.client_tls.trusted_certificates"
+	ViperKeyProxyClientTLSCacheRefreshFrequency = "serve.proxy.client_tls.cache.refresh_frequency"
+	ViperKeyProxyClientTLSCacheTimeToLive       = "serve.proxy.client_tls.cache.ttl"
 	ViperKeyAPIServeAddressHost                 = "serve.api.host"
 	ViperKeyAPIServeAddressPort                 = "serve.api.port"
 	ViperKeyAPIReadTimeout                      = "serve.api.timeout.read"
@@ -179,6 +182,18 @@ func (v *ViperProvider) ProxyServeAddress() string {
 	)
 }
 
+func (v *ViperProvider) ProxyServeClientTLSTrustedCerts() []string {
+	return viperx.GetStringSlice(v.l, ViperKeyProxyClientTLSTrustedCerts, nil)
+}
+
+func (v *ViperProvider) ProxyServeClientTLSCacheRefreshFrequency() int {
+	return viperx.GetInt(v.l, ViperKeyProxyClientTLSCacheRefreshFrequency, 1000)
+}
+
+func (v *ViperProvider) ProxyServeClientTLSCacheTimeToLive() time.Duration {
+	return viperx.GetDuration(v.l, ViperKeyProxyClientTLSCacheTimeToLive, time.Minute*5)
+}
+
 func (v *ViperProvider) APIReadTimeout() time.Duration {
 	return viperx.GetDuration(v.l, ViperKeyAPIReadTimeout, time.Second*5)
 }

internal/certs/cert_manager.go

@@ -0,0 +1,183 @@
+package certs
+
+import (
+	"crypto/x509"
+	"io/ioutil"
+	"os"
+	"runtime"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/pkg/errors"
+
+	"github.com/ory/oathkeeper/driver/configuration"
+)
+
+type CertManager struct {
+	c configuration.Provider
+
+	// isWindows is set to true if the application is running in a Windows
+	// environment. This information is used to decide whether the system
+	// certificate pool should be loaded or not as Windows does not support
+	// this feature and will return an error.
+	isWindows bool
+
+	// cachePool is used to optimize performance and to avoid reloading the cert
+	// pool at every request. The cache expires after its time-to-live has ended
+	// or the an external action has invalidated the cache itself.
+	cachePool *x509.CertPool
+
+	// cacheTime contains the last update of the cache and is used to check
+	// whether it has reached the end of its time-to-live. This value is used for
+	// caching purposes.
+	cacheTime time.Time
+
+	// cacheCerts contains the cached certificates and all file information
+	// associated with them such as size and last modification time.
+	cacheCerts sync.Map
+
+	// requests is an atomic counter that keeps track of how many requests have
+	// been served since the last certificate refresh. This value is used for
+	// caching purposes.
+	requests int64
+}
+
+type CertCache struct {
+	path string
+	stat *os.FileInfo
+}
+
+func NewCertManager(c configuration.Provider) *CertManager {
+	return &CertManager{
+		c:         c,
+		isWindows: runtime.GOOS == "windows",
+	}
+}
+
+func (cm *CertManager) systemCertPool() (*x509.CertPool, error) {
+	if cm.isWindows {
+		return x509.NewCertPool(), nil
+	}
+
+	return x509.SystemCertPool()
+}
+
+func (cm *CertManager) additionalCerts() ([][]byte, error) {
+	var certs [][]byte
+	for _, cert := range cm.c.ProxyServeClientTLSTrustedCerts() {
+		data, err := ioutil.ReadFile(cert)
+		if err != nil {
+			return nil, err
+		}
+
+		stat, err := os.Stat(cert)
+		if err != nil {
+			return nil, err
+		}
+
+		cm.cacheCerts.Store(cert, &CertCache{
+			path: cert,
+			stat: &stat,
+		})
+
+		certs = append(certs, data)
+	}
+
+	return certs, nil
+}
+
+func (cm *CertManager) cacheIsExpired() bool {
+	if cm.c.ProxyServeClientTLSCacheTimeToLive() == 0 {
+		return false
+	}
+
+	// If the last time the transport was accessed is beyond the cache TTL then
+	// a refresh of the cache is forced whether the file was updated or not.
+	// This ensures that the cache is always refreshed at fixed intervals
+	// regardless of the environment. If the TTL is set to 0 skip the check.
+	return time.Since(cm.cacheTime) > cm.c.ProxyServeClientTLSCacheTimeToLive()
+}
+
+func (cm *CertManager) lookupCertificate(cert string) (*CertCache, bool) {
+	cacheItem, ok := cm.cacheCerts.Load(cert)
+	if !ok {
+		return nil, false
+	}
+
+	cache, ok := cacheItem.(*CertCache)
+	return cache, ok
+}
+
+func (cm *CertManager) isCertificateValid(cert string) (bool, error) {
+	cache, ok := cm.lookupCertificate(cert)
+	if !ok {
+		return false, nil
+	}
+
+	refreshFrequency := cm.c.ProxyServeClientTLSCacheRefreshFrequency()
+	if refreshFrequency <= 0 {
+		return true, nil
+	}
+
+	if cm.requests%int64(refreshFrequency) != 0 {
+		return true, nil
+	}
+
+	stat, err := os.Stat(cert)
+	if err != nil {
+		return false, err
+	}
+
+	if stat.Size() != (*cache.stat).Size() || stat.ModTime() != (*cache.stat).ModTime() {
+		return true, nil
+	}
+
+	return false, nil
+}
+
+func (cm *CertManager) cacheIsValid() (bool, error) {
+	for _, cert := range cm.c.ProxyServeClientTLSTrustedCerts() {
+		valid, err := cm.isCertificateValid(cert)
+		if err != nil {
+			return false, err
+		}
+
+		if !valid {
+			return false, nil
+		}
+	}
+
+	return true, nil
+}
+
+func (cm *CertManager) CertPool() (*x509.CertPool, error) {
+	atomic.AddInt64(&cm.requests, 1)
+
+	cacheValid, err := cm.cacheIsValid()
+	if err != nil {
+		return nil, err
+	}
+
+	if !cm.cacheIsExpired() && cacheValid {
+		return cm.cachePool, nil
+	}
+
+	certs, err := cm.additionalCerts()
+	if err != nil {
+		return nil, err
+	}
+
+	pool, err := cm.systemCertPool()
+	if err != nil {
+		return nil, err
+	}
+
+	for _, data := range certs {
+		if ok := pool.AppendCertsFromPEM(data); !ok {
+			return nil, errors.New("No certs appended, only system certs present, did you specify the correct cert file?")
+		}
+	}
+
+	return pool, nil
+}