trauth

README

trauth

🔑 A simple, cookie based Traefik middleware plugin for HTTP Basic Single Sign-on

trauth reads htpasswd formatted data as a credentials database, prompting via HTTP basic auth. Once authenticated, a (configurable) cookie will be set such that any other services sharing that domain will also be authenticated.

Note: This plugin changed significantly in the version 2 release from a ForwardAuth server to a middleware plugin. If you are interested in the ForwardAuth server then checkout the latest version 1.3 tag.

usage

As this is a middleware plugin, you need to do two things. Install the plugin and then configure the middleware.

installation

A static configuration is needed. Either add it to your existing traefik.yml like this:

experimental:
  plugins:
    trauth:
      moduleName: github.com/leonjza/trauth
      version: 2.0.0 # or whatever is the latest version

Or, add it as labels to your docker-compose.yml (or similar).

services:
  traefik:
    image: traefik
    command:
      - --experimental.plugins.trauth.moduleName=github.com/leonjza/trauth
      - --experimental.plugins.trauth.version=2.0.0

configuration

As 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.

The available configuration options are as follows:

Option	Required	Default Value	Notes
domain	True		The domain name the authentication cookie will be scoped to.
realm	False	Restricted	A message to display when prompting for credentials. Note, not all browsers show this to users anymore.
cookiename	False	trauth	A message to display when prompting for credentials. Note, not all browsers show this to users anymore.
cookiepath	False	/	The name of the cookie to use for authentication.
cookiekey	False	generated	The authentication key used to check cookie authenticity. Note See cookiekey section below
cookieksecure	False	false	Use the secure flag when setting the authentication cookie.
cookiekhttponly	False	false	Use the httponly flag when setting the authentication cookie.
users	False if usersfile is set		A htpasswd formatted list of users to accept authentication for. If usersfile is not set, then this value must be set.
usersfile	False if users is set		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.

cookiekey

By 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 asci 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.

For an example, have a look a the docker-compose.yml file in this repository.

configuration examples

As dynamic configuration:

http:
  routers:
    myservice:
      middlewares:
        - sso
    
  middlewares:
    sso:
      plugin:
        trauth:
          domain: mydomain.local
          cookiname: sso-cookie
          users: admin:$$2y$$05$$fVvJElbTaB/Cw9FevNc2keGo6sMRhY2e55..U.6zOsca3rQuuAU1e

As labels:

traefik.http.routers.myservice.middlewares: sso
traefik.http.middlewares.sso.plugin.trauth.domain: mydomain.local
traefik.http.middlewares.sso.plugin.trauth.cookiename: sso-cookie
# *note* the double $$ here to escape a single $
traefik.http.middlewares.sso.plugin.trauth.users: admin:$$2y$$05$$fVvJElbTaB/Cw9FevNc2keGo6sMRhY2e55..U.6zOsca3rQuuAU1e

For more a more complete example, check out the docker-compose.yml file in this repo.

development

An 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.

adding users

trauth uses a basic Apache htpasswd file format. For detailed usage of htpasswd, please see this guide.

Users 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.

To add a new user in a new htpass file, using the Bcrypt hashing algorithm, run:

htpasswd -Bc htpass username1

To add a new user to an existing htpass file, run:

htpasswd -B htpass username2

Documentation

Index

• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• func NewLogger() *log.Logger
• type Config
  • func CreateConfig() *Config
  • func (c *Config) Validate() error
• type Trauth
  • func (t *Trauth) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type User

Functions

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

New created a new plugin.

func NewLogger

func NewLogger() *log.Logger

Types

type Config

type Config struct {
	// Required Values
	Domain    string `yaml:"domain"`
	Users     string `yaml:"users"`
	UsersFile string `yaml:"usersfile"`

	// Values with internal defaults
	CookieName     string `yaml:"cookiename"`
	CookiePath     string `yaml:"cookiepath"`
	CookieSecure   bool   `yaml:"cookiesecure"`
	CookieHttpOnly bool   `yaml:"cookiehttponly"`
	CookieKey      string `yaml:"cookiekey"`
	Realm          string `yaml:"realm"`
	// contains filtered or unexported fields
}

Config the plugin configuration.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

func (*Config) Validate

func (c *Config) Validate() error

Validate parses configuration information.

This function does a few things:

1. Prepare the session store
2. Prepare user credentials.

There are two types of credentials you case set. Users, and UsersFile. If Users is set, a buffered reader is configured to parse that information. If UsersFile is set, a file read is configured.

It is an error to set both.

type Trauth

type Trauth struct {
	// contains filtered or unexported fields
}

Trauth is a Traefik plugin.

func (*Trauth) ServeHTTP

func (t *Trauth) ServeHTTP(rw http.ResponseWriter, req *http.Request)

type User

type User struct {
	Username      string
	Authenticated bool
}

User holds a users session information.