📝[#114] add documentation

CHANGELOG.rst

@@ -5,6 +5,9 @@ Changelog
 0.20.0 (????)
 =============
 
+New Features:
+
+* Add optional support for ``django setup configuration``
 
 
 0.19.0 (2024-07-02)

docs/index.rst

@@ -33,6 +33,7 @@ Using ``email`` as the unique identifier is not recommended, as mentioned in the
 
    quickstart
    customizing
+   setup_configuration
    reference
    architecture
    changelog

docs/quickstart.rst

@@ -24,6 +24,12 @@ This will also install the following packages:
 - ``django-solo``
 - ``django-jsonform``
 
+You can optionally install ``django-setup-configuration`` support with:
+
+.. code-block:: bash
+
+    pip install mozilla-django-oidc-db[setupconfig]
+
 Django settings
 ---------------
 

docs/setup_configuration.rst

@@ -0,0 +1,66 @@
+==========================
+Django Setup Configuration
+==========================
+
+There is optional support for ``django-setup-configuration`` that allows you to automatically configure the
+OpenID Connect configuration the the ``setup_configuration`` commmand.
+
+You must install the ``setupconfig`` dependency:
+
+
+.. code-block:: bash
+
+    pip install mozilla-django-oidc-db[setupconfig]
+
+
+You must then define the required and any optional django settings mentioned below and
+put the ``AdminOIDCConfigurationStep`` in your django-setup-configuration steps:
+
+.. code-block:: python
+
+    SETUP_CONFIGURATION_STEPS = [
+        ...
+        "mozilla_django_oidc_db.setupconfig.bootstrap.auth.AdminOIDCConfigurationStep",
+        ...
+    ]
+
+Environment Variables
+===============================
+
+Required
+--------
+
+* ``ADMIN_OIDC_OIDC_RP_CLIENT_ID``: OpenID Connect client ID – indicates whether OpenID Connect for
+  authentication/authorization is enabled
+* ``ADMIN_OIDC_OIDC_RP_CLIENT_SECRET``: OpenID Connect secret – client ID provided by the OIDC Provider
+
+
+Optional
+--------
+
+
+* ``ADMIN_OIDC_OIDC_RP_SCOPES_LIST``: OpenID Connect scopes – scopes that are requested during login
+* ``ADMIN_OIDC_OIDC_RP_SIGN_ALGO``: OpenID sign algorithm – algorithm the Identity Provider uses to sign ID tokens
+* ``ADMIN_OIDC_OIDC_RP_IDP_SIGN_KEY``: Sign key – key the Identity Provider uses to sign ID tokens in the case
+  of an RSA sign algorithm. Should be the signing key in PEM or DER format.
+* ``ADMIN_OIDC_OIDC_OP_DISCOVERY_ENDPOINT``: Discovery endpoint – URL of your OpenID Connect provider discovery endpoint ending with a slash
+  (`.well–known/...` will be added automatically). If this is provided, the remaining endpoints can be omitted, as they will be derived from this endpoint.
+* ``ADMIN_OIDC_OIDC_OP_JWKS_ENDPOINT``: JSON Web Key Set endpoint – URL of your OpenID Connect provider JSON Web Key Set endpoint.
+  Required if `RS256` is used as signing algorithm.
+* ``ADMIN_OIDC_OIDC_OP_AUTHORIZATION_ENDPOINT``: Authorization endpoint – URL of your OpenID Connect provider authorization endpoint
+* ``ADMIN_OIDC_OIDC_OP_TOKEN_ENDPOINT``: Token endpoint – URL of your OpenID Connect provider token endpoint
+* ``ADMIN_OIDC_OIDC_OP_USER_ENDPOINT``: User endpoint – URL of your OpenID Connect provider userinfo endpoint
+* ``ADMIN_OIDC_USERNAME_CLAIM``: Username claim – the name of the OIDC claim that is used as the username
+* ``ADMIN_OIDC_GROUPS_CLAIM``: groups claim – the name of the OIDC claim that holds the values to map to local user groups.
+* ``ADMIN_OIDC_CLAIM_MAPPING``: claim mapping – mapping from user-model fields to OIDC claims
+* ``ADMIN_OIDC_SYNC_GROUPS``: create local user groups if they do not exist yet"
+* ``ADMIN_OIDC_SYNC_GROUPS_GLOB_PATTERN``: groups glob pattern – The glob pattern that groups must match to be synchronized to the local database.
+* ``ADMIN_OIDC_DEFAULT_GROUPS``: default groups – the default groups to which every user logging in with OIDC will be assigned
+* ``ADMIN_OIDC_MAKE_USERS_STAFF``: make users staff – Users will be flagged as being a staff user automatically. This allows
+  users to login to the admin interface. By default they have no permissions, even if they are staff.
+* ``ADMIN_OIDC_SUPERUSER_GROUP_NAMES``: superuser group names – "If any of these group names are present in the claims upon login,
+  the user will be marked as a superuser. If none of these groups are present the user will lose superuser permissions.
+* ``ADMIN_OIDC_OIDC_USE_NONCE``: use nonce – controls whether the OpenID Connect client uses nonce verification
+* ``ADMIN_OIDC_OIDC_NONCE_SIZE``: nonce size – Sets the length of the random string used for OpenID Connect nonce verification
+* ``ADMIN_OIDC_OIDC_STATE_SIZE``: state size – sets the length of the random string used for OpenID Connect state verification
+* ``ADMIN_OIDC_USERINFO_CLAIMS_SOURCE``: user information claims extracted from – indicates the source from which the user information claims should be extracted.

mozilla_django_oidc_db/setupconfig/bootstrap/auth.py

@@ -38,7 +38,6 @@ class AdminOIDCConfigurationStep(BaseConfigurationStep):
         "ADMIN_OIDC_OIDC_USE_NONCE",
         "ADMIN_OIDC_OIDC_NONCE_SIZE",
         "ADMIN_OIDC_OIDC_STATE_SIZE",
-        "ADMIN_OIDC_OIDC_EXEMPT_URLS",
         "ADMIN_OIDC_USERINFO_CLAIMS_SOURCE",
     ]
     enable_setting = "ADMIN_OIDC_CONFIG_ENABLE"