aclstore

README

aclstore: a persistent store for ACLs

This makes it easy for a service to add role-based access controls for a fixed set of roles.

Documentation

Index

• Constants
• Variables
• type ACLLister
• type ACLStore
  • func NewACLStore(kv simplekv.Store) ACLStore
• type HandlerParams
• type Identity
• type Manager
  • func NewManager(ctx context.Context, p Params) (*Manager, error)
  • func (m *Manager) ACL(ctx context.Context, name string) ([]string, error)
  • func (h *Manager) CreateACL(ctx context.Context, name string, initialUsers ...string) error
  • func (m *Manager) NewHandler(p HandlerParams) http.Handler
• type Params

Constants

const AdminACL = "admin"

AdminACL holds the name of the administrator ACL.

const CodeACLNotFound = "ACL not found"

CodeACLNotFound holds the error code returned from the HTTP endpoints when an ACL name has not been created.

Variables

var (
	ErrACLNotFound = errgo.Newf("ACL not found")
	ErrBadUsername = errgo.Newf("bad username")
)

Types

type ACLLister

type ACLLister interface {
	ACLs(ctx context.Context) ([]string, error)
}

ACLLister enables clients to list stored ACLs.

type ACLStore

type ACLStore interface {
	// CreateACL creates an ACL with the given name and initial users.
	// If the ACL already exists, this is a no-op and the initialUsers
	// argument is ignored.
	// It may return an error with an ErrBadUsername if the initial users
	// are not valid.
	CreateACL(ctx context.Context, aclName string, initialUsers []string) error

	// Add adds users to the ACL with the given name.
	// Adding a user that's already in the ACL is a no-op.
	// It returns an error with an ErrACLNotFound cause if the ACL
	// does not exist, or with an ErrBadUsername cause if any
	// of the usernames are not valid.
	Add(ctx context.Context, aclName string, users []string) error

	// Remove removes users from the ACL with the given name.
	// It returns an error with an ErrACLNotFound cause if the ACL
	// does not exist. It returns an error with an ErrUserNotFound
	// cause if any of the users do not exist.
	// TODO should it do nothing in that case?
	Remove(ctx context.Context, aclName string, users []string) error

	// Set sets the users held in the ACL with the given name.
	// It returns an ErrACLNotFound cause if the ACL does not
	// exist, or with an ErrBadUsername cause if any
	// of the usernames are not valid.
	Set(ctx context.Context, aclName string, users []string) error

	// Get returns the users held in the ACL with the given name,
	// sorted lexically. It returns an error with an ErrACLNotFound cause
	// if the ACL does not exist.
	Get(ctx context.Context, aclName string) ([]string, error)
}

ACLStore is the persistent storage interface used by an ACLHandler.

func NewACLStore

func NewACLStore(kv simplekv.Store) ACLStore

NewACLStore returns an ACLStore implementation that uses an underlying key-value store for persistent storage.

type HandlerParams

type HandlerParams struct {
	// RootPath holds the root URL path prefix to use
	// for the ACL endpoints. All the endpoints will be
	// prefixed with this path.
	RootPath string

	// Authenticate authenticates the given HTTP request and returns
	// the resulting authenticated identity. If authentication
	// fails, Authenticate should write its own response and return
	// an error.
	Authenticate func(ctx context.Context, w http.ResponseWriter, req *http.Request) (Identity, error)
}

HandlerParams holds the parameters for a NewHandler call.

type Identity

type Identity interface {
	// Allow reports whether the user should be allowed to access
	// any of the users or groups in the given ACL slice.
	Allow(ctx context.Context, acl []string) (bool, error)
}

Identity represents an authenticated user.

type Manager

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

Manager implements an ACL manager.

func NewManager

func NewManager(ctx context.Context, p Params) (*Manager, error)

NewManager returns a new Manager instance that manages a set of ACLs. It ensures there is at least one ACL created, named "admin", which is given p.InitialAdminUsers when it is first created.

func (*Manager) ACL

func (m *Manager) ACL(ctx context.Context, name string) ([]string, error)

ACL returns the members of the given ACL.

func (*Manager) CreateACL

func (h *Manager) CreateACL(ctx context.Context, name string, initialUsers ...string) error

CreateACL creates an ACL with the given name. It also creates an ACL _name which is the ACL that guards membership of the ACL itself. Any member of _name or any member of the admin ACL may change the membership of ACL name. Only members of the admin ACL may change the membership of _name.

The name itself must not start with an underscore.

This does nothing if an ACL with that name already exists.

func (*Manager) NewHandler

func (m *Manager) NewHandler(p HandlerParams) http.Handler

NewHandler creates an ACL administration interface that allows clients to manipulate the ACLs. The set of ACLs that can be manipulated can be changed with the Manager.CreateACL method.

type Params

type Params struct {
	// Store holds the persistent storage used by the handler.
	Store ACLStore

	// InitialAdminUsers holds the contents of the admin ACL
	// when it is first created.
	InitialAdminUsers []string
}

Params holds the parameters for a NewManager call.