{"id":19223681,"url":"https://github.com/pixnyb/authentication-proxy","last_synced_at":"2026-03-19T08:47:00.123Z","repository":{"id":241840398,"uuid":"805081121","full_name":"PixNyb/authentication-proxy","owner":"PixNyb","description":"Authenticate against traefik using a variety of providers. Such as a htpasswd file, generic OAuth, generic OIDC, Google and Apple","archived":false,"fork":false,"pushed_at":"2025-01-23T13:37:51.000Z","size":1055,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-23T14:20:22.968Z","etag":null,"topics":["authentication","forward-auth","proxy","traefik"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PixNyb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"buy_me_a_coffee":"pixnyb"}},"created_at":"2024-05-23T21:03:03.000Z","updated_at":"2025-01-23T13:37:54.000Z","dependencies_parsed_at":"2024-05-30T09:30:30.831Z","dependency_job_id":"d769355b-d55f-46bc-b3b8-14fa99cdda02","html_url":"https://github.com/PixNyb/authentication-proxy","commit_stats":null,"previous_names":["pixnyb/authentication-proxy"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PixNyb%2Fauthentication-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PixNyb%2Fauthentication-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PixNyb%2Fauthentication-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PixNyb%2Fauthentication-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PixNyb","download_url":"https://codeload.github.com/PixNyb/authentication-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240298487,"owners_count":19779283,"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":["authentication","forward-auth","proxy","traefik"],"created_at":"2024-11-09T15:09:15.613Z","updated_at":"2026-02-28T02:04:14.035Z","avatar_url":"https://github.com/PixNyb.png","language":"JavaScript","funding_links":["https://buymeacoffee.com/pixnyb"],"categories":[],"sub_categories":[],"readme":"# Dockerised Authentication Proxy\n\n[![Build and Publish Docker Image](https://github.com/PixNyb/authentication-proxy/actions/workflows/deploy.yml/badge.svg)](https://github.com/PixNyb/authentication-proxy/actions/workflows/deploy.yml)\n\nThis is a Dockerised authentication for use cases where basic authentication doesn't cut it.\nIt integrates with the traefik reverse proxy as forward authentication middleware.\n\n## Usage\n\n### Build the Docker image\n\n```bash\ndocker build -t authentication-proxy .\n```\n\n### Run the Docker container\n\n```bash\ndocker run -d -p 8080:3000 \\\n    -e AUTH_HOST=localhost:8080 \\\n    -e COOKIE_SECURE=false \\\n    -e COOKIE_HOSTS=localhost:8080 \\\n    -e COOKIE_HOSTS_USE_ROOT=true \\\n    -e LOCAL_HTPASSWD_USERS=user:password \\\n    -e LOCAL_HTPASSWD_USERS_FILE=/etc/nginx/.htpasswd \\\n    -e LOCAL_HTPASSWD_DISPLAY_NAME=Local \\\n    -e OAUTH2_GITHUB_AUTH_URL=https://github.com/login/oauth/authorize \\\n    -e OAUTH2_GITHUB_TOKEN_URL=https://github.com/login/oauth/access_token \\\n    -e OAUTH2_GITHUB_USER_URL=https://api.github.com/user \\\n    -e OAUTH2_GITHUB_CLIENT_ID=xxx \\\n    -e OAUTH2_GITHUB_CLIENT_SECRET=xxx \\\n    -e OAUTH2_GITHUB_DOMAIN_WHITELIST=xxx \\\n    -e OAUTH2_GITHUB_ICON=fab fa-github\n```\n\nOn first glance, this looks like a mess. Let's break it down:\n\n- `-d` runs the container in detached mode\n- `-p 8080:3000` maps port 8080 on the host to port 3000 in the container\n- `-e AUTH_HOST=localhost:8080` is the host and port of the authentication proxy, this is used to redirect users when authentication is required.\n- `-e COOKIE_SECURE=false` sets the secure flag on the cookie to false, this is useful when running the container locally, will default to true if not set.\n- `-e COOKIE_HOSTS=localhost:8080` is a list of hosts that the authentication proxy is available on, this is used to be able to set cookies on multiple domains (e.g. `domain1.dev,domain2.me`)\n- `-e COOKIE_HOSTS_USE_ROOT=true` sets the cookie path on the base domain, useful when all subdomains should be authenticated.\n\nThe rest of the environment variables are used to configure the authentication methods.\n\n### Environment variables\n\nAs mentioned above, there are a few environment variables that can be used to configure the authentication proxy, these are:\n\n| Variable                  | Description                                                                                           | Default          |\n| ------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------- |\n| AUTH_PREFIX               | The prefix for the authentication proxy                                                               |                  |\n| AUTH_HOST                 | The host and port of the authentication proxy, used to redirect users when authentication is required | `localhost`      |\n| SESSION_SECRET            | The secret used to sign the session cookie                                                            |                  |\n| ACCESS_TOKEN_NAME         | The name of the access token cookie                                                                   | `_access_token`  |\n| ACCESS_TOKEN_SECRET       | The secret used to sign the access token cookie                                                       | `secret`         |\n| ACCESS_TOKEN_EXPIRATION   | The expiration time for the access token cookie                                                       | `15m`            |\n| REFRESH_TOKEN_NAME        | The name of the refresh token cookie                                                                  | `_refresh_token` |\n| REFRESH_TOKEN_SECRET      | The secret used to sign the refresh token cookie                                                      | `refresh`        |\n| REFRESH_TOKEN_EXPIRATION  | The expiration time for the refresh token cookie                                                      | `7d`             |\n| COOKIE_SECURE             | Whether the cookies should be secure or not                                                           | `true`           |\n| COOKIE_HOSTS              | A list of hosts that the authentication proxy is available on                                         | `localhost`      |\n| COOKIE_HOSTS_USE_ROOT     | Whether the base domain should be used as the cookie domain                                           | `false`          |\n| LONG_LIVED_TOKENS_ENABLED | Whether long lived tokens should be enabled or not                                                    | `false`          |\n| LONG_LIVED_TOKENS_NUMBER  | The number of long lived tokens that should be generated                                              | `6`              |\n| LONG_LIVED_TOKENS         | A list of tokens that should be added as name:token pairs separated by a comma                        |                  |\n| FORM_TITLE                | The title of the login form                                                                           | `Login`          |\n| FORM_ADMIN_EMAIL          | The email address of the administrator, this will be shown in the help dialog                         |                  |\n| FORM_DISABLE_CREDITS      | Whether the credits should be disabled or not                                                         | `false`          |\n\n\u003e [!NOTE]\n\u003e The `(ACCESS|REFRESH)_TOKEN_EXPIRATION` variables should be in the format `\u003cduration\u003e\u003cunit\u003e`, where `\u003cduration\u003e` is a number and `\u003cunit\u003e` is one of `s`, `m`, `h`, `d`.\n\n\u003e [!NOTE]\n\u003e The `LONG_LIVED_TOKENS` variable should be in the format `name:token,name:token`. These tokens can be found after logging in to the auth service and visiting the `AUTH_HOST`.\n\u003e ![LONG_LIVED_TOKENS](docs/images/long-lived-tokens.png)\n\nThe proxy login form will change based on the authentication methods that are configured. The form will show a list of buttons for each configured provider, as well as a username and password field for the local provider.\n\n| Both providers configured                                     | Only local provider configured                                         | Only external providers configured                                         |\n| ------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| ![Both providers configured](docs/images/login-form-both.png) | ![Only local provider configured](docs/images/login-form-internal.png) | ![Only external providers configured](docs/images/login-form-external.png) |\n\n### Provider configuration\n\nThe authentication proxy supports multiple kinds of providers with support for multiple instances of each one. For all provider configuration variables the following scheme is used:\n`\u003cTYPE\u003e_\u003cIDENTIFIER\u003e_\u003cFIELD\u003e` where `\u003cTYPE\u003e` is the provider type, `\u003cIDENTIFIER\u003e` is the instance identifier and `\u003cFIELD\u003e` is the field name.\n\n\u003e [!NOTE]\n\u003e From here on out, the provider configuration variables will be referred to as `_\u003cFIELD\u003e`. For example, `OAUTH2_GITHUB_AUTH_URL` will be referred to as `_AUTH_URL`.\n\nThe following variables are supported for each provider:\n\n| Variable           | Description                                                                           | Default |\n| ------------------ | ------------------------------------------------------------------------------------- | ------- |\n| \\_DISPLAY_NAME     | The name of the provider, this will be shown on the login form and in the help dialog |         |\n| \\_ICON             | The fontawesome icon to use for the provider (e.g. `fab fa-github`)                   |         |\n| \\_DOMAIN_WHITELIST | A list of domains that are allowed to authenticate using this provider                |         |\n| \\_USER_WHITELIST   | A list of users that are allowed to authenticate using this provider                  |         |\n\n\u003e [!NOTE]\n\u003e Although technically supported, the `LOCAL` provider does not show an icon on the login form or use the whitelists, since the user list is in itself a whitelist.\n\n#### LOCAL\n\nThe local provider is used to authenticate users using a username and password.\n\nPasswords should be encrypted as md5 hashes, just like in the `.htpasswd` file.\n\n| Variable     | Description                                                            | Default |\n| ------------ | ---------------------------------------------------------------------- | ------- |\n| \\_USERS      | A list of users in the format `username:password` separated by a comma |         |\n| \\_USERS_FILE | The path to the users file                                             |         |\n\n#### OAUTH2\n\nThe OAuth2 provider is used to authenticate users using an OAuth2 provider.\n\n| Variable        | Description                                                                                              | Default |\n| --------------- | -------------------------------------------------------------------------------------------------------- | ------- |\n| \\_AUTH_URL      | The URL to the OAuth2 provider's authentication endpoint                                                 |         |\n| \\_TOKEN_URL     | The URL to the OAuth2 provider's token endpoint                                                          |         |\n| \\_USER_URL      | The URL to the OAuth2 provider's user endpoint                                                           |         |\n| \\_USER_FIELD    | The field in the user object that should be used as the identifier, this is used to check the whitelists | `email` |\n| \\_CLIENT_ID     | The client ID for the OAuth2 provider                                                                    |         |\n| \\_CLIENT_SECRET | The client secret for the OAuth2 provider                                                                |         |\n\n#### OIDC\n\nThe OIDC provider is used to authenticate users using OpenID Connect.\n\n| Variable        | Description                                            | Default |\n| --------------- | ------------------------------------------------------ | ------- |\n| \\_ISSUER        | The issuer URL for the OIDC provider                   |         |\n| \\_AUTH_URL      | The URL to the OIDC provider's authentication endpoint |         |\n| \\_TOKEN_URL     | The URL to the OIDC provider's token endpoint          |         |\n| \\_USER_URL      | The URL to the OIDC provider's user endpoint           |         |\n| \\_CLIENT_ID     | The client ID for the OIDC provider                    |         |\n| \\_CLIENT_SECRET | The client secret for the OIDC provider                |         |\n\n#### GOOGLE\n\nThe Google provider is used to authenticate users using Google.\n\n| Variable        | Description                               | Default |\n| --------------- | ----------------------------------------- | ------- |\n| \\_CLIENT_ID     | The client ID for the Google provider     |         |\n| \\_CLIENT_SECRET | The client secret for the Google provider |         |\n\n#### APPLE\n\nThe Apple provider is used to authenticate users using Apple ID.\n\n| Variable               | Description                                            | Default              |\n| ---------------------- | ------------------------------------------------------ | -------------------- |\n| \\_CLIENT_ID            | The client ID for the Apple provider                   |                      |\n| \\_TEAM_ID              | The team ID for the Apple provider                     |                      |\n| \\_KEY_ID               | The key ID for the Apple provider                      |                      |\n| \\_PRIVATE_KEY_LOCATION | The location of the private key for the Apple provider | `/etc/auth/apple.p8` |\n\n\u003e [!NOTE]\n\u003e Make sure the private key is mounted into the container at the location specified by the `PRIVATE_KEY_LOCATION` variable.\n\n\u003e [!NOTE]\n\u003e In order to set up this provider, you'll need to enroll in the Apple Developer Program. You can find more information [here](https://developer.apple.com/sign-in-with-apple/get-started/).\n\n#### LDAP\n\nThe LDAP provider is used to authenticate users against an LDAP server.\n\n| Variable           | Description                              | Default |\n| ------------------ | ---------------------------------------- | ------- |\n| \\_URL              | The URL to the LDAP server               |         |\n| \\_BIND_DN          | The bind DN for the LDAP server          |         |\n| \\_BIND_CREDENTIALS | The bind credentials for the LDAP server |         |\n| \\_SEARCH_BASE      | The search base for the LDAP server      |         |\n| \\_SEARCH_FILTER    | The search filter for the LDAP server    |         |\n\n### Metrics\n\nThe authentication proxy exposes metrics in the Prometheus format on `*:9100/metrics`. This can be used to monitor the authentication proxy and track the number of successful and failed logins. The following metrics are exposed:\n\n| Metric                                   | Description                                                     | Labels               |\n| ---------------------------------------- | --------------------------------------------------------------- | -------------------- |\n| `auth_proxy_unauthorized_requests_total` | The number of unauthorized requests to the authentication proxy | `host`, `path`       |\n| `auth_proxy_authorized_requests_total`   | The number of authorized requests to the authentication proxy   | `host`, `path`       |\n| `auth_proxy_login_requests_total`        | The number of login requests to the authentication proxy        | `provider`, `status` |\n| `auth_proxy_logout_requests_total`       | The number of logout requests to the authentication proxy       | `status`             |\n| `auth_proxy_refresh_requests_total`      | The number of refresh requests to the authentication proxy      | `status`             |\n| `auth_proxy_token_requests_total`        | The number of token requests to the authentication proxy        | `token`, `status`    |\n\n## Contributing\n\nContributions are welcome, please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixnyb%2Fauthentication-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpixnyb%2Fauthentication-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixnyb%2Fauthentication-proxy/lists"}