kanboard_ynh/sources/doc/plugin-authentication-architecture.markdown

Authentication Architecture

Kanboard provides a flexible and pluggable authentication architecture.

By default, user authentication can be done with multiple methods:

• Username and password authentication (Local database and LDAP)
• OAuth2 authentication
• Reverse-Proxy authentication
• Cookie based authentication (Remember Me)

More over, after a successful authentication, a Two-Factor post authentication can be done. Kanboard supports natively the TOTP standard.

Authentication Interfaces

To have a pluggable system, authentication drivers must implement a set of interfaces:

Interface	Role
AuthenticationProviderInterface	Base interface for other authentication interfaces
PreAuthenticationProviderInterface	The user is already authenticated when reaching the application, web servers usually define some environment variables
PasswordAuthenticationProviderInterface	Authentication methods that uses the username and password provided in the login form
OAuthAuthenticationProviderInterface	OAuth2 providers
PostAuthenticationProviderInterface	Two-Factor auhentication drivers, ask for confirmation code
SessionCheckProviderInterface	Providers that are able to check if the user session is valid

Examples of authentication providers:

• The default Database method implements PasswordAuthenticationProviderInterface and SessionCheckProviderInterface
• The Reverse-Proxy method implements PreAuthenticationProviderInterface and SessionCheckProviderInterface
• The Google method implements OAuthAuthenticationProviderInterface
• The LDAP method implements PasswordAuthenticationProviderInterface
• The RememberMe cookie method implements PreAuthenticationProviderInterface
• The Two-Factor TOTP method implements PostAuthenticationProviderInterface

Authentication Workflow

For each HTTP request:

1. If the user session is already open, execute registered providers that implements SessionCheckProviderInterface
2. Execute all providers that implements PreAuthenticationProviderInterface
3. If the end-user submit the login form, providers that implements PasswordAuthenticationProviderInterface are executed
4. If the end-user wants to use OAuth2, the selected provider will be executed
5. After a successful authentication, the last registered PostAuthenticationProviderInterface will be used
6. Synchronize user information if necessary

This workflow is managed by the class Kanboard\Core\Security\AuthenticationManager.

Events triggered:

• AuthenticationManager::EVENT_SUCCESS: Successful authentication
• AuthenticationManager::EVENT_FAILURE: Failed authentication

Each time a failure event occurs, the counter of failed logins is incremented.

The user account can be locked down for the configured period of time and a captcha can be shown to avoid brute force attacks.

User Provider Interface

When the authentication is successful, the AuthenticationManager will ask the user information to your driver by calling the method getUser(). This method must return an object that implements the interface Kanboard\Core\User\UserProviderInterface.

This class abstract the information gathered from another system.

Examples:

• DatabaseUserProvider provides information for an internal user
• LdapUserProvider for a LDAP user
• ReverseProxyUserProvider for a Reverse-Proxy user
• GoogleUserProvider represents a Google user

Methods for User Provider Interface:

• isUserCreationAllowed(): Return true to allow automatic user creation
• getExternalIdColumn(): Get external id column name (google_id, github_id, gitlab_id...)
• getInternalId(): Get internal database id
• getExternalId(): Get external id (Unique id)
• getRole(): Get user role
• getUsername(): Get username
• getName(): Get user full name
• getEmail(): Get user email address
• getExternalGroupIds(): Get external group ids, automatically sync group membership if present
• getExtraAttributes(): Get extra attributes to set for the user during the local sync

It's not mandatory to return a value for each method.

User Local Synchronization

User information can be automatically synced with the local database.

• If the method getInternalId() return a value no synchronization is performed
• The methods getExternalIdColumn() and getExternalId() must return a value to sync the user
• Properties that returns an empty string won't be synced