The JWT proxy is intended to be used as a complementary service for authenticating, and possibly authorizing requests made between services. There is a forward proxy component, which can be configured to sign outgoing requests to another service, and a reverse proxy component, which can be used to authenticate incoming requests from another service.
The JWT forward proxy is used to sign outgoing requests with a JWT using a private key.
- Append a JWT
Authorizationheader containing claims about which service the request originated from, and who is the intended recipient - Autogenerate private signing keys, and publish the public portion to a server following the key server specification
- Ability to use a preshared private key if we don't want to use autogenerated keys (useful when originating service is HA)
- Ability to sign SSL requests using MITM SSL with configurable certificate authority
- Ability to append static claims via config
- Ability to read dynamic claims out of a request header and turn them into JWT claims
- When the proxy is configured to use MITM SSL, the
CONNECTtunneling mechanism is only available to forward HTTPS requests. By default, most clients exclusively useCONNECTfor HTTPS requests, which is 100% supported.
The JWT reverse proxy is used to verify incoming requests that were signed by the forward proxy.
- Ability to decode and verify JWT
Authorizationheaders on incoming requests - Ability to verify the signature based on the specified signing key against a public key fetched from a key server
- Ability to verify from a single issuer using a pre-shared public key (likely only useful for testing)
- Ability to verify SSL requests by doing SSL termination on behalf of the upstream
- Pluggable claims verifier interface, with bundled static claims verifier implementation
Run with:
jwtproxy -config config.yamlThe configuration yaml file contains a jwtproxy top level config flag, which allows a single yaml file to be used to configure multiple services. The presence or absence of a signer config or verifier config block will enable the forward and reverse proxy respectively.
jwtproxy:
<Signer Config>verifier_proxies:
- <Verifier Config>
- <Verifier Config>Usage examples are provided in the examples folder.
Configures and enables the JWT forward signing proxy.
jwtproxy:
signer_proxy:
enabled: <bool|true># Addr at which to bind proxy serverlisten_addr: <string|:8080>shutdown_timeout: <time.Duration|1m># Optional key and CA certificate to forge MITM SSL certificatesca_key_file: <path|nil>ca_crt_file: <path|nil># Certificates to be trusted by the proxy when its MITM mechanism communicates with remotes.# This is optional. Specifying it currently replaces system root certificates entirely.trusted_certificates: <[]string|system root certificates># Whether the remotes' certificate chain and host name should be verified.insecure_skip_verify: <bool|false>signer:
# Signing service nameissuer: <string|nil># Validity durationexpiration_time: <time.Duration|5m># How much time skew we allow between signer and verifiermax_skew: <time.Duration|1m># Length of random nonce valuesnonce_length: <int|32># Registerable private key source typeprivate_key:
type: <string|nil>options: <map[string]interface{}>Configures a private key source which generates key pairs automatically and publishes them to a key server.
private_key:
type: autogeneratedoptions:
# How often we publish a new keyrotate_every: <time.Duration|12h># Folder in which to store autogenerated keys on diskkey_folder: <string|~/.config/jwtproxy/># Registerable key server and config at which to publish public keyskey_server:
type: <string|nil>options: <map[string]interface{}>Configures a key server which talks to a server which implements the key registry protocol.
key_server:
type: keyregistryoptions:
# Base URL from which to access key registry endpoints.registry: <string|nil>Configures a private key source which simply uses the key files specified.
private_key:
type: presharedoptions:
# Unique identifier for the private keykey_id: <string|nil># Location of PEM encoded private key fileprivate_key_path: <path|nil>Configures and enables one or more JWT verifying reverse proxyies.
jwtproxy:
verifier_proxies:
- enabled: <bool|true># Addr at which to listen for requests# It can either be an HTTP(s) URL or an UNIX socket path prefixed by 'unix:'listen_addr: <string|:8081>shutdown_timeout: <time.Duration|1m># Optional PEM private key and certificate files for SSL terminationkey_file: <path|nil>crt_file: <path|nil>verifier:
# Upstream server to which to forward requests# It can either be an HTTP(s) URL or an UNIX socket path prefixed by 'unix:'upstream: <string|nil># Required value for audience claim,# Usually our advertised protocol and hostnameaudience: <string|nil># How much time skew we allow between signer and verifiermax_skew: <time.Duration|1m># Maximum total amount of time for which a JWT can be signedmax_ttl: <time.Duration|5m># List of paths which should be proxied without authenticationexcludes: <[]string|nil># URL where unauthenticated requests should be redirected to# If null then 403 response code will be responded without redirectionauth_redirect_url: <string|nil># Configures whether token should be searched in cookie `access_token`# `false` by default, so JwtProxy ignores token specified in cookiescookies_enabled: <bool|nil># Registerable key server type and options used to fetch# public keys for verifying signatureskey_server:
type: <string|nil>options: <map[string]interface{}># Registerable type and options where we track used noncesnonce_storage:
type: <string|nil>options: <map[string]interface{}># a path on which the `access_token` cookie should be stored. This means that the browsers will only use the# cookie on requests for URLs on the sub paths of the cookie_path.cookie_path: <string|nil># In case the JWT proxy is placed behind a path-rewriting reverse proxy (such as Kubernetes Ingress)# the value of this property can be used to modify the "apparent" path of the request as the JWT proxy# sees it when composing the redirect to be used after the authentication request.public_base_path: <string|nil>Configures a key server which fetches public keys from a server which implements the key registry protocol.
key_server:
type: keyregistryoptions:
# Base URL from which to access key registry endpoints.registry: <string|nil># Optional cache config to alleviate load on the key server.cache:
# How long the keys stay valid in the cacheduration: <time.Duration|10m># How often expired keys are removed from memorypurge_interval: <time.Duration|1m>Configures a local preshared mock key server which can return one and only one public key. This should probably be used only for testing.
key_server:
type: presharedoptions:
# Configures the only issuer we will allowissuer: <string|nil># Unique ID of the only key from which we validate requestskey_id: <string|nil># File path to the PEM encoded public key to verify signaturespublic_key_path: <path|nil>Configures nonce storage which stores previously seen nonces in a TTL cache in memory.
nonce_storage:
type: localoptions:
# How often we run the cache janitor to clean up expired noncespurge_interval: <time.Duration|0>Configures void storage which does not do any storing or validating of nonces. Supposed to be used when no strict 'jti' claim uniqueness verification needed.
nonce_storage:
type: voidWhen it comes to sign HTTPs requests, the forward proxy must hijack connections and act as a man-in-the-middle. Therefore, the proxy requires a CA certificate and private key in order to forge TLS/SSL certificates on behalf on the remote HTTPs server. If none are specified, the forward proxy will throw a warning at startup and refuse to proxy HTTPs requests.
The following commands generate both, valid for a year, without any passphrase (otherwise, the proxy would require us to type it).
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ca.key -out ca.crt
The certificate then has to be distributed and trusted by every clients that goes through the forward proxy. The private key must remain secret.
The CA certificate and private key should be specified using the ca_key_file and ca_crt_file parameters in the Signer configuration.
To confirm reverse proxy's authenticity and to guarantee confidentiality and integrity of the exchanged data, the reverse proxy can terminate TLS/SSL using a public/private key pair. The key pair could either be provided by a trusted certificate authority or self-signed using the commands below:
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout reverseProxy.key -out reverseProxy.crt
Note that to the question Common Name (e.g. server FQDN or YOUR name), you must write the host that you expect to use for the reverse proxy.
The key pair should be specified using the key_file and crt_file parameters in the Verifier configuration.
Also, because the key pair is self-signed, the certificate must be trusted by the forward proxy. This can be done by trusting the certificate system-wide or by specifying it using the trusted_certificates list parameter in the Signer configuration.
Run tests in project with:
go test ./...Build Binary file locally with:
go build -o jwtproxy cmd/jwtproxy/main.go
Then you'll be able to run it with:
./jwtproxy -config config.yaml
Build JwtProxy docker image with:
docker build -t jwtproxy .
Then you'll be able to run it with:
docker run -it -v /local/folder/with/jwtproxy/:/config jwtproxy -config /config/config.yaml
The following CentOS CI jobs are associated with the repository: