Merge pull request #155 from maykinmedia/feature/154-add-options-example-to-setup-config-documentation

📝 [#154] add options example to setup config documentation

Author: stevenbal

mozilla_django_oidc_db/setup_configuration/models.py

@@ -70,7 +70,7 @@ class OIDCConfigProviderModel(ConfigurationModel):
         OIDCProvider,
         "identifier",
         description="a unique identifier for this OIDC provider.",
-        examples=["admin-oidc-provider"],
+        examples=["test-oidc-provider"],
     )
     endpoint_config: OIDCProviderConfigUnion
 
@@ -95,12 +95,36 @@ class AdminOIDCConfigurationModelItem(ConfigurationModel):
 
     enabled: bool = DjangoModelRef(OIDCClient, "enabled", default=True)
     oidc_rp_scopes_list: list[str] = DjangoModelRef(OIDCClient, "oidc_rp_scopes_list")
-    options: dict = DjangoModelRef(OIDCClient, "options", default_factory=dict)
+    options: dict = DjangoModelRef(
+        OIDCClient,
+        "options",
+        default_factory=dict,
+        examples=[
+            {
+                "user_settings": {
+                    "claim_mappings": {
+                        "username": ["sub"],
+                        "email": ["email"],
+                        "first_name": ["given_name"],
+                        "last_name": ["family_name"],
+                    },
+                    "username_case_sensitive": False,
+                },
+                "groups_settings": {
+                    "make_users_staff": True,
+                    "superuser_group_names": ["superuser"],
+                    "sync": True,
+                    "sync_pattern": "*",
+                    "claim_mapping": ["roles"],
+                },
+            }
+        ],
+    )
 
     endpoint_config: OIDCProviderConfigUnion | None = Field(
         description=_("Configuration for the OIDC Provider endpoints."),
         default=None,
-        deprecated=True,
+        deprecated="Moved to `providers.endpoint_config`",
     )
     oidc_provider_identifier: str = DjangoModelRef(
         OIDCProvider, "identifier", examples=["test-oidc-provider"], default=""
@@ -114,7 +138,7 @@ class AdminOIDCConfigurationModelItem(ConfigurationModel):
             "last_name": ["family_name"],
         },
         description=_("Mapping from User model field names to a path in the claim."),
-        deprecated=True,
+        deprecated="Moved to `items.options.user_settings.claim_mappings`",
     )
     oidc_token_use_basic_auth: bool = Field(
         default=False,
@@ -123,67 +147,67 @@ class AdminOIDCConfigurationModelItem(ConfigurationModel):
             "header when obtaining the access token. Otherwise, they are sent in the "
             "request body."
         ),
-        deprecated=True,
+        deprecated="Moved to `providers.oidc_token_use_basic_auth`",
     )
     oidc_use_nonce: bool = Field(
         default=True,
         description=_("Controls whether the client uses nonce verification"),
-        deprecated=True,
+        deprecated="Moved to providers.oidc_use_nonce",
     )
     oidc_nonce_size: int = Field(
         default=32,
         description=_(
             "Sets the length of the random string used for nonce verification"
         ),
-        deprecated=True,
+        deprecated="Moved to `providers.oidc_nonce_size`",
     )
     oidc_state_size: int = Field(
         default=32,
         description=_(
             "Sets the length of the random string used for state verification"
         ),
-        deprecated=True,
+        deprecated="Moved to `providers.oidc_state_size`",
     )
     # Arrays are overridden to make the typing simpler (the underlying Django field is an ArrayField, which is non-standard)
     username_claim: list[str] = Field(
         default_factory=lambda: ["sub"],
         description=_("Path in the claims to the value to use as username."),
-        deprecated=True,
+        deprecated="Moved to `items.options.user_settings.claim_mappings.username`",
         examples=[["nested", "username", "claim"]],
     )
     groups_claim: list[str] = Field(
         default_factory=lambda: ["roles"],
         description=_("Path in the claims to the value with group names."),
-        deprecated=True,
+        deprecated="Moved to `items.options.group_settings.claim_mapping`",
         examples=[["nested", "group", "claim"]],
     )
     superuser_group_names: list[str] = Field(
         default_factory=list,
         description=_("Superuser group names"),
-        deprecated=True,
+        deprecated="Moved to `items.options.group_settings.superuser_group_names`",
         examples=[["superusers"]],
     )
     default_groups: list[str] = Field(
         default_factory=list,
         description=_("Default group names"),
-        deprecated=True,
+        deprecated="Moved `items.options.group_settings.default_groups`",
         examples=[["read-only-users"]],
     )
     sync_groups: bool = Field(
         description=_("Whether to sync local groups"),
-        deprecated=True,
+        deprecated="Moved to `items.options.group_settings.sync`",
         examples=[True],
         default=True,
     )
     sync_groups_glob_pattern: str = Field(
         description=_("Pattern that the group names to sync should follow."),
-        deprecated=True,
+        deprecated="Moved to `items.options.group_settings.sync_pattern`",
         examples=["*"],
         default="*",
     )
     make_users_staff: bool = Field(
         description=_("Whether to make the users staff."),
-        deprecated=True,
+        deprecated="Moved to `items.options.groups_settings.make_users_staff`",
         examples=[False],
         default=False,
     )

pyproject.toml

@@ -46,7 +46,7 @@ Changelog = "https://github.com/maykinmedia/mozilla-django-oidc-db/blob/master/C
 
 [project.optional-dependencies]
 setup-configuration = [
-    "django-setup-configuration>=0.8.2",
+    "django-setup-configuration>=0.11.0",
 ]
 tests = [
     "psycopg",