Update plugin doc

1 files changed, 99 insertions, 0 deletions

diff --git a/doc/plugin-authentication-architecture.markdown b/doc/plugin-authentication-architecture.markdown
new file mode 100644
index 00000000..6ef1fb88
--- /dev/null
+++ b/doc/plugin-authentication-architecture.markdown
@@ -0,0 +1,99 @@
+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