Contribute to help us improve!

Are there edge cases or problems that we didn't consider? Is there a technical pitfall that we should add? Did we miss a comma in a sentence?

If you have any input for us, we would love to hear from you and appreciate every contribution. Our goal is to learn from projects for projects such that nobody has to reinvent the wheel.

Let's collect our experiences together to make room to explore the novel!

To contribute click on Contribute to this page on the toolbar.

Authentication with Keycloak using a OAuth 2 Proxy

OAuth2 proxy is a reverse proxy that runs in front of your services to handle the complexity of OpenID Connect / OAuth 2. Applications behind the proxy can be sure, that requests to them have already been authorized. The proxy supports a variety of identity providers like Google, GitHub, Keycloak…​

Authentication flow

A detailed flow diagram can be found here


The OAuth 2 proxy can be deployed from a prebuilt binary, a prebuilt docker image or by helm chart inside a Kubernetes cluster.

Request Flow
  1. Unauthorized request

  2. Ingress redirect to OAuth 2 proxy

  3. OAuth 2 proxy redirects users browser to the OAuth screen

  4. OAuth screen request

  5. Ingress redirects to keycloak

  6. After a successful login the users browser is redirected to a callback url with auth header

  7. Authorized Request

  8. Ingress redirect to OAuth 2 proxy

  9. OAuth 2 proxy redirect to upstream


In this example, keycloak is used as identity provider. For more details on keycloak read this introduction article. Keycloak can be deployed with variety of deployment options.

After keycloak is running go to the admin ui and configure a client. Make sure to follow the guide of OAuth 2 proxy to set up the group mapping properly.

Keycloak Database

Keycloak stores it’s data in a separate database. There is support for different database vendors. For production environments, file and in memory databases should not be used.


The task of the ingress is to redirect all requests to a specific host path to the OAuth 2 proxy and all requests to another host path to the keycloak service. It’s important to have the keycloak service accessible form outside the cluster to allow redirects to the oauth screen in the users browser.

Make sure to have a single ingress controller like nginx running in the cluster to allow the ingress to work properly.

Auth2 Proxy

The OAuth 2 proxy is running between the user and the application. If the user sends a request, the proxy will check the request for the proxy’s session cookie or a JWT. When the authentication is not provided, the user’s browser is redirected to the OAuth screen of a configured identity provider. If the request is authorized, the proxy will forward the request to a configured upstream.

The proxy can be configured to allow multiple groups access to multiple services. It is not possible to allow different groups to access different services. For a more fine grain access control, allow the services to use the authorization header/Token or use a different authentication system like istio.

Minimal configuration:





The used OAuth provider



The external url of the OpenID Connect service, used in the session cookie


The service or list of services to redirect requests to after they are authenticated



Scopes that will be added to the OAuth request

openid email


The group or list of groups that are authorized to pass the proxy



A string or list to specify the email addresses that are allowed to pass the proxy


A detailed overview for all configuration option can be found here


Requests from outside the cluster can only access the application over the main ingress. Because of that, the application can be sure that every request has passed through the OAuth 2 proxy and got authenticated. This has the advantage that the application doesn’t have to implement security itself. The application can get access to the authentication header or token to allow a more fine grain authentication.

Special configuration for local testing

To get a FQDN for the ingress without changing the host file, the example is using the domain, which will get resolve to by a public DNS server.

This created some problems. When trying to access the keycloak server from the proxy, it’s necessary to use the kubernetes internal URL. Because using the localtest URL will always try to access the loopback device of the pod sending the request.

Localhost Problem

This increased the complexity of the configuration, because the login URL is different from the tokens issuer URL. To resolve this problem, you have to enable skip-oidc-discovery in the OAuth 2 proxy configuration and set all URLs manually.

oidc-issuer-url =
oidc-jwks-url   = keycloak.default.svc.cluster.local
redeem-url      = keycloak.default.svc.cluster.local
login-url       =