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 <feature_cli>`. Canaille can handle data stored in different :ref:`database backends <feature_databases>`.
Canaille web interface can be used either in :doc:`production environments <tutorial/deployment>` or locally for development purposes.
.. screenshot:: |canaille|/profile/user :context: user :align: right :width: 275px The user profile edition page.
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.
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.
.. screenshot:: |canaille|/groups/users :context: admin :align: right :width: 275px Group edition
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.
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>`.
.. screenshot:: |canaille|/join :align: right :width: 275px The registration page.
Users can create accounts on Canaille if the :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.
.. screenshot:: |canaille|/invite :context: admin :align: right :width: 275px The invitation form page.
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.
If Canaille is plugged to a :ref:`backend <feature_databases>` 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.
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.
.. screenshot:: |canaille|/reset :align: right :width: 275px The password reset page.
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.
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.
.. screenshot:: |canaille|/firstlogin/james :context: james :align: right :width: 275px The first login page.
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.
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>`.
If the :attr:`one-time password feature <canaille.core.configuration.CoreSettings.OTP_METHOD>` is set, then users will need to authenticate themselves using a one-time password via an authenticator app. Two options are supported : "TOTP" for time one-time password, and "HOTP" for HMAC-based one-time password. In case of lost token, TOTP/HOTP authentication can be reset by users with :attr:`user management permission <canaille.core.configuration.Permission.MANAGE_USERS>`. If a :class:`mail server <canaille.core.configuration.SMTPSettings>` is configured and the :attr:`email one-time password feature <canaille.core.configuration.CoreSettings.EMAIL_OTP>` is enabled, then users will need to authenticate themselves via a one-time password sent to their primary email address. If a :class:`smpp server <canaille.core.configuration.SMPPSettings>` is configured and the :attr:`sms one-time password feature <canaille.core.configuration.CoreSettings.SMS_OTP>` is enabled, then users will need to authenticate themselves via a one-time password sent to their primary phone number.
If the :attr:`intruder lockout feature <canaille.core.configuration.CoreSettings.ENABLE_INTRUDER_LOCKOUT>` is enabled, then users will have to wait for an increasingly long time between each failed login attempt.
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.
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.
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>`.
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.
.. screenshot:: |canaille|/oauth/authorize?response_type=code&client_id=client1&redirect_uri=http%3A%2F%2Flocalhost%3A5001%2Flogin_callback&scope=openid+profile+email+phone+address+groups&state=state&nonce=nonce :context: admin :align: right :width: 275px The consent request dialog.
Users can give their consent to application requesting access to their personal information, and then revoke those consent at their will.
.. screenshot:: |canaille|/admin/client/edit/client1 :context: admin :align: right :width: 275px The client addition page.
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.
Canaille implements the :doc:`Discovery specifications <development/specifications>` so most of the applications plugged to Canaille can auto-configure themselves.
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.
Canaille comes with a :abbr:`CLI (Command Line Interface)` to help administrators in hosting and management.
There are tools to :ref:`generate and check a configuration file <cli_config>` 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.
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.
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 log level "security" for easy retrieval :
- Authentication attempt
- Password update
- Email update
- Forgotten password mail sent to user
- One-time password mail sent to user
- Multi-factor authentication reset
- Token emission
- Token refresh
- Token revokation
- New consent given for client application
- Consent revokation
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.
Before we push Canaille in stable version we want to achieve the following tasks: