auth

Documentation

Overview

Package auth provides request authentication and authorization. By default, there is no auth; all callers and requests are allowed. The Plugin interface allows user-defined auth in combination with user-defined request spec ACLs. See docs/auth.md.

Index

• type ACL
• type AllowAll
  • func (a AllowAll) Authenticate(*http.Request) (Caller, error)
  • func (a AllowAll) Authorize(c Caller, op string, req proto.Request) error
• type Caller
• type Manager
  • func NewManager(plugin Plugin, acls map[string][]ACL, adminRoles []string, strict bool) Manager
  • func (m Manager) Authenticate(req *http.Request) (Caller, error)
  • func (m Manager) Authorize(caller Caller, op string, req proto.Request) error
• type Plugin

Types

type ACL

type ACL struct {
	// User-defined role. This must exactly match a Caller role for the ACL
	// to match.
	Role string

	// Role grants admin access (all ops) to request. Mutually exclusive with Ops.
	Admin bool

	// Ops granted to this role. Mutually exclusive with Admin.
	Ops []string
}

ACL represents one role-based ACL entry. This ACL is the same as spec.ACL. The latter is mapped to the former in Server.Boot to keep the two packages decoupled, i.e. decouple spec syntax from internal data structures.

type AllowAll

type AllowAll struct{}

AllowAll is the default Plugin which allows all callers and requests (no auth).

func (AllowAll) Authenticate

func (a AllowAll) Authenticate(*http.Request) (Caller, error)

Authenticate returns a zero value Caller and nil (allow).

func (AllowAll) Authorize

func (a AllowAll) Authorize(c Caller, op string, req proto.Request) error

Authorize returns nil (allow).

type Caller

type Caller struct {
	// Name of the caller, whether human (username) or machine (app name). The
	// name is user-defined and only used by Spin Cycle for logging and setting
	// proto.Request.User.
	Name string

	// Roles are user-defined role names, like "admin" or "engineer". Rolls
	// are matched against request ACL roles in specs, which are also user-defined.
	// Roles are case-sensitive and not modified by Spin Cycle in any way.
	Roles []string
}

Caller represents an HTTP client making a request. Callers are determined by the Plugin Authenticate method. The default Plugin (AllowAll) returns a zero value Caller.

type Manager

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

Manager uses a Plugin to authenticate and authorize. It handles all auth-related code and config: user-defined Plugin (or default: AllowAll), request ACLs from specs, and options from the config file. Other components use a Manager, not the Plugin directly.

func NewManager

func NewManager(plugin Plugin, acls map[string][]ACL, adminRoles []string, strict bool) Manager

func (Manager) Authenticate

func (m Manager) Authenticate(req *http.Request) (Caller, error)

Authenticate wraps the plugin Authenticate method. Unlike Authorize, there is no extra logic.

func (Manager) Authorize

func (m Manager) Authorize(caller Caller, op string, req proto.Request) error

Authorize authorizes the request based on its ACLs, if any. If the Caller has an admin role, it is allowed immediately (no further checks). Else, Caller roles are matched to request ACL roles. On match, the op is matched to the request ACL ops. On match again, the Plugin Authorize method is called for post-authorization. If it returns nil, the request is allowed.

If the request has no ACLs and the caller does not have an admin role, strict mode determines the result: allow if disabled (no ACLs = allow all), deny if enabled (no ACLs = deny all non-admins).

Any return error denies the request (HTTP 401), and the error message explains why.

type Plugin

type Plugin interface {
	// Authenticate caller from HTTP request. If allowed, return a Caller and nil.
	// Access is denied (HTTP 401) on any error.
	//
	// The returned Caller is user-defined. The most important field is Roles
	// which will be matched against request ACL roles from the specs.
	Authenticate(*http.Request) (Caller, error)

	// Authorize caller to do op for the request. If allowed, return nil.
	// Access is denied (HTTP 401) on any error.
	//
	// This method is post-authorization. Pre-authorization happens automatically
	// by Spin Cycle: it matches a caller role and op to a request ACL role and op.
	// On match, it calls this method. Therefore, when this method is called,
	// it is guaranteed that the caller is authorized for the request and op based
	// on the request ACLs. This method can do further authorization based on
	// the request. For example, if request "stop-host" has arg "hostname", a
	// user-defined Plugin can limit callers to stopping only hosts they own by
	// inspecting the "hostname" arg in the request.
	Authorize(c Caller, op string, req proto.Request) error
}

Plugin represents the auth plugin. Every request is authenticated and authorized. The default Plugin (AllowAll) allows everything: all callers, requests, and ops.

To enable user-defined auth, set App.Context.Plugins.Auth. See docs/customize.md.