okay: abstract cross-package auth[nz]
okay is a package that allows consumers to pass authentication and authorization checks across package boundaries.
Consumers should start with the base OK, which denies everyone to everything,
and add permissions as required with the Allow, Validate, and Verify
functions.
Overview
Often there is some resource to which we want to restrict access; databases (or columns, or rows), file systems, URL endpoints, or even specific functions or methods.
Say we have a file system type:
package fs
import (
"io"
"os"
"path/filepath"
)
type FileSystem struct {
Root string
}
func (fs FileSystem) Open(path string) (io.ReadCloser, error) {
return os.Open(filepath.Join(fs.Root, path))
}This could be used to e.g. serve the file via HTTP, but it provides no access controls. We could add this by modifying Open to take a Context which contains the appropriate credentials:
import (
"context"
"io"
"os"
"path/filepath"
)
func (fs FileSystem) Open(ctx context.Context, path string) (io.ReadCloser, error) {
// TODO: check context somehow
return os.Open(filepath.Join(fs.Root, path))
}How should we check the context? If we're serving this via HTTP, we could provide simple authentication by wrapping HTTP basic authentication into a context:
package server
import (
"context"
"net/http"
)
type authType string
func getContext(r *http.Request) context.Context {
ctx := r.Context()
if user, pass, ok := r.BasicAuth(); ok {
ctx = context.WithValue(ctx, authType("user"), user)
ctx = context.WithValue(ctx, authType("pass"), pass)
}
return ctx
}
func handleRequest(rw http.ResponseWriter, r *http.Request) {
ctx := getContext(r)
doTheThing(ctx, rw)
}...and then providing a facility to verify that context:
package server
import "context"
func (s *Server) Authenticate(ctx context.Context) (bool, error) {
user, ok := ctx.Value(authType("user")).(string)
if !ok {
return false, nil
}
pass, ok := ctx.Value(authType("pass")).(string)
if !ok {
return false, nil
}
return s.checkCredentials(user, pass)
}Now we know how to check the context and can successfully gate access to our files.
import (
"context"
"fmt"
"io"
"os"
"path/filepath"
"server"
)
type FileSystem struct {
Server server.Server
Root string
}
func (fs *FileSystem) Open(ctx context.Context, path string) (io.ReadCloser, error) {
ok, err := fs.Server.Authenticate(ctx)
if err != nil {
return nil, err
}
if !ok {
return nil, fmt.Errorf("%s: permission denied", path)
}
return os.Open(filepath.Join(fs.Root, path))
}Unfortunately, this very tightly couples packages fs and server. If fs
wants to grant users via another scheme, such as OAuth2, or to certain
administrator users, or in some other way, all the methods which check for
authentication must be updated. It may be that server is not something we
can modify; it may be that fs isn't something we can modify.
This can be fixed by having fs accept OK types:
import (
"context"
"fmt"
"io"
"okay"
"os"
"path/filepath"
)
type FileSystem struct {
Auths []okay.OK
Root string
}
func (fs FileSystem) Open(ctx context.Context, path string) (io.ReadCloser, error) {
ok, err := okay.Check(ctx, path, fs.Auths...)
if err != nil {
return nil, err
}
if !ok {
return nil, fmt.Errorf("%s: permission denied", path)
}
return os.Open(filepath.Join(fs.Root, path))
}Now fs and server are distinct packages coupled only by the OK interface.
FileSystem.Auths can be extended at will by fs or any consumer of fs, and
it will gate the guarded resources appropriately.
Use
Packages using okay should begin with the base type, and add authentication
(Verify()), authorization (Allows()), and validation (Valid()) checks as
needed.
The base type is always valid, and authenticates nobody and authorizes nothing.
Validation
OKs are valid until they are not, and are thereafter never valid. If a
consumer wishes to create an access grant that expires (for example, to allow
access to a file for only 24 hours), they should do so by creating an OK that
expires after that period of time. The okay package has several helper
functions for this:
ok := okay.New()
ok = okay.WithTimeout(ok, 24*time.Hour)Or, for an OK that invalidates itself when a Context expires or is canceled:
ok := okay.New()
ok = okay.WithContext(ok, ctx)However, consumers can implement more sophisticated behavior by implementing their own validation functions:
import (
"os"
"os/signal"
"sync/atomic"
"okay"
)
func SigintCancel() OK {
ch := make(chan os.Signal, 1)
signal.Notify(ch, os.Interrupt)
var v int32
go func() {
<-ch
atomic.StoreInt32(&v, 1)
}()
ok := okay.New()
ok = okay.Validate(ok, func() bool {
return atomic.LoadInt32(&v) == 0
})
return ok
}Authentication
Consumers are expected to provide custom authentication with the Verify()
function.
Here is a simple package that provides token-based authentication:
package authtoken
import (
"context"
"okay"
)
type authToken struct{}
// WithToken returns a context that contains the given auth token.
func WithToken(ctx context.Context, token string) context.Context {
return context.WithValue(ctx, authToken{}, token)
}
// TokenOK returns an OK that verifies the given token.
func TokenOK(ok okay.OK, token string) okay.OK {
return okay.Verify(ok, func(ctx context.Context) (bool, error) {
tok, ok := ctx.Value(authToken{}).(string)
if !ok {
return false, nil
}
return tok == token, nil
})
}Authorization
Authorization is provided via the Allow() function, which allows access to
resources.
The fs package (or consumers of it) might implement the following:
package fs
import (
"strings"
"okay"
)
func AllowFiles(ok okay.OK, file ...string) OK {
check := make(map[string]bool)
for _, f := range file {
check[f] = true
}
return okay.Allow(ok, func(i interface{}) (bool, error) {
f, ok := i.(string)
if !ok {
return false, nil
}
return check[f], nil
})
}
func AllowPrefix(ok okay.OK, pfx string) OK {
return okay.Allow(ok, func(i interface{}) (bool, error) {
f, ok := i.(string)
if !ok {
return false, nil
}
return strings.HasPrefix(f, pfx), nil
})
}
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent