authc

Documentation

Index

• Variables
• type AuthenticationInfo
  • func NewAuthenticationInfo() *AuthenticationInfo
  • func (a *AuthenticationInfo) Merge(oa *AuthenticationInfo) *AuthenticationInfo
  • func (a *AuthenticationInfo) PrimaryPrincipal() *Principal
  • func (a *AuthenticationInfo) Principal(claim string) *Principal
  • func (a AuthenticationInfo) String() string
• type AuthenticationToken
  • func (a AuthenticationToken) String() string
• type Authenticator
• type Principal
  • func (p Principal) String() string
• type PrincipalProvider

Variables

var (
	// ErrAuthenticatorIsNil error is returned when given authenticator is nil.
	ErrAuthenticatorIsNil = errors.New("security/authc: authenticator is nil")

	//ErrPrincipalIsNil error is returned when given principal provider is nil.
	ErrPrincipalIsNil = errors.New("security/authc: principal provider is nil")

	// ErrAuthenticationFailed error is returned when user authentication fails;
	// such as subject password doesn't match, is-locked or is-expired.
	ErrAuthenticationFailed = errors.New("security/authc: authentication failed")

	// ErrSubjectNotExists error is returned when Subject is not exists in the application
	// datasource.
	ErrSubjectNotExists = errors.New("security/authc: subject not exists")
)

Types

type AuthenticationInfo

type AuthenticationInfo struct {
	Credential []byte
	IsLocked   bool
	IsExpired  bool
	Principals []*Principal
}

AuthenticationInfo represents a Subject's (aka user's) stored account information relevant to the authentication/log-in process only.

It is important to understand the difference between this interface and the AuthenticationToken struct. AuthenticationInfo implementations represent already-verified and stored account data, whereas an AuthenticationToken represents data submitted for any given login attempt (which may or may not successfully match the verified and stored account AuthenticationInfo).

Because the act of authentication (log-in) is orthogonal to authorization (access control), this struct is intended to represent only the account data needed by aah framework during an authentication attempt. aah framework also has a parallel AuthorizationInfo struct for use during the authorization process that references access control data such as roles and permissions.

func NewAuthenticationInfo

func NewAuthenticationInfo() *AuthenticationInfo

NewAuthenticationInfo method creates an `AuthenticationInfo` instance with zero values. Then using this instance you fill-in user credential, principals, locked, expried information.

func (*AuthenticationInfo) Merge

func (a *AuthenticationInfo) Merge(oa *AuthenticationInfo) *AuthenticationInfo

Merge method merges the given authentication information into existing `AuthenticationInfo` instance. IsExpired and IsLocked values considered as latest from the given object.

func (*AuthenticationInfo) PrimaryPrincipal

func (a *AuthenticationInfo) PrimaryPrincipal() *Principal

PrimaryPrincipal method returns the primary Principal instance if principal object has `IsPrimary` as true otherwise nil.

Typically one principal is required for the subject aka user.

func (*AuthenticationInfo) Principal

func (a *AuthenticationInfo) Principal(claim string) *Principal

Principal method returns the principal that matches given Claim.

For e.g:
	value := AuthenticationInfo.Principal("Email")

func (AuthenticationInfo) String

func (a AuthenticationInfo) String() string

String method is stringer interface implementation.

type AuthenticationToken

type AuthenticationToken struct {
	// Scheme denotes the authentication scheme. It is derived value.
	// For e.g.: form, basic, api, etc.
	Scheme string

	// Identity is an account username or principal or token.
	Identity string

	// Credential is an account or subject secret.
	Credential string
}

AuthenticationToken is an account's principals and supporting credentials submitted by a user during an authentication attempt.

The auth token is submitted to an Authenticator via the GetAuthenticationInfo(authToken) method to get `AuthenticationInfo` for the the authentication/log-in process.

Common implementations of an AuthenticationToken would have username/password pairs, auth token, or anything else you can think of.

func (AuthenticationToken) String

func (a AuthenticationToken) String() string

String method is stringer interface implementation.

type Authenticator

type Authenticator interface {
	// Init method gets called by aah during an application start.
	Init(appCfg *config.Config) error

	// GetAuthenticationInfo method called by auth scheme to get subject's authentication
	// info for given authentication token.
	GetAuthenticationInfo(authcToken *AuthenticationToken) (*AuthenticationInfo, error)
}

Authenticator interface is used to provide authentication information of application during a login.

type Principal

type Principal struct {
	Realm     string
	Claim     string
	Value     string
	IsPrimary bool
}

Principal struct holds the principal associated with a corresponding Subject. A principal is just a security term for an identifying attribute, such as a username or user id or social security number or anything else that can be considered an 'identifying' attribute for a Subject.

func (Principal) String

func (p Principal) String() string

String method is stringer interface implementation.

type PrincipalProvider

type PrincipalProvider interface {
	// Init method gets called by aah during an application start.
	Init(appCfg *config.Config) error

	// Principal method called by auth scheme to get Principals.
	//
	// 	For e.g: keyName is the auth scheme configuration KeyName.
	// 		 security.auth_schemes.<keyname>
	Principal(keyName string, v ess.Valuer) ([]*Principal, error)
}

PrincipalProvider interface is implemented to provide Subject's principals where authentication is done third party, for e.g. OAuth2, etc.