{"id":16774694,"url":"https://github.com/leonjza/trauth","last_synced_at":"2025-03-17T02:31:35.735Z","repository":{"id":65338897,"uuid":"221656675","full_name":"leonjza/trauth","owner":"leonjza","description":"🔑 A simple, cookie based Traefik middleware plugin for HTTP Basic / Ceritificate Based Single Sign-on","archived":false,"fork":false,"pushed_at":"2024-12-17T09:48:06.000Z","size":242,"stargazers_count":45,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-16T07:31:40.184Z","etag":null,"topics":["authentication","forwardauth","sso","traefik","traefik-plugin"],"latest_commit_sha":null,"homepage":"https://plugins.traefik.io/plugins/64a53f2e498e334469bdbd28/trauth","language":"Go","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/leonjza.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-14T09:15:49.000Z","updated_at":"2025-03-05T13:15:09.000Z","dependencies_parsed_at":"2024-01-28T12:27:58.943Z","dependency_job_id":"2cf1d8cc-143c-4e80-9469-77c35e87f86f","html_url":"https://github.com/leonjza/trauth","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Ftrauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Ftrauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Ftrauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Ftrauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonjza","download_url":"https://codeload.github.com/leonjza/trauth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243961791,"owners_count":20375315,"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","forwardauth","sso","traefik","traefik-plugin"],"created_at":"2024-10-13T06:49:51.317Z","updated_at":"2025-03-17T02:31:35.314Z","avatar_url":"https://github.com/leonjza.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# trauth\n\n\u003cimg align=\"right\" src=\"./images/logo.png\" height=\"300\" alt=\"beacon-pip-frame-proxy\"\u003e\n\n🔑 A simple, cookie based Traefik middleware [plugin](https://plugins.traefik.io/plugins) for HTTP Basic or mTLS Single Sign-on\n\n`trauth` can either read [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) formatted data as a credentials database, prompting via HTTP basic auth or validate client TLS certificates against a pre-configured CA. Once authenticated, a (configurable) cookie will be set such that any other services sharing that domain will also be authenticated.\n\n**Note:** This plugin changed significantly in the version 1.4.x release from a ForwardAuth server to a middleware plugin. If you are interested in the ForwardAuth server then checkout the [old branch](https://github.com/leonjza/trauth/tree/old).\n\n## usage\n\nAs this is a middleware plugin, you need to do two things to use it. Install the plugin and then configure the middleware.\n\n### installation\n\nA static configuration is needed. Either add it to your existing `traefik.yml` like this:\n\n```yml\nexperimental:\n  plugins:\n    trauth:\n      moduleName: github.com/leonjza/trauth\n      version: v1.6.5 # or whatever the latest version is\n```\n\nOr, add it as labels to your `docker-compose.yml` (or similar).\n\n```text\nservices:\n  traefik:\n    image: traefik\n    command:\n      - --experimental.plugins.trauth.moduleName=github.com/leonjza/trauth\n      - --experimental.plugins.trauth.version=v1.6.5\n```\n\n### authentication types\n\nIt is possible to use both mTLS and HTTP Basic Authentication at the same time. In that case, trauth will prefer mTLS over basic authentication, but if a connection came it that does not have a client certificate (or isn't TLS to begin with), it will fall back to Basic Authentication.\n\nIf none of the authentication methods are configured, it will not be possible to authenticate, meaning a webservice protected with trauth will only response with HTTP 401's.\n\nFor configuration examples refer to the docker-compose.yml files in this repo. For more information about the available configuration options see the [#configuration](#configuration) section below.\n\n#### mtls\n\nIn the case of mTLS, a client's peer certificate will be validated against a configured Certificate Authority (CA). Configuring mTLS authentication requires two things:\n\n- A CA needs to be configured as a path to a PEM encoded file using the `capath` configuration value.\n- The relevant Traefik [TLS options](https://doc.traefik.io/traefik/https/tls/#client-authentication-mtls) need to be set on the relevant service router.\n\nRegardless if you use docker labels or a dynamic configuration, you need to specify the relevant TLS options as a seperate file. An example can be seen in the [tls.yml](./tls.yml) file.\n\nWith mTLS configured, provision the client certificate as needed. An example `curl` request that includes a client certificate to authenticate to a `trauth` protected service, accepting a cookie to include in a redirection would be:\n\n```bash\ncurl -kvL -b cookies.txt --cert ca/user1/user1.pem https://whoami-3.dev.local/\n```\n\n#### basic auth\n\nIn the case of HTTP Basic Authentication, trauth needs to have an `httpasswd` formatted user database configured. That can be done using either the `users` option to specify them inline, or via `usersfile` to set a path containing the user database.\n\nAn example `curl` request that includes the credentials to authenticate to an HTTP Basic Authentication protected service would be:\n\n```bash\ncurl -kvL -b cookies.txt --user admin:password http://whoami-2.dev.local/\n```\n\n### configuration\n\nAs this plugin is middleware, you need to both attach the middleware to an appropriate `http.router`, as well as configure the middleware itself. Configuration will depend on how you use Traefik, but here are some examples.\n\nThe available configuration options are as follows:\n\n| Option | Required | Default Value | Notes |\n|--------|----------|---------------|-------|\n| `domain` | True | | The domain name the authentication cookie will be scoped to. |\n| `realm` | False | `Restricted` | A message to display when prompting for credentials. Note, not all browsers show this to users anymore.  |\n| `logunauthenticated` | False | `false` | Log unauthenticated requests. |\n| `capath` | False |  | A path to a PEM encoded Certificate Authority to validate client provided certificates against. |\n| `cookiename` | False | `trauth` | The name of the cookie to use for authentication.  |\n| `cookiepath` | False | `/` | The path of the cookie to use for authentication. |\n| `cookiekey` | False | generated | The authentication key used to check cookie authenticity. **Note** See [cookiekey](#cookiekey) section below |\n| `cookiesecure` | False | `false` | Use the `secure` flag when setting the authentication cookie. |\n| `cookiehttponly` | False | `false` | Use the `httponly` flag when setting the authentication cookie. |\n| `users` | False | | A htpasswd formatted list of users to accept authentication for. If `usersfile` is not set, then this value must be set. |\n| `usersfile` | False | | A path to a htpasswd formatted file with a list of users to accept authentication for. If `users` is not set, then this value must be set. |\n| `rules` | False | | A rules object that defines hostnames and paths where authentication requirements are skipped |\n\n#### cookiekey\n\nBy default, trauth will generate a new, random value for `cookiekey` if one is not explicitly set, or is set to a value that is not 32 ascii characters long. In many cases, this is ok, however, special consideration should be given to cases where this plugin is used in multiple places. By setting a static `cookiekey`, you garuantee that cookies across instances of the plugin can read the values within. If each instance of the plugin (where multiple instances will spawn if there are multiple unique definititions of the middleware) generated their own key, none will accept the cookie value set by another.\n\nFor an example, have a look a the [docker-compose.yml](docker-compose.yml) file in this repository.\n\n#### rules\n\nRules are optional and useful if you have situations where trauth should not block and require a valid authentication session. Rules define conditions for when authentication is not required. For example, based on a request to a specific path, or a request coming from a specific source IP network range.\n\nIn the case of path exclusions, this could be used for web services that should be authenticated by default, but some parts of the service should be available without authentication (or at least, not blocked by this middleware as it may have its own authentication you want to use instead). For example, say a web application exposes an API, and you want to have that API (or parts of it), available externally.\n\nIn the case of IP network range exclusions, this could be used if a trusted network may use a web service without extra authentication, but everyone else should provide an identity first.\n\nRules have two configuration options. A domain, and the relevant excludes (paths or IP networks). For some examples, have a look a the [docker-compose.dev.yml](docker-compose.dev.yml) file in this repository.\n\n#### configuration examples\n\nAs dynamic configuration:\n\n```yml\nhttp:\n  routers:\n    myservice:\n      middlewares:\n        - sso\n    \n  middlewares:\n    sso:\n      plugin:\n        trauth:\n          domain: mydomain.local\n          cookiename: sso-cookie\n          users: admin:$$2y$$05$$fVvJElbTaB/Cw9FevNc2keGo6sMRhY2e55..U.6zOsca3rQuuAU1e\n          # for mTLS (/ca/ca.pem needs to be readable to the traefik service in case of docker)\n          capath: /ca/ca.pem\n          rules:\n          - domain: service.mydomain.local\n            path:\n            - ^/api/v1/.*$\n            - ^/api/v2/.*$\n          - domain: admin.mydomain.local\n            ipnet:\n            - 10.0.0.0/24\n```\n\nAs labels:\n\n```text\ntraefik.http.routers.myservice.middlewares: sso\ntraefik.http.middlewares.sso.plugin.trauth.domain: mydomain.local\ntraefik.http.middlewares.sso.plugin.trauth.cookiename: sso-cookie\ntraefik.http.middlewares.sso.plugin.trauth.capath: /ca/ca.pem\n# optional rules\ntraefik.http.middlewares.sso.plugin.trauth.rules[0].domain: service.mydomain.local\ntraefik.http.middlewares.sso.plugin.trauth.rules[0].excludes[0].path: ^/api/v1/.*$\ntraefik.http.middlewares.sso.plugin.trauth.rules[0].excludes[1].path: ^/api/v2/.*$\ntraefik.http.middlewares.sso.plugin.trauth.rules[1].domain: admin.mydomain.local\ntraefik.http.middlewares.sso.plugin.trauth.rules[1].excludes[0].path: 10.0.0.0/24\n# *note* the double $$ here to escape a single $\ntraefik.http.middlewares.sso.plugin.trauth.users: admin:$$2y$$05$$fVvJElbTaB/Cw9FevNc2keGo6sMRhY2e55..U.6zOsca3rQuuAU1e\n```\n\n## development\n\nAn example `docker-compose.dev.yml` is included to show how to get this plugin up and running. No binary releases are nessesary as the stack is configured to mount this source repository in the appropriate location.\n\n## adding users\n\ntrauth uses a basic Apache htpasswd file format. For detailed usage of `htpasswd`, please see [this](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) guide.\n\nUsers can be specified using either ther `users` or `usersfile` configuration options. In both cases, the same format is needed. For the `users` option, the content of a well formatted htpasswd file can be pasted as the value of the key. For `usersfile`, the location of a file generated using the steps that follow need to be set.\n\nTo add a new user in a new `htpass` file, using the Bcrypt hashing algorithm, run:\n\n```bash\nhtpasswd -Bc htpass username1\n```\n\nTo add a new user to an existing `htpass` file, run:\n\n```bash\nhtpasswd -B htpass username2\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonjza%2Ftrauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonjza%2Ftrauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonjza%2Ftrauth/lists"}