📝[#114] update setup config docs

maykinmedia · Nov 25, 2024 · dfbfe29 · dfbfe29
1 parent 25feb25
commit dfbfe29
Show file tree

Hide file tree

Showing 10 changed files with 58 additions and 39 deletions.
diff --git a/docs/setup_configuration.rst b/docs/setup_configuration.rst
@@ -22,50 +22,64 @@ put the ``AdminOIDCConfigurationStep`` in your django-setup-configuration steps:
 
     SETUP_CONFIGURATION_STEPS = [
         ...
-        "mozilla_django_oidc_db.setup_config.AdminOIDCConfigurationStep",
+        "mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep",
         ...
     ]
 
-Configuration Settings:
-=======================
+Configuration Settings YAML:
+============================
 
-* ``OIDC_DB_CONFIG_ENABLE``: enable setup configuration step
+
+The setup configuration admin must contain the following base keys to use setup configuration:
+
+* ``OIDC_DB_CONFIG_ENABLE``: enable setup configuration step boolean
 
 * ``OIDC_DB_SETUP_CONFIG_ADMIN_AUTH``: Dictionary that maps OIDC fields to their values.
 
 
 Example:
 
-.. code-block:: python
+.. code-block:: YAML
 
-    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/",
-    }
+    OTHER_ENABLE: True
+    OTHER_CONFiG:
+    ...
+    OIDC_DB_CONFIG_ENABLE: True
+    OIDC_DB_SETUP_CONFIG_ADMIN_AUTH:
+      oidc_rp_client_id: client-id
+      oidc_rp_client_secret: secret
+      endpoint_config:
+        oidc_op_discovery_endpoint: https://keycloak.local/protocol/openid-connect/
+    ...
 
 
+Any field from the ``OpenIDConnectConfig`` can be added to ``OIDC_DB_SETUP_CONFIG_ADMIN_AUTH`` (except endpoints, see below)
+
 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.
+* ``endpoint_config``: Dictionary containing endpoint information
 
-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).
+    * ``oidc_op_discovery_endpoint``: URL of your OpenID Connect provider discovery endpoint ending with a slash (`.well-known/...` will be added automatically).
 
