github.com/vetinari/planb-tokeninfo

Plan B Token Info service for JWT tokens


License
Other
Install
go get github.com/vetinari/planb-tokeninfo

Documentation

Plan B Token Info Service

https://travis-ci.org/zalando/planb-tokeninfo.svg?branch=master https://codecov.io/github/zalando/planb-tokeninfo/coverage.svg?branch=master https://goreportcard.com/badge/github.com/zalando/planb-tokeninfo Documentation Status

Lightweight service providing an OAuth 2 token info HTTP endpoint to validate JWT tokens issued by the Plan B OpenID Connect Provider.

Current features:

  • Download public keys (set of JWKs) from OpenID provider
  • Verify signed JWT tokens using the right public key (identified by "kid" JOSE header)
  • Proxy to upstream tokeninfo for non-JWT tokens and cache the response
  • Download revocation lists from Plan B Revocation Service
  • Deny JWT tokens matching any revocation list

More information is available in our Plan B Documentation.

Building

Requires Go 1.5 or higher.

$ sudo apt-get install golang  # how to install Go on Ubuntu 15.10
$ export GOPATH=$(pwd)         # first set GOPATH if not done already
$ go get -t github.com/zalando/planb-tokeninfo
$ go test github.com/zalando/planb-tokeninfo/...
$ go install github.com/zalando/planb-tokeninfo

Running

$ export OPENID_PROVIDER_CONFIGURATION_URL=https://planb-provider.example.org/.well-known/openid-configuration
$ export UPSTREAM_TOKENINFO_URL=https://auth.example.org/oauth2/tokeninfo
$ export REVOCATION_PROVIDER_URL=https://planb-revocation.example.org/revocations
$ $GOPATH/bin/planb-tokeninfo  # start server on port 9021

Now we can test our token info endpoint with a valid JWT access token:

$ # using the Authorization header is the preferred method
$ curl -H 'Authorization: Bearer MjoxLjUuMS0wdW..' localhost:9021/oauth2/tokeninfo
$ # simple GET query parameter works too (not recommended!)
$ curl localhost:9021/oauth2/tokeninfo?access_token=MjoxLjUuMS0wdW..

Running with Docker:

$ TAG=$(curl https://registry.opensource.zalan.do/teams/stups/artifacts/planb-tokeninfo/tags | jq -r .[].name | tail -n 1)
$ docker run -it -v /etc/ssl/certs:/etc/ssl/certs -p 9021:9021 -e OPENID_PROVIDER_CONFIGURATION_URL=https://planb-provider.example.org/.well-known/openid-configuration registry.opensource.zalan.do/stups/planb-tokeninfo:$TAG

Configuration

The following environment variables are supported:

OPENID_PROVIDER_CONFIGURATION_URL
URL of the OpenID Connect configuration discovery document containing the jwks_uri which points to a set of JWKs.
OPENID_PROVIDER_REFRESH_INTERVAL
The OpenID Connect configuration refresh interval. See Time based settings
UPSTREAM_TOKENINFO_URL
URL of upstream OAuth 2 token info for non-JWT Bearer tokens.
UPSTREAM_CACHE_MAX_SIZE
Maximum number of entries for upstream token cache. It defaults to 10000.
UPSTREAM_CACHE_TTL
The TTL for upstream token cache entries. It defaults to 60 seconds. Zero will disable the cache. See also Time based settings
REVOCATION_PROVIDER_URL
URL of of the Revocation service.
REVOCATION_PROVIDER_REFRESH_INTERVAL
Refresh interval for polling the Revocation service. See Time based settings
REVOCATION_REFRESH_TOLERANCE
Amount of time to account for network latencies when polling the revocation service. Default is 60 seconds. See Time based settings
REVOCATION_CACHE_TTL
The TTL for Revocation cache entries. Default is 30 days. See Time based settings
REVOCATION_HASHING_SALT
Shared salt with Revocation service. Used for comparing hashed tokens from the Revocation service.
LISTEN_ADDRESS
The address for the application listener. It defaults to ':9021'
METRICS_LISTEN_ADDRESS
The address for the metrics listener. Should be different from the application listener. It defaults to ':9020'
HTTP_CLIENT_TIMEOUT
The timeout for the default HTTP client. See Time based settings
HTTP_CLIENT_TLS_TIMEOUT
The timeout for the default HTTP client when using TLS. See Time based settings

Time based settings

Some of the above settings accept time based definitions. Those definitions can be specified as a string that can be understood by time.ParseDuration(). For ex., '10s' for 10 seconds, '1h10m' for 1 hour and 10 minutes, '100ms' for 100 milliseconds. A simple numeric value is interpreted as Seconds. For ex., '30' is interpreted as 30 seconds.

Metrics

Metrics are exposed by default on port 9020 "/metrics". They include:

planb.openidprovider.numkeys
Number of public keys in memory.
planb.tokeninfo.proxy
Timer for the proxy handler (includes cached results and upstream calls).
planb.tokeninfo.proxy.cache.hits
Number of upstream cache hits.
planb.tokeninfo.proxy.cache.misses
Number of upstream cache misses.
planb.tokeninfo.proxy.cache.expirations
Number of upstream cache misses because of expiration.
planb.tokeninfo.proxy.upstream
Timer for calls to the upstream tokeninfo. Cached responses are not measured here.