forked from Github-Mirrors/canaille
332 lines
14 KiB
ReStructuredText
332 lines
14 KiB
ReStructuredText
.. This page should list the functional perimiter of Canaille,
|
|
without mentioning too much technical details. We should avoid giving
|
|
explicit configuration parameters for instance. However, we should put as
|
|
much links to other sections of the documentation as possible.
|
|
|
|
TODO: replace 'users with user management permission' by 'administrators'?
|
|
|
|
Features
|
|
########
|
|
|
|
Here are the different features that Canaille provides.
|
|
You can enable any of those features with the :doc:`configuration <references/configuration>` to fit any :doc:`use cases <usecases>` you may meet.
|
|
Check our :ref:`roadmap <features:Roadmap>` to see what is coming next.
|
|
|
|
Users can interact with Canaille through its :ref:`web interface <features:Web interface>` and administrators can also use its :ref:`command line interface <features:Command line interface>`.
|
|
Canaille can handle data stored in different :ref:`database backends <features:Backends>`.
|
|
|
|
Web interface
|
|
*************
|
|
|
|
Canaille web interface can be used either in :doc:`production environments <tutorial/deployment>` or locally for development purposes.
|
|
|
|
.. _feature_profile_management:
|
|
|
|
Profile management
|
|
==================
|
|
|
|
.. image:: _static/profile.webp
|
|
:width: 200px
|
|
:alt: Profile
|
|
:align: right
|
|
|
|
Canaille provides an interface to manage user profiles.
|
|
|
|
The exact list of displayed fields, and whether they are :attr:`writable <canaille.core.configuration.ACLSettings.WRITE>` or :attr:`read-only <canaille.core.configuration.ACLSettings.READ>` depends on the user :class:`Access Control List settings (ACL) <canaille.core.configuration.ACLSettings>`.
|
|
|
|
Depending on their ACL :class:`permissions <canaille.core.configuration.Permission>`, users can either be allowed to edit their own profile, edit any user profile, or do nothing at all.
|
|
|
|
.. _feature_email_confirmation:
|
|
|
|
Email confirmation
|
|
==================
|
|
|
|
If the :attr:`email confirmation feature <canaille.core.configuration.CoreSettings.EMAIL_CONFIRMATION>` is enabled, any modification or addition of a profile email will send a confirmation mail to the new address. The mail will contain a link that users will need to click on to confirm their email address.
|
|
|
|
Users with :attr:`user management permission <canaille.core.configuration.Permission.MANAGE_USERS>` can set user emails without confirmation though.
|
|
|
|
.. _feature_group_management:
|
|
|
|
Group management
|
|
================
|
|
|
|
.. image:: _static/group-edition.webp
|
|
:width: 200px
|
|
:alt: Group edition
|
|
:align: right
|
|
|
|
In a similar fashion than :ref:`profile management <feature_profile_management>` Canaille provides an interface to manage user groups.
|
|
|
|
The group management is quite simple at the moment and consists in a group name and description, and the list of its members.
|
|
Group membership can be use as :attr:`ACL Filter <canaille.core.configuration.ACLSettings.FILTER>` to define user permissions.
|
|
|
|
.. todo::
|
|
At the moment adding an user to a group can only be achieved by the user settings page, but we are :issue:`working to improve this <192>`.
|
|
|
|
Group management can be enable with a :attr:`dedicated user permission <canaille.core.configuration.Permission.MANAGE_GROUPS>`.
|
|
|
|
.. important::
|
|
Due to limitations in the :ref:`LDAP backend <tutorial/databases:LDAP>`, groups must have at least one member.
|
|
Thus it is not possible to remove the last user of a group without removing the group.
|
|
|
|
.. _feature_user_authentication:
|
|
|
|
User authentication
|
|
===================
|
|
|
|
Unless their account is :ref:`locked <feature_account_locking>`, users can authenticate with a login and a password.
|
|
|
|
.. important::
|
|
|
|
For security reasons, it won't be told to users if they try to sign in with an unexisting logging, unless explicitly :attr:`set in the configuration <canaille.core.configuration.CoreSettings.HIDE_INVALID_LOGINS>`.
|
|
|
|
.. todo:: :ref:`LDAP backend <tutorial/databases:LDAP>` users can define which :class:`user field <canaille.core.models.User>` should be used as the login (such as :attr:`~canaille.core.models.User.user_name` or :attr:`~canaille.core.models.User.emails`) using a :attr:`configuration parameter <canaille.backends.ldap.configuration.LDAPSettings.USER_FILTER>`, but other backends can only login using :attr:`~canaille.core.models.User.user_name`. We are :issue:`working to improve this <196>`.
|
|
|
|
.. _feature_user_registration:
|
|
|
|
User registration
|
|
=================
|
|
|
|
Users can create accounts on Canaille if the feature :attr:`registration feature <canaille.core.configuration.CoreSettings.ENABLE_REGISTRATION>` is enabled. They will be able to fill a registration form with the fields detailed in the default :class:`ACL settings <canaille.core.configuration.ACLSettings>`.
|
|
|
|
If :attr:`email confirmation <canaille.core.configuration.CoreSettings.EMAIL_CONFIRMATION>` is also enabled, users will be sent a confirmation link to their email address, on which they will need to click in order to finalize their registration.
|
|
|
|
.. _feature_user_invitation:
|
|
|
|
User invitation
|
|
===============
|
|
|
|
.. image:: _static/user-invite.webp
|
|
:width: 200px
|
|
:alt: User invitation
|
|
:align: right
|
|
|
|
If a :class:`mail server <canaille.core.configuration.SMTPSettings>` is configured, users with :attr:`user management permission <canaille.core.configuration.Permission.MANAGE_USERS>` can create an invitation link for one user.
|
|
|
|
The link goes to a registration form, even if regular :ref:`user registration <feature_user_registration>` is disabled.
|
|
|
|
It can be automatically sent by email to the new user.
|
|
|
|
.. _feature_account_locking:
|
|
|
|
Account locking
|
|
===============
|
|
|
|
If Canaille is plugged to a :ref:`backend <features:Backends>` that supports it, user accounts can be locked by users with :attr:`user management permission <canaille.core.configuration.Permission.MANAGE_USERS>`.
|
|
The lock date can be set instantly or at a given date in the future.
|
|
|
|
At the moment a user account is locked:
|
|
|
|
- their open sessions will be closed;
|
|
- they won't be able to sign in again;
|
|
- no new OIDC token will be issued;
|
|
|
|
User accounts must be manually unlocked by an administrator for the users to regain access to those actions.
|
|
|
|
.. _feature_account_deletion:
|
|
|
|
Account deletion
|
|
================
|
|
|
|
Users with the :attr:`account deletion permission <canaille.core.configuration.Permission.DELETE_ACCOUNT>` are allowed to delete their own account.
|
|
|
|
Users that also have the :attr:`user management permission <canaille.core.configuration.Permission.MANAGE_USERS>` are also allowed to delete other users accounts.
|
|
|
|
.. _feature_password_recovery:
|
|
|
|
Password recovery
|
|
=================
|
|
|
|
.. image:: _static/password-recovery.webp
|
|
:width: 200px
|
|
:alt: Group edition
|
|
:align: right
|
|
|
|
If a :class:`mail server <canaille.core.configuration.SMTPSettings>` is configured and the :attr:`password recovery feature <canaille.core.configuration.CoreSettings.ENABLE_PASSWORD_RECOVERY>` is enabled, then users can ask for a password reset email if they cannot remember their password.
|
|
|
|
The email will be sent to the email addresses filled in their profile, and will contain a link that will allow them to choose a new password. .
|
|
|
|
.. todo::
|
|
|
|
Check that password recovery is disabled on locked accounts.
|
|
|
|
.. _feature_password_reset:
|
|
|
|
Password reset
|
|
==============
|
|
|
|
If a :class:`mail server <canaille.core.configuration.SMTPSettings>` is configured, :attr:`user management permission <canaille.core.configuration.Permission.MANAGE_USERS>` can send password reset mails to users.
|
|
The mails contains a link that allow users to choose a new password without having to retrieve the old one.
|
|
|
|
.. _feature_password_initialization:
|
|
|
|
Password initialization
|
|
=======================
|
|
|
|
User :attr:`passwords <canaille.core.models.User.password>` are optional.
|
|
If a :class:`mail server <canaille.core.configuration.SMTPSettings>` is configured, when users with no password attempt to sign in, they are invited to click a button that will send them a password initialization mail.
|
|
The mail contains a link that leads to a form that allows users to choose a password.
|
|
|
|
.. _feature_password_compromission_check:
|
|
|
|
Password compromission check
|
|
============================
|
|
|
|
If :attr:`password compromission check feature <canaille.core.configuration.CoreSettings.ENABLE_PASSWORD_COMPROMISSION_CHECK>` is enabled, Canaille will check for password compromise on HIBP (https://haveibeenpwned.com/) every time a new password is register. You will need to set an :attr:`admin email <canaille.core.configuration.CoreSettings.ADMIN_EMAIL>`.
|
|
|
|
.. _feature_i18n:
|
|
|
|
Internationalization
|
|
====================
|
|
|
|
.. image:: https://hosted.weblate.org/widgets/canaille/-/canaille/multi-blue.svg
|
|
:alt: Translation state
|
|
:align: right
|
|
:width: 600px
|
|
|
|
Canaile will display in your :attr:`preferred language <canaille.core.models.User.preferred_language>` if available, or your browser language if available (and if it is not you can :ref:`help us with the translation <development/contributing:Code translation>`).
|
|
If you prefer, you can also :attr:`force a language <canaille.core.configuration.CoreSettings.FAVICON>` for every users.
|
|
|
|
.. _feature_ui:
|
|
|
|
Lightweight
|
|
===========
|
|
|
|
The web interface is lightweight, so everything should load quickly.
|
|
There is a few Javascript here and there to smooth the experience, but no Javascript at all is needed to use Canaille.
|
|
|
|
Customizable
|
|
============
|
|
|
|
The default theme should be good enough for most usages.
|
|
It has a dark theme, display well on mobile, and let you choose a :attr:`logo <canaille.core.configuration.CoreSettings.LOGO>` and a :attr:`favicon <canaille.core.configuration.CoreSettings.FAVICON>`.
|
|
|
|
If you need more you can also use a :attr:`custom theme <canaille.core.configuration.CoreSettings.THEME>`.
|
|
|
|
.. _feature_oidc:
|
|
|
|
OpenID Connect
|
|
**************
|
|
|
|
Canaille implements a :ref:`subset<development/specifications:State of the specs in Canaille>` of the OAuth2/OpenID Connect specifications .
|
|
This allows to provide :abbr:`SSO (Single Sign-On)` and :abbr:`SLO (Single Log-On)` to applications plugged to Canaille.
|
|
|
|
Consent management
|
|
==================
|
|
|
|
.. image:: _static/consent.webp
|
|
:width: 200px
|
|
:alt: Profile
|
|
:align: right
|
|
|
|
|
|
Users can give their consent to application requesting access to their personal information,
|
|
and then revoke those consent at their will.
|
|
|
|
Application management
|
|
======================
|
|
|
|
Users with the right :attr:`permission <canaille.core.configuration.Permission.MANAGE_OIDC>` can manager OIDC clients through the web interface.
|
|
|
|
In some cases, it might be useful to avoid the consent page for some trusted applications, so clients can be pre-consented.
|
|
|
|
Discovery
|
|
=========
|
|
|
|
Canaille implements the :doc:`Discovery specifications <development/specifications>` so most of the applications plugged to Canaille can auto-configure themselves.
|
|
|
|
Dynamic Client Registration
|
|
===========================
|
|
|
|
Canaille implements the :doc:`Dynamic Client Registration specifications <development/specifications>`, so when the :attr:`feature is enabled <canaille.oidc.configuration.OIDCSettings.DYNAMIC_CLIENT_REGISTRATION_OPEN>`, clients can register themselves on Canaille without an administrator intervention.
|
|
|
|
.. _feature_cli:
|
|
|
|
Command Line Interface
|
|
**********************
|
|
|
|
Canaille comes with a :abbr:`CLI (Command Line Interface)` to help administrators in hosting and management.
|
|
|
|
There are tools to :ref:`check your configuration <cli_check>` or to :ref:`install missing parts <cli_install>`.
|
|
You can use the CLI to :ref:`create <cli_create>`, :ref:`read <cli_get>`, :ref:`update <cli_set>` and :ref:`delete <cli_delete>` models such as :class:`users <canaille.core.models.User>`, :class:`groups <canaille.core.models.Group>` or :class:`OIDC clients <canaille.oidc.basemodels.Client>`.
|
|
|
|
There are also tools to :ref:`fill your database <cli_populate>` with random objects, for tests purpose for instance.
|
|
|
|
.. _feature_backends:
|
|
|
|
Backends
|
|
********
|
|
|
|
Canaille can handle data from the most :ref:`common SQL databases <tutorial/databases:SQL>` such as PostgreSQL, MariaDB or SQLite, as well as :ref:`OpenLDAP <tutorial/databases:LDAP>`.
|
|
It also comes with a no-dependency :ref:`in-memory database <tutorial/databases:Memory>` that can be used in unit tests suites.
|
|
|
|
Miscellaneous
|
|
*************
|
|
|
|
.. _feature_logging:
|
|
|
|
Logging
|
|
=======
|
|
|
|
Canaille writes :attr:`logs <canaille.core.configuration.CoreSettings.LOGGING>` for every important event happening, to help administrators understand what is going on and debug funky situations.
|
|
|
|
The following security events are logged with the tag [SECURITY] for easy retrieval :
|
|
|
|
- Authentication attempt
|
|
- Password update
|
|
- Email update
|
|
- Forgotten password mail sent to user
|
|
- Token emission
|
|
- Token refresh
|
|
- Token revokation
|
|
- New consent given for client application
|
|
- Consent revokation
|
|
|
|
.. _feature_development:
|
|
|
|
A tool for your development and tests
|
|
=====================================
|
|
|
|
Thanks to its lightweight :ref:`in-memory database <tutorial/databases:Memory>` and its curated :ref:`dependency list <tutorial/install:Get the code>`, Canaille can be used in the unit test suite of your application, so you can check how it behaves against a real world OpenID Connect server. If you work with python you might want to check :doc:`pytest-iam:index`.
|
|
|
|
It can also being launched in your development environment, if you find that launching a Keycloak in a Docker container is too heavy for your little web application.
|
|
|
|
It also fits well in continuous integration scenarios. Thanks to its :ref:`CLI <feature_cli>`, you can prepare data in Canaille, let your application interact with it, and then check the side effects.
|
|
|
|
Roadmap
|
|
*******
|
|
|
|
Bêta version
|
|
============
|
|
|
|
To go out of the current Alpha version we want to achieve the following tasks:
|
|
|
|
- :issue:`Configuration validation using pydantic <138>`
|
|
|
|
Stable version
|
|
==============
|
|
|
|
Before we push Canaille in stable version we want to achieve the following tasks:
|
|
|
|
Security
|
|
--------
|
|
|
|
- :issue:`Password hashing configuration <175>`
|
|
- :issue:`Authentication logging policy <177>`
|
|
- :issue:`Intruder lockout <173>`
|
|
- :issue:`Password expiry policy <176>`
|
|
- :issue:`Multi-factor authentication: Email <47>`
|
|
- :issue:`Multi-factor authentication: SMS <47>`
|
|
- :issue:`Multi-factor authentication: OTP <47>`
|
|
|
|
Packaging
|
|
---------
|
|
|
|
- :issue:`Nix package <190>`
|
|
- :issue:`Docker / OCI package <59>`
|
|
|
|
And beyond
|
|
==========
|
|
|
|
- :issue:`OpenID Connect certification <182>`
|
|
- :issue:`SCIM support <116>`
|