From 51df1e4079697fed814e808b1c0612f175419c43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89loi=20Rivard?= Date: Mon, 25 Nov 2024 13:00:53 +0000 Subject: [PATCH] Use case documentation --- doc/features.rst | 44 ++++++++++++++++++++++++++++++-------------- doc/index.rst | 4 +++- doc/usecases.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+), 15 deletions(-) create mode 100644 doc/usecases.rst diff --git a/doc/features.rst b/doc/features.rst index 42120f2c..e1d23785 100644 --- a/doc/features.rst +++ b/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 ` to fit any :doc:`use cases ` you may meet. Check our :ref:`roadmap ` to see what is coming next. -Users can interact with Canaille through its :ref:`web interface ` and administrators can also use its :ref:`command line interface `. -Canaille can handle data stored in different :ref:`database backends `. +Users can interact with Canaille through its :ref:`web interface ` and administrators can also use its :ref:`command line interface `. +Canaille can handle data stored in different :ref:`database backends `. -Web interface -************* +User and group management +************************* Canaille web interface can be used either in :doc:`production environments ` 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 ` that supports it, user accounts can be locked by users with :attr:`user management permission `. +If Canaille is plugged to a :ref:`backend ` that supports it, user accounts can be locked by users with :attr:`user management permission `. 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 ` 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 `. +Web interface +************* + .. _feature_i18n: Internationalization @@ -240,10 +243,13 @@ Dynamic Client Registration Canaille implements the :doc:`Dynamic Client Registration specifications `, so when the :attr:`feature is enabled `, 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 `, :ref:`read `, :ref:` There are also tools to :ref:`fill your database ` 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 ` such as PostgreSQL, MariaDB or SQLite, as well as :ref:`OpenLDAP `. It also comes with a no-dependency :ref:`in-memory database ` 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 ` and its curated :ref:`dependency list `, 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 `, you can prepare data in Canaille, let your application interact with it, and then check the side effects. Roadmap diff --git a/doc/index.rst b/doc/index.rst index 95765ac4..29861eea 100644 --- a/doc/index.rst +++ b/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 ` + :doc:`Common use cases ` .. 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 diff --git a/doc/usecases.rst b/doc/usecases.rst new file mode 100644 index 00000000..01e03176 --- /dev/null +++ b/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 ` and you want to add a :ref:`OpenID Connect ` :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 ` and you want to provide a way to your users to :ref:`edit their personal information ` by themselves, without requiring any administrator intervention. + +Password recovery with a LDAP directory +======================================= + +Your organization has an historic :ref:`LDAP directory ` and you want to provide a way to your users to :ref:`recover their password ` when they cannot remember it, without any administrator intervention. + +A lightweight IAM for unit testing +================================== + +You are :ref:`developing ` 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 `, and test your application against different identity provider tunings. + +A lightweight IAM for developing +================================ + +You are :ref:`developing ` an application relying on OAuth2 or OpenID Connect to authenticate the users. You need a :ref:`IAM server to develop ` locally, but your old computer cannot bear launching a full Keycloak in a Docker container. + +A lightweight IAM for CIs +========================= + +You are :ref:`developing ` 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 `. + +A CLI to quickly edit LDAP directory users +========================================== + +Your organization has an historic :ref:`LDAP directory `. +You are tired to deal with *ldif* syntax to manage your users and group and would prefer a simple human-readable CLI.