From aca780282d77f2d6a2bfaeff5f042aac51a7e058 Mon Sep 17 00:00:00 2001 From: Conor Holden Date: Fri, 26 Jul 2024 14:53:14 +0200 Subject: [PATCH] :memo:[#114] add documentation --- CHANGELOG.rst | 3 + docs/index.rst | 1 + docs/quickstart.rst | 6 + docs/setup_configuration.rst | 207 ++++++++++++++++++ .../setupconfig/boostrap.py | 1 - 5 files changed, 217 insertions(+), 1 deletion(-) create mode 100644 docs/setup_configuration.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 48a940a..b506f32 100644 --- a/CHANGELOG.rst +++ b/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) 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..8c27272 --- /dev/null +++ b/docs/setup_configuration.rst @@ -0,0 +1,207 @@ +========================== +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", + ... + ] + +Settings Overview +================= + + +Enable/Disable configuration: +""""""""""""""""""""""""""""" + +:: + + ADMIN_OIDC_CONFIG_ENABLE + + + +Required: +""""""""" + +:: + + ADMIN_OIDC_DEFAULT_GROUPS + ADMIN_OIDC_OIDC_RP_CLIENT_ID + ADMIN_OIDC_OIDC_RP_CLIENT_SECRET + + +All settings: +""""""""""""" + +:: + + ADMIN_OIDC_CLAIM_MAPPING + ADMIN_OIDC_DEFAULT_GROUPS + ADMIN_OIDC_GROUPS_CLAIM + ADMIN_OIDC_MAKE_USERS_STAFF + ADMIN_OIDC_OIDC_NONCE_SIZE + ADMIN_OIDC_OIDC_OP_AUTHORIZATION_ENDPOINT + ADMIN_OIDC_OIDC_OP_DISCOVERY_ENDPOINT + ADMIN_OIDC_OIDC_OP_JWKS_ENDPOINT + ADMIN_OIDC_OIDC_OP_TOKEN_ENDPOINT + ADMIN_OIDC_OIDC_OP_USER_ENDPOINT + ADMIN_OIDC_OIDC_RP_CLIENT_ID + ADMIN_OIDC_OIDC_RP_CLIENT_SECRET + ADMIN_OIDC_OIDC_RP_IDP_SIGN_KEY + ADMIN_OIDC_OIDC_RP_SCOPES_LIST + ADMIN_OIDC_OIDC_RP_SIGN_ALGO + ADMIN_OIDC_OIDC_STATE_SIZE + ADMIN_OIDC_OIDC_USE_NONCE + ADMIN_OIDC_SUPERUSER_GROUP_NAMES + ADMIN_OIDC_SYNC_GROUPS + ADMIN_OIDC_SYNC_GROUPS_GLOB_PATTERN + ADMIN_OIDC_USERINFO_CLAIMS_SOURCE + ADMIN_OIDC_USERNAME_CLAIM + +Detailed Information +==================== + +:: + + Variable ADMIN_OIDC_CLAIM_MAPPING + Setting claim mapping + Description Mapping from user-model fields to OIDC claims + Possible values Mapping: {'some_key': 'Some value'} + Default value {'email': 'email', 'first_name': 'given_name', 'last_name': 'family_name'} + + Variable ADMIN_OIDC_GROUPS_CLAIM + Setting groups claim + Description The name of the OIDC claim that holds the values to map to local user groups. + Possible values string, comma-delimited ('foo,bar,baz') + Default value roles + + Variable ADMIN_OIDC_MAKE_USERS_STAFF + Setting make users staff + Description 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. + Possible values True, False + Default value False + + Variable ADMIN_OIDC_OIDC_NONCE_SIZE + Setting Nonce size + Description Sets the length of the random string used for OpenID Connect nonce verification + Possible values string representing a positive integer + Default value 32 + + Variable ADMIN_OIDC_OIDC_OP_AUTHORIZATION_ENDPOINT + Setting Authorization endpoint + Description URL of your OpenID Connect provider authorization endpoint + Possible values string (URL) + Default value No default + + Variable ADMIN_OIDC_OIDC_OP_DISCOVERY_ENDPOINT + Setting Discovery endpoint + Description 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. + Possible values string (URL) + Default value No default + + Variable ADMIN_OIDC_OIDC_OP_JWKS_ENDPOINT + Setting JSON Web Key Set endpoint + Description URL of your OpenID Connect provider JSON Web Key Set endpoint. Required if `RS256` is used as signing algorithm. + Possible values string (URL) + Default value No default + + Variable ADMIN_OIDC_OIDC_OP_TOKEN_ENDPOINT + Setting Token endpoint + Description URL of your OpenID Connect provider token endpoint + Possible values string (URL) + Default value No default + + Variable ADMIN_OIDC_OIDC_OP_USER_ENDPOINT + Setting User endpoint + Description URL of your OpenID Connect provider userinfo endpoint + Possible values string (URL) + Default value No default + + Variable ADMIN_OIDC_OIDC_RP_CLIENT_ID + Setting OpenID Connect client ID + Description OpenID Connect client ID provided by the OIDC Provider + Possible values string + Default value No default + + Variable ADMIN_OIDC_OIDC_RP_CLIENT_SECRET + Setting OpenID Connect secret + Description OpenID Connect secret provided by the OIDC Provider + Possible values string + Default value No default + + Variable ADMIN_OIDC_OIDC_RP_IDP_SIGN_KEY + Setting Sign key + Description 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. + Possible values string + Default value No default + + Variable ADMIN_OIDC_OIDC_RP_SCOPES_LIST + Setting OpenID Connect scopes + Description OpenID Connect scopes that are requested during login + Possible values string, comma-delimited ('foo,bar,baz') + Default value openid, email, profile + + Variable ADMIN_OIDC_OIDC_RP_SIGN_ALGO + Setting OpenID sign algorithm + Description Algorithm the Identity Provider uses to sign ID tokens + Possible values string + Default value HS256 + + Variable ADMIN_OIDC_OIDC_STATE_SIZE + Setting State size + Description Sets the length of the random string used for OpenID Connect state verification + Possible values string representing a positive integer + Default value 32 + + Variable ADMIN_OIDC_OIDC_USE_NONCE + Setting Use nonce + Description Controls whether the OpenID Connect client uses nonce verification + Possible values True, False + Default value True + + Variable ADMIN_OIDC_SUPERUSER_GROUP_NAMES + Setting Superuser group names + Description 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. + Possible values string, comma-delimited ('foo,bar,baz') + Default value + + Variable ADMIN_OIDC_SYNC_GROUPS + Setting Create local user groups if they do not exist yet + Description If checked, local user groups will be created for group names present in the groups claim, if they do not exist yet locally. + Possible values True, False + Default value True + + Variable ADMIN_OIDC_SYNC_GROUPS_GLOB_PATTERN + Setting groups glob pattern + Description The glob pattern that groups must match to be synchronized to the local database. + Possible values string + Default value * + + Variable ADMIN_OIDC_USERINFO_CLAIMS_SOURCE + Setting user information claims extracted from + Description Indicates the source from which the user information claims should be extracted. + Possible values userinfo_endpoint, id_token + Default value userinfo_endpoint + + Variable ADMIN_OIDC_USERNAME_CLAIM + Setting username claim + Description The name of the OIDC claim that is used as the username + Possible values string, comma-delimited ('foo,bar,baz') + Default value sub \ No newline at end of file diff --git a/mozilla_django_oidc_db/setupconfig/boostrap.py b/mozilla_django_oidc_db/setupconfig/boostrap.py index 821a8a9..d4e917a 100644 --- a/mozilla_django_oidc_db/setupconfig/boostrap.py +++ b/mozilla_django_oidc_db/setupconfig/boostrap.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"