Merge branch 'main' into callback-routes

Author: gbip

README.md

@@ -13,19 +13,26 @@ It can be used to setup a Single Sign On using an identity provider (Keycloak, e
 
 **Warning** : this library has not been audited. However, we are based on [pyoidc](https://github.com/CZ-NIC/pyoidc/) which we believe is a sane OIDC implementation.
 
+We tried to make OpenID Connect (OIDC) configuration as easy and secure as possible. However 
+everything can be customized, and we tried to take into account every use case in the library design.
+If you are not satisfied with the default configuration, take a look at the cookbook or the setting reference.
+
 ## Features
 
 - Easy configuration through premade [`Provider`](https://django-pyoidc.readthedocs.io/en/latest/user.html#providers) classes.
-- Multiple provider support
+- Authenticate users from multiple providers
+- Bearer authentication support for [django-rest-framework](https://www.django-rest-framework.org/) integration (**single provider**)
 - Easy integration with the [Django permission system](https://django-pyoidc.readthedocs.io/en/latest/how-to.html#use-the-django-permission-system-with-oidc)
 - Highly customizable design that should suit most needs
-- Back-channel Logout
+- Support back-channel logout
+- Support service accounts (accounts for machine-to-machine uses)
 - Sane and secure defaults settings
 
 ## Roadmap
 
-- `Bearer` authentication support for `django-rest-framework` integration
 - Frontchannel logout
+- Switch to django signal system login/logout hooks
+- Allow for audience check without customizing `get_user` using a setting
 
 ## Acknowledgement
 
@@ -47,7 +54,7 @@ The documentation is graciously hosted at [readthedocs](https://django-pyoidc.re
 First, install the python package :
 
 ```bash
-pip install makina-django-doic
+pip install django_pyoidc
 ```
 
 Then add the library app to your django applications, after `django.contrib.sessions` and `django.contrib.auth` :
@@ -86,52 +93,49 @@ CACHES = {
 }
 ```
 
-Now you can pick an identity provider from the [available providers](https://django-pyoidc.readthedocs.io/en/latest/user.html#providers). Providers class are a quick way to generate the library configuration and URLs for a givenv identity provider. You can also use [manual set] if you wish.
-
-Create a file named `oidc.py` next to your settings file and initialize your provider there :
-
-FIXME: Here config as settings only OR using custom provider
-
-```python
-from django_pyoidc.providers.keycloak import KeycloakProvider
-
-my_oidc_provider = KeycloakProvider(
-    op_name="keycloak",
-    keycloak_base_uri="http://keycloak.local:8080/auth/", # we use the auth/ path prefix option on Keycloak
-    keycloak_realm="Demo",
-    client_secret="s3cret",
-    client_id="my_client_id",
-    logout_redirect="http://app.local:8082/",
-    failure_redirect="http://app.local:8082/",
-    success_redirect="http://app.local:8082/",
-    redirect_requires_https=False,
-    login_uris_redirect_allowed_hosts=["app.local:8082"],
-)
-```
+Now you can pick an identity provider from the [available providers](https://django-pyoidc.readthedocs.io/en/latest/user.html#providers). Providers class are a quick way to generate the library configuration and URLs. You can also configure the settings manually, but this is not recommended if you are not familiar with the OpendID Connect (OIDC) protocol.
 
-You can then add to your django configuration the following line :
+Add the following `DJANGO_PYOIDC` to your `settings.py` :
 
 ```python
-from .oidc_providers import my_oidc_provider
-
+# settings
 DJANGO_PYOIDC = {
-    **my_oidc_provider.get_config(),
-}
+    # This is the name that your identity provider will have within the library
+    "sso": {
+        # change the following line to use your provider
+        "provider_class": "django_pyoidc.providers.keycloak_18.Keycloak18Provider",
+        
+        # your secret should not be stored in settings.py, load them from an env variable
+        "client_secret": os.getenv("SSO_CLIENT_SECRET"),
+        "client_id": os.getenv("SSO_CLIENT_ID"),
+        
+        "provider_discovery_uri": "https://keycloak.example.com/auth/realms/fixme",
+        
+        # This setting allow the library to cache the provider configuration auto-detected using
+        # the `provider_discovery_uri` setting
+        "oidc_cache_provider_metadata": True,
+    }
 ```
 
 Finally, add OIDC views to your url configuration (`urls.py`):
 
 ```python
-from .oidc_providers import my_oidc_provider
+from django_pyoidc.helper import OIDCHelper
+
+# `op_name` must be the name of your identity provider as used in the `DJANGO_PYOIDC` setting
+oidc_helper = OIDCHelper(op_name="sso")
 
 urlpatterns = [
-    path("auth", include(my_oidc_provider.get_urlpatterns())),
+    path(
+        "auth/",
+        include((oidc_helper.get_urlpatterns(), "django_pyoidc"), namespace="auth"),
+    ),
 ]
 ```
 
 And you are ready to go !
 
-If you struggle with those instructions, take a look at [the quickstart tutorial](https://django-pyoidc.readthedocs.io/en/latest/tutorial.html#getting-started).
+If you struggle with those instructions, take a look at [the quickstart tutorial](https://django-pyoidc.readthedocs.io/en/latest/tutorial.html#requirements).
 
 ## Usage/Examples
 

docs/explanation.rst

@@ -1,8 +1,5 @@
-Makina Django OIDC Explanations
-===============================
-
-Other OIDC libraries
---------------------
+Why make a new OIDC library ?
+=============================
 
 We decided to role our own OIDC integration with Django, and that is not a small work. As such we first performed an analysis of the existing libraries, evaluating whether or not we should contribute to them or implement our own.
 
@@ -15,6 +12,12 @@ Here are our criteria :
 * is it still maintained ?
 * does it supports *Bearer* authentication (for ``django-rest-framework``).
 
+
+`django-allauth <https://github.com/pennersr/django-allauth/>`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Todo**
+
 `django-auth-oidc <https://gitlab.com/aiakos/django-auth-oidc>`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -69,7 +72,7 @@ This library is based on ``django-auth-oidc`` and adds some glue to allow more f
 
 - Very old and unmaintained
 
- `Django OAuth Toolkit <https://github.com/jazzband/django-oauth-toolkit>`_
+`Django OAuth Toolkit <https://github.com/jazzband/django-oauth-toolkit>`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
@@ -85,10 +88,11 @@ This library is based on ``django-auth-oidc`` and adds some glue to allow more f
 - Documentation (which needs to covers also the *server* part) is not easy to use for an *simple* oidc client integration
 
 This Project Goals
--------------------
+==================
 
-This project aim to make OIDC client integration with Django easier while still being robust, exapandable and flexible.
+This project aim to make OIDC client integration with Django easier while still being robust, expandable and flexible.
 To reach this goal we wanted a project with:
+
 - good documentations, based on use cases and helping users doing the right things in the quite complex OIDC world
 - robust security components (handling the cryptography and security aspects of OIDC)
 - more real world usage than the too simple 'handle OIDC login' examples (like API modes, logouts, asynchronous logouts, MtoM mode, multi-tenant setup, etc.)
@@ -97,7 +101,7 @@ Handling the 'login' part in OIDC is quite easy, on the client side. And this pa
 
 Direct Logout and Asynchronous logouts are more complex to understand and manage. The next section is a deeper explanation on this subject.
 
-MtoM mode is about Machine-To-Machine communication, like B-to-B, the fact that you application may need to use OIDC not only to handle real
+MtoM mode is about Machine-To-Machine communication, like B-to-B, the fact that your application may need to use OIDC not only to handle real
 (human) users sessions, but also maybe connections made by some other applications, or you may also need to perform such operation (connecting
 a remote web service using OIDC, not using an human account but a service account instead, identifying as an application and not as a human).
 
@@ -298,8 +302,8 @@ Note: if your Django acts as an OIDC SSO server for other applications, receivin
 containing an iframe with front channel logouts links for all the client applications of your Django. In this library we consider the
 Django website to be only an OIDC client (not server) and we did not implement this cascading front channel logout specification.
 
-Cache Management
-----------------
+About caching
+=============
 
 This library depends on **Django cache system**. Why do an OIDC client depends on a cache ?
 
@@ -321,4 +325,4 @@ This data is stored in a database table.
     :alt: Illustration of how a user session is killed in a backchannel logout request
 
 .. image:: images/cache/oidc_bl_2.png
-    :alt: Illustration of how a user session is killed in a backchannel logout request
+    :alt: Illustration of how a user session is killed in a backchannel logout request