The Keycloak Auth Proxy provides OpenID Connect/OAuth authentication and authorization too web resources that have no build in authentication.

This Auth Proxy Service uses Keycloak Proxy, which is a Java/Undertow solution designed for Keycloak but that should also work with any other solution that supports OpenID/Connect.

1. External traffic is directed to the auth proxy. The Auth proxy decides based on it configuration if the destination needs authentication.
2. The Auth Proxy work together with the IAM (Keycloak) and redirects the user to the IAM so the user can login.
3. After a successful login the proxy forwards the user to the protected content. According to proxy configuration setting the proxy checks if the user is allowed to access the path.

There are two very common use cases why one would use the Keycloak Auth Proxy together with an Identity & Access Management Service (IAM)

• Protect static websites from unauthorized access, allowing only authenticated users to see the content.
  This is useful in combination with static website generator or other generated documentation.
• Outsource the authentication/authorization step to Keycloak Auth Proxy and just relay on the forward HTTP headers with username/grants in the upstream application.
  This approach can be handy if you have an application, where there are no OpenID Connect library or if you don't won't perform to many changes in the application.

The proxy configuration settings can be set with environment variables or with the file proxy.json mounted as a volume to /app/proxy.json.

Set the mandatory environment variables.

docker-compose up

The intended use is, that every service that needs authentication has a dedicated auth proxy in front of it. However the Auth Proxy can be configured to behave differently, but not with the given the configuration via environment variable. For this case you have to mount the self created proxy.json for example.

docker run -v proxy.json:/app/proxy.json 8gears/keycloak-auth-proxy 

Can be used if you want to auth one service.

See the file proxy.tmpl

Variables without default values are mandatory.

• TARGET_URL The URL to forward the traffic through
• HTTP_PORT (default 80) The port to bind the Auth Proxy too
• BASE_PATH (default / )
• REALM Adapter config realm
• REALM_PUBLIC_KEYRealm public key
• AUTH_SERVER_URL The auth server URL
• RESOURCE (default account) The resource to request aka client id
• SECRET Credential secret
• CONSTRAINT_PATH (default /*) You can define multiple path but they must be separated with an ;

Despite the uniqueness of keycloak-auth-proxy there are other project that solve the similar problem differently.

What makes this project special is, that it can be configured with environment variables and can be deployed and run on OpenShift.

• OpenID / Keycloak Proxy service This in Golang written proxy should work nicely with Keycloak and might be a value alternative to the current jvm proxy.
• OAuth2 Proxy
• Lua Resty OpenID/Connect This library is designed for Nginx/OpenResty.