auth

Documentation

Overview

auth module contains helper functions for authentication of users in a one or more step-fashion.

# How does auth work? A user has a main authentication provider, which is always used, and a list of secondary stages for auth. The auth modules are "loaded" in at init-time, if they are compiled in.

## Procedure on login

### (0) View First authentication view is always used for "native"-auth module (username and password). The problem is, that before the first user input, the user is not identifyable, therefore we do not know what main-auth to use. After the MainAuth checked out, the next view is identified by auth module (see user.AuthExtra.Order).

### (1) MainAuth First the user.AuthProvider and user.AuthProviderExtra will be used to verify the login credentials. It's configuration is always stored in user.AuthProviderExtra.

### (2) Additional Steps After the MainAuth checked out, the user.AuthExtra field is evaluated. If additional steps are Enabled, the order-field identifies the names of the additional modules (comma seperated). They are loaded from the AuthProvider table, where their extra field is stored. When the order-field is exhausted, "fin" is returned as next step identifying that all steps have been traversed. The current step is stored in LoginToken.Step

## Secrets Some auth modules needs secrets, which need to be set before enabling the auth-module. A module can either:

• generate a secret on enabling, if no user interaction is required
• generate a secret, request the user to interact with the module, e.g. type in the first TOTP code, then commit its secret and enable itself

Index

• func AuthDisable(db *gorm.DB, user *core.User, name string) error
• func AuthEnable(db *gorm.DB, user *core.User, name string) (string, error)
• func AuthEnableCommit(db *gorm.DB, user *core.User, name string, given string) error
• func AuthSetMain(db *gorm.DB, u *core.User, name string, module string, extra string) error
• func AuthSetSecret(user *core.User, name string, given string, extra string) error
• func AuthVerify(user *core.User, name string, stepExtra string, given string, extra string, ...) error
• func ConfigCommit(db *gorm.DB, user core.User, name string, params url.Values) error
• func ConfigView(db *gorm.DB, user core.User, name string) (string, map[string]string)
• func EnsureEnabled(db *gorm.DB, u core.User, name string, module string, extra string, ...) error
• func FollowUp(user core.User, step string) string
• func HumanName(name string) string
• func LoginView(name string) string
• func SeedStep(name string, stepExtra string) string
• func SetupView(db *gorm.DB, user core.User, name string, challenge string) (string, string)
• func VerifyExtra(db *gorm.DB, user core.User, step string, stepExtra string, given string, ...) error
• func VerifyMain(db *gorm.DB, user core.User, given string, name string, ...) error
• type AdminViewPostFunc
• type AuthExtra
• type ConfigFunc
• type ConfigViewFunc
• type EnableCommitFunc
• type EnableFunc
• type Provider
  • func GetAuthProvider() []Provider
• type ProviderCap
• type SeedFunc
• type SetSecretFunc
• type SetupViewFunc
• type UserProviderCap
• type UserProviderStruct
  • func ListAuth(u core.User) []UserProviderStruct
• type VerifyFunc

Functions

func AuthDisable

func AuthDisable(db *gorm.DB, user *core.User, name string) error

disable an authentication module for a given user and remove it from this users chain.

func AuthEnable

func AuthEnable(db *gorm.DB, user *core.User, name string) (string, error)

enables an authentication module for a user and adds it to her authentication chain, calls provider.Enable

func AuthEnableCommit

func AuthEnableCommit(db *gorm.DB, user *core.User, name string, given string) error

If a two-step enabling process is necessary, this step will enable the authentication provider for a given user and add it to her chain, calls provider.EnableCommit

func AuthSetMain

func AuthSetMain(db *gorm.DB, u *core.User, name string, module string, extra string) error

Sets a given authentication module to be the main authentication provider of a given user. Will also make sure that it is enabled.

func AuthSetSecret

func AuthSetSecret(user *core.User, name string, given string, extra string) error

Set the secret for a authentication step of a user, calls provider.SetSecret

func AuthVerify

func AuthVerify(user *core.User, name string, stepExtra string, given string, extra string, providerExtra string) error

verify user-input against the previously set secret, calls provider.Verify

func ConfigCommit

func ConfigCommit(db *gorm.DB, user core.User, name string, params url.Values) error

commit the configuration change to the database, by saving the new provider infos and user infos in the database, calls provider.ConfigCommit

func ConfigView

func ConfigView(db *gorm.DB, user core.User, name string) (string, map[string]string)

Find the view for configuring a given Authentication module, returning the view filename and a config-map from the authentication module, calls provider.ConfigView

func EnsureEnabled

