Skip to content

Commit

Permalink
📝[#114] update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@Coperh
Coperh committed Aug 14, 2024
1 parent cd68db8 commit 8761799
Show file tree
Hide file tree
Showing 3 changed files with 69 additions and 194 deletions.
3 changes: 2 additions & 1 deletion CHANGELOG.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@ Changelog

New Features:

* Add optional support for ``django setup configuration``
* Add optional support for `django-setup-configuration`_

.. _django-setup-configuration: https://pypi.org/project/django-setup-configuration/

0.19.0 (2024-07-02)
===================
Expand Down
251 changes: 67 additions & 184 deletions docs/setup_configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,190 +20,73 @@ put the ``AdminOIDCConfigurationStep`` in your django-setup-configuration steps:
SETUP_CONFIGURATION_STEPS = [
...
"mozilla_django_oidc_db.setupconfig.bootstrap.auth.AdminOIDCConfigurationStep",
"mozilla_django_oidc_db.setupconfig.bootstrap.AdminOIDCConfigurationStep",
...
]
Settings Overview
=================


Enable/Disable configuration:
"""""""""""""""""""""""""""""

::

ADMIN_OIDC_CONFIG_ENABLE



Required:
"""""""""

::

ADMIN_OIDC_OIDC_RP_CLIENT_ID
ADMIN_OIDC_OIDC_RP_CLIENT_SECRET
ADMIN_OIDC_OIDC_OP_AUTHORIZATION_ENDPOINT
ADMIN_OIDC_OIDC_OP_TOKEN_ENDPOINT
ADMIN_OIDC_OIDC_OP_USER_ENDPOINT


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
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_authorization_endpoint": "https://keycloak.local/protocol/openid-connect/auth",
"oidc_op_token_endpoint": "https://keycloak.local/protocol/openid-connect/token",
"oidc_op_user_endpoint": "https://keycloak.local/protocol/openid-connect/userinfo",
}
Required Fields:
""""""""""""""""


* ``oidc_rp_client_id``: OpenID Connect client ID provided by the OIDC Provider.
* ``oidc_rp_client_secret``: OpenID Connect secret provided by the OIDC Provider.

The discovery endpoint can be provided to automatically fetch the other endpoints. Otherwise they must be provided 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"``.
9 changes: 0 additions & 9 deletions mozilla_django_oidc_db/setupconfig/boostrap.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,6 @@ class AdminOIDCConfigurationStep(BaseConfigurationStep):
"""

verbose_name = "Configuration for admin login via OpenID Connect"
required_fields = {
"OIDC_DB_SETUP_CONFIG_ADMIN_AUTH": [
"oidc_rp_client_id",
"oidc_rp_client_secret",
"oidc_op_authorization_endpoint",
"oidc_op_token_endpoint",
"oidc_op_user_endpoint",
]
}
required_settings = ["OIDC_DB_SETUP_CONFIG_ADMIN_AUTH"]
enable_setting = "OIDC_DB_CONFIG_ENABLE"

Expand Down

0 comments on commit 8761799

Please sign in to comment.