authn

package
v2.0.0-alpha.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 1, 2021 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const ServiceAccountKind = "ServiceAccount"

ServiceAccountKind represents the canonical Service Account kind string

View Source 
const SessionKind = "Session"

SessionKind represents the canonical Session kind string

View Source 
const UserKind = "User"

UserKind represents the canonical User kind string

Variables

This section is empty.

Functions

func ContextWithSessionID 

func ContextWithSessionID(
	ctx context.Context,
	sessionID string,
) context.Context

ContextWithSessionID returns a context.Context that has been augmented with the provided Session identifier.

func SessionIDFromContext 

func SessionIDFromContext(ctx context.Context) string

SessionIDFromContext extracts a Session identifier from the provided context.Context and returns it.

Types

type MockServiceAccountStore 

type MockServiceAccountStore struct {
	CreateFn func(context.Context, ServiceAccount) error
	ListFn   func(
		context.Context,
		meta.ListOptions,
	) (ServiceAccountList, error)
	GetFn              func(context.Context, string) (ServiceAccount, error)
	GetByHashedTokenFn func(context.Context, string) (ServiceAccount, error)
	LockFn             func(context.Context, string) error
	UnlockFn           func(
		ctx context.Context,
		id string,
		newHashedToken string,
	) error
}

func (*MockServiceAccountStore) Create 

func (m *MockServiceAccountStore) Create(
	ctx context.Context,
	serviceAccount ServiceAccount,
) error

func (*MockServiceAccountStore) Get 

func (m *MockServiceAccountStore) Get(
	ctx context.Context,
	id string,
) (ServiceAccount, error)

func (*MockServiceAccountStore) GetByHashedToken 

func (m *MockServiceAccountStore) GetByHashedToken(
	ctx context.Context,
	token string,
) (ServiceAccount, error)

func (*MockServiceAccountStore) List 

func (m *MockServiceAccountStore) List(
	ctx context.Context,
	opts meta.ListOptions,
) (ServiceAccountList, error)

func (*MockServiceAccountStore) Lock 

func (m *MockServiceAccountStore) Lock(ctx context.Context, id string) error

func (*MockServiceAccountStore) Unlock 

func (m *MockServiceAccountStore) Unlock(
	ctx context.Context,
	id string,
	newHashedToken string,
) error

type MockThirdPartyAuthHelper 

type MockThirdPartyAuthHelper struct {
	AuthURLFn  func(oauth2State string) string
	ExchangeFn func(
		ctx context.Context,
		oauth2State string,
		oauth2Code string,
	) (ThirdPartyIdentity, error)
}

func (*MockThirdPartyAuthHelper) AuthURL 

func (m *MockThirdPartyAuthHelper) AuthURL(oauth2State string) string

func (*MockThirdPartyAuthHelper) Exchange 

func (m *MockThirdPartyAuthHelper) Exchange(
	ctx context.Context,
	oauth2State string,
	oauth2Code string,
) (ThirdPartyIdentity, error)

type MockUsersStore 

type MockUsersStore struct {
	CreateFn func(context.Context, User) error
	ListFn   func(context.Context, meta.ListOptions) (UserList, error)
	GetFn    func(context.Context, string) (User, error)
	LockFn   func(context.Context, string) error
	UnlockFn func(context.Context, string) error
}

func (*MockUsersStore) Create 

func (m *MockUsersStore) Create(ctx context.Context, user User) error

func (*MockUsersStore) Get 

func (m *MockUsersStore) Get(ctx context.Context, id string) (User, error)

func (*MockUsersStore) List 

func (m *MockUsersStore) List(
	ctx context.Context,
	opts meta.ListOptions,
) (UserList, error)

func (*MockUsersStore) Lock 

func (m *MockUsersStore) Lock(ctx context.Context, id string) error

func (*MockUsersStore) Unlock 

func (m *MockUsersStore) Unlock(ctx context.Context, id string) error

type ServiceAccount 

type ServiceAccount struct {
	// ObjectMeta encapsulates ServiceAccount metadata.
	meta.ObjectMeta `json:"metadata" bson:",inline"`
	// Description is a natural language description of the ServiceAccount's
	// purpose.
	Description string `json:"description" bson:"description"`
	// HashedToken is a secure, one-way hash of the ServiceAccount's token.
	HashedToken string `json:"-" bson:"hashedToken"`
	// Locked indicates when the ServiceAccount has been locked out of the system
	// by an administrator. If this field's value is nil, the ServiceAccount is
	// not locked.
	Locked *time.Time `json:"locked,omitempty" bson:"locked"`
}

