Base interface for authentication implementations.
Plugins that provide Auth implementations must provide a class that implements this interface. Additionally, an instance of that class must be set in the container with the 'Piwik\Auth' key during the Request.initAuthenticationObject event.
Authentication implementations must support authentication via username and clear-text password and authentication via username and token auth. They can additionally support authentication via username and an MD5 hash of a password. If they don't support it, then formless authentication will fail.
Derived implementations should favor authenticating by password over authenticating by token auth. That is to say, if a token auth and a password are set, password authentication should be used.
How an Auth implementation will be used
// authenticating by password $auth = StaticContainer::get('Piwik\Auth'); $auth->setLogin('user'); $auth->setPassword('password'); $result = $auth->authenticate(); // authenticating by token auth $auth = StaticContainer::get('Piwik\Auth'); $auth->setLogin('user'); $auth->setTokenAuth('...'); $result = $auth->authenticate();
The interface defines the following methods:
getName()ash; Must return the Authentication module's name, e.g.,
setTokenAuth()— Sets the authentication token to authenticate with.
getLogin()— Returns the login of the user being authenticated.
getTokenAuthSecret()— Returns the secret used to calculate a user's token auth.
setLogin()— Sets the login name to authenticate with.
setPassword()— Sets the password to authenticate with.
setPasswordHash()— Sets the hash of the password to authenticate with.
authenticate()— Authenticates a user using the login and password set using the setters.
Must return the Authentication module's name, e.g.,
Sets the authentication token to authenticate with.
string) — authentication token
Returns the login of the user being authenticated.
Returns the secret used to calculate a user's token auth.
A users token auth is generated using the user's login and this secret. The secret should be specific to the user and not easily guessed. Matomo (formerly Piwik)'s default Auth implementation uses an MD5 hash of a user's password.
Exception— if the token auth secret does not exist or cannot be obtained.
Sets the login name to authenticate with.
string) — The username.
Sets the password to authenticate with.
string) — Password (not hashed).
Sets the hash of the password to authenticate with. The hash will be an MD5 hash.
string) — The hashed password.
Exception— if authentication by hashed password is not supported.
Authenticates a user using the login and password set using the setters. Can also authenticate via token auth if one is set and no password is set.
Note: this method must successfully authenticate if the token auth supplied is a special hash of the user's real token auth. This is because the SessionInitializer class stores a hash of the token auth in the session cookie. You can calculate the token auth hash using the \Piwik\Plugins\Login\SessionInitializer::getHashTokenAuth() method.
Exception— if the Auth implementation has an invalid state (ie, no login was specified). Note: implementations are not required to throw exceptions for invalid state, but they are allowed to.