auth

Documentation

Overview

Package auth implements authentication checks and storage.

Index

• func ExtractAccessToken(req *http.Request) (string, error)
• func GenerateAccessToken() (string, error)
• func LoginFromJSONReader(ctx context.Context, r io.Reader, accountDB AccountDatabase, ...) (*Login, LoginCleanupFunc, *util.JSONResponse)
• func VerifyUserFromRequest(req *http.Request, userAPI api.UserInternalAPI) (*api.Device, *util.JSONResponse)
• type AccountDatabase
• type Challenge
• type DeviceDatabase
• type GetAccountByPassword
• type Login
  • func (r *Login) ThirdPartyID() (medium, address string)
  • func (r *Login) Username() string
• type LoginCleanupFunc
• type LoginIdentifier
• type LoginTypePassword
  • func (t *LoginTypePassword) Login(ctx context.Context, req interface{}) (*Login, *util.JSONResponse)
  • func (t *LoginTypePassword) LoginFromJSON(ctx context.Context, reqBytes []byte) (*Login, LoginCleanupFunc, *util.JSONResponse)
  • func (t *LoginTypePassword) Name() string
• type LoginTypeToken
  • func (t *LoginTypeToken) LoginFromJSON(ctx context.Context, reqBytes []byte) (*Login, LoginCleanupFunc, *util.JSONResponse)
  • func (t *LoginTypeToken) Name() string
• type PasswordRequest
• type Type
• type UserInteractive
  • func NewUserInteractive(accountDB AccountDatabase, cfg *config.ClientAPI) *UserInteractive
  • func (u *UserInteractive) AddCompletedStage(sessionID, authType string)
  • func (u *UserInteractive) Challenge(sessionID string) *util.JSONResponse
  • func (u *UserInteractive) IsSingleStageFlow(authType string) bool
  • func (u *UserInteractive) NewSession() *util.JSONResponse
  • func (u *UserInteractive) ResponseWithChallenge(sessionID string, response interface{}) *util.JSONResponse
  • func (u *UserInteractive) Verify(ctx context.Context, bodyBytes []byte, device *api.Device) (*Login, *util.JSONResponse)
• type UserInternalAPIForLogin

Functions

func ExtractAccessToken

func ExtractAccessToken(req *http.Request) (string, error)

ExtractAccessToken from a request, or return an error detailing what went wrong. The error message MUST be human-readable and comprehensible to the client.

func GenerateAccessToken

func GenerateAccessToken() (string, error)

GenerateAccessToken creates a new access token. Returns an error if failed to generate random bytes.

func LoginFromJSONReader

func LoginFromJSONReader(ctx context.Context, r io.Reader, accountDB AccountDatabase, userAPI UserInternalAPIForLogin, cfg *config.ClientAPI) (*Login, LoginCleanupFunc, *util.JSONResponse)

LoginFromJSONReader performs authentication given a login request body reader and some context. It returns the basic login information and a cleanup function to be called after authorization has completed, with the result of the authorization. If the final return value is non-nil, an error occurred and the cleanup function is nil.

func VerifyUserFromRequest

func VerifyUserFromRequest(
	req *http.Request, userAPI api.UserInternalAPI,
) (*api.Device, *util.JSONResponse)

VerifyUserFromRequest authenticates the HTTP request, on success returns Device of the requester. Finds local user or an application service user. Note: For an AS user, AS dummy device is returned. On failure returns an JSON error response which can be sent to the client.

Types

type AccountDatabase

type AccountDatabase interface {
	// Look up the account matching the given localpart.
	GetAccountByLocalpart(ctx context.Context, localpart string) (*api.Account, error)
	GetAccountByPassword(ctx context.Context, localpart, password string) (*api.Account, error)
}

AccountDatabase represents an account database.

type Challenge

type Challenge struct {
	Completed []string              `json:"completed"`
	Flows     []userInteractiveFlow `json:"flows"`
	Session   string                `json:"session"`
	// TODO: Return any additional `params`
	Params map[string]interface{} `json:"params"`
}

type DeviceDatabase

type DeviceDatabase interface {
	// Look up the device matching the given access token.
	GetDeviceByAccessToken(ctx context.Context, token string) (*api.Device, error)
}

DeviceDatabase represents a device database.

type GetAccountByPassword

type GetAccountByPassword func(ctx context.Context, localpart, password string) (*api.Account, error)

type Login

type Login struct {
	LoginIdentifier                 // Flat fields deprecated in favour of `identifier`.
	Identifier      LoginIdentifier `json:"identifier"`

	// Both DeviceID and InitialDisplayName can be omitted, or empty strings ("")
	// Thus a pointer is needed to differentiate between the two
	InitialDisplayName *string `json:"initial_device_display_name"`
	DeviceID           *string `json:"device_id"`
}

Login represents the shared fields used in all forms of login/sudo endpoints.

func (*Login) ThirdPartyID

func (r *Login) ThirdPartyID() (medium, address string)

ThirdPartyID returns the 3PID medium and address for this login, if it exists.

