auth

README

caddy-auth

Authentication App for Caddy v2.

This Caddy v2 Application provides a way of consolidating the management of individual authentication plugins, e.g. caddy-auth-portal and caddy-auth-jwt.

This way, all major configiration happens in caddy-auth and the instances of the individual plugins can inherit their settings from the application. At the same time, the individual plugins can extend or overwrite the setting in the caddy-auth application.

Getting Started

Please study the assets/conf/local/config.json configuration file as a configuration reference. The relevant parts of the configuration in YAML format are:

apps:
  auth:
    providers:
    - provider_type: portal
      auth_url_path: /auth
      backends:
      - type: local
        path: assets/backends/local/users.json
        realm: local
      jwt:
        token_secret: 383aca9a-1c39-4d7a-b4d8-67ba4718dd3f
        token_issuer: 7a50e023-2c6e-4a5e-913e-23ecd0e2b940
      ui:
        templates:
          login: assets/ui/login.template
          portal: assets/ui/portal.template
        logo_url: https://caddyserver.com/resources/images/caddy-circle-lock.svg
        logo_description: Caddy
        allow_role_selection: false
        auto_redirect_url: ''
        private_links:
        - title: Prometheus
          link: /prometheus
        - title: Alertmanager
          link: /alertmanager
    - provider_type: jwt
      context: default
      token_name: access_token
      token_secret: 383aca9a-1c39-4d7a-b4d8-67ba4718dd3f
      token_issuer: 7a50e023-2c6e-4a5e-913e-23ecd0e2b940
      auth_url_path: /auth
      access_list:
      - action: allow
        claim: roles
        values:
        - anonymous
        - guest
        - admin
        - superadmin
      strip_token: false
      pass_claims: false
      token_types:
      - HS256
      - HS384
      - HS512
      token_sources:
      - header
      - cookie
      - query
  http:
    http_port: 3080
    https_port: 3443
    servers:
      srv0:
        listen:
        - :3443
        routes:
        - match:
          - path:
            - /
          handle:
          - handler: static_response
            headers:
              Location:
              - /auth
            status_code: 302
          terminal: true
        - handle:
          - handler: authentication
            providers:
              portal: {}
          match:
          - path:
            - /auth*
          terminal: true
        - handle:
          - handler: authentication
            providers:
              jwt: {}
          - handler: static_response
            status_code: 200
            body: prometheus
          match:
          - path:
            - /prometheus
          terminal: true
        - handle:
          - handler: authentication
            providers:
              jwt:
                access_list:
                - action: allow
                  claim: roles
                  values:
                  - anonymous
                  - guest
                  - admin
                  - superadmin
          - handler: static_response
            status_code: 200
            body: alertmanager
          match:
          - path:
            - /alertmanager
          terminal: true
        - handle:
          - handler: static_response
            status_code: 200
            body: 1.0.0
          match:
          - path:
            - /version
          terminal: true

The apps.auth.providers section of the configuration defines global configuration settings for portal and jwt plugins:

apps:
  auth:
    providers:
    - provider_type: portal
      // ... omitted ...
    - provider_type: jwt
      // ... omitted ...

Later, in the apps.http section of the configuration, the portal and jwt plugin initialize their instances. Each route handler gets its own instance of the plugins. When Caddy configures the route handler using an authentication plugin, the plugin reached to global authentication configuration settings, i.e. apps.auth.providers, for defaults.

apps:

  // ... intentionally omitted ...

  http:

        // ... intentionally omitted ...

        routes:
        
        // ... intentionally omitted ...
        
        - handle:
          - handler: authentication
            providers:
              portal: {}

        // ... intentionally omitted ...

        - handle:
          - handler: authentication
            providers:
              jwt: {}

        // ... intentionally omitted ...

Documentation

Index

• type App
  • func (App) CaddyModule() caddy.ModuleInfo
  • func (m *App) Provision(ctx caddy.Context) error
  • func (m App) Start() error
  • func (m App) Stop() error
• type GlobalConfiguration
  • func (c *GlobalConfiguration) AddProvider(ctx caddy.Context, name string, data []byte) error
• type Provider
  • func (p Provider) MarshalJSON() ([]byte, error)
  • func (p *Provider) UnmarshalJSON(inputConfig []byte) error

Types

type App

type App struct {
	Name      string     `json:"-"`
	Providers []Provider `json:"providers,omitempty"`
	// contains filtered or unexported fields
}

App binds various authentication plugins.

func (App) CaddyModule

func (App) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*App) Provision

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

Provision provisions JWT authorization provider

func (App) Start

func (m App) Start() error

Start starts the authentication app module.

func (App) Stop

func (m App) Stop() error

Stop stops the authentication app module.

type GlobalConfiguration

type GlobalConfiguration struct {
	Portal map[string]*portal.AuthProvider `json:"portal,omitempty"`
	Jwt    map[string]*jwt.AuthProvider    `json:"jwt,omitempty"`
	Saml   map[string]*saml.AuthProvider   `json:"saml,omitempty"`
	// contains filtered or unexported fields
}

GlobalConfiguration represents the global configuration of authentication plugins.

var (
	// Configuration is the global authentication plugin configuration.
	Configuration *GlobalConfiguration
)

func (*GlobalConfiguration) AddProvider

func (c *GlobalConfiguration) AddProvider(ctx caddy.Context, name string, data []byte) error

AddProvider registers an authentication/authorization provider in global authentication configuration.

type Provider

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

Provider is an authentication backend.

func (Provider) MarshalJSON

func (p Provider) MarshalJSON() ([]byte, error)

MarshalJSON packs configuration info JSON byte array

func (*Provider) UnmarshalJSON

func (p *Provider) UnmarshalJSON(inputConfig []byte) error

UnmarshalJSON unpacks configuration into appropriate structures.