{"id":27168957,"url":"https://github.com/mkuhlmann/forward-auth","last_synced_at":"2025-04-09T06:22:12.914Z","repository":{"id":44822967,"uuid":"177890852","full_name":"mkuhlmann/forward-auth","owner":"mkuhlmann","description":"Flexible and easily configurable oauth2 forward authentication service for use with traefik and nginx. ","archived":false,"fork":false,"pushed_at":"2022-01-22T12:15:09.000Z","size":311,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2023-04-27T19:41:39.203Z","etag":null,"topics":["auth","docker","nginx","nodejs","oauth","oauth2","oauth2-proxy","proxy","traefik"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/mkuhlmann/forward-auth","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkuhlmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-27T00:43:22.000Z","updated_at":"2023-03-10T15:12:55.000Z","dependencies_parsed_at":"2022-09-19T06:50:39.206Z","dependency_job_id":null,"html_url":"https://github.com/mkuhlmann/forward-auth","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkuhlmann%2Fforward-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkuhlmann%2Fforward-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkuhlmann%2Fforward-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkuhlmann%2Fforward-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkuhlmann","download_url":"https://codeload.github.com/mkuhlmann/forward-auth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247988240,"owners_count":21029075,"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","docker","nginx","nodejs","oauth","oauth2","oauth2-proxy","proxy","traefik"],"created_at":"2025-04-09T06:22:12.089Z","updated_at":"2025-04-09T06:22:12.869Z","avatar_url":"https://github.com/mkuhlmann.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# forward-auth\n![GitHub Workflow Status](https://img.shields.io/github/workflow/status/mkuhlmann/forward-auth/build)\n\nHighly flexible forward auth service for use with an oauth endpoint and a reverse proxy (e.g. [traefik](https://docs.traefik.io/middlewares/forwardauth/)).\n\n## Configuration\n\nforward-auth can be configurated in three ways, values are applied in following priority (low to high): \n\n`config.json \u003c environment variables \u003c query params` \n\nPlease use UPPER_CASE in environment variables, lower_case otherwise. Note that listen_host, listen_port, app_key, cookie_name and cookie_age cannot be set via query params.\n\nThe following options are available:\n\nConfig Key | Description | Required | Default\n---------- | ----------- | -------   | -------\nlisten_host| host to bind |  | `0.0.0.0`\nlisten_port| port to bind | | `8080`\napp_key    | keys for cookie signing, passed to koajs | ✔ |\ncookie_name | Name of Cookie | | `__auth`\ncookie_age | Max age of cookie in seconds  | | `604800` (7 days)\nredirect_code | HTTP status code to return, when redirecting\u003csup\u003e[because](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html)\u003c/sup\u003e | | 302\nauthorize_url  | OAuth Authorization Request URL ([spec](https://tools.ietf.org/html/rfc6749#section-4.1.1)) | ✔ |\ntoken_url  | OAuth Access Token Endpoint| ✔ |\nuserinfo_url   | OpenID Connect UserInfo endpoint, must include `sub` field| ✔ |\nclient_id | OAuth Client Id| ✔ |\nclient_secret | OAuth Client Secret| ✔ |\nallowed_users | Comma-seperated list of allowed `sub`s, empty = anyone | | `[]`\nscopes | Comma-seperated OAuth Scopes |  | `id`\n\nWhen client is authenticated, forward_auth passes X-Auth-User with the sub and X-Auth-Info with the json encoded userinfo_url response, those may be passed to your application via the reverse proxy (see example below).\n\n\n\n## Usage\n\nExample `docker-compose.yml`\n\n```yaml\nversion: '3.5'\n  \nservices:\n  traefik:\n    image: traefik:2.2\n    restart: always\n    command:\n      - \"--providers.docker=true\"\n      - \"--providers.docker.exposedbydefault=false\"\n      - \"--entrypoints.web.address=:80\"\n    ports:\n      - 80:80\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n\n      \n    forward_auth:\n      image: mkuhlmann/forward-auth\n      restart: unless-stopped\n      environment:\n        - APP_KEY=CHANGE_ME\n        - AUTHORIZE_URL=https://example.com/oauth/authorize\n        - TOKEN_URL=https://example.com/oauth/token\n        - USERINFO_URL=https://example.com/oauth/userinfo\n        - CLIENT_ID=clientid\n        - CLIENT_SECRET=verysecret\n    \n    nginx:\n      image: nginx:mainline-alpine\n      networks:\n        - proxy\n      labels:\n        - \"traefik.enable=true\"\n        - \"traefik.http.services.nginx.loadbalancer.server.port: 80\"\n        - \"traefik.http.routers.nginx.entrypoints=web\"\n        - \"traefik.http.routers.nginx.rule=Host(`private.example.com`)\"\n        - \"traefik.http.middlewares.forward_auth.forwardauth.address=http://forward_auth:8080/auth?allowed_users=ALLOWED_USER_SUB\"\n        - \"traefik.http.middlewares.forward_auth.forwardauth.authResponseHeaders=X-Auth-User,X-Auth-Info\"\n```\n\nExample nginx config, be sure to set redirect_code to 403!\n\n```nginxconf\nserver {\n\tlisten 443 ssl http2;\n\tlisten [::]:443 ssl http2;\n\tserver_name secret.example.com;\n\n\tlocation = /auth {\n\t\tinternal;\n\t\tproxy_pass http://forward_auth:8080;\n\t\tproxy_intercept_errors on;\n\t\tproxy_set_header Host $host;\n\t\tproxy_set_header X-Real-IP $remote_addr;\n\t\tproxy_set_header X-Forwarded-Host $host;\n\t\tproxy_set_header X-Forwarded-Proto $scheme;\n\t\tproxy_set_header X-Forwarded-Uri $request_uri;\n\n\t\tproxy_pass_request_headers on;\n\t\tproxy_set_header Content-Length \"\";\n\t}\n\n\tlocation @auth_redirect {\n\t\tadd_header Set-Cookie $auth_cookie;\n\t\treturn 302 $auth_location;\n\t}\n\n\tlocation / {\n\t\tauth_request /auth;\n\t\tauth_request_set $auth_location $upstream_http_location;\n\n\t\tauth_request_set $auth_cookie $upstream_http_set_cookie;\n\t\tadd_header Set-Cookie $auth_cookie;\n\n\t\terror_page 403 = @auth_redirect;\n\t\terror_page 401 = /no_auth;\n\n\t\tauth_request_set $auth_user  $upstream_http_x_auth_user;\n\t\tauth_request_set $auth_info  $upstream_http_x_auth_info;\n\t\tproxy_set_header X-Auth-User $auth_user;\n\t\tproxy_set_header X-Auth-Info $auth_info;\n\n\t\tproxy_buffering off;\n\t\tproxy_pass http://upstream;\n\t\tproxy_set_header Host $host;\n\t\tproxy_redirect http:// https://;\n\t\tproxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n\t\tproxy_set_header Upgrade $http_upgrade;\n\t\tproxy_set_header Connection $connection_upgrade;\n\t}\n\n\tlocation = /noauth {\n\t\tinternal;\n\t\tadd_header Content-Type text/plain;\n\t\treturn 200 'unauthenticated';\n\t}\n}\n\n```\n## Contributing\n\nPull request are *very* welcome!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkuhlmann%2Fforward-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkuhlmann%2Fforward-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkuhlmann%2Fforward-auth/lists"}