auth

Documentation

Overview

The auth package provides useful authentication library functions for use with REST-ful API requests. In particular, `SetAuthorizationContext` may be used to process incoming requests for authentication and setting up the `Authentiactor` struct on the request Context for downstream access.

Users may be assigned 'claims' which can be treated as simple 'roles' or indicate particular special permissions. In theory, a claim could encode a limited amount of information, but they are inherently limited and for all practical purposes are simple labels. This may be sufficient for some applications, though in general developers are encouraged to use the Liquid Code Authorization (Liquid Azn) framework (TODO: link). Liquid Azn is a flexible grant based system that can be used to setup simple roles, but also provides support for fine-grained, user-driven access/authorization management.

That being said, we provide methods to do basic claims check. The 'HasXXX' methods are informational, returning booleans. The 'RequireXXX' methods instead return an error unless the condition is satisifed. We support 'Any' and 'All' conditions, for a total of four basic metods (HasAnyClaims, HasAllClaims, etc.). 'GetClaims' will provide a list of the claims. Remember, though, if you need more complex checks, consider whether claims are really the best answer.

Index

• Constants
• func SetAuthOracleOnContext(authOracle AuthOracle, ctx context.Context) context.Context
• func SetAuthorizationContext(next http.Handler) http.Handler
• type AuthOracle
  • func GetAuthOracleFromContext(ctx context.Context) AuthOracle
• type Claimant
• type FbAuthOracle
• type FbOracle
  • func (a *FbOracle) GetAuthID() string
  • func (a *FbOracle) GetClaims() []string
  • func (a *FbOracle) GetFirebaseAuthClient() *fbauth.Client
  • func (a *FbOracle) GetRequest() *http.Request
  • func (a *FbOracle) HasAllClaims(req ...string) bool
  • func (a *FbOracle) HasAnyClaim(req ...string) bool
  • func (auth *FbOracle) InitFromRequest(r *http.Request) Terror
  • func (a *FbOracle) IsRequestAuthenticated() bool
  • func (a *FbOracle) RequireAllClaims(req ...string) Terror
  • func (a *FbOracle) RequireAnyClaim(req ...string) Terror
  • func (authOracle *FbOracle) RequireAuthentication() Terror

Constants

const AuthOracleKey authOracleKey = authOracleKey(`lc-authOracle`)

Functions

func SetAuthOracleOnContext

func SetAuthOracleOnContext(authOracle AuthOracle, ctx context.Context) context.Context

func SetAuthorizationContext

func SetAuthorizationContext(next http.Handler) http.Handler

SetAuthorizationContext initializes an AuthOracle and is intended for use as the first or an early member of the rquest processing chain. To use a specific AuthOracle implementation (tied to a specific authentication provider, or for testing), simply place an empty, non-nill struct of the approprite type implementing AuthOracle in the request context using `AuthOracleKey`. If no such stuct is found, we default to the FbOracle.

Types

type AuthOracle

type AuthOracle interface {
	// InitFromRequest initialaizes an authentic from an HTTP request. This is typically called by the HTTP handler SetAuthorizationContext. This method expects an empty, non-nil reciever.
	InitFromRequest(*http.Request) Terror

	// RquireAuthentication creates an appropriate, typed error if the request is not authenticated.
	RequireAuthentication() Terror

	// IsRequestAuthenticated returns true if the request is authenticated, and false otherwise.
	IsRequestAuthenticated() bool

	// GetAuthID returns the authenticated user's authorization ID as maintained by the authentication provider. This is distinct from our own ID.
	GetAuthID() string

	// GetRequest returns the HTTP request which was processed to determine authentication. The request is usually available from the handler, and this is provided as a convenience.
	GetRequest() *http.Request
}

AuthOracle defines the interface for detecting and extracting authentication information from an HTTP request. In live usage, `SetAuthorizationContext` is used to inject an AuthOracle into the request context for use in downstream processing. Downstream handlers can access the AuthOracle via GetAuthOracleFromContext.

func GetAuthOracleFromContext

func GetAuthOracleFromContext(ctx context.Context) AuthOracle

type Claimant

type Claimant interface {
	// HasAllClaims returns true if the authenticated user has all the indicated claims.
	HasAllClaims(claims ...string) bool

	// RequireAllClaims returns a typed error unless the authenticated user has all the indicated claims.
	RequireAllClaims(claims ...string) Terror

	// HasAnyClaim returns true if the authenticated user has any of the indicated claims.
	HasAnyClaim(claims ...string) bool

	// RequireAnyClaim returns a typed error unless the authenticated user has at least on of the indicated claims.
	RequireAnyClaims()

	// GetClaims provides a list of the claims held by the authenticated user. If the user has no claims, or is not authenticated, this will be an empty, non-nil list.
	GetClaims() []string
}

type FbAuthOracle

type FbAuthOracle interface {
	// GetFirebaseAuthClient returns the underlying Firebase authentication/authorization client used to verify tokens and retrieve claims from google.
	GetFirebaseAuthClient() *fbauth.Client
}

type FbOracle

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

func (*FbOracle) GetAuthID

func (a *FbOracle) GetAuthID() string

func (*FbOracle) GetClaims

func (a *FbOracle) GetClaims() []string

func (*FbOracle) GetFirebaseAuthClient

func (a *FbOracle) GetFirebaseAuthClient() *fbauth.Client

func (*FbOracle) GetRequest

func (a *FbOracle) GetRequest() *http.Request

func (*FbOracle) HasAllClaims

func (a *FbOracle) HasAllClaims(req ...string) bool

func (*FbOracle) HasAnyClaim

func (a *FbOracle) HasAnyClaim(req ...string) bool

func (*FbOracle) InitFromRequest

func (auth *FbOracle) InitFromRequest(r *http.Request) Terror

func (*FbOracle) IsRequestAuthenticated

func (a *FbOracle) IsRequestAuthenticated() bool

func (*FbOracle) RequireAllClaims

func (a *FbOracle) RequireAllClaims(req ...string) Terror

func (*FbOracle) RequireAnyClaim

func (a *FbOracle) RequireAnyClaim(req ...string) Terror

func (*FbOracle) RequireAuthentication

func (authOracle *FbOracle) RequireAuthentication() Terror