ServiceAccount represents a non-human Brigade user, such as an Event gateway.

func (ServiceAccount) MarshalJSON 

func (s ServiceAccount) MarshalJSON() ([]byte, error)

MarshalJSON amends ServiceAccount instances with type metadata.

type ServiceAccountList 

type ServiceAccountList struct {
	// ListMeta contains list metadata.
	meta.ListMeta `json:"metadata"`
	// Items is a slice of ServiceAccounts.
	Items []ServiceAccount `json:"items,omitempty"`
}

ServiceAccountList is an ordered and pageable list of ServiceAccounts.

func (ServiceAccountList) MarshalJSON 

func (s ServiceAccountList) MarshalJSON() ([]byte, error)

MarshalJSON amends ServiceAccountList instances with type metadata.

type ServiceAccountsService 

type ServiceAccountsService interface {
	// Create creates a new ServiceAccount. If a ServiceAccount having the same ID
	// already exists, implementations MUST return a *meta.ErrConflict error.
	Create(context.Context, ServiceAccount) (Token, error)
	// List retrieves a ServiceAccountList.
	List(context.Context, meta.ListOptions) (ServiceAccountList, error)
	// Get retrieves a single ServiceAccount specified by its identifier. If the
	// specified ServiceAccount does not exist, implementations MUST return a
	// *meta.ErrNotFound error.
	Get(context.Context, string) (ServiceAccount, error)
	// GetByToken retrieves a single ServiceAccount specified by token. If no
	// such ServiceAccount exists, implementations MUST return a *meta.ErrNotFound
	// error.
	GetByToken(context.Context, string) (ServiceAccount, error)

	// Lock revokes system access for a single ServiceAccount specified by its
	// identifier. If the specified ServiceAccount does not exist, implementations
	// MUST return a *meta.ErrNotFound error.
	Lock(context.Context, string) error
	// Unlock restores system access for a single ServiceAccount (after presumably
	// having been revoked) specified by its identifier. It returns a new Token.
	// If the specified ServiceAccount does not exist, implementations MUST return
	// a *meta.ErrNotFound error.
	Unlock(context.Context, string) (Token, error)
}

ServiceAccountsService is the specialized interface for managing ServiceAccounts. It's decoupled from underlying technology choices (e.g. data store) to keep business logic reusable and consistent while the underlying tech stack remains free to change.

func NewServiceAccountsService 

func NewServiceAccountsService(
	authorizeFn libAuthz.AuthorizeFn,
	store ServiceAccountsStore,
) ServiceAccountsService

NewServiceAccountsService returns a specialized interface for managing ServiceAccounts.

type ServiceAccountsStore 

type ServiceAccountsStore interface {
	// Create persists a new ServiceAccount in the underlying data store. If a
	// ServiceAccount having the same ID already exists, implementations MUST
	// return a *meta.ErrConflict error.
	Create(context.Context, ServiceAccount) error
	// List retrieves a ServiceAccountList from the underlying data store, with
	// its Items (ServiceAccounts) ordered by ID.
	List(context.Context, meta.ListOptions) (ServiceAccountList, error)
	// Get retrieves a single ServiceAccount from the underlying data store. If
	// the specified ServiceAccount does not exist, implementations MUST return
	// a *meta.ErrNotFound error.
	Get(context.Context, string) (ServiceAccount, error)
	// GetByHashedToken retrieves a single ServiceAccount having the provided
	// hashed token from the underlying data store. If no such ServiceAccount
	// exists, implementations MUST return a *meta.ErrNotFound error.
	GetByHashedToken(context.Context, string) (ServiceAccount, error)

	// Lock updates the specified ServiceAccount in the underlying data store to
	// reflect that it has been locked out of the system. If the specified
	// ServiceAccount does not exist, implementations MUST return a
	// *meta.ErrNotFound error.
	Lock(context.Context, string) error
	// Unlock updates the specified ServiceAccount in the underlying data store to
	// reflect that it's system access (after presumably having been revoked) has
	// been restored. A hashed token must be provided as a replacement for the
	// existing token. If the specified ServiceAccount does not exist,
	// implementations MUST return a *meta.ErrNotFound error.
	Unlock(ctx context.Context, id string, newHashedToken string) error
}