func (*Login) Username

func (r *Login) Username() string

Username returns the user localpart/user_id in this request, if it exists.

type LoginCleanupFunc

type LoginCleanupFunc func(context.Context, *util.JSONResponse)

type LoginIdentifier

type LoginIdentifier struct {
	Type string `json:"type"`
	// when type = m.id.user
	User string `json:"user"`
	// when type = m.id.thirdparty
	Medium  string `json:"medium"`
	Address string `json:"address"`
}

LoginIdentifier represents identifier types https://matrix.org/docs/spec/client_server/r0.6.1#identifier-types

type LoginTypePassword

type LoginTypePassword struct {
	GetAccountByPassword GetAccountByPassword
	Config               *config.ClientAPI
}

LoginTypePassword implements https://matrix.org/docs/spec/client_server/r0.6.1#password-based

func (*LoginTypePassword) Login

func (t *LoginTypePassword) Login(ctx context.Context, req interface{}) (*Login, *util.JSONResponse)

func (*LoginTypePassword) LoginFromJSON

func (t *LoginTypePassword) LoginFromJSON(ctx context.Context, reqBytes []byte) (*Login, LoginCleanupFunc, *util.JSONResponse)

func (*LoginTypePassword) Name

func (t *LoginTypePassword) Name() string

type LoginTypeToken

type LoginTypeToken struct {
	UserAPI uapi.LoginTokenInternalAPI
	Config  *config.ClientAPI
}

LoginTypeToken describes how to authenticate with a login token.

func (*LoginTypeToken) LoginFromJSON

func (t *LoginTypeToken) LoginFromJSON(ctx context.Context, reqBytes []byte) (*Login, LoginCleanupFunc, *util.JSONResponse)

LoginFromJSON implements Type. The cleanup function deletes the token from the database on success.

func (*LoginTypeToken) Name

func (t *LoginTypeToken) Name() string

Name implements Type.

type PasswordRequest

type PasswordRequest struct {
	Login
	Password string `json:"password"`
}

type Type

type Type interface {
	// Name returns the name of the auth type e.g `m.login.password`
	Name() string
	// Login with the auth type, returning an error response on failure.
	// Not all types support login, only m.login.password and m.login.token
	// See https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-login
	// This function will be called when doing login and when doing 'sudo' style
	// actions e.g deleting devices. The response must be a 401 as per:
	// "If the homeserver decides that an attempt on a stage was unsuccessful, but the
	// client may make a second attempt, it returns the same HTTP status 401 response as above,
	// with the addition of the standard errcode and error fields describing the error."
	//
	// The returned cleanup function must be non-nil on success, and will be called after
	// authorization has been completed. Its argument is the final result of authorization.
	LoginFromJSON(ctx context.Context, reqBytes []byte) (login *Login, cleanup LoginCleanupFunc, errRes *util.JSONResponse)
}

Type represents an auth type https://matrix.org/docs/spec/client_server/r0.6.1#authentication-types

type UserInteractive

type UserInteractive struct {
	Completed []string
	Flows     []userInteractiveFlow
	// Map of login type to implementation
	Types map[string]Type
	// Map of session ID to completed login types, will need to be extended in future
	Sessions map[string][]string
}

UserInteractive checks that the user is who they claim to be, via a UI auth. This is used for things like device deletion and password reset where the user already has a valid access token, but we want to double-check that it isn't stolen by re-authenticating them.

func NewUserInteractive

func NewUserInteractive(accountDB AccountDatabase, cfg *config.ClientAPI) *UserInteractive

func (*UserInteractive) AddCompletedStage

func (u *UserInteractive) AddCompletedStage(sessionID, authType string)

func (*UserInteractive) Challenge

func (u *UserInteractive) Challenge(sessionID string) *util.JSONResponse

Challenge returns an HTTP 401 with the supported flows for authenticating

func (*UserInteractive) IsSingleStageFlow

func (u *UserInteractive) IsSingleStageFlow(authType string) bool

func (*UserInteractive) NewSession

func (u *UserInteractive) NewSession() *util.JSONResponse

NewSession returns a challenge with a new session ID and remembers the session ID

func (*UserInteractive) ResponseWithChallenge

func (u *UserInteractive) ResponseWithChallenge(sessionID string, response interface{}) *util.JSONResponse

ResponseWithChallenge mixes together a JSON body (e.g an error with errcode/message) with the standard challenge response.

func (*UserInteractive) Verify

func (u *UserInteractive) Verify(ctx context.Context, bodyBytes []byte, device *api.Device) (*Login, *util.JSONResponse)

Verify returns an error/challenge response to send to the client, or nil if the user is authenticated. `bodyBytes` is the HTTP request body which must contain an `auth` key. Returns the login that was verified for additional checks if required.

type UserInternalAPIForLogin

type UserInternalAPIForLogin interface {
	uapi.LoginTokenInternalAPI
}

UserInternalAPIForLogin contains the aspects of UserAPI required for logging in.