{"id":13558602,"url":"https://github.com/8gears/keycloak-auth-proxy","last_synced_at":"2025-04-03T13:31:39.471Z","repository":{"id":132448416,"uuid":"87324822","full_name":"8gears/keycloak-auth-proxy","owner":"8gears","description":"Reverse auth proxy container for OAuth/OpenID Connect ","archived":false,"fork":false,"pushed_at":"2018-09-19T15:27:22.000Z","size":47,"stargazers_count":40,"open_issues_count":0,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-04T09:37:27.197Z","etag":null,"topics":["auth-proxy","docker","iam","k8s","keycloak","keycloak-proxy","oauth","openid","openid-connect","openshift","proxy","proxy-service","reverse-proxy"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/8gears.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-04-05T15:17:50.000Z","updated_at":"2024-08-06T16:04:59.000Z","dependencies_parsed_at":"2024-01-14T16:08:40.410Z","dependency_job_id":"c66a942f-e8aa-4cac-9731-9585f420372b","html_url":"https://github.com/8gears/keycloak-auth-proxy","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8gears%2Fkeycloak-auth-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8gears%2Fkeycloak-auth-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8gears%2Fkeycloak-auth-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8gears%2Fkeycloak-auth-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/8gears","download_url":"https://codeload.github.com/8gears/keycloak-auth-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247009644,"owners_count":20868583,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth-proxy","docker","iam","k8s","keycloak","keycloak-proxy","oauth","openid","openid-connect","openshift","proxy","proxy-service","reverse-proxy"],"created_at":"2024-08-01T12:05:03.371Z","updated_at":"2025-04-03T13:31:39.202Z","avatar_url":"https://github.com/8gears.png","language":"Shell","funding_links":[],"categories":["Shell","docker"],"sub_categories":[],"readme":"# Keycloak Auth Proxy\n\n[![Docker Automated build](https://img.shields.io/docker/automated/8gears/keycloak-auth-proxy.svg?style=flat-square)](https://hub.docker.com/r/8gears/keycloak-auth-proxy/)\n[![Docker Pulls](https://img.shields.io/docker/pulls/8gears/keycloak-auth-proxy.svg?style=flat-square)](https://hub.docker.com/r/8gears/keycloak-auth-proxy/)\n[![Docker Stars](https://img.shields.io/docker/stars/8gears/keycloak-auth-proxy.svg?style=flat-square)](https://hub.docker.com/r/8gears/keycloak-auth-proxy/)\n[![MicroBadger Size](https://img.shields.io/microbadger/image-size/8gears/keycloak-auth-proxy.svg?style=flat-square)](https://hub.docker.com/r/8gears/keycloak-auth-proxy/)\n\nThe Reverse Auth Proxy in a Docker Container the provides OpenID Connect/OAuth authentication and authorization for HTTP services that that can't or won't do it themself.\n\nThis Auth Proxy Service uses [gambol99/keycloak-proxy](https://github.com/gambol99/keycloak-proxy), which is a Java/Undertow solution designed for Keycloak. However it should also work with any other OpenID Connect Provider.\n\nWhat makes this project special is, that it can be configured with environment variables and can be easily deployed to Docker, Kubernetes or OpenShift.\n\n## Mode of operation\n\n![How reverse auth proxy works][prx_diag]\n\n1. External traffic is directed to the auth proxy. The Auth proxy decides based on it configuration if the destination needs authentication.\n2. The Auth Proxy work together with the IAM (Keycloak) and redirects the user to the IAM so the user can login.\n3. 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.\n\n## Typical Use cases\n\nThere are two very common use cases why one would use the Keycloak Auth Proxy in combination with an Identity \u0026 Access Management Service (IAM).\n\nIt is recommended that every service that needs authentication has a dedicated auth proxy in front of it.\n\n- Protect static websites from unauthorized access, allowing only authenticated users to see the content.  \n  This is useful in combination with static website generator or other generated documentation.\n- Outsource the authentication/authorization step to Keycloak Auth Proxy and just relay on the forward HTTP headers with username/grants in the upstream application.  \n  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.\n\n## Usage\n\nThere are three ways how the proxy can be configured.\nThe proxy configuration settings can be set with environment variables,environment variables plus config template or with the file `proxy.json` mounted as a volume to `/app/proxy.json`.\n\nThe option that you choose depend on the use case. For simple static website auth the default proxy template is sufficient. For more complex scenarios the custom Proxy Config Template is able cover all possible options.\n\n### Running with the default Proxy Config Template\n\nIn the simplest case the only thing you need to do is to set the mandatory environment variables. Prior the execution the variables merged with the default proxy config and then the proxy application is started.\n\n```sh\ndocker run -ti \\\n-e TARGET_URL=asdf \\\n-e REALM=\"realm\" \\\n-e REALM_PUBLIC_KEY='pub'\n-e .... \\\n8gears/keycloak-auth-proxy\n```\n\nWith Docker Compose download the default docker-compose.yml\n\n```sh\nwget https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/docker-compose.yml\n```\n\nAdapt the mandatory env variables in `docker-compose.yml` and hit:\n\n```sh\ndocker-compose - up\n```\n\n### Running with custom Proxy Config Template\n\nIn order to combine the simplicity of the environment variables with the flexibility of the custom proxy config it is possible to provide your own template.\n\nTake the existing `proxy.tmpl` from this repository and extended it to your need.\nWhen you are done with the template minfy the content and set the variable ??`PROXY_TMPL` with the content.\n\n```sh\ndocker run -ti \\\n-e PROXY_TMPL={\"target-url\": \"http://172.17.0.2:2015\",\"bind-address\": \"0.0.0.0\", ....\n-e TARGET_URL=asdf \\\n-e REALM=\"realm\" \\\n-e REALM_PUBLIC_KEY='pub'\n-e .... \\\n8gears/keycloak-auth-proxy\n```\n\n### Running with custom Proxy Config\n\nWrite your `proxy.json` file and mount it to `/app/proxy.json`. Prior start the Auth proxy startup script will check if the file exist and start the proxy with the provided file ignoring the template or any provided environment variables.\n\nInstead of mapping you can provide the content via environment variable ?`PROXY_JSON` just like in the template example above.\n\n```sh\ndocker run -v proxy.json:/app/proxy.json 8gears/keycloak-auth-proxy\n```\n\n## Environment Variables\n\nCan be used if you want to auth one service.\n\nSee the file [proxy.tmpl](proxy.tmpl)\n\nVariables without default values are mandatory.\n\n- `TARGET_URL` The URL to forward the traffic through\n- `HTTP_PORT` (default `8080`) The port to bind the Auth Proxy too\n- `BASE_PATH` (default `/` )\n- `REALM` Adapter config realm\n- `REALM_PUBLIC_KEY` Realm public key\n- `AUTH_SERVER_URL` The auth server URL\n- `RESOURCE` (default `account`) The resource to request aka client id\n- `SECRET` Credential secret\n- `CONSTRAINT_PATH` (default `/*`) You can define multiple path but they must be separated with an `;`\n- `PROXY_TMPL` Instead of using the provided proxy config it is possible to provide a custom config.\n\n## OpenShift Deployment\n\nIn OpenShift you can create the service from the template `openshift_template.yml` by using the Web UI or CLI.\n\nCopy the content of `openshift_template.yml` and paste it to the _Import YAML / JSON_ tab in the service catalog.\nThe OpenShift has a [detailed tutorial]([create_from_ui]) that covers the manual template instantiation.\n\nFrom the CLI execute the first command with the `--parameter` argument to get a list of all the possible parameters.\nNext in the second command add all the needed parameters and pipe it to create.\n\n```sh\noc process --parameter -f https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/openshift_template.yml\n\noc process -f https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/openshift_template.yml \\\n    -p TARGET_URL=http://service-name:123 \\\n    -p REALM=app42 \\\n    | oc create -f -\n```\n\n### OpenShift Service Catalog import\n\nImport the template to the current namespace service catalog.\n\n```sh\noc create -f https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/openshift_template.yml\n```\n\nImport template to global service catalog, so all users in all namespaces can use that template.\n\n```sh\noc create -f https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/openshift_template.yml -n openshift\n```\n\n## Alternatives\n\nDespite the uniqueness of _keycloak-auth-proxy_ there are other project that solve the similar problem differently.\n\n- [OpenID / Keycloak Proxy service](https://github.com/gambol99/keycloak-proxy) This in Golang written proxy should work nicely with Keycloak and might be a value alternative to the current jvm proxy.\n- [OAuth2 Proxy](https://github.com/bitly/oauth2_proxy)\n- [Lua Resty OpenID/Connect](https://github.com/pingidentity/lua-resty-openidc) This library is designed for Nginx/OpenResty.\n\n\u003c!-- Links --\u003e\n\n[kcp]: https://github.com/keycloak/keycloak/tree/master/proxy\n[prx_diag]: https://cdn.rawgit.com/8gears/keycloak-auth-proxy/master/docs/images/How_Keycloak_Auth_Proxy_works.svg\n[create_from_ui]: https://docs.openshift.org/latest/dev_guide/templates.html#creating-from-templates-using-the-web-console\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F8gears%2Fkeycloak-auth-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F8gears%2Fkeycloak-auth-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F8gears%2Fkeycloak-auth-proxy/lists"}