From 25feb25b79f44157c35677e9aeb7ce9721ba094a Mon Sep 17 00:00:00 2001 From: Conor Holden Date: Tue, 22 Oct 2024 17:26:09 +0200 Subject: [PATCH] :memo:[#114] add setup configuration documentation --- CHANGELOG.rst | 9 ++++ docs/index.rst | 1 + docs/quickstart.rst | 6 +++ docs/setup_configuration.rst | 92 ++++++++++++++++++++++++++++++++++++ 4 files changed, 108 insertions(+) create mode 100644 docs/setup_configuration.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 901237a..3e2d7c9 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -2,6 +2,15 @@ Changelog ========= +0.20.0 (????) +============= + +New Features: + +* Add optional support for `django-setup-configuration`_ + +.. _django-setup-configuration: https://pypi.org/project/django-setup-configuration/ + 0.19.0 (2024-07-02) =================== diff --git a/docs/index.rst b/docs/index.rst index 132e0f9..4936494 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f7595f9..e8ee57b 100644 --- a/docs/quickstart.rst +++ b/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 --------------- diff --git a/docs/setup_configuration.rst b/docs/setup_configuration.rst new file mode 100644 index 0000000..e3205d1 --- /dev/null +++ b/docs/setup_configuration.rst @@ -0,0 +1,92 @@ +========================== +Django Setup Configuration +========================== + +There is optional support for`django-setup-configuration`_ that allows you to automatically configure the +OpenID Connect configuration the ``setup_configuration`` commmand. + +You must install the ``setupconfig`` dependency group: + +.. _django-setup-configuration: https://pypi.org/project/django-setup-configuration/ + + +.. 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.setup_config.AdminOIDCConfigurationStep", + ... + ] + +Configuration Settings: +======================= + +* ``OIDC_DB_CONFIG_ENABLE``: enable setup configuration step + +* ``OIDC_DB_SETUP_CONFIG_ADMIN_AUTH``: Dictionary that maps OIDC fields to their values. + + +Example: + +.. code-block:: python + + OIDC_DB_SETUP_CONFIG_ADMIN_AUTH = { + "oidc_rp_client_id": "client-id", + "oidc_rp_client_secret": "secret", + "oidc_op_discovery_endpoint": "https://keycloak.local/protocol/openid-connect/", + } + + +Required Fields: +"""""""""""""""" + + +* ``oidc_rp_client_id``: OpenID Connect client ID from the OIDC Provider. +* ``oidc_rp_client_secret``: OpenID Connect secret from the OIDC Provider. + +The discovery endpoint can be configured to automatically fetch the other endpoints. Otherwise the endpoints must be set individually. + +* ``oidc_op_discovery_endpoint``: URL of your OpenID Connect provider discovery endpoint ending with a slash (`.well-known/...` will be added automatically). + + **OR** + +* ``oidc_op_authorization_endpoint``: URL of your OpenID Connect provider authorization endpoint +* ``oidc_op_token_endpoint``: URL of your OpenID Connect provider token endpoint +* ``oidc_op_user_endpoint``: URL of your OpenID Connect provider userinfo endpoint + + + +Optional Fields: +"""""""""""""""" + +* ``oidc_op_jwks_endpoint``: URL of your OpenID Connect provider JSON Web Key Set endpoint. + Required if ``RS256`` is used as signing algorithm. No default value. +* ``claim_mapping``: Mapping from user-model fields to OIDC claims. + Defaults to ``{"email": ["email"], "first_name": ["given_name"], "last_name": ["family_name"]}`` +* ``username_claim``: The name of the OIDC claim that is used as the username. Defaults to ``["sub"]`` +* ``groups_claim``: The name of the OIDC claim that holds the values to map to local user groups. Defaults to ``["roles"]`` +* ``default_groups``: The default groups to which every user logging in with OIDC will be assigned. No default values. +* ``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. Defaults to empty list. +* ``make_users_staff``: Users will be flagged as being a staff user automatically. + This allows users to login to the admin interface. Defaults to ``False``. +* ``oidc_use_nonce``: Controls whether the OpenID Connect client uses nonce verification. Defaults to ``True``. +* ``oidc_nonce_size``: Sets the length of the random string used for OpenID Connect nonce verification. Defaults to ``32``. +* ``oidc_state_size``: Sets the length of the random string used for OpenID Connect state verification. Defaults to ``32``. +* ``oidc_rp_idp_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. No default. +* ``oidc_rp_scopes_list``: OpenID Connect scopes that are requested during login. Defaults to ``["openid", "email", "profile"]``. +* ``oidc_rp_sign_algo``: Algorithm the Identity Provider uses to sign ID tokens. Defaults to ``"HS256"``. +* ``sync_groups``: If checked, local user groups will be created for group names present in the groups claim, + if they do not exist yet locally. Defaults to ``True``. +* ``sync_groups_glob_pattern``: The glob pattern that groups must match to be synchronized to the local database. Defaults to ``"*"``. +* ``userinfo_claims_source``: Indicates the source from which the user information claims should be extracted + (``"userinfo_endpoint"`` or ``"id_token"``). Defaults to ``"userinfo_endpoint"``.