ServiceAccountsStore is an interface for components that implement ServiceAccount persistence concerns.

type Session 

type Session struct {
	// ObjectMeta encapsulates Session metadata.
	meta.ObjectMeta `json:"metadata" bson:",inline"`
	// Root indicates whether the Session belongs to the root user (true) or a
	// some discrete User.
	Root bool `json:"root" bson:"root"`
	// UserID, if set, identifies the discrete User to whom this Session belongs.
	UserID string `json:"userID" bson:"userID"`
	// HashedOAuth2State, if set, is a secure hash of the OAuth 2 "state" code
	// used in completing authentication via a third-party identity provider.
	HashedOAuth2State string `json:"-" bson:"hashedOAuth2State"`
	// HashedToken is a secure hash of the opaque bearer token associated with
	// this Session.
	HashedToken string `json:"-" bson:"hashedToken"`
	// Authenticated indicates the date/time at which authentication was completed
	// successfully. If the value of this field is nil, the Session is NOT
	// authenticated.
	Authenticated *time.Time `json:"authenticated" bson:"authenticated"`
	// Expires, if set, specified an expiry date/time for the Session and its
	// associated token.
	Expires *time.Time `json:"expires" bson:"expires"`
	// AuthSuccessURL indicates a URL to redirect the User to after successful
	// completion of a third-party authentication workflow. If not specified, a
	// default URL is used.
	AuthSuccessURL string `json:"authSuccessURL" bson:"authSuccessURL"`
}

Session encapsulates details of a session belonging either to the root user or a discrete User that has authenticated (or is in the process of authenticating) via OpenID Connect or GitHub.

type SessionsService 

type SessionsService interface {
	// CreateRootSession creates a Session for the root user (if enabled by the
	// system administrator) and returns a Token with a short expiry period
	// (determined by a system administrator). If authentication as the root user
	// is not enabled, implementations MUST return a *meta.ErrNotSupported error.
	// If the specified username is not "root" or the specified password is
	// incorrect, implementations MUST return a *meta.ErrAuthentication error.
	CreateRootSession(
		ctx context.Context,
		username string,
		password string,
	) (Token, error)
	// CreateUserSession creates a new User Session and initiates a third-party
	// authentication workflow (if enabled by the system administrator). It
	// returns ThirdPartyAuthDetails containing all information required to
	// continue the authentication process with the third-party identity provider.
	// If authentication using a third-party is not enabled, implementations MUST
	// return a *meta.ErrNotSupported error.
	CreateUserSession(
		context.Context,
		*ThirdPartyAuthOptions,
	) (ThirdPartyAuthDetails, error)
	// Authenticate completes the final steps of the third-party authentication
	// workflow (if enabled by the system administrator) and returns a URL to
	// which the user may be redirected. It uses the provided state to identify an
	// as-yet anonymous Session (with an as-yet unactivated token). It
	// communicates with the third-party identity provider, exchanging the
	// provided code for user information. This information can be used to
	// correlate the as-yet anonymous Session to an existing User. If the User is
	// previously unknown to Brigade, implementations MUST seamlessly create one
	// (with no initial permissions) based on information provided by the identity
	// provider. Finally, the Session's token is activated. If authentication
	// using a third-party is not enabled, implementations MUST return a
	// *meta.ErrNotSupported error.
	Authenticate(ctx context.Context, state string, code string) (string, error)
	// GetByToken retrieves the Session having the provided token. If no such
	// Session is found or is found but is expired, implementations MUST return a
	// *meta.ErrAuthentication error.
	GetByToken(ctx context.Context, token string) (Session, error)
	// Delete deletes the specified Session.
	Delete(ctx context.Context, id string) error
}

SessionsService is the specialized interface for managing Sessions. It's decoupled from underlying technology choices (e.g. data store) to keep business logic reusable and consistent while the underlying tech stack remains free to change.

func NewSessionsService 

func NewSessionsService(
	sessionsStore SessionsStore,
	usersStore UsersStore,
	grantRoleFn func(context.Context, libAuthz.RoleAssignment) error,
	thirdPartyAuthHelper ThirdPartyAuthHelper,
	config *SessionsServiceConfig,
) SessionsService

NewSessionsService returns a specialized interface for managing Sessions.

type SessionsServiceConfig 

