authn

package
v2.0.0-alpha.3 Latest Latest
Warning

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

 Go to latest Published: Apr 7, 2021 License: Apache-2.0 Imports: 11 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 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 OAuth2Helper 

type OAuth2Helper interface {
	// AuthCodeURL given an OAuth 2 state code and oauth2.AuthCodeOption returns
	// the URL that a user may visit with their web browser in order to complete
	// authentication using OpenID Connect.
	AuthCodeURL(
		state string,
		opts ...oauth2.AuthCodeOption,
	) string
	// Exchange exchanges the given OAuth 2 code for an *oauth2.Token.
	Exchange(
		ctx context.Context,
		code string,
		opts ...oauth2.AuthCodeOption,
	) (*oauth2.Token, error)
}

OAuth2Helper is an interface for the subset of *oauth2.Config functions used for Brigade Session management. Dependence on this interface instead of directly upon the *oauth2.Config allows for the possibility of utilizing a mock implementation for testing purposes. Adding only the subset of functions that we actually use limits the effort involved in creating such mocks.

type OIDCAuthDetails 

type OIDCAuthDetails struct {
	// AuthURL is a URL that can be requested in a user's web browser to complete
	// authentication via a third-party OIDC 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 OIDC 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"`
}

OIDCAuthDetails encapsulates all information required for a client authenticating by means of OpenID Connect to complete the authentication process using a third-party identity provider.

func (OIDCAuthDetails) MarshalJSON 

func (o OIDCAuthDetails) MarshalJSON() ([]byte, error)

MarshalJSON amends OIDCAuthDetails instances with type metadata.

type OpenIDConnectTokenVerifier 

type OpenIDConnectTokenVerifier interface {
	Verify(ctx context.Context, rawIDToken string) (*oidc.IDToken, error)
}

OpenIDConnectTokenVerifier is an interface for the subset of *oidc.IDTokenVerifier used for Brigade Session management. Dependence on this interface instead of directly upon the *oidc.IDTokenVerifier allows for the possibility of utilizing a mock implementation for testing purposes. Adding only the subset of functions that we actually use limits the effort involved in creating such mocks.

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 OpenID Connect.
	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"`
}

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.

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 an OpenID
	// Connect authentication workflow (if authentication using OpenID connect has
	// been enabled by the system administrator). It returns an OIDCAuthDetails
	// containing all information required to continue the authentication process
	// with a third-party OIDC identity provider. If authentication using OpenID
	// Connect is not enabled, implementations MUST return a *meta.ErrNotSupported
	// error.
	CreateUserSession(context.Context) (OIDCAuthDetails, error)
	// Authenticate completes the final steps of the OpenID Connect authentication
	// workflow (if authentication using OpenID connect has been enabled by the
	// system administrator). It uses the provided oauth2State to identify an
	// as-yet anonymous Session (with an as-yet unactivated token). It
	// communicates with the third-party OIDC identity provider, exchanging the
	// provided oidcCode 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 read-only permissions) based on information provided by the identity
	// provider. Finally, the Session's token is activated. If authentication
	// using OpenID Connect is not enabled, implementations MUST return a
	// *meta.ErrNotSupported error.
	Authenticate(
		ctx context.Context,
		oauth2State string,
		oidcCode 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,
	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
	// OpenIDConnectEnabled indicates whether the Session service should permit
	// User authentication via OpenID Connect.
	OpenIDConnectEnabled 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
	// OAuth2Helper provides authentication-related functions configured for a
	// specific OpenID Connect identity provider. This field is applicable only
	// when value of the OpenIDConnectEnabled field is true.
	OAuth2Helper OAuth2Helper
	// OpenIDConnectTokenVerifier provides an OpenID Connect token verifier. This
	// field is applicable only when value of the OpenIDConnectEnabled field is
	// true.
	OpenIDConnectTokenVerifier OpenIDConnectTokenVerifier
}

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 the OpenID Connect
	// authentication workflow. 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 the
	// OpenID Connect authentication workflow.
	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 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.