func EnsureEnabled(db *gorm.DB, u core.User, name string, module string, extra string, prov *core.AuthProvider) error

enable the given module if it is not enabled already

func FollowUp

func FollowUp(user core.User, step string) string

returns the string of the next authProvider given the current step from the user.AuthExtra.Order field fin -> finished, login successful fail -> failed auth, probably wrong configuration

func HumanName

func HumanName(name string) string

return the human name of an auth provider given its internal name

func LoginView

func LoginView(name string) string

return the name of the template of the login-view

func SeedStep

func SeedStep(name string, stepExtra string) string

Seeds the authentication module by calling provider.Seed Calls provider.Seed

func SetupView

func SetupView(db *gorm.DB, user core.User, name string, challenge string) (string, string)

Find the setup-view of a given authenticaton module and return the template file name and a configuration string from the auth module. Calls provider.EnableView

func VerifyExtra

func VerifyExtra(db *gorm.DB, user core.User, step string, stepExtra string, given string, e string, authProviderExtra string) error

API for the login-handler verify against extra steps, outlined in user.AuthExtra

func VerifyMain

func VerifyMain(db *gorm.DB, user core.User, given string, name string, authProviderExtra string) error

API for login-handler verifies against main auth on the user-object

Types

type AdminViewPostFunc

type AdminViewPostFunc func() error

type AuthExtra

type AuthExtra struct {
	Enable bool   // are any extra auth steps enabled?
	Order  string // names of the auth extra-modules, comma separated
}

struct type for the user.AuthExtra field look up the extra-config for every extra step in the AuthProvider table

type ConfigFunc

type ConfigFunc func(*core.User, *core.AuthProvider, url.Values) error

type ConfigViewFunc

type ConfigViewFunc func(core.User, *core.AuthProvider) (map[string]string, error)

type EnableCommitFunc

type EnableCommitFunc func(core.User, *core.AuthProvider, string) error

type EnableFunc

type EnableFunc func(core.User, *core.AuthProvider) (string, error)

type Provider

type Provider struct {
	Name        string // internal name of the auth provider, must not contain spaces, must be usable in an URL
	HumanName   string // human readable name
	Description string // description of what it does or how it works

	Verify       VerifyFunc       // verify given passowrd at login
	Seed         SeedFunc         // seed extra information for the next step, if they are based on random
	Enable       EnableFunc       // enable authProvider, seed for authProvider.Extra, maybe initiate the second step of verification
	EnableCommit EnableCommitFunc // second stage enabling - check the secret against user input, and return nil if successful

	EnableView SetupViewFunc // Callback for finding and configuring the setup-view of a given auth module
	SetSecret  SetSecretFunc // Set a given secret of the authentication module

	ConfigView   ConfigViewFunc // Callback for finding and configuring the config-view of a given auth module
	ConfigCommit ConfigFunc     // Callback for committing configuration options

	Cap ProviderCap // Capabilities of the provider
}

structure for describing a provider with its callback functions

func GetAuthProvider

func GetAuthProvider() []Provider

copy list of authProviders for a user to modify

type ProviderCap

type ProviderCap struct {
	Seed                 bool // the auth provider needs a seed
	SetSecretCommit      bool // the auth provider uses two-step secret verification (secret show, verify, commit secret to DB)
	ValidateRegistration bool // allows verifying a registration
	MainEnable           bool // can be used as main authentification module
	Instantiable         bool // there can be several instances of this auth module in the system (i.e. > 1 entry in AuthProvider)
	Configurable         bool // can the auth provider be configured again without dis- and enabling?
}

capabilities of the auth provider

type SeedFunc

type SeedFunc func(string) string

type SetSecretFunc

type SetSecretFunc func(*core.User, string, string) error

type SetupViewFunc

type SetupViewFunc func(core.User, *core.AuthProvider) (string, error)

type UserProviderCap

type UserProviderCap struct {
	MainAble       bool // can be used as main auth
	IsConfigurable bool // can the auth provider be setup without dis- and enabling?
}

type UserProviderStruct

type UserProviderStruct struct {
	Name         string          // internal name
	HumanName    string          // human readable name
	Description  string          // a description of what it does or how it works
	Extra        string          // extra information
	InstanceName string          // name of the instance
	Cap          UserProviderCap // capabilities
	IsMain       bool            // is enabled as the main auth for the user
	IsEnabled    bool            // is enabled at all
}

struct for reading back the authProviders for user-interaction

func ListAuth

func ListAuth(u core.User) []UserProviderStruct

list the authProviders for a given user

type VerifyFunc

type VerifyFunc func(*core.User, string, string, string, string) error