Fetching contributors…
Cannot retrieve contributors at this time
496 lines (388 sloc) 20.4 KB


{project_name} provides a Go programming language adapter for use with OpenID Connect (OIDC) that supports both access tokens in a browser cookie or bearer tokens.

This documentation details how to build and configure {generic_adapter_name} followed by details of how to use each of its features.

For further information, see the included help file which includes a full list of commands and switches. View the file by entering the following at the command line (modify the location to match where you install {generic_adapter_name}):

    $ bin/keycloak-gatekeeper help


  • Golang must be installed.

  • Make must be installed.

  • Run make dep-install to install all needed dependencies.

  • Run make test to run the included tests.

  • Run make to build the project. You can instead use make static if you prefer to build a binary that includes within it all of the required dependencies.

You can also build via docker container: make docker-build. A Docker image is available at

Configuration options

Configuration can come from a yaml/json file or by using command line options. Here is a list of options.

# is the url for retrieve the OpenID configuration - normally the <server>/auth/realm/<realm_name>
# the client id for the 'client' application
client-id: <CLIENT_ID>
# the secret associated to the 'client' application
client-secret: <CLIENT_SECRET>
# the interface definition you wish the proxy to listen, all interfaces is specified as ':<port>', unix sockets as unix://<REL_PATH>|</ABS PATH>
# whether to enable refresh tokens
enable-refresh-tokens: true
# the location of a certificate you wish the proxy to use for TLS support
# the location of a private key for TLS
# the redirection url, essentially the site url, note: /oauth/callback is added at the end
# the encryption key used to encode the session state
encryption-key: <ENCRYPTION_KEY>
# the upstream endpoint which we should proxy request
# additional scopes to add to add to the default (openid+email+profile)
- vpn-user
# a collection of resource i.e. urls that you wish to protect
- uri: /admin/test
  # the methods on this url that should be protected, if missing, we assuming all
  - GET
  # a list of roles the user must have in order to access urls under the above
  # If all you want is authentication ONLY, simply remove the roles array - the user must be authenticated but
  # no roles are required
  - openvpn:vpn-user
  - openvpn:prod-vpn
  - test
- uri: /admin/*
  - GET
  - openvpn:vpn-user
  - openvpn:commons-prod-vpn

Options issued at the command line have a higher priority and will override or merge with options referenced in a config file. Examples of each style are shown here.

Example usage and configuration

Assuming you have some web service you wish protected by {project_name}:

  • Create the client using the {project_name} GUI or CLI; the client protocol is 'openid-connect', access-type: confidential.

  • Add a Valid Redirect URI of

  • Grab the client id and client secret.

  • Create the various roles under the client or existing clients for authorization purposes.

Here is an example configuration file.

client-id: <CLIENT_ID>
client-secret: <CLIENT_SECRET> # require for access_type: confidential
# Note the redirection-url is optional, it will default to the X-Forwarded-Proto / X-Forwarded-Host r the URL scheme and host not found
enable-default-deny: true
encryption_key: AgXa7xRcoClDEU0ZDSH4X0XhL5Qy2Z2j
- uri: /admin*
  - GET
  - client:test1
  - client:test2
  require-any-role: true
  - admins
  - users
- uri: /backend*
  - client:test1
- uri: /public/*
  white-listed: true
- uri: /favicon
  white-listed: true
- uri: /css/*
  white-listed: true
- uri: /img/*
  white-listed: true

Anything defined in a configuration file can also be configured using command line options, such as in this example.

bin/{generic_adapter_name} \
    --discovery-url=<REALM_NAME> \
    --client-id=<CLIENT_ID> \
    --client-secret=<SECRET> \
    --listen= \ # unix sockets format unix://path
    --redirection-url= \
    --enable-refresh-tokens=true \
    --encryption-key=AgXa7xRcoClDEU0ZDSH4X0XhL5Qy2Z2j \
    --upstream-url= \
    --enable-default-deny=true \
    --resources="uri=/admin*|roles=test1,test2" \
    --resources="uri=/backend*|roles=test1" \
    --resources="uri=/css/*|white-listed=true" \
    --resources="uri=/img/*|white-listed=true" \

By default the roles defined on a resource perform a logical AND so all roles specified must be present in the claims, this behavior can be altered by the require-any-role option, however, so as long as one role is present the permission is granted.

HTTP routing

By default all requests will be proxyed on to the upstream, if you wish to ensure all requests are authentication you can use this:

--resource=uri=/* # note, unless specified the method is assumed to be 'any|ANY'

The HTTP routing rules follow the guidelines from chi. The ordering of the resources do not matter, the router will handle that for you.

Session-only cookies

By default the access and refresh cookies are session-only and disposed of on browser close; you can disable this feature using the --enable-session-cookies option.

Forward-signing proxy

Forward-signing provides a mechanism for authentication and authorization between services using tokens issued from the IdP. When operating in this mode the proxy will automatically acquire an access token (handling the refreshing or logins on your behalf) and tag outbound requests with a Authorization header. You can control which domains are tagged with the --forwarding-domains option. Note, this option use a contains comparison on domains. So, if you wanted to match all domains under *.svc.cluster.local you can use: --forwarding-domain=svc.cluster.local.

At present the service performs a login using oauth client_credentials grant type, so your IdP service must support direct (username/password) logins.

Example setup:

You have collection of micro-services which are permitted to speak to one another; you have already set up the credentials, roles, and clients in Keycloak, providing granular role controls over issue tokens.

- name: {generic_adapter_name}
  - --enable-forwarding=true
  - --forwarding-username=projecta
  - --forwarding-password=some_password
  - --forwarding-domains=projecta.svc.cluster.local
  - --forwarding-domains=projectb.svc.cluster.local
  - --tls-ca-certificate=/etc/secrets/ca.pem
  - --tls-ca-key=/etc/secrets/ca-key.pem
  # Note: if you don't specify any forwarding domains, all domains will be signed; Also the code checks is the
  # domain 'contains' the value (it's not a regex) so if you wanted to sign all requests to svc.cluster.local, just use
  # svc.cluster.local
  - name: keycloak-socket
    mountPoint: /var/run/keycloak
- name: projecta
  image: some_images

# test the forward proxy
$ curl -k --proxy https://test.projesta.svc.cluster.local

On the receiver side you could set up the {generic_adapter_name_full} (--no=redirects=true) and permit this to verify and handle admission for you. Alternatively, the access token can found as a bearer token in the request.

Forwarding signed HTTPS connections

Handling HTTPS requires a man-in-the-middle sort of TLS connection. By default, if no --tls-ca-certificate and --tls-ca-key are provided the proxy will use the default certificate. If you wish to verify the trust, you’ll need to generate a CA, for example.

$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ca.key -out ca.pem
$ bin/{generic_adapter_name} \
  --enable-forwarding \
  --forwarding-username=USERNAME \
  --forwarding-password=PASSWORD \
  --client-id=CLIENT_ID \
  --client-secret=SECRET \
  --discovery-url= \
  --tls-ca-certificate=ca.pem \

HTTPS redirect

The proxy supports an HTTP listener, so the only real requirement here is to perform an HTTP → HTTPS redirect. You can enable the option like this:

--enable-security-filter=true  # is required for the https redirect

Let’s Encrypt configuration

Here is an example of the required configuration for Let’s Encrypt support:

enable-https-redirection: true
enable-security-filter: true
use-letsencrypt: true
letsencrypt-cache-dir: ./cache/
redirection-url: https://domain.tld:443/
  - domain.tld

Listening on port 443 is mandatory.

Access token encryption

By default, the session token is placed into a cookie in plaintext. If you prefer to encrypt the session cookie, use the --enable-encrypted-token and --encryption-key options. Note that the access token forwarded in the X-Auth-Token header to upstream is unaffected.

Upstream headers

On protected resources, the upstream endpoint will receive a number of headers added by the proxy, along with custom claims, like this:

# add the header to the upstream endpoint
id := user.(*userContext)
cx.Request().Header.Set("X-Auth-ExpiresIn", id.expiresAt.String())
cx.Request().Header.Set("X-Auth-Groups", strings.Join(id.groups, ","))
cx.Request().Header.Set("X-Auth-Roles", strings.Join(id.roles, ","))
cx.Request().Header.Set("X-Auth-Token", id.token.Encode())
// step: add the authorization header if requested
if r.config.EnableAuthorizationHeader {
	cx.Request().Header.Set("Authorization", fmt.Sprintf("Bearer %s", id.token.Encode()))

To control the Authorization header use the enable-authorization-header yaml configuration or the --enable-authorization-header command line option. By default this option is set to true.

Custom claim headers

You can inject additional claims from the access token into the authorization headers with the --add-claims option. For example, a token from a {project_name} provider might include the following claims:

"resource_access": {},
"name": "Beloved User",
"preferred_username": "beloved.user",
"given_name": "Beloved",
"family_name": "User",
"email": ""

In order to request you receive the given_name, family_name and name in the authentication header we would add --add-claims=given_name and --add-claims=family_name and so on, or we can do it in the configuration file, like this:

- given_name
- family_name
- name

This would add the additional headers to the authenticated request along with standard ones.

X-Auth-Family-Name: User
X-Auth-Given-Name: Beloved
X-Auth-Name: Beloved User

Encryption key

In order to remain stateless and not have to rely on a central cache to persist the refresh_tokens, the refresh token is encrypted and added as a cookie using crypto/aes. The key must be the same if you are running behind a load balancer. The key length should be either 16 or 32 bytes, depending or whether you want AES-128 or AES-256.

Claim matching

The proxy supports adding a variable list of claim matches against the presented tokens for additional access control. You can match the 'iss' or 'aud' to the token or custom attributes; each of the matches are regex’s. For example, --match-claims 'aud=sso.*' or --claim iss=https://.*' or via the configuration file, like this:

  aud: openvpn

or via the CLI, like this:


You can limit the email domain permitted; for example if you want to limit to only users on the domain:

  email: ^.*$

The adapter supports matching on multi-value strings claims. The match will succeed if one of the values matches, for example:

  perms: perm1

will successfully match

  "iss": "",
  "sub": "",
  "perms": ["perm1", "perm2"]

Group claims

You can match on the group claims within a token via the groups parameter available within the resource. While roles are implicitly required, such as roles=admin,user where the user MUST have roles 'admin' AND 'user', groups are applied with an OR operation, so groups=users,testers requires that the user MUST be within either 'users' OR 'testers'. The claim name is hard-coded to groups, so a JWT token would look like this:

  "iss": "",
  "sub": "",
  "aud": "test",
  "exp": 1515269245,
  "iat": 1515182845,
  "email": "",
  "groups": [
  "name": "Beloved"

Custom pages

By default, {generic_adapter_name_full} will immediately redirect you for authentication and hand back a 403 for access denied. Most users will probably want to present the user with a more friendly sign-in and access denied page. You can pass the command line options (or via config file) paths to the files with --signin-page=PATH. The sign-in page will have a 'redirect' variable passed into the scope and holding the oauth redirection url. If you wish to pass additional variables into the templates, such as title, sitename and so on, you can use the --tags key=pair option, like this: --tags title="This is my site" and the variable would be accessible from {{ .title }}.

<a href="{{ .redirect }}">Sign-in</a>

White-listed URL’s

Depending on how the application URL’s are laid out, you might want protect the root / url but have exceptions on a list of paths, for example /health. While this is best solved by adjusting the paths, you can add exceptions to the protected resources, like this:

  - uri: /some_white_listed_url
    white-listed: true
  - uri: /*
      - GET

Or on the command line

  --resources "uri=/some_white_listed_url|white-listed=true"
  --resources "uri=/*"  # requires authentication on the rest
  --resources "uri=/admin*|roles=admin,superuser|methods=POST,DELETE"

Mutual TLS

The proxy support enforcing mutual TLS for the clients by adding the --tls-ca-certificate command line option or configuration file option. All clients connecting must present a certificate which was signed by the CA being used.

Certificate rotation

The proxy will automatically rotate the server certificates if the files change on disk. Note, no down time will occur as the change is made inline. Clients who connected prior to the certificate rotation will be unaffected and will continue as normal with all new connections presented with the new certificate.

Refresh tokens

If a request for an access token contains a refresh token and --enable-refresh-tokens is set to true, the proxy will automatically refresh the access token for you. The tokens themselves are kept either as an encrypted (--encryption-key=KEY) cookie (cookie name: kc-state). or a store (still requires encryption key).

At present the only store options supported are Redis and Boltdb.

To enable a local boltdb store use --store-url boltdb:///PATH or using a relative path boltdb://PATH.

To enable a local redis store use redis://[USER:PASSWORD@]HOST:PORT. In both cases the refresh token is encrypted before being placed into the store.

Logout endpoint

A /oauth/logout?redirect=url is provided as a helper to log users out. In addition to dropping any session cookies, we also attempt to revoke access via revocation url (config revocation-url or --revocation-url) with the provider. For Keycloak, the url for this would be If the url is not specified we will attempt to grab the url from the OpenID discovery response.

Cross-origin resource sharing (CORS)

You can add a CORS header via the --cors-[method] with these configuration options.

  • Access-Control-Allow-Origin

  • Access-Control-Allow-Methods

  • Access-Control-Allow-Headers

  • Access-Control-Expose-Headers

  • Access-Control-Allow-Credentials

  • Access-Control-Max-Age

You can add using the config file:

- '*'

or via the command line:

--cors-origins [--cors-origins option]                  a set of origins to add to the CORS access control (Access-Control-Allow-Origin)
--cors-methods [--cors-methods option]                  the method permitted in the access control (Access-Control-Allow-Methods)
--cors-headers [--cors-headers option]                  a set of headers to add to the CORS access control (Access-Control-Allow-Headers)
--cors-exposes-headers [--cors-exposes-headers option]  set the expose cors headers access control (Access-Control-Expose-Headers)

Upstream URL

You can control the upstream endpoint via the --upstream-url option. Both HTTP and HTTPS are supported with TLS verification and keep-alive support configured via the --skip-upstream-tls-verify / --upstream-keepalives option. Note, the proxy can also upstream via a UNIX socket, --upstream-url unix://path/to/the/file.sock.


  • /oauth/authorize is authentication endpoint which will generate the OpenID redirect to the provider

  • /oauth/callback is provider OpenID callback endpoint

  • /oauth/expired is a helper endpoint to check if a access token has expired, 200 for ok and, 401 for no token and 401 for expired

  • /oauth/health is the health checking endpoint for the proxy, you can also grab version from headers

  • /oauth/login provides a relay endpoint to login via grant_type=password, for example, POST /oauth/login form values are username=USERNAME&password=PASSWORD (must be enabled)

  • /oauth/logout provides a convenient endpoint to log the user out, it will always attempt to perform a back channel log out of offline tokens

  • /oauth/token is a helper endpoint which will display the current access token for you

  • /oauth/metrics is a Prometheus metrics handler


Assuming --enable-metrics has been set, a Prometheus endpoint can be found on /oauth/metrics; at present the only metric being exposed is a counter per HTTP code.


Keep in mind browser cookie limits if you use access or refresh tokens in the browser cookie. Keycloak-generic-adapter divides the cookie automatically if your cookie is longer than 4093 bytes. Real size of the cookie depends on the content of the issued access token. Also, encryption might add additional bytes to the cookie size. If you have large cookies (>200 KB), you might reach browser cookie limits.

All cookies are part of the header request, so you might find a problem with the max headers size limits in your infrastructure (some load balancers have very low this value, such as 8 KB). Be sure that all network devices have sufficient header size limits. Otherwise, your users won’t be able to obtain an access token.