auth

Documentation

Overview

Package auth implements authentication checks and storage.

Index

• func ExtractAccessToken(req *http.Request) (string, error)
• func GenerateAccessToken() (string, error)
• func VerifyUserFromRequest(req *http.Request, userAPI api.UserInternalAPI) (*api.Device, *util.JSONResponse)
• type AccountDatabase
• type DeviceDatabase
• type GetAccountByPassword
• type Login
  • func (r *Login) ThirdPartyID() (medium, address string)
  • func (r *Login) Username() string
• type LoginIdentifier
• type LoginTypePassword
  • func (t *LoginTypePassword) Login(ctx context.Context, req interface{}) (*Login, *util.JSONResponse)
  • func (t *LoginTypePassword) Name() string
  • func (t *LoginTypePassword) Request() interface{}
• type PasswordRequest
• type Type
• type UserInteractive
  • func NewUserInteractive(getAccByPass GetAccountByPassword, 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)

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 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)
}

AccountDatabase represents an account database.

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 {
	Type       string          `json:"type"`
	Identifier LoginIdentifier `json:"identifier"`
	User       string          `json:"user"`    // deprecated in favour of identifier
	Medium     string          `json:"medium"`  // deprecated in favour of identifier
	Address    string          `json:"address"` // deprecated in favour of 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 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) Name

func (t *LoginTypePassword) Name() string

func (*LoginTypePassword) Request

func (t *LoginTypePassword) Request() interface{}

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
	// Request returns a pointer to a new request body struct to unmarshal into.
	Request() interface{}
	// 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
	// `req` is guaranteed to be the type returned from Request()
	// 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."
	Login(ctx context.Context, req interface{}) (login *Login, 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(getAccByPass GetAccountByPassword, 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.