Merge branch 'issues-120-121-documentation' into 'main'

Use case documentation

See merge request yaal/canaille!191

doc/features.rst

@@ -12,11 +12,11 @@ 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>`.
+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>`.
 
-Web interface
-*************
+User and group management
+*************************
 
 Canaille web interface can be used either in :doc:`production environments <tutorial/deployment>` or locally for development purposes.
 
@@ -112,7 +112,7 @@ It can be automatically sent by email to the new user.
 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>`.
+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:
@@ -174,6 +174,9 @@ 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>`.
 
+Web interface
+*************
+
 .. _feature_i18n:
 
 Internationalization
@@ -240,10 +243,13 @@ 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.
 
+System administration
+*********************
+
 .. _feature_cli:
 
 Command Line Interface
-**********************
+======================
 
 Canaille comes with a :abbr:`CLI (Command Line Interface)` to help administrators in hosting and management.
 
@@ -252,17 +258,14 @@ You can use the CLI to :ref:`create <cli_create>`, :ref:`read <cli_get>`, :ref:`
 
 There are also tools to :ref:`fill your database <cli_populate>` with random objects, for tests purpose for instance.
 
-.. _feature_backends:
+.. _feature_databases:
 
-Backends
-********
+Databases
+=========
 
 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
@@ -284,13 +287,26 @@ The following security events are logged with the tag [SECURITY] for easy retrie
 
 .. _feature_development:
 
-A tool for your development and tests
-=====================================
+Development and testing tool
+****************************
+
+.. _feature_testing:
+
+Unit-testing tool
+=================
 
 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`.
 
+Development server
+==================
+
 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.
 
+.. _feature_ci:
+
+Continuous Integration tools
+============================
+
 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

doc/index.rst

@@ -45,7 +45,7 @@ It aims to be very light, simple to install and simple to maintain. Its main fea
 
     .. grid-item-card:: Multi-database support
         :link-type: ref
-        :link: feature_backends
+        :link: feature_databases
 
         PostgreSQL, Mariadb and OpenLDAP first-class citizenship
 
@@ -64,6 +64,7 @@ It aims to be very light, simple to install and simple to maintain. Its main fea
 .. container:: buttons
 
     :doc:`Full feature list <features>`
+    :doc:`Common use cases <usecases>`
 
 .. rst-class:: lead
 
@@ -75,6 +76,7 @@ It aims to be very light, simple to install and simple to maintain. Its main fea
    :maxdepth: 2
 
    features
+   usecases
    tutorial/index
    references/index
    development/index

doc/usecases.rst

@@ -0,0 +1,43 @@
+.. terminer les paragraphes par 'user feature and feature'
+
+Use cases
+#########
+
+Canaille is a lightweight IAM for simple needs.
+Here are a few use cases you might recognize in, where Canaille would fit your needs.
+
+OpenID Connect provider on top of a LDAP directory
+==================================================
+
+Your organization has an historic :ref:`LDAP directory <feature_databases>` and you want to add a :ref:`OpenID Connect <feature_oidc>` :abbr:`SSO (Single Sign-On)` layer on top of it, so users can use all your application while signin-in only once, without any data migration.
+
+Profile edition of LDAP users
+=============================
+
+Your organization has a :ref:`LDAP directory <feature_databases>` and you want to provide a way to your users to :ref:`edit their personal information <feature_profile_management>` by themselves, without requiring any administrator intervention.
+
+Password recovery with a LDAP directory
+=======================================
+
+Your organization has an historic :ref:`LDAP directory <feature_databases>` and you want to provide a way to your users to :ref:`recover their password <feature_password_recovery>` when they cannot remember it, without any administrator intervention.
+
+A lightweight IAM for unit testing
+==================================
+
+You are :ref:`developing <feature_development>` an application relying on OAuth2 or OpenID Connect to authenticate the users. You don't want to mock the calls to the identity provider in your unit tests, but you want to :ref:`perform real OAuth2/OIDC requests <feature_testing>`, and test your application against different identity provider tunings.
+
+A lightweight IAM for developing
+================================
+
+You are :ref:`developing <feature_development>` an application relying on OAuth2 or OpenID Connect to authenticate the users. You need a :ref:`IAM server to develop <feature_development>` locally, but your old computer cannot bear launching a full Keycloak in a Docker container.
+
+A lightweight IAM for CIs
+=========================
+
+You are :ref:`developing <feature_development>` an application relying on OAuth2 or OpenID Connect to authenticate the users. You need a IAM server that could can populate with custom data, and integrate in your :ref:`continuous integration environment <feature_ci>`.
+
+A CLI to quickly edit LDAP directory users
+==========================================
+
+Your organization has an historic :ref:`LDAP directory <feature_databases>`.
+You are tired to deal with *ldif* syntax to manage your users and group and would prefer a simple human-readable CLI.