mirror of
https://github.com/YunoHost-Apps/kanboard_ynh.git
synced 2024-09-03 19:36:17 +02:00
99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
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
|