diff --git a/docs/advanced_topics.rst b/docs/advanced_topics.rst index d92d71b12..0b2ee20b0 100644 --- a/docs/advanced_topics.rst +++ b/docs/advanced_topics.rst @@ -31,7 +31,7 @@ Django OAuth Toolkit lets you extend the AbstractApplication model in a fashion custom user models. If you need, let's say, application logo and user agreement acceptance field, you can do this in -your Django app (provided that your app is in the list of the INSTALLED_APPS in your settings +your Django app (provided that your app is in the list of the ``INSTALLED_APPS`` in your settings module):: from django.db import models @@ -44,11 +44,11 @@ module):: Then you need to tell Django OAuth Toolkit which model you want to use to represent applications. Write something like this in your settings module:: - OAUTH2_PROVIDER_APPLICATION_MODEL='your_app_name.MyApplication' + OAUTH2_PROVIDER_APPLICATION_MODEL = 'your_app_name.MyApplication' Be aware that, when you intend to swap the application model, you should create and run the -migration defining the swapped application model prior to setting OAUTH2_PROVIDER_APPLICATION_MODEL. -You'll run into models.E022 in Core system checks if you don't get the order right. +migration defining the swapped application model prior to setting ``OAUTH2_PROVIDER_APPLICATION_MODEL``. +You'll run into ``models.E022`` in Core system checks if you don't get the order right. You can force your migration providing the custom model to run in the right order by adding:: @@ -61,15 +61,15 @@ to the migration class. That's all, now Django OAuth Toolkit will use your model wherever an Application instance is needed. - **Notice:** `OAUTH2_PROVIDER_APPLICATION_MODEL` is the only setting variable that is not namespaced, this +.. note:: ``OAUTH2_PROVIDER_APPLICATION_MODEL`` is the only setting variable that is not namespaced, 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 + See `issue #90 `_ for details. Multiple Grants ~~~~~~~~~~~~~~~ The default application model supports a single OAuth grant (e.g. authorization code, client credentials). If you need -applications to support multiple grants, override the `allows_grant_type` method. For example, if you want applications +applications to support multiple grants, override the ``allows_grant_type`` method. For example, if you want applications to support the authorization code *and* client credentials grants, you might do the following:: from oauth2_provider.models import AbstractApplication @@ -86,12 +86,12 @@ Skip authorization form Depending on the OAuth2 flow in use and the access token policy, users might be prompted for the same authorization multiple times: sometimes this is acceptable or even desirable but other times it isn't. -To control DOT behaviour you can use the `approval_prompt` parameter when hitting the authorization endpoint. +To control DOT behaviour you can use the ``approval_prompt`` parameter when hitting the authorization endpoint. Possible values are: -* `force` - users are always prompted for authorization. +* ``force`` - users are always prompted for authorization. -* `auto` - users are prompted only the first time, subsequent authorizations for the same application +* ``auto`` - users are prompted only the first time, subsequent authorizations for the same application and scopes will be automatically accepted. Skip authorization completely for trusted applications @@ -109,7 +109,7 @@ Overriding views ================ You may want to override whole views from Django OAuth Toolkit, for instance if you want to -change the login view for unregistred users depending on some query params. +change the login view for unregistered users depending on some query params. In order to do that, you need to write a custom urlpatterns diff --git a/docs/contributing.rst b/docs/contributing.rst index 1d88bc4b0..c31e72990 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -12,7 +12,7 @@ This is a `Jazzband `_ project. By contributing you agree t Setup ===== -Fork `django-oauth-toolkit` repository on `GitHub `_ and follow these steps: +Fork ``django-oauth-toolkit`` repository on `GitHub `_ and follow these steps: * Create a virtualenv and activate it * Clone your repository locally @@ -55,14 +55,14 @@ is a better way to structure the code so that it is more readable. Documentation ============= -You can edit the documentation by editing files in ``docs/``. This project +You can edit the documentation by editing files in :file:`docs/`. This project uses sphinx to turn ``ReStructuredText`` into the HTML docs you are reading. In order to build the docs in to HTML, you can run:: tox -e docs -This will build the docs, and place the result in ``docs/_build/html``. +This will build the docs, and place the result in :file:`docs/_build/html`. Alternatively, you can run:: tox -e livedocs @@ -89,7 +89,7 @@ For example, to add Deutsch:: cd oauth2_provider django-admin makemessages --locale de -Then edit ``locale/de/LC_MESSAGES/django.po`` to add your translations. +Then edit :file:`locale/de/LC_MESSAGES/django.po` to add your translations. When deploying your app, don't forget to compile the messages with:: @@ -108,8 +108,8 @@ And, if a new migration is needed, use:: django-admin makemigrations --settings tests.mig_settings -Auto migrations frequently have ugly names like `0004_auto_20200902_2022`. You can make your migration -name "better" by adding the `-n name` option:: +Auto migrations frequently have ugly names like ``0004_auto_20200902_2022``. You can make your migration +name "better" by adding the ``-n name`` option:: django-admin makemigrations --settings tests.mig_settings -n widget @@ -117,7 +117,7 @@ name "better" by adding the `-n name` option:: Pull requests ============= -Please avoid providing a pull request from your `master` and use **topic branches** instead; you can add as many commits +Please avoid providing a pull request from your ``master`` and use **topic branches** instead; you can add as many commits as you want but please keep them in one branch which aims to solve one single issue. Then submit your pull request. To create a topic branch, simply do:: @@ -129,7 +129,7 @@ When you're ready to submit your pull request, first push the topic branch to yo git push origin fix-that-issue Now you can go to your repository dashboard on GitHub and open a pull request starting from your topic branch. You can -apply your pull request to the `master` branch of django-oauth-toolkit (this should be the default behaviour of GitHub +apply your pull request to the ``master`` branch of django-oauth-toolkit (this should be the default behaviour of GitHub user interface). When you begin your PR, you'll be asked to provide the following: @@ -150,29 +150,29 @@ When you begin your PR, you'll be asked to provide the following: * Update the documentation (in `docs/`) to describe the new or changed functionality. -* Update `CHANGELOG.md` (only for user relevant changes). We use `Keep A Changelog `_ +* Update ``CHANGELOG.md`` (only for user relevant changes). We use `Keep A Changelog `_ format which categorizes the changes as: - * `Added` for new features. + * ``Added`` for new features. - * `Changed` for changes in existing functionality. + * ``Changed`` for changes in existing functionality. - * `Deprecated` for soon-to-be removed features. + * ``Deprecated`` for soon-to-be removed features. - * `Removed` for now removed features. + * ``Removed`` for now removed features. - * `Fixed` for any bug fixes. + * ``Fixed`` for any bug fixes. - * `Security` in case of vulnerabilities. (Please report any security issues to the - JazzBand security team ``. Do not file an issue on the tracker + * ``Security`` in case of vulnerabilities. (Please report any security issues to the + JazzBand security team ````. Do not file an issue on the tracker or submit a PR until directed to do so.) -* Make sure your name is in `AUTHORS`. We want to give credit to all contributors! +* Make sure your name is in :file:`AUTHORS`. We want to give credit to all contributors! If your PR is not yet ready to be merged mark it as a Work-in-Progress -By prepending `WIP:` to the PR title so that it doesn't get inadvertently approved and merged. +By prepending ``WIP:`` to the PR title so that it doesn't get inadvertently approved and merged. -Make sure to request a review by assigning Reviewer `jazzband/django-oauth-toolkit`. +Make sure to request a review by assigning Reviewer ``jazzband/django-oauth-toolkit``. This will assign the review to the project team and a member will review it. In the meantime you can continue to add commits to your topic branch (and push them up to GitHub) either if you see something that needs changing, or in response to a reviewer's comments. If a reviewer asks for changes, you do not need to close the pull and reissue it @@ -194,7 +194,7 @@ Then merge the changes that you fetched:: git merge upstream/master -For more info, see http://help.github.com/fork-a-repo/ +For more information, see the `GitHub Docs on forking the repository `_. .. note:: Please be sure to rebase your commits on the master when possible, so your commits can be fast-forwarded: we try to avoid *merge commits* when they are not necessary. @@ -209,7 +209,7 @@ The Checklist A checklist template is automatically added to your PR when you create it. Make sure you've done all the applicable steps and check them off to indicate you have done so. This is -what you'll see when creating your PR: +what you'll see when creating your PR:: Fixes # @@ -251,7 +251,7 @@ You can check your coverage locally with the `coverage `_ @@ -301,14 +302,14 @@ and rtfd.io. This checklist is a reminder of the required steps. to make them meaningful to users. - Make a final PR for the release that updates: - - CHANGELOG to show the release date. - - `oauth2_provider/__init__.py` to set `__version__ = "..."` + - :file:`CHANGELOG.md` to show the release date. + - :file:`oauth2_provider/__init__.py` to set ``__version__ = "..."`` - Once the final PR is merged, create and push a tag for the release. You'll shortly get a notification from Jazzband of the availability of two pypi packages (source tgz and wheel). Download these locally before releasing them. -- Do a `tox -e build` and extract the downloaded and bullt wheel zip and tgz files into - temp directories and do a `diff -r` to make sure they have the same content. +- Do a ``tox -e build`` and extract the downloaded and built wheel zip and tgz files into + temp directories and do a ``diff -r`` to make sure they have the same content. (Unfortunately the checksums do not match due to timestamps in the metadata so you need to compare all the files.) - Once happy that the above comparison checks out, approve the releases to Pypi.org. diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 388afa300..2d7ebe269 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -42,7 +42,7 @@ Create a Django project:: django-admin startproject iam -This will create a mysite directory in your current directory. With the following estructure:: +This will create a mysite directory in your current directory. With the following structure:: . └── iam @@ -109,7 +109,7 @@ Configure ``users.User`` to be the model used for the ``auth`` application by ad .. code-block:: python - AUTH_USER_MODEL='users.User' + AUTH_USER_MODEL = 'users.User' Create inital migration for ``users`` application ``User`` model:: @@ -203,7 +203,7 @@ Last change, add ``LOGIN_URL`` to :file:`iam/settings.py`: .. code-block:: python - LOGIN_URL='/admin/login/' + LOGIN_URL = '/admin/login/' We will use Django Admin login to make our life easy. @@ -332,7 +332,7 @@ To be more easy to visualize:: The OAuth2 provider will return the follow response: -.. code-block:: javascript +.. code-block:: json { "access_token": "jooqrnOrNa0BrNWlg68u9sl6SkdFZg", @@ -402,7 +402,7 @@ To be easier to visualize:: The OAuth2 provider will return the following response: -.. code-block:: javascript +.. code-block:: json { "access_token": "PaZDOD5UwzbGOFsQr34LQ7JUYOj3yK", diff --git a/docs/install.rst b/docs/install.rst index 65dcb1d17..7186a94c0 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,11 +1,11 @@ Installation ============ -Install with pip -:: +Install with pip:: + pip install django-oauth-toolkit -Add `oauth2_provider` to your `INSTALLED_APPS` +Add ``oauth2_provider`` to your ``INSTALLED_APPS`` .. code-block:: python @@ -15,7 +15,7 @@ Add `oauth2_provider` to your `INSTALLED_APPS` ) -If you need an OAuth2 provider you'll want to add the following to your urls.py +If you need an OAuth2 provider you'll want to add the following to your :file:`urls.py` .. code-block:: python @@ -26,7 +26,7 @@ If you need an OAuth2 provider you'll want to add the following to your urls.py path('o/', include('oauth2_provider.urls', namespace='oauth2_provider')), ] -Or using `re_path()` +Or using ``re_path()`` .. code-block:: python @@ -34,7 +34,6 @@ Or using `re_path()` urlpatterns = [ ... - re_path(r'^o/', include('oauth2_provider.urls', namespace='oauth2_provider')), ] @@ -43,7 +42,7 @@ Sync your database .. sourcecode:: sh - $ python manage.py migrate oauth2_provider + python manage.py migrate oauth2_provider Next step is :doc:`getting started ` or :doc:`first tutorial `. diff --git a/docs/management_commands.rst b/docs/management_commands.rst index aa36e2ebf..83770041e 100644 --- a/docs/management_commands.rst +++ b/docs/management_commands.rst @@ -92,5 +92,5 @@ The ``createapplication`` management command provides a shortcut to create a new --force-color Force colorization of the command output. --skip-checks Skip system checks. -If you let `createapplication` auto-generate the secret then it displays the value before hashing it. +If you let ``createapplication`` auto-generate the secret then it displays the value before hashing it. diff --git a/docs/rest-framework/getting_started.rst b/docs/rest-framework/getting_started.rst index bff2b9017..4e6b037b0 100644 --- a/docs/rest-framework/getting_started.rst +++ b/docs/rest-framework/getting_started.rst @@ -4,20 +4,16 @@ Getting started Django OAuth Toolkit provide a support layer for `Django REST Framework `_. This tutorial is based on the Django REST Framework example and shows you how to easily integrate with it. -**NOTE** - -The following code has been tested with Django 2.0.3 and Django REST Framework 3.7.7 +.. note:: The following code has been tested with Django 2.0.3 and Django REST Framework 3.7.7 Step 1: Minimal setup --------------------- -Create a virtualenv and install following packages using `pip`... - -:: +Create a virtualenv and install following packages using ``pip``:: pip install django-oauth-toolkit djangorestframework -Start a new Django project and add `'rest_framework'` and `'oauth2_provider'` to your `INSTALLED_APPS` setting. +Start a new Django project and add ``'rest_framework'`` and ``'oauth2_provider'`` to your ``INSTALLED_APPS`` setting. .. code-block:: python @@ -29,7 +25,7 @@ Start a new Django project and add `'rest_framework'` and `'oauth2_provider'` to ) Now we need to tell Django REST Framework to use the new authentication backend. -To do so add the following lines at the end of your `settings.py` module: +To do so add the following lines at the end of your :file:`settings.py` module: .. code-block:: python @@ -44,7 +40,7 @@ Step 2: Create a simple API Let's create a simple API for accessing users and groups. -Here's our project's root `urls.py` module: +Here's our project's root :file:`urls.py` module: .. code-block:: python @@ -95,7 +91,7 @@ Here's our project's root `urls.py` module: # ... ] -Also add the following to your `settings.py` module: +Also add the following to your :file:`settings.py` module: .. code-block:: python @@ -114,7 +110,7 @@ Also add the following to your `settings.py` module: LOGIN_URL = '/admin/login/' -`OAUTH2_PROVIDER.SCOPES` setting parameter contains the scopes that the application will be aware of, +``OAUTH2_PROVIDER.SCOPES`` setting parameter contains the scopes that the application will be aware of, so we can use them for permission check. Now run the following commands: @@ -149,25 +145,23 @@ views you can use to CRUD application instances, just point your browser at: Click on the link to create a new application and fill the form with the following data: -* Name: *just a name of your choice* -* Client Type: *confidential* -* Authorization Grant Type: *Resource owner password-based* +* **Name:** *just a name of your choice* +* **Client Type:** *confidential* +* **Authorization Grant Type:** *Resource owner password-based* Save your app! Step 4: Get your token and use your API --------------------------------------- -At this point we're ready to request an access_token. Open your shell - -:: +At this point we're ready to request an access_token. Open your shell:: curl -X POST -d "grant_type=password&username=&password=" -u":" http://localhost:8000/o/token/ The *user_name* and *password* are the credential of the users registered in your :term:`Authorization Server`, like any user created in Step 2. Response should be something like: -.. code-block:: javascript +.. code-block:: json { "access_token": "", @@ -177,9 +171,7 @@ Response should be something like: "scope": "read write groups" } -Grab your access_token and start using your new OAuth2 API: - -:: +Grab your access_token and start using your new OAuth2 API:: # Retrieve users curl -H "Authorization: Bearer " http://localhost:8000/users/ @@ -191,15 +183,13 @@ Grab your access_token and start using your new OAuth2 API: # Insert a new user curl -H "Authorization: Bearer " -X POST -d"username=foo&password=bar&scope=write" http://localhost:8000/users/ -Some time has passed and your access token is about to expire, you can get renew the access token issued using the `refresh token`: - -:: +Some time has passed and your access token is about to expire, you can get renew the access token issued using the `refresh token`:: curl -X POST -d "grant_type=refresh_token&refresh_token=&client_id=&client_secret=" http://localhost:8000/o/token/ -Your response should be similar to your first access_token request, containing a new access_token and refresh_token: +Your response should be similar to your first ``access_token`` request, containing a new access_token and refresh_token: -.. code-block:: javascript +.. code-block:: json { "access_token": "", @@ -214,15 +204,13 @@ Your response should be similar to your first access_token request, containing a Step 5: Testing Restricted Access --------------------------------- -Let's try to access resources using a token with a restricted scope adding a `scope` parameter to the token request - -:: +Let's try to access resources using a token with a restricted scope adding a ``scope`` parameter to the token request:: curl -X POST -d "grant_type=password&username=&password=&scope=read" -u":" http://localhost:8000/o/token/ -As you can see the only scope provided is `read`: +As you can see the only scope provided is ``read``: -.. code-block:: javascript +.. code-block:: json { "access_token": "", @@ -232,15 +220,13 @@ As you can see the only scope provided is `read`: "scope": "read" } -We now try to access our resources: - -:: +We now try to access our resources:: # Retrieve users curl -H "Authorization: Bearer " http://localhost:8000/users/ curl -H "Authorization: Bearer " http://localhost:8000/users/1/ -Ok, this one works since users read only requires `read` scope. +OK, this one works since users read only requires ``read`` scope. :: @@ -250,5 +236,5 @@ Ok, this one works since users read only requires `read` scope. # 'write' scope needed curl -H "Authorization: Bearer " -X POST -d"username=foo&password=bar" http://localhost:8000/users/ -You'll get a `"You do not have permission to perform this action"` error because your access_token does not provide the -required scopes `groups` and `write`. +You'll get a ``"You do not have permission to perform this action"`` error because your access_token does not provide the +required scopes ``groups`` and ``write``. diff --git a/docs/settings.rst b/docs/settings.rst index c64c24954..db5ef110b 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -1,10 +1,10 @@ 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 +``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 `_ for details. For example: @@ -45,7 +45,7 @@ this value if you wrote your own implementation (subclass of 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. +``oauthlib.oauth2.rfc6749.tokens.random_token_generator`` is (normally) used if not provided. ALLOWED_REDIRECT_URI_SCHEMES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -72,7 +72,7 @@ A list of schemes that the ``allowed_origins`` field will be validated against. Setting this to ``["https"]`` only in production is strongly recommended. Adding ``"http"`` to the list is considered to be safe only for local development and testing. Note that `OAUTHLIB_INSECURE_TRANSPORT `_ -environment variable should be also set to allow http origins. +environment variable should be also set to allow HTTP origins. APPLICATION_MODEL @@ -187,15 +187,15 @@ this value if you wrote your own implementation (subclass of ROTATE_REFRESH_TOKEN ~~~~~~~~~~~~~~~~~~~~ -When is set to `True` (default) a new refresh token is issued to the client when the client refreshes an access token. -If `False`, it will reuse the same refresh token and only update the access token with a new token value. +When is set to ``True`` (default) a new refresh token is issued to the client when the client refreshes an access token. +If ``False``, it will reuse the same refresh token and only update the access token with a new token value. See also: validator's rotate_refresh_token method can be overridden to make this variable (could be usable with expiring refresh tokens, in particular, so that they are rotated when close to expiration, theoretically). REFRESH_TOKEN_GENERATOR ~~~~~~~~~~~~~~~~~~~~~~~ -See `ACCESS_TOKEN_GENERATOR`. This is the same but for refresh tokens. +See `ACCESS_TOKEN_GENERATOR`_. This is the same but for refresh tokens. Defaults to access token generator if not provided. REQUEST_APPROVAL_PROMPT @@ -210,7 +210,7 @@ Defaults to ``oauth2_provider.scopes.SettingsScopes``, which reads scopes throug SCOPES ~~~~~~ -.. note:: (0.12.0+) Only used if `SCOPES_BACKEND_CLASS` is set to the SettingsScopes default. +.. note:: (0.12.0+) Only used if ``ACCESS_TOKEN_GENERATOR`` is set to the SettingsScopes default. A dictionary mapping each scope name to its human description. @@ -218,11 +218,11 @@ A dictionary mapping each scope name to its human description. DEFAULT_SCOPES ~~~~~~~~~~~~~~ -.. note:: (0.12.0+) Only used if `SCOPES_BACKEND_CLASS` is set to the SettingsScopes default. +.. note:: (0.12.0+) Only used if ``ACCESS_TOKEN_GENERATOR`` 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. -By default this is set to '__all__' meaning that the whole set of SCOPES will be returned. +This is a subset of the keys of the ``SCOPES`` setting. +By default this is set to ``'__all__'`` meaning that the whole set of ``SCOPES`` will be returned. .. code-block:: python @@ -230,13 +230,13 @@ By default this is set to '__all__' meaning that the whole set of SCOPES will be READ_SCOPE ~~~~~~~~~~ -.. note:: (0.12.0+) Only used if `SCOPES_BACKEND_CLASS` is set to the SettingsScopes default. +.. note:: (0.12.0+) Only used if ``ACCESS_TOKEN_GENERATOR`` is set to the SettingsScopes default. The name of the *read* scope. WRITE_SCOPE ~~~~~~~~~~~ -.. note:: (0.12.0+) Only used if `SCOPES_BACKEND_CLASS` is set to the SettingsScopes default. +.. note:: (0.12.0+) Only used if ``ACCESS_TOKEN_GENERATOR`` is set to the SettingsScopes default. The name of the *write* scope. @@ -248,8 +248,8 @@ Only applicable when used with `Django REST Framework `_ - For confidential clients, the use of PKCE `RFC7636 `_ is RECOMMENDED. - - - - - OIDC_RSA_PRIVATE_KEY ~~~~~~~~~~~~~~~~~~~~ Default: ``""`` @@ -328,7 +323,7 @@ OIDC_RP_INITIATED_LOGOUT_ENABLED ~~~~~~~~~~~~~~~~~~~~~~~~ Default: ``False`` -When is set to `False` (default) the `OpenID Connect RP-Initiated Logout `_ +When is set to ``False`` (default) the `OpenID Connect RP-Initiated Logout `_ endpoint is not enabled. OpenID Connect RP-Initiated Logout enables an :term:`Client` (Relying Party) to request that a :term:`Resource Owner` (End User) is logged out at the :term:`Authorization Server` (OpenID Provider). @@ -356,7 +351,7 @@ OIDC_RP_INITIATED_LOGOUT_DELETE_TOKENS Default: ``True`` Whether to delete the access, refresh and ID tokens of the user that is being logged out. -The types of applications for which tokens are deleted can be customized with `RPInitiatedLogoutView.token_types_to_delete`. +The types of applications for which tokens are deleted can be customized with ``RPInitiatedLogoutView.token_types_to_delete``. The default is to delete the tokens of all applications if this flag is enabled. OIDC_ISS_ENDPOINT @@ -412,7 +407,7 @@ Default: ``0`` Time of sleep in seconds used by ``cleartokens`` management command between batch deletions. -Set this to a non-zero value (e.g. `0.1`) to add a pause between batch sizes to reduce system +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. diff --git a/docs/signals.rst b/docs/signals.rst index fe696ae2c..f35832af5 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -4,7 +4,7 @@ Signals Django-oauth-toolkit sends messages to various signals, depending on the action that has been triggered. -You can easily import signals from `oauth2_provider.signals` and attach your +You can easily import signals from ``oauth2_provider.signals`` and attach your own listeners. For example: @@ -20,5 +20,5 @@ For example: Currently supported signals are: -* `oauth2_provider.signals.app_authorized` - fired once an oauth code has been +* ``oauth2_provider.signals.app_authorized`` - fired once an oauth code has been authorized and an access token has been granted diff --git a/docs/tutorial/tutorial_01.rst b/docs/tutorial/tutorial_01.rst index a7bf20466..9f1ace1bd 100644 --- a/docs/tutorial/tutorial_01.rst +++ b/docs/tutorial/tutorial_01.rst @@ -117,9 +117,9 @@ process we'll explain shortly) Test Your Authorization Server ------------------------------ Your authorization server is ready and can begin issuing access tokens. To test the process you need an OAuth2 -consumer; if you are familiar enough with OAuth2, you can use curl, requests, or anything that speaks http. +consumer; if you are familiar enough with OAuth2, you can use curl, requests, or anything that speaks HTTP. -For this tutorial, we suggest using [Postman](https://www.postman.com/downloads/) : +For this tutorial, we suggest using `Postman `_. Open up the Authorization tab under a request and, for this tutorial, set the fields as follows: @@ -150,7 +150,7 @@ again to the consumer service. Possible errors: -* loginTemplate: If you are not redirected to the correct page after logging in successfully, you probably need to `setup your login template correctly`__. +* loginTemplate: If you are not redirected to the correct page after logging in successfully, you probably need to `setup your login template correctly `_. * invalid client: client id and client secret needs to be correct. Secret cannot be copied from Django admin after creation. (but you can reset it by pasting the same random string into Django admin and into Postman, to avoid recreating the app) * invalid callback url: Add the postman link into your app in Django admin. diff --git a/docs/tutorial/tutorial_02.rst b/docs/tutorial/tutorial_02.rst index cdc94540c..556eb6356 100644 --- a/docs/tutorial/tutorial_02.rst +++ b/docs/tutorial/tutorial_02.rst @@ -14,7 +14,7 @@ to provide an API to access some kind of resources. We don't need an actual reso endpoint protected with OAuth2: let's do it in a *class based view* fashion! Django OAuth Toolkit provides a set of generic class based view you can use to add OAuth behaviour to your views. Open -your `views.py` module and import the view: +your :file:`views.py` module and import the view: .. code-block:: python @@ -29,7 +29,7 @@ Then create the view which will respond to the API endpoint: def get(self, request, *args, **kwargs): return HttpResponse('Hello, OAuth2!') -That's it, our API will expose only one method, responding to `GET` requests. Now open your `urls.py` and specify the +That's it, our API will expose only one method, responding to ``GET`` requests. Now open your :file:`urls.py` and specify the URL this view will respond to: .. code-block:: python @@ -73,15 +73,15 @@ URL this view will respond to: You will probably want to write your own application views to deal with permissions and access control but the ones packaged with the library can get you started when developing the app. -Since we inherit from `ProtectedResourceView`, we're done and our API is OAuth2 protected - for the sake of the lazy +Since we inherit from ``ProtectedResourceView``, we're done and our API is OAuth2 protected - for the sake of the lazy programmer. Testing your API ---------------- Time to make requests to your API. -For a quick test, try accessing your app at the url `/api/hello` with your browser -and verify that it responds with a `403` (in fact no `HTTP_AUTHORIZATION` header was provided). +For a quick test, try accessing your app at the url ``/api/hello`` with your browser +and verify that it responds with a ``403`` (in fact no ``HTTP_AUTHORIZATION`` header was provided). You can test your API with anything that can perform HTTP requests, but for this tutorial you can use the online `consumer client `_. Just fill the form with the URL of the API endpoint (i.e. http://localhost:8000/api/hello if you're on localhost) and diff --git a/docs/tutorial/tutorial_03.rst b/docs/tutorial/tutorial_03.rst index ef5d57969..a9e063785 100644 --- a/docs/tutorial/tutorial_03.rst +++ b/docs/tutorial/tutorial_03.rst @@ -31,28 +31,28 @@ which takes care of token verification. In your settings.py: '...', ] -You will likely use the `django.contrib.auth.backends.ModelBackend` along with the OAuth2 backend +You will likely use the ``django.contrib.auth.backends.ModelBackend`` along with the OAuth2 backend (or you might not be able to log in into the admin), only pay attention to the order in which Django processes authentication backends. -If you put the OAuth2 backend *after* the AuthenticationMiddleware and `request.user` is valid, -the backend will do nothing; if `request.user` is the Anonymous user it will try to authenticate +If you put the OAuth2 backend *after* the ``AuthenticationMiddleware`` and ``request.user`` is valid, +the backend will do nothing; if ``request.user`` is the Anonymous user it will try to authenticate the user using the OAuth2 access token. -If you put the OAuth2 backend *before* AuthenticationMiddleware, or AuthenticationMiddleware is +If you put the OAuth2 backend *before* ``AuthenticationMiddleware``, or AuthenticationMiddleware is not used at all, it will try to authenticate user with the OAuth2 access token and set -`request.user` and `request._cached_user` fields so that AuthenticationMiddleware (when active) +``request.user`` and ``request._cached_user`` fields so that AuthenticationMiddleware (when active) will not try to get user from the session. -If you use AuthenticationMiddleware, be sure it appears before OAuth2TokenMiddleware. -However AuthenticationMiddleware is NOT required for using django-oauth-toolkit. +If you use ``AuthenticationMiddleware``, be sure it appears before ``OAuth2TokenMiddleware``. +However ``AuthenticationMiddleware`` is NOT required for using ``django-oauth-toolkit``. -Note, `OAuth2TokenMiddleware` adds the user to the request object. There is also an optional `OAuth2ExtraTokenMiddleware` that adds the `Token` to the request. This makes it convenient to access the `Application` object within your views. To use it just add `oauth2_provider.middleware.OAuth2ExtraTokenMiddleware` to the `MIDDLEWARE` setting. +Note, ``OAuth2TokenMiddleware`` adds the user to the request object. There is also an optional ``OAuth2ExtraTokenMiddleware`` that adds the ``Token`` to the request. This makes it convenient to access the ``Application`` object within your views. To use it just add ``oauth2_provider.middleware.OAuth2ExtraTokenMiddleware`` to the ``MIDDLEWARE`` setting. Protect your view ----------------- -The authentication backend will run smoothly with, for example, `login_required` decorators, so -that you can have a view like this in your `views.py` module: +The authentication backend will run smoothly with, for example, ``login_required`` decorators, so +that you can have a view like this in your :file:`views.py` module: .. code-block:: python @@ -75,7 +75,7 @@ To check everything works properly, mount the view above to some url: You should have an :term:`Application` registered at this point, if you don't, follow the steps in the previous tutorials to create one. Obtain an :term:`Access Token`, either following the OAuth2 flow of your application or manually creating in the Django admin. -Now supposing your access token value is `123456` you can try to access your authenticated view: +Now supposing your access token value is ``123456`` you can try to access your authenticated view: :: @@ -92,7 +92,7 @@ It would be nice to reuse those views **and** support token handling. Instead of those classes to be ProtectedResourceView based, the solution is much simpler than that. Assume you have already modified the settings as was already shown. -The key is setting a class attribute to override the default *permissions_classes* with something that will use our :term:`Access Token` properly. +The key is setting a class attribute to override the default ``permissions_classes`` with something that will use our :term:`Access Token` properly. .. code-block:: python @@ -107,7 +107,7 @@ The key is setting a class attribute to override the default *permissions_classe permission_classes = [TokenHasReadWriteScope] Note that this example overrides the Django default permission class setting. There are several other -ways this can be solved. Overriding the class function *get_permission_classes* is another way +ways this can be solved. Overriding the class function ``get_permission_classes`` is another way to solve the problem. A detailed dive into the `Django REST framework permissions is here. `_ diff --git a/docs/tutorial/tutorial_04.rst b/docs/tutorial/tutorial_04.rst index 07759d1e7..089f2ac25 100644 --- a/docs/tutorial/tutorial_04.rst +++ b/docs/tutorial/tutorial_04.rst @@ -7,12 +7,12 @@ You've granted a user an :term:`Access Token`, following :doc:`part 1 `, you'll have a URL at `/o/revoke_token`. By submitting the appropriate request to that URL, you can revoke a user's :term:`Access Token`. +Be sure that you've granted a valid token. If you've hooked in ``oauth-toolkit`` into your :file:`urls.py` as specified in :doc:`part 1 `, you'll have a URL at ``/o/revoke_token``. By submitting the appropriate request to that URL, you can revoke a user's :term:`Access Token`. `Oauthlib `_ is compliant with https://rfc-editor.org/rfc/rfc7009.html, so as specified, the revocation request requires: -- token: REQUIRED, this is the :term:`Access Token` you want to revoke -- token_type_hint: OPTIONAL, designating either 'access_token' or 'refresh_token'. +- ``token``: REQUIRED, this is the :term:`Access Token` you want to revoke +- ``token_type_hint``: OPTIONAL, designating either 'access_token' or 'refresh_token'. Note that these revocation-specific parameters are in addition to the authentication parameters already specified by your particular client type. @@ -36,7 +36,7 @@ obtained in :doc:`part 1 `. If your application type is `Confidenti token=XXXX&client_id=XXXX&client_secret=XXXX -The server will respond wih a `200` status code on successful revocation. You can use `curl` to make a revoke request on your server. If you have access to a local installation of your authorization server, you can test revoking a token with a request like that shown below, for a `Confidential` client. +The server will respond wih a ``200`` status code on successful revocation. You can use ``curl`` to make a revoke request on your server. If you have access to a local installation of your authorization server, you can test revoking a token with a request like that shown below, for a `Confidential` client. :: diff --git a/docs/tutorial/tutorial_05.rst b/docs/tutorial/tutorial_05.rst index 1be656b88..e75f3e23e 100644 --- a/docs/tutorial/tutorial_05.rst +++ b/docs/tutorial/tutorial_05.rst @@ -38,7 +38,7 @@ See the `RabbitMQ Installing on Windows `_. :: @@ -58,7 +58,7 @@ in the database and adds a Django Admin interface for configuring them. } -Now add a new file to your app to add Celery: ``tutorial/celery.py``: +Now add a new file to your app to add Celery: :file:`tutorial/celery.py`: .. code-block:: python @@ -74,8 +74,8 @@ Now add a new file to your app to add Celery: ``tutorial/celery.py``: # Load task modules from all registered Django apps. app.autodiscover_tasks() -This will autodiscover any ``tasks.py`` files in the list of installed apps. -We'll add ours now in ``tutorial/tasks.py``: +This will autodiscover any :file:`tasks.py` files in the list of installed apps. +We'll add ours now in :file:`tutorial/tasks.py`: .. code-block:: python @@ -87,7 +87,7 @@ We'll add ours now in ``tutorial/tasks.py``: clear_expired() -Finally, update ``tutorial/__init__.py`` to make sure Celery gets loaded when the app starts up: +Finally, update :file:`tutorial/__init__.py` to make sure Celery gets loaded when the app starts up: .. code-block:: python @@ -162,8 +162,6 @@ References The preceding is based on these references: -https://docs.celeryq.dev/en/stable/django/first-steps-with-django.html - -https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html#beat-custom-schedulers - -https://django-celery-beat.readthedocs.io/en/latest/index.html +* https://docs.celeryq.dev/en/stable/django/first-steps-with-django.html +* https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html#beat-custom-schedulers +* https://django-celery-beat.readthedocs.io/en/latest/index.html diff --git a/docs/views/application.rst b/docs/views/application.rst index a9f04bcd3..c5ec70d3b 100644 --- a/docs/views/application.rst +++ b/docs/views/application.rst @@ -2,9 +2,9 @@ Application Views ================= A set of views is provided to let users handle application instances without accessing Django Admin -Site. Application views are listed at the url `applications/` and you can register a new one at the -url `applications/register`. You can override default templates located in -`templates/oauth2_provider` folder and provide a custom layout. Every view provides access only to +Site. Application views are listed at the url ``applications/`` and you can register a new one at the +url ``applications/register``. You can override default templates located in +:file:`templates/oauth2_provider` folder and provide a custom layout. Every view provides access only to data belonging to the logged in user who performs the request. diff --git a/docs/views/class_based.rst b/docs/views/class_based.rst index 543ed58bb..d5573a600 100644 --- a/docs/views/class_based.rst +++ b/docs/views/class_based.rst @@ -38,7 +38,7 @@ using the *Class Based View* approach. .. class:: ReadWriteScopedResourceView(ReadWriteScopedResourceMixin, ProtectedResourceView): A view that provides OAuth2 authentication and read/write default scopes. - ``GET``, ``HEAD``, ``OPTIONS`` http methods require ``read`` scope, others methods + ``GET``, ``HEAD``, ``OPTIONS`` HTTP methods require ``read`` scope, others methods need the ``write`` scope. If you need, you can always specify an additional list of scopes in the ``required_scopes`` field:: diff --git a/docs/views/function_based.rst b/docs/views/function_based.rst index cc0650bd9..57884b2b9 100644 --- a/docs/views/function_based.rst +++ b/docs/views/function_based.rst @@ -43,8 +43,8 @@ Django OAuth Toolkit provides decorators to help you in protecting your function .. function:: rw_protected_resource(scopes=None, validator_cls=OAuth2Validator, server_cls=Server) Decorator to protect views by providing OAuth2 authentication and read/write scopes out of the - box. GET, HEAD, OPTIONS http methods require "read" scope. - Otherwise "write" scope is required:: + box. ``GET``, ``HEAD``, ``OPTIONS`` HTTP methods require ``'read'`` scope. + Otherwise ``'write'`` scope is required:: from oauth2_provider.decorators import rw_protected_resource @@ -54,7 +54,7 @@ Django OAuth Toolkit provides decorators to help you in protecting your function # ... pass - If you need, you can ask for other scopes over "read" and "write":: + If you need, you can ask for other scopes over ``'read'`` and ``'write'``:: from oauth2_provider.decorators import rw_protected_resource diff --git a/docs/views/token.rst b/docs/views/token.rst index ead0d023d..6c6d2b6ae 100644 --- a/docs/views/token.rst +++ b/docs/views/token.rst @@ -5,10 +5,10 @@ A set of views is provided to let users handle tokens that have been granted to Every view provides access only to the tokens that have been granted to the user performing the request. -Granted Token views are listed at the url `authorized_tokens/`. +Granted Token views are listed at the url ``authorized_tokens/``. -For each granted token there is a delete view that allows you to delete such token. You can override default templates `authorized-tokens.html` for the list view and `authorized-token-delete.html` for the delete view; they are located inside `templates/oauth2_provider` folder. +For each granted token there is a delete view that allows you to delete such token. You can override default templates :file:`authorized-tokens.html` for the list view and :file:`authorized-token-delete.html` for the delete view; they are located inside :file:`templates/oauth2_provider` folder. .. automodule:: oauth2_provider.views.token