discodove_interface_auth

README

discodove-auth-plugin

Interfaces necessary to write a discodove authentication plugin.

Documentation

Overview

Written by Dave Richards. * * These are the types required to communicate with the authenticator service as a client.

Written by Dave Richards. * * This is the top-level plugin interface, where you produce a new instance of an authenticator.

Index

• Constants
• type DiscoDoveAuthPlugin
• type DiscoDoveAuthRequest
• type DiscoDoveAuthResponse

Constants

const (
	QueryImplements = iota
	PerformAuthentication
)

For use in requestType in DiscoDoveAuthRequest

const (
	AuthBasicUsernameAndPassword = iota
	AuthSASLLogin
	AuthSASLPlain
)

For use in authType in DiscoDoveAuthRequest and used in DiscoDoveAuthPlugin.Implements If AuthBasicUsernameAndPassword is specified, we will also provide AuthSASLLogin support The plugin must explicity implement AuthSASLPlain if the plugin is coded for it.

const (
	AuthOK = iota
	AuthFail
)

For use with authResult in DiscoDoveAuthResponse

Types

type DiscoDoveAuthPlugin

type DiscoDoveAuthPlugin interface {

	/* This will be called once when we load this plugin, if you feel compelled to set something up, perhaps a
	 * control/query/admin thread or something, then do it here in a controlled manner - similarly if
	 * you want to pool connections, etc....  We assume that each plugin can scale itself, we do no magic
	 * to allow for scalability, so you might want some worker threads.
	 *
	 * Each plugin is responsible for creating it's own syslog connection as *syslog.Writer has a mutex, and
	 * I don't want the auth threads to be blocking on writing to syslog - so you need to scale logging yourself.
	 *
	 * We use Viper for config, and you will be passed the config directives for your module, but as it's viper you
	 * can access the entire discodove config too.  Feel free to specify your own config directives.
	 *
	 * name	 	: will be the name of the process, in 99.999% of cases it will just be "discodove" - please
	 *            prefix your log messages with this and perhaps your own identifier e.g. "ldapauth"
	 * syslogFacility : which facility to use in syslog.
	 * conf: a Viper subtree configuration for this service as specified in the discodove config.
	 */
	Initialize(name string, syslogFacility syslog.Priority, conf *viper.Viper) error

	/* This functions is used to determine which authentication methods will be offered by this plugin,
	 * using the constants specified above to check availability.  This function is used for efficiency
	 * when determining if this plugin will even be consulted when a specific authentication method is requested
	 * by a client.
	 * Example return: [AuthBasicUsernameAndPassword, AuthSASLPlain]
	 */
	Implements() []int

	/* These are the interfaces you need to implement if you support those authentication types.
	 * return the authenticated username on success, on fail return blank and set error. You should
	 * expect many concurrent calls (as go routines) of these functions.
	 *
	 * The authenticating user is authzid, and if authcid is blank then it should be ignored.  However,
	 * if authcid is not blank, the plugin should assess if the authzid user is allowed to authenticate
	 * a session for authcid.  See the SASL PLAIN method for more details.
	 */
	AuthBasicUsernamePassword(authcid string, authzid string, password string) (string, error)
}

type DiscoDoveAuthRequest

type DiscoDoveAuthRequest struct {
	RequestType  int
	AuthType     int
	Username     string
	Password     string
	CommsPort    *textproto.Conn
	ResponseChan chan DiscoDoveAuthResponse
}

Send this down the auth channel to request an authentication via discodove, and it will do the hard * work to figure out what plugins to use. * requestType : from the const's above, either perform an auth, or query * authType : from the const's above, depending on hwhat you would like to offer * username : username to authenticate * password : passwrod to authenticate * commsPort : the connection over which to perform some non-username/password authentication, for * example SASL Plain * responseChan : the channel, of type DiscoDoveAuthResponse, down which the authenticator will send * the response - the authenticator will not close this channel.

type DiscoDoveAuthResponse

type DiscoDoveAuthResponse struct {
	Implements []int
	AuthResult int
	AuthedUser string
}

The authenticators response to your request * implements : if you queried the auth types implemented, a slice of supported mechanisms using the * contstants above. * authResults : the results of a PerformAuthentication request * authedUser : the user for whom you should assume the session is for - in SASL for example, the * authenticated user may not be the session user.