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, auhentication 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 want 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 bruteforce 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 returns a value to sync the user
- Properties that returns an empty string won't be synced