-   **OR**
+            **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
+    * ``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
 
 
+The endpoints must be provided in the ``endpoint_config`` dictionary.
+You can add the discovery endpoint to automatically fetch the other endpoints.
+Otherwise the endpoints must be specified individually.
+Providing both will cause the validation to fail.
 
 Optional Fields:
 """"""""""""""""
+All the following keys are placed in the ``OIDC_DB_SETUP_CONFIG_ADMIN_AUTH`` dictionary.
 
 * ``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.

diff --git a/mozilla_django_oidc_db/setup_configuration/steps.py b/mozilla_django_oidc_db/setup_configuration/steps.py
@@ -16,8 +16,8 @@ class AdminOIDCConfigurationStep(BaseConfigurationStep[AdminOIDCConfigurationMod
 
     verbose_name = "Configuration for admin login via OpenID Connect"
     config_model = AdminOIDCConfigurationModel
-    namespace = "ADMIN_OIDC"
-    enable_setting = "ADMIN_OIDC_CONFIG_ENABLE"
+    namespace = "OIDC_DB_SETUP_CONFIG_ADMIN_AUTH"
+    enable_setting = "OIDC_DB_CONFIG_ENABLE"
 
     def execute(self, model: AdminOIDCConfigurationModel) -> None:
 

diff --git a/testapp/settings.py b/testapp/settings.py
@@ -87,7 +87,6 @@
 
     INSTALLED_APPS += ["django_setup_configuration"]
 
-    OIDC_DB_CONFIG_ENABLE = True
     SETUP_CONFIGURATION_STEPS = [
         "mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep",
     ]

diff --git a/tests/setupconfig/files/defaults.yml b/tests/setupconfig/files/defaults.yml
@@ -1,5 +1,5 @@
-ADMIN_OIDC_CONFIG_ENABLE: True
-ADMIN_OIDC:
+OIDC_DB_CONFIG_ENABLE: True
+OIDC_DB_SETUP_CONFIG_ADMIN_AUTH:
   oidc_rp_client_id: client-id
   oidc_rp_client_secret: secret
   endpoint_config:

diff --git a/tests/setupconfig/files/discovery.yml b/tests/setupconfig/files/discovery.yml
@@ -1,5 +1,5 @@
-ADMIN_OIDC_CONFIG_ENABLE: True
-ADMIN_OIDC:
+OIDC_DB_CONFIG_ENABLE: True
+OIDC_DB_SETUP_CONFIG_ADMIN_AUTH:
   oidc_rp_client_id: testid
   oidc_rp_client_secret: 7DB3KUAAizYCcmZufpHRVOcD0TOkNO3I
   endpoint_config:

diff --git a/tests/setupconfig/files/discovery_disabled.yml b/tests/setupconfig/files/discovery_disabled.yml
@@ -1,5 +1,5 @@
-ADMIN_OIDC_CONFIG_ENABLE: False
-ADMIN_OIDC:
+OIDC_DB_CONFIG_ENABLE: False
+OIDC_DB_SETUP_CONFIG_ADMIN_AUTH:
   oidc_rp_client_id: testid
   oidc_rp_client_secret: 7DB3KUAAizYCcmZufpHRVOcD0TOkNO3I
   endpoint_config:

diff --git a/tests/setupconfig/files/empty.yml b/tests/setupconfig/files/empty.yml
@@ -1,2 +1,2 @@
-ADMIN_OIDC_CONFIG_ENABLE: True
-ADMIN_OIDC: {}
+OIDC_DB_CONFIG_ENABLE: True
+OIDC_DB_SETUP_CONFIG_ADMIN_AUTH: {}
diff --git a/tests/setupconfig/files/full_setup.yml b/tests/setupconfig/files/full_setup.yml
@@ -1,5 +1,5 @@
-ADMIN_OIDC_CONFIG_ENABLE: True
-ADMIN_OIDC:
+OIDC_DB_CONFIG_ENABLE: True
+OIDC_DB_SETUP_CONFIG_ADMIN_AUTH:
   oidc_rp_client_id: client-id
   oidc_rp_client_secret: secret
   oidc_rp_scopes_list:

diff --git a/tests/setupconfig/files/partial_endpoints.yml b/tests/setupconfig/files/partial_endpoints.yml
@@ -1,5 +1,5 @@
-ADMIN_OIDC_CONFIG_ENABLE: True
-ADMIN_OIDC:
+OIDC_DB_CONFIG_ENABLE: True
+OIDC_DB_SETUP_CONFIG_ADMIN_AUTH:
   oidc_rp_client_id: client-id
   oidc_rp_client_secret: secret
   endpoint_config:

diff --git a/tests/setupconfig/test_steps.py b/tests/setupconfig/test_steps.py
@@ -84,9 +84,13 @@ def test_required_settings():
         command_error.value
     )
 
-    assert "ADMIN_OIDC.oidc_rp_client_id" in str(command_error.value)
-    assert "ADMIN_OIDC.oidc_rp_client_secret" in str(command_error.value)
-    assert "ADMIN_OIDC.endpoint_config" in str(command_error.value)
+    assert "OIDC_DB_SETUP_CONFIG_ADMIN_AUTH.oidc_rp_client_id" in str(
+        command_error.value
+    )
+    assert "OIDC_DB_SETUP_CONFIG_ADMIN_AUTH.oidc_rp_client_secret" in str(
+        command_error.value
+    )
+    assert "OIDC_DB_SETUP_CONFIG_ADMIN_AUTH.endpoint_config" in str(command_error.value)
 
     config = OpenIDConnectConfig.get_solo()
     assert not config.enabled
@@ -111,11 +115,13 @@ def test_partial_endpoints_provided():
         command_error.value
     )
 
-    assert "ADMIN_OIDC.endpoint_config.all.oidc_op_token_endpoint" in str(
-        command_error.value
+    assert (
+        "OIDC_DB_SETUP_CONFIG_ADMIN_AUTH.endpoint_config.all.oidc_op_token_endpoint"
+        in str(command_error.value)
     )
-    assert "ADMIN_OIDC.endpoint_config.all.oidc_op_user_endpoint" in str(
-        command_error.value
+    assert (
+        "OIDC_DB_SETUP_CONFIG_ADMIN_AUTH.endpoint_config.all.oidc_op_user_endpoint"
+        in str(command_error.value)
     )
 
     config = OpenIDConnectConfig.get_solo()