auth

Documentation

Overview

Package auth provides interfaces and types required for implementing an authenticaor.

Index

• type AuthHandler
• type Duration
  • func (d *Duration) UnmarshalJSON(b []byte) error
• type Feature
  • func (f Feature) MarshalJSON() ([]byte, error)
  • func (f Feature) MarshalText() ([]byte, error)
  • func (f Feature) String() string
  • func (f *Feature) UnmarshalJSON(b []byte) error
  • func (f *Feature) UnmarshalText(b []byte) error
• type Level
  • func ParseAuthLevel(name string) Level
  • func (a Level) MarshalJSON() ([]byte, error)
  • func (a Level) MarshalText() ([]byte, error)
  • func (a Level) String() string
  • func (a *Level) UnmarshalJSON(b []byte) error
  • func (a *Level) UnmarshalText(b []byte) error
• type Rec

Types

type AuthHandler

type AuthHandler interface {
	// Init initializes the handler taking config string and logical name as parameters.
	Init(jsonconf json.RawMessage, name string) error

	// IsInitialized returns true if the handler is initialized.
	IsInitialized() bool

	// AddRecord adds persistent authentication record to the database.
	// Returns: updated auth record, error
	AddRecord(rec *Rec, secret []byte, remoteAddr string) (*Rec, error)

	// UpdateRecord updates existing record with new credentials.
	// Returns updated auth record, error.
	UpdateRecord(rec *Rec, secret []byte, remoteAddr string) (*Rec, error)

	// Authenticate: given a user-provided authentication secret (such as "login:password"), either
	// return user's record (ID, time when the secret expires, etc), or issue a challenge to
	// continue the authentication process to the next step, or return an error code.
	// The remoteAddr (i.e. the IP address of the client) can be used by custom authenticators for
	// additional validation. The stock authenticators don't use it.
	// store.Users.GetAuthRecord("scheme", "unique")
	// Returns: user auth record, challenge, error.
	Authenticate(secret []byte, remoteAddr string) (*Rec, []byte, error)

	// AsTag converts search token into prefixed tag or an empty string if it
	// cannot be represented as a prefixed tag.
	AsTag(token string) string

	// IsUnique verifies if the provided secret can be considered unique by the auth scheme
	// E.g. if login is unique.
	IsUnique(secret []byte, remoteAddr string) (bool, error)

	// GenSecret generates a new secret, if appropriate.
	GenSecret(rec *Rec) ([]byte, time.Time, error)

	// DelRecords deletes (or disables) all authentication records for the given user.
	DelRecords(uid types.Uid) error

	// RestrictedTags returns the tag namespaces (prefixes) which are restricted by this authenticator.
	RestrictedTags() ([]string, error)

	// GetResetParams returns authenticator parameters passed to password reset handler
	// for the provided user id.
	// Returns: map of params.
	GetResetParams(uid types.Uid) (map[string]interface{}, error)

	// GetRealName returns the hardcoded name of the authenticator.
	GetRealName() string
}

AuthHandler is the interface which auth providers must implement.

type Duration

type Duration time.Duration

Duration is identical to time.Duration except it can be sanely unmarshallend from JSON.

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON handles the cases where duration is specified in JSON as a "5000s" string or just plain seconds.

type Feature

type Feature uint16

Feature is a bitmap of authenticated features, such as validated/not validated.

const (
	// FeatureValidated bit is set if user's credentials are already validated (V).
	FeatureValidated Feature = 1 << iota
	// FeatureNoLogin is set if the token should not be used to permanently authenticate a session (L).
	FeatureNoLogin
)

func (Feature) MarshalJSON

func (f Feature) MarshalJSON() ([]byte, error)

MarshalJSON converts Feature to a quoted string.

func (Feature) MarshalText

func (f Feature) MarshalText() ([]byte, error)

MarshalText converts Feature to ASCII byte slice.

func (Feature) String

func (f Feature) String() string

String Featureto a string representation.

func (*Feature) UnmarshalJSON

func (f *Feature) UnmarshalJSON(b []byte) error

UnmarshalJSON reads Feature from a quoted string or an integer.

func (*Feature) UnmarshalText

func (f *Feature) UnmarshalText(b []byte) error

UnmarshalText parses Feature string as byte slice.

type Level

type Level int

Level is the type for authentication levels.

const (
	// LevelNone is undefined/not authenticated
	LevelNone Level = iota * 10
	// LevelAnon is anonymous user/light authentication
	LevelAnon
	// LevelAuth is fully authenticated user
	LevelAuth
	// LevelRoot is a superuser (currently unused)
	LevelRoot
)

Authentication levels

func ParseAuthLevel

func ParseAuthLevel(name string) Level

ParseAuthLevel parses authentication level from a string.

func (Level) MarshalJSON

func (a Level) MarshalJSON() ([]byte, error)

MarshalJSON converts Level to a quoted string.

func (Level) MarshalText

func (a Level) MarshalText() ([]byte, error)

MarshalText converts Level to a slice of bytes with the name of the level.

func (Level) String

func (a Level) String() string

String implements Stringer interface: gets human-readable name for a numeric authentication level.

func (*Level) UnmarshalJSON

func (a *Level) UnmarshalJSON(b []byte) error

UnmarshalJSON reads Level from a quoted string.

func (*Level) UnmarshalText

func (a *Level) UnmarshalText(b []byte) error

UnmarshalText parses authentication level from a string.

type Rec

type Rec struct {
	// User ID.
	Uid types.Uid `json:"uid,omitempty"`
	// Authentication level.
	AuthLevel Level `json:"authlvl,omitempty"`
	// Lifetime of this record.
	Lifetime Duration `json:"lifetime,omitempty"`
	// Bitmap of features. Currently 'validated'/'not validated' only.
	Features Feature `json:"features,omitempty"`
	// Tags generated by this authentication record.
	Tags []string `json:"tags,omitempty"`
	// User account state received or read by the authenticator.
	State types.ObjState

	// Authenticator may request the server to create a new account.
	// These are the account parameters which can be used for creating the account.
	DefAcs  *types.DefaultAccess `json:"defacs,omitempty"`
	Public  interface{}          `json:"public,omitempty"`
	Private interface{}          `json:"private,omitempty"`
}

Rec is an authentication record.