type SessionsServiceConfig struct {
	// RootUserEnabled indicates whether the Session service should permit the
	// "root" user to authenticate using a password.
	RootUserEnabled bool
	// RootUserSessionTTL specifies the TTL for the root user session. This value
	// will be used to set the Expires field on the Session record for the root
	// user.
	RootUserSessionTTL time.Duration
	// RootUserPassword specifies the password that must be supplied by users
	// attempting to authenticate as the "root" user. This field is applicable
	// only when value of the RootUserEnabled field is true.
	RootUserPassword string
	// ThirdPartyAuthEnabled indicates whether authentication using a third-party
	// identity provider is supported by the Sessions service.
	ThirdPartyAuthEnabled bool
	// UserSessionTTL specifies the TTL for user sessions. This value will be
	// used to set the Expires field on the Session record for each user.
	UserSessionTTL time.Duration
	// AdminUserIDs enumerates users who should be granted system admin privileges
	// the first time they log in.
	AdminUserIDs []string
}

SessionsServiceConfig encapsulates several configuration options for the Sessions service.

type SessionsStore 

type SessionsStore interface {
	// Create stores the provided Session. Implementations MUST return an error if
	// a Session having the indicated identifier already exists.
	Create(context.Context, Session) error
	// GetByHashedOAuth2State returns a Session having the indicated secure hash
	// of the OAuth 2 "state" code. This is used in completing both OpenID Connect
	// and GitHub authentication workflows. If no such Session exists,
	// implementations MUST return a *meta.ErrNotFound error.
	GetByHashedOAuth2State(context.Context, string) (Session, error)
	// GetByHashedToken returns a Session having the indicated secure hash of the
	// opaque bearer token. If no such Session exists, implementations MUST
	// return a *meta.ErrNotFound error.
	GetByHashedToken(context.Context, string) (Session, error)
	// Authenticate updates the specified, as-yet-anonymous Session (with an
	// as-yet unactivated token) to denote ownership by the indicated User and to
	// assign the specified expiry date/time. This is used in completing
	// third-party authentication workflows.
	Authenticate(
		ctx context.Context,
		sessionID string,
		userID string,
		expires time.Time,
	) error
	// Delete deletes the specified Session. If no Session having the given
	// identifier is found, implementations MUST return a *meta.ErrNotFound error.
	Delete(context.Context, string) error
	// DeleteByUser deletes all sessions belonging to the specified User.
	DeleteByUser(ctx context.Context, userID string) error
}

SessionsStore is an interface for Session persistence operations.

type ThirdPartyAuthDetails 

type ThirdPartyAuthDetails struct {
	// AuthURL is a URL that can be requested in a user's web browser to complete
	// authentication via a third-party identity provider.
	AuthURL string `json:"authURL"`
	// Token is an opaque bearer token issued by Brigade to correlate a User with
	// a Session. It remains unactivated (useless) until the authentication
	// workflow is successfully completed. Clients may expect that that the token
	// expires (at an interval determined by a system administrator) and, for
	// simplicity, is NOT refreshable. When the token has expired,
	// re-authentication is required.
	Token string `json:"token"`
}

ThirdPartyAuthDetails encapsulates all information required for a client authenticating by means of a third-party identity provider to complete the authentication workflow.

func (ThirdPartyAuthDetails) MarshalJSON 

func (t ThirdPartyAuthDetails) MarshalJSON() ([]byte, error)

MarshalJSON amends ThirdPartyAuthDetails instances with type metadata.

type ThirdPartyAuthHelper 

type ThirdPartyAuthHelper interface {
	// AuthURL returns a URL to which a User may be redirected for purposes of
	// completing authentication using a third-party identity provider.
	AuthURL(oauth2State string) string
	// Exchange exchanges a code issued by a third-party identity provider for
	// User identity information.
	Exchange(
		ctx context.Context,
		oauth2State string,
		oauth2Code string,
	) (ThirdPartyIdentity, error)
}

ThirdPartyAuthHelper is an interface for components that implement pluggable portions of third party authentication schemes based on OAuth2. OpenID Connect (used by certain identity providers like Azure Active Directory or Google Cloud Identity Platform) is built on top of OAuth2 (strictly speaking OAuth2 is for authorization; not authentication, but OpenID Connect extends OAuth2 with an authentication standard), but other authentication schemes (like GitHub's) are ALSO based on OAuth2, but DON'T implement OpenID Connect. This interface allows universal parts of authentication based on OAuth2 to be common for all third-party identity providers while utilizing standard-specific or provider-specific functionality for the portions of those authentication schemes that vary.

type ThirdPartyAuthOptions 

type ThirdPartyAuthOptions struct {
	// SuccessURL indicates where users should be redirected to after successful
	// completion of a third-party authentication workflow. If this is left
	// unspecified, users will be redirected to a default success page.
	SuccessURL string
}

ThirdPartyAuthOptions encapsulates user-specified options when creating a new Session that will authenticate using a third-party identity provider.

type ThirdPartyAuthStrategy 

type ThirdPartyAuthStrategy string

type ThirdPartyIdentity 

type ThirdPartyIdentity struct {
	// ID is a handle or email address for the User.
	ID string
	// Name is the User's given name + surname.
	Name string
}

ThirdPartyIdentity encapsulates ID (handle or email address) and name information for a User obtained from a third-party identity provider.

type Token 

type Token struct {
	Value string `json:"value" bson:"value"`
}

Token represents an opaque bearer token used to authenticate to the Brigade API.

func (Token) MarshalJSON 

func (t Token) MarshalJSON() ([]byte, error)

MarshalJSON amends Token instances with type metadata.

type User 

type User struct {
	// ObjectMeta encapsulates User metadata.
	meta.ObjectMeta `json:"metadata" bson:",inline"`
	// Name is the given name and surname of the User.
	Name string `json:"name" bson:"name"`
	// Locked indicates when the User has been locked out of the system by an
	// administrator. If this field's value is nil, the User is not locked.
	Locked *time.Time `json:"locked" bson:"locked"`
}

User represents a (human) Brigade user.

func (User) MarshalJSON 

func (u User) MarshalJSON() ([]byte, error)

MarshalJSON amends User instances with type metadata.

type UserList 

type UserList struct {
	// ListMeta contains list metadata.
	meta.ListMeta `json:"metadata"`
	// Items is a slice of Users.
	Items []User `json:"items,omitempty"`
}

UserList is an ordered and pageable list of Users.

func (UserList) MarshalJSON 

func (u UserList) MarshalJSON() ([]byte, error)

MarshalJSON amends UserList instances with type metadata.

type UsersService 

type UsersService interface {
	// List returns a UserList.
	List(context.Context, meta.ListOptions) (UserList, error)
	// Get retrieves a single User specified by their identifier.
	Get(context.Context, string) (User, error)

	// Lock removes access to the API for a single User specified by their
	// identifier.
	Lock(context.Context, string) error
	// Unlock restores access to the API for a single User specified by their
	// identifier.
	Unlock(context.Context, string) error
}

UsersService is the specialized interface for managing Users. It's decoupled from underlying technology choices (e.g. data store) to keep business logic reusable and consistent while the underlying tech stack remains free to change.

func NewUsersService 

func NewUsersService(
	authorizeFn libAuthz.AuthorizeFn,
	usersStore UsersStore,
	sessionsStore SessionsStore,
) UsersService

NewUsersService returns a specialized interface for managing Users.

type UsersStore 

type UsersStore interface {
	// Create persists a new User in the underlying data store. If a User having
	// the same ID already exists, implementations MUST return a *meta.ErrConflict
	// error.
	Create(context.Context, User) error
	// List retrieves a UserList from the underlying data store, with its Items
	// (Users) ordered by ID.
	List(context.Context, meta.ListOptions) (UserList, error)
	// Get retrieves a single User from the underlying data store. Implementations
	// MUST use a case insensitive query for this operation. If the specified User
	// does not exist, implementations MUST return a *meta.ErrNotFound error.
	Get(context.Context, string) (User, error)

	// Lock updates the specified User in the underlying data store to reflect
	// that it has been locked out of the system. Implementations MUST use a case
	// insensitive update statement for this operation. If the specified User does
	// not exist, implementations MUST return a *meta.ErrNotFound error.
	Lock(context.Context, string) error
	// Unlock updates the specified User in the underlying data store to reflect
	// that its system access (after presumably having been revoked) has been
	// restored. Implementations MUST use a case insensitive update statement for
	// this operation. If the specified User does not exist, implementations MUST
	// return a *meta.ErrNotFound error.
	Unlock(ctx context.Context, id string) error
}

UsersStore is an interface for User persistence operations.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.