portal

README

caddy-auth-portal

Authentication Plugin for Caddy v2 implementing Form-Based Authentication and Basic Authentication.

Please ask questions either here or via LinkedIn. I am happy to help you! @greenpau

Overview

The purpose of this plugin is providing authentication only. The plugin issue JWT tokens upon successful authentication. In turn, the authorization of the tokens is being handled by caddy-auth-jwt.

The plugin supports the following authentication backends:

• Local (local) - JSON flat file database
• LDAP (ldap) - remote Microsoft AD database

Please follow these links for the documentation:

• Local
• LDAP

The plugin accepts user credentials for authentication with:

• Form-based Authentication: POST with application/x-www-form-urlencoded
• Basic Authentication: GET with Authorization: Basic header

The following digram is visual representation of the configuration of caddy-auth-portal and caddy-auth-jwt.

Authentication Portal

Authentication Methods

Basic Authentication

The following command demonstrates basic authentication process. The plugin returns JWT token via Set-Cookie: access_token and token field in JSON response.

curl --insecure -H "Accept: application/json" --user webadmin:password123 -v https://127.0.0.1:3443/auth

The expected output is as follows:

* About to connect() to 127.0.0.1 port 3443 (#0)
*   Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 3443 (#0)
* Initializing NSS with certpath: sql:/etc/pki/nssdb
* skipping SSL peer certificate verification
* SSL connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate:
*       subject: E=admin@caddy.local,OU=Local Developement,CN=*.caddy.localhost,L=Local Developement,O=Local Developement,ST=NY,C=US
*       start date: Mar 02 08:01:16 2020 GMT
*       expire date: Feb 28 08:01:16 2030 GMT
*       common name: *.caddy.localhost
*       issuer: E=admin@caddy.local,OU=Local Developement,CN=*.caddy.localhost,L=Local Developement,O=Local Developement,ST=NY,C=US
* Server auth using Basic with user 'webadmin'
> GET /auth HTTP/1.1
> Authorization: Basic d2ViYWRtaW46cGFzc3dvcmQxMjM=
> User-Agent: curl/7.29.0
> Host: 127.0.0.1:3443
> Accept: application/json
>
< HTTP/1.1 200 OK
< Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTE3MzE0NzksInN1YiI6IndlYmFkbWluIiwiZW1haWwiOiJ3ZWJhZG1pbkBsb2NhbGRvbWFpbi5sb2NhbCIsInJvbGVzIjpbInN1cGVyYWRtaW4iLCJndWVzdCIsImFub255bW91cyJdLCJvcmlnaW4iOiJsb2NhbGhvc3QifQ.OmFOCu-UJdx16FYLa2ezr7WRmOdUbgrQadhfk1tN4AliIwu69x9TLgzoke_Cr3TqzvMjlQDd22r-3DHBXuzllw
< Cache-Control: no-store
< Content-Type: application/json
< Pragma: no-cache
< Server: Caddy
< Set-Cookie: access_token=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTE3MzE0NzksInN1YiI6IndlYmFkbWluIiwiZW1haWwiOiJ3ZWJhZG1pbkBsb2NhbGRvbWFpbi5sb2NhbCIsInJvbGVzIjpbInN1cGVyYWRtaW4iLCJndWVzdCIsImFub255bW91cyJdLCJvcmlnaW4iOiJsb2NhbGhvc3QifQ.OmFOCu-UJdx16FYLa2ezr7WRmOdUbgrQadhfk1tN4AliIwu69x9TLgzoke_Cr3TqzvMjlQDd22r-3DHBXuzllw Secure; HttpOnly;
< Date: Tue, 09 Jun 2020 19:22:59 GMT
< Content-Length: 318
<
* Connection #0 to host 127.0.0.1 left intact
{"token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTE3MzE0NzksInN1YiI6IndlYmFkbWluIiwiZW1haWwiOiJ3ZWJhZG1pbkBsb2NhbGRvbWFpbi5sb2NhbCIsInJvbGVzIjpbInN1cGVyYWRtaW4iLCJndWVzdCIsImFub255bW91cyJdLCJvcmlnaW4iOiJsb2NhbGhvc3QifQ.OmFOCu-UJdx16FYLa2ezr7WRmOdUbgrQadhfk1tN4AliIwu69x9TLgzoke_Cr3TqzvMjlQDd22r-3DHBXuzllw"}

Documentation

Index

• type AuthProvider
  • func (m AuthProvider) Authenticate(w http.ResponseWriter, r *http.Request) (caddyauth.User, bool, error)
  • func (AuthProvider) CaddyModule() caddy.ModuleInfo
  • func (m *AuthProvider) Provision(ctx caddy.Context) error
  • func (m *AuthProvider) Validate() error
• type AuthProviderPool
  • func (p *AuthProviderPool) Provision(name string) error
  • func (p *AuthProviderPool) Register(m *AuthProvider) error
• type AuthResponse
• type Backend
  • func (b *Backend) Authenticate(reqID string, data map[string]string) (*jwt.UserClaims, int, error)
  • func (b *Backend) Configure(p *AuthProvider) error
  • func (b *Backend) GetRealm() string
  • func (b Backend) MarshalJSON() ([]byte, error)
  • func (b *Backend) UnmarshalJSON(data []byte) error
  • func (b *Backend) Validate(p *AuthProvider) error
• type BackendDriver
• type UserInterfaceParameters

Types

type AuthProvider

type AuthProvider struct {
	Name            string                   `json:"-"`
	Provisioned     bool                     `json:"-"`
	ProvisionFailed bool                     `json:"-"`
	PrimaryInstance bool                     `json:"primary,omitempty"`
	Context         string                   `json:"context,omitempty"`
	AuthURLPath     string                   `json:"auth_url_path,omitempty"`
	UserInterface   *UserInterfaceParameters `json:"ui,omitempty"`
	Backends        []Backend                `json:"backends,omitempty"`
	TokenProvider   *jwt.TokenProviderConfig `json:"jwt,omitempty"`
	TokenValidator  *jwt.TokenValidator      `json:"-"`
	// contains filtered or unexported fields
}

AuthProvider authorizes access to endpoints based on the credentials provided in a request.

func (AuthProvider) Authenticate

func (m AuthProvider) Authenticate(w http.ResponseWriter, r *http.Request) (caddyauth.User, bool, error)

Authenticate authorizes access based on the presense and content of JWT token.

func (AuthProvider) CaddyModule

func (AuthProvider) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*AuthProvider) Provision

func (m *AuthProvider) Provision(ctx caddy.Context) error

Provision provisions authentication portal provider

func (*AuthProvider) Validate

func (m *AuthProvider) Validate() error

Validate implements caddy.Validator.

type AuthProviderPool

type AuthProviderPool struct {
	Members          []*AuthProvider
	RefMembers       map[string]*AuthProvider
	PrimaryInstances map[string]*AuthProvider
	MemberCount      int
	// contains filtered or unexported fields
}

AuthProviderPool provides access to all instances of the plugin.

var ProviderPool *AuthProviderPool

ProviderPool is the global authentication provider pool. It provides access to all instances of authentication portal plugin.

func (*AuthProviderPool) Provision

func (p *AuthProviderPool) Provision(name string) error

Provision provisions non-primary instances in an authentication context.

func (*AuthProviderPool) Register

func (p *AuthProviderPool) Register(m *AuthProvider) error

Register registers authentication provider instance with the pool.

type AuthResponse

type AuthResponse struct {
	Error   bool   `json:"error,omitempty"`
	Message string `json:"message,omitempty"`
	Token   string `json:"token,omitempty"`
}

AuthResponse represents authentication response object.

type Backend

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

Backend is an authentication backend.

func (*Backend) Authenticate

func (b *Backend) Authenticate(reqID string, data map[string]string) (*jwt.UserClaims, int, error)

Authenticate performs authentication with an authentication provider.

func (*Backend) Configure

func (b *Backend) Configure(p *AuthProvider) error

Configure configures backend with the authentication provider settings.

func (*Backend) GetRealm

func (b *Backend) GetRealm() string

GetRealm returns realm associated with an authentication provider.

func (Backend) MarshalJSON

func (b Backend) MarshalJSON() ([]byte, error)

MarshalJSON packs configuration info JSON byte array

func (*Backend) UnmarshalJSON

func (b *Backend) UnmarshalJSON(data []byte) error

UnmarshalJSON unpacks configuration into appropriate structures.

func (*Backend) Validate

func (b *Backend) Validate(p *AuthProvider) error

Validate checks whether an authentication provider is functional.

type BackendDriver

type BackendDriver interface {
	GetRealm() string
	Authenticate(string, map[string]string) (*jwt.UserClaims, int, error)
	ConfigureLogger(*zap.Logger) error
	ConfigureTokenProvider(*jwt.TokenProviderConfig) error
	ConfigureAuthenticator() error
	Validate() error
}

BackendDriver is an interface to an authentication provider.

type UserInterfaceParameters

type UserInterfaceParameters struct {
	Templates          map[string]string      `json:"templates,omitempty"`
	AllowRoleSelection bool                   `json:"allow_role_selection,omitempty"`
	Title              string                 `json:"title,omitempty"`
	LogoURL            string                 `json:"logo_url,omitempty"`
	LogoDescription    string                 `json:"logo_description,omitempty"`
	PrivateLinks       []ui.UserInterfaceLink `json:"private_links,omitempty"`
	AutoRedirectURL    string                 `json:"auto_redirect_url"`
	Realms             []ui.UserRealm         `json:"realms"`
}

UserInterfaceParameters represent a common set of configuration settings for HTML UI.