Skip to content

Improve settings documentation #1567

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 18, 2025
Merged

Improve settings documentation #1567

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 45 additions & 35 deletions docs/settings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
Settings
========

Our configurations are all namespaced under the ``OAUTH2_PROVIDER`` settings with the exception of
``OAUTH2_PROVIDER_APPLICATION_MODEL``, ``OAUTH2_PROVIDER_ACCESS_TOKEN_MODEL``, ``OAUTH2_PROVIDER_GRANT_MODEL``,
``OAUTH2_PROVIDER_REFRESH_TOKEN_MODEL``: this is because of the way Django currently implements
swappable models. See `issue #90 <https://github.com/jazzband/django-oauth-toolkit/issues/90>`_ for details.
Our configurations are all namespaced under the ``OAUTH2_PROVIDER`` settings, with the exception
of the `List of non-namespaced settings`_.

For example:

Expand All @@ -24,32 +22,24 @@ For example:
A big *thank you* to the guys from Django REST Framework for inspiring this.


List of available settings
--------------------------
List of available settings within OAUTH2_PROVIDER
-------------------------------------------------

ACCESS_TOKEN_EXPIRE_SECONDS
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Default: ``36000``

The number of seconds an access token remains valid. Requesting a protected
resource after this duration will fail. Keep this value high enough so clients
can cache the token for a reasonable amount of time.

ACCESS_TOKEN_MODEL
~~~~~~~~~~~~~~~~~~
The import string of the class (model) representing your access tokens. Overwrite
this value if you wrote your own implementation (subclass of
``oauth2_provider.models.AccessToken``).

ACCESS_TOKEN_GENERATOR
~~~~~~~~~~~~~~~~~~~~~~
Import path of a callable used to generate access tokens.
``oauthlib.oauth2.rfc6749.tokens.random_token_generator`` is (normally) used if not provided.

ALLOWED_REDIRECT_URI_SCHEMES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Default: ``["http", "https"]``

A list of schemes that the ``redirect_uri`` field will be validated against.
Expand All @@ -65,7 +55,6 @@ a per-application basis.

ALLOW_URI_WILDCARDS
~~~~~~~~~~~~~~~~~~~

Default: ``False``

SECURITY WARNING: Enabling this setting can introduce security vulnerabilities. Only enable
Expand Down Expand Up @@ -96,7 +85,6 @@ deployments for development previews and user acceptance testing.

ALLOWED_SCHEMES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Default: ``["https"]``

A list of schemes that the ``allowed_origins`` field will be validated against.
Expand All @@ -105,13 +93,6 @@ Adding ``"http"`` to the list is considered to be safe only for local developmen
Note that `OAUTHLIB_INSECURE_TRANSPORT <https://oauthlib.readthedocs.io/en/latest/oauth2/security.html#envvar-OAUTHLIB_INSECURE_TRANSPORT>`_
environment variable should be also set to allow HTTP origins.


APPLICATION_MODEL
~~~~~~~~~~~~~~~~~
The import string of the class (model) representing your applications. Overwrite
this value if you wrote your own implementation (subclass of
``oauth2_provider.models.Application``).

AUTHORIZATION_CODE_EXPIRE_SECONDS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Default: ``60``
Expand Down Expand Up @@ -214,12 +195,6 @@ period the application, the app then has only a consumed refresh token and the
only recourse is to have the user re-authenticate. A suggested value, if this
is enabled, is 2 minutes.

REFRESH_TOKEN_MODEL
~~~~~~~~~~~~~~~~~~~
The import string of the class (model) representing your refresh tokens. Overwrite
this value if you wrote your own implementation (subclass of
``oauth2_provider.models.RefreshToken``).

REFRESH_TOKEN_REUSE_PROTECTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When this is set to ``True`` (default ``False``), and ``ROTATE_REFRESH_TOKEN`` is used, the server will check
Expand Down Expand Up @@ -257,15 +232,15 @@ Defaults to ``oauth2_provider.scopes.SettingsScopes``, which reads scopes throug

SCOPES
~~~~~~
.. note:: (0.12.0+) Only used if ``ACCESS_TOKEN_GENERATOR`` is set to the SettingsScopes default.
.. note:: (0.12.0+) Only used if ``SCOPES_BACKEND_CLASS`` is set to the SettingsScopes default.

A dictionary mapping each scope name to its human description.

.. _settings_default_scopes:

DEFAULT_SCOPES
~~~~~~~~~~~~~~
.. note:: (0.12.0+) Only used if ``ACCESS_TOKEN_GENERATOR`` is set to the SettingsScopes default.
.. note:: (0.12.0+) Only used if ``SCOPES_BACKEND_CLASS`` is set to the SettingsScopes default.

A list of scopes that should be returned by default.
This is a subset of the keys of the ``SCOPES`` setting.
Expand All @@ -277,13 +252,13 @@ By default this is set to ``'__all__'`` meaning that the whole set of ``SCOPES``

READ_SCOPE
~~~~~~~~~~
.. note:: (0.12.0+) Only used if ``ACCESS_TOKEN_GENERATOR`` is set to the SettingsScopes default.
.. note:: (0.12.0+) Only used if ``SCOPES_BACKEND_CLASS`` is set to the SettingsScopes default.

The name of the *read* scope.

WRITE_SCOPE
~~~~~~~~~~~
.. note:: (0.12.0+) Only used if ``ACCESS_TOKEN_GENERATOR`` is set to the SettingsScopes default.
.. note:: (0.12.0+) Only used if ``SCOPES_BACKEND_CLASS`` is set to the SettingsScopes default.

The name of the *write* scope.

Expand Down Expand Up @@ -340,7 +315,6 @@ Default: ``False``

Whether or not :doc:`oidc` support is enabled.


OIDC_RSA_PRIVATE_KEY
~~~~~~~~~~~~~~~~~~~~
Default: ``""``
Expand Down Expand Up @@ -470,11 +444,47 @@ Time of sleep in seconds used by ``cleartokens`` management command between batc
Set this to a non-zero value (e.g. ``0.1``) to add a pause between batch sizes to reduce system
load when clearing large batches of expired tokens.

List of non-namespaced settings
-------------------------------
.. note::
These settings must be set as top-level Django settings (outside of ``OAUTH2_PROVIDER``),
because of the way Django currently implements swappable models.
See `issue #90 <https://github.com/jazzband/django-oauth-toolkit/issues/90>`_ for details.


OAUTH2_PROVIDER_ACCESS_TOKEN_MODEL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The import string of the class (model) representing your access tokens.
Overwrite this value if you wrote your own implementation (subclass of
``oauth2_provider.models.AccessToken``).

OAUTH2_PROVIDER_APPLICATION_MODEL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The import string of the class (model) representing your applications.
Overwrite this value if you wrote your own implementation (subclass of
``oauth2_provider.models.Application``).

OAUTH2_PROVIDER_ID_TOKEN_MODEL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The import string of the class (model) representing your OpenID Connect ID Token.
Overwrite this value if you wrote your own implementation (subclass of
``oauth2_provider.models.IDToken``).

OAUTH2_PROVIDER_GRANT_MODEL
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The import string of the class (model) representing your OAuth2 grants.
Overwrite this value if you wrote your own implementation (subclass of
``oauth2_provider.models.Grant``).

OAUTH2_PROVIDER_REFRESH_TOKEN_MODEL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The import string of the class (model) representing your refresh tokens.
Overwrite this value if you wrote your own implementation (subclass of
``oauth2_provider.models.RefreshToken``).

Settings imported from Django project
-------------------------------------

USE_TZ
~~~~~~

Used to determine whether or not to make token expire dates timezone aware.
Loading