What is Gatekeeper?

The current Keycloak documentation has a table of contents like this:

  • OpenID Connect
    • Java Adapters
    • Javascript Adapter
    • Node.js Adapter
    • Keycloak Gatekeeper

And the entry for Gatekeeper reads:

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

Now, I’m new to Keycloak so I assume someone more experienced wouldn’t have this difficulty, but I read this as we have a Java adapter, a JavaScript adapter, a Node.js adapter, and a Go adapter.

It wasn’t until I went to the Downloads page and saw the Server and Gatekeeper download at the very top, listed separately from the language adapters, that I knew for certain Gatekeeper must be a different kind of thing.

So where in all the documentation is a high-level description of what Gatekeeper is? I can see a clue in the documentation URL – https://www.keycloak.org/docs/latest/securing_apps/index.html#_keycloak_generic_adapter – it’s a “generic adapter”, but the documentation never actually says this, it just launches immediately in to how to configure it.

Is there some blog post or documentation that introduces Gatekeeper, its architecture, its features, and when it should be used?

p.s. Keycloak looks really great and I’m excited to use it. The tone of this post sounds a bit angry maybe, but I’m really just looking for advice.

IMHO “Go programming language adapter” isn’t correct definition.

I would say: Keycloak Gatekeeper is authentication (optional authorization) proxy application written in Golang. Recommended usage is when used app/lib doesn’t support grant code flow (sorry not designated for SPA apps), but it is able to read user identity from request headers. It is good solution for dockerized environment due to small memory footprint, stateless functionality, horizontal scaling ability, … It was originally community project, so not all Keycloak features are implemented in the Keycloak way (e.g authorization).

It is not coupled deeply with Keycloak => it doesn’t introduce any Keycloak vendor lock-in, so it should work with any standard OIDC IdP.

1 Like

@sharpedavid there’s a lot to improve into our documentation and the links that you mentioned are the only ones available at the moment. if you have any suggestions about how to improve our docs, you’re more than welcome to submit a pull-request to https://github.com/keycloak/keycloak-documentation/blob/master/securing_apps/topics/oidc/keycloak-gatekeeper.adoc or https://github.com/keycloak/keycloak-web //cc @jangaraj

@jangaraj your definition makes sense to me. The only word that we avoid all the time is “proxy”, because the goal of Gatekeeper is to act more like a sidecar protecting apps, instead of act like a proxy and provide things like load-balancing and proxy related functionality.


Because I only just learned what Gatekeeper is (thanks to this forum thread), I don’t think I"m a good person to write an official description of Gatekeeper. I hope @jangaraj has some time to submit a pull-request, because I really think a basic description of Gatekeeper would help adoption: people aren’t going to use it if they don’t even know what it is.

I have discovered a good way to learn more about Gatekeeper. In September 2018 Gatekeeper was renamed from Keycloak Proxy. If you Google “Keycloak Proxy”, you will find many more blog posts and videos. I particularly liked this one because it has a sequence diagram.