reauth

Another authentication plugin for CaddyServer (v1)

For CaddyServer V2 Please caddy2-reauth

Contents

• reauth
  • Abstract
  • Supported backends
  • Supported failure handlers
  • Configuration
  • Spaces in configuration
  • Backends
  • Simple
  • Upstream
  • Refresh
  • GitlabCI
  • LDAP
  • Failure handlers
  • HTTPBasic
  • Redirect
  • Status
  • Todo
  • Other notes

Abstract

Provides a common basis for various and multiple authentication systems. This came to be as we wanted to dynamically authenticate our docker registry against gitlab-ci and avoid storing credentials in gitlab while still permitting users to log in with their own credentials.

Supported backends

The following backends are supported.

• Simple
• Upstream
• Refresh
• GitlabCI
• LDAP

With more to come...

Supported failure handlers

The following failure handlers are supported.

• HTTPBasic
• Redirect
• Status

Configuration

The core of the plugin supports the following arguments:

Example:

    reauth {
        path /
        except /public
        except /not_so_secret
    }

Along with these two arguments you are required to specify at least one backend.

Spaces in configuration

Through experimentation by @mh720 (Mike Holloway) it has been discovered that if you need spaces in your configuration that the best bet is to use unicode escaping.

For example:

OU=GROUP\u0020NAME

I imagine this would allow you to escape any character you need this way including quotes.

Backends

Simple

This is the simplest plugin, taking just a list of username=password[,username=password].

Example:

    simple user1=password1,user2=password2

Upstream

Authentication against an upstream http server by performing a http basic authenticated request and checking the response for a http 200 OK status code. Anything other than a 200 OK status code will result in a failure to authenticate.

Parameters for this backend:

Examples

    upstream url=https://google.com,skipverify=true,timeout=5s
  upstream url=https://google.com,skipverify=true,timeout=5s,follow=true,match=login

Refresh

Authentication with Refresh Token against configurable endpoints with response caching and cache entry expiration times. If failure conditions in the configuration file are met a 401 is returned otherwise result will be successful. This module is designed to be used with the caddy-secrets plugin, a yaml file with a reauth object with an endpoints array will hold configurations for endpoints and how they work together for auth service.

Parameters for this backend:

Examples

• Caddyfile

  refresh url=https://example.com,skipverify=true,timeout=5s,lifetime=3h,cleaninterval=1s,limit=1000

• Secrets file

  reauth:
  client_authorization: 1                             # authorization flag (required) - 0/1 whether to check for Authorization header, 2 will throw 500 if missing
                                                        Authorization access token stored in 'ResultsMap' under 'client_token' key
  endpoints                                           # endpoints array (required)
  - name: refresh                                   # endpoint of name 'refresh' (required)
    url: null                                       
    path: "/access_token"
    method: POST                                    # auth request method (required) - at the moment only POST and GET are handled (value must be in caps)
    data:                                           # data array (required)
      - key: grant_type
        value: refresh_token
      - key: refresh_token                          # object with 'refresh_token' key (required)
        value: <refresh token to get access token>  # value (required) - holds actual refresh token to request access token with
    cachekey: refresh_token
    headers:
      - key: Content-Type
        value: "application/x-www-form-urlencoded"
    skipverify: true
    cookies: true
    responsekey: jwt_token
    failures:
      - validation: equality                        # there are 3 types of validation, 'equality' will have auth fail if
        key: message                                # response body value under failure object key equality failure object value
        value: Forbidden
        valuemessage: false
        message: "Refresh access token failed"
                                                    # access token is stored in 'ResultsMap' under 'refresh' key
  
  - name: security_context                          # endpoint responses get stored in 'ResultsMap' under the name of the endpoint
    url: https://different.example.com              # url value should be set if endpoint uses different url than one in Caddyfile
    path: "/security_context"                       # path is concatenated after url for request 
    method: GET                                     # request method, GET will put data params in query, POST will encode form
    data:                                           # data needed for request
      - key: access_token
        value: "{client_token}"                     # surrounding keys with {}'s will have them replaced by values in 'ResultsMap'
    cachekey: client_token                          # cache entry key
    headers:                                        # keys and values to set on endpoint request headers
      - key: Authorization                          
        value: "Bearer {refresh}"                   # surrounding keys with {}'s will have them replaced by values in 'ResultsMap' 
    skipverify: true                                # whether endpoint request should use Caddyfile skipverify configuration
    cookies: true                                   # whether endpoint request should use Caddyfile cookies configuration
    responsekey: null                               # if set, the key will be used to pull value from endpoint response
    failures:
      - validation: presence                        # 'presence' validation will have auth fail if response body has failure object key
        key: error
        value: ~
        valuemessage: true                          # if valuemessage bool is true, response object value under failure object key
        message: "Security context error: "             is concatenated to failure message
      - validataion: status                         # 'status' validation will have auth fail if endpoint response status
        key: ~                                          matches failure object value
        value: 401
        valuemessage: false
        message: "Security context unauthorized"
  resultkey: security_context                         # last endpoint response stored in 'ResultsMap' is passed down caddy filter chain
                                                        in a query param with the key named after 'resultkey' value

GitlabCI

Authenticate against Gitlab as the gitlab-ci-user for the purposes of letting the gitlab-ci access otherwise protected resources without storing credentials in gitlab or gitlab-ci.yml. Works basically like the [Upstream]#upstream backend except the username you provide is the project path

Parameters for this backend:

Example

    gitlabci url=https://gitlab.example.com,skipverify=true,timeout=5s

Example of logging in via gitlab-ci.yml

    docker login docker.example.com -u "$CI_PROJECT_PATH" -p "$CI_BUILD_TOKEN"

LDAP

Authenticate against a specified LDAP server - for example a Microsoft AD server.

Parameters for this backend:

Example

    ldap url=ldap://ldap.example.com:389,timeout=5s,base="OU=Users,OU=Company,DC=example,DC=com",filter="(&(memberOf=CN=group,OU=Users,OU=Company,DC=example,DC=com)(objectClass=user)(sAMAccountName=%s))"

Failure handlers

HTTPBasic

This is the default failure handler and is by default configured to send the requested host as the realm

Parameters for this handler:

Example

    failure  basicauth realm=example.org

Redirect

Redirect the user, perhaps to a login page?

Parameters for this handler:

Example

    failure redirect target=example.org,code=303

Example with uri

    failure redirect target=/auth?redir={uri},code=303

Status

Simplest possible failure handler, return http status $code

Parameters for this handler:

Example

    failure status code=418

Todo

Modularise the failure handlers...

Other notes

• Have embedded https://github.com/startsmartlabs/caddy-secrets in lib/caddy-secrets for easier maintenance.