Adding OAuth2 Support¶
Overview¶
The Web API utilities provided by Djblets can be augmented to add support for authentication via OAuth2. In order to do this, there are a few steps:
Additional Requirements¶
OAuth2 support requires the django-oauth-toolkit module to be installed. This module has only been tested with version 0.9.0.
settings.py
¶
The following settings need to be updated in settings.py
to take
advantage of OAuth2 support.
INSTALLED_APPS
:- Add
'oauth2_provider'
to this list. WEB_API_AUTH_BACKENDS
:Add
''djblets.webapi.auth.backends.oauth2_tokens.OAuth2TokenAuthBackend'
to this list.WEB_API_AUTH_BACKENDS = ( 'djblets.webapi.auth.backends.basic.WebAPIBasicAuthBackend', 'djblets.webapi.auth.backends.oauth2_tokens.OAuth2TokenAuthBackend', )
AUTHENTICATION_BACKENDS
:Create an authentication backend using
OAuth2TokenBackendMixin
and add it to this setting:from djblets.webapi.auth.backends.oauth2_tokens import OAuth2TokenBackendMixin from django.contrib.auth.backends import ModelBackend class EnabledOAuth2TokenBackend(OAuth2TokenBackendMixin, ModelBackend): """An OAuth2 token auth backend using a custom Application model.""" def verify_request(self, request, token, user): return token.application.some_custom_property
AUTHENTICATION_BACKENDS = ( 'django.contrib.auth.backends.ModelBackend', # ... 'myapp.auth_backends.EnabledOAuth2TokenBackend', )
WEB_API_ROOT_RESOURCE
:Define this to be the full import path of your root resource.
WEB_API_ROOT_RESOURCE = 'myapp.webapi.resources.root.root_resource'
WEB_API_SCOPE_DICT_CLASS
:This setting determines what class defines the OAuth2 scopes for your web API. By default, each resource will require
scope_name:method
wherescope_name
is defined byResourceOAuth2TokenMixin.scope_name
andmethod
is one ofread
(for HTTP GET, HEAD, and OPTIONS),write
(for HTTP PUT and POST), ordestroy
(for HTTP DELETE).Djblets provides two possible scope dictionary classes for your web API:
djblets.webapi.oauth2_scopes.ExtensionEnabledWebAPIScopeDictionary
:- For apps that use the djblets extensions framework.
djblets.webapi.oauth2_scopes.WebAPIScopeDictionary
:- For apps that do not use the djblets extensions framework.
# If using extensions: WEB_API_SCOPE_DICT_CLASS = \ 'djblets.webapi.oauth2_scopes.ExtensionEnabledWebAPIScopeDictionary' # Otherwise: WEB_API_SCOPE_DICT_CLASS = \ 'djblets.webapi.oauth2_scopes.WebAPIScopeDictionary'
OAUTH_PROVIDER
:This setting must, at a minimum, define the
DEFAULT_SCOPES
andSCOPES
keys. The following example presumes that your root resource is named'root'
and you are using one of the provided scope dictionaries.The
SCOPES
key should be an empty dictionary. It will be replaced at runtime with the proper dictionary.OAUTH2_PROVIDER = { 'DEFAULT_SCOPES': 'root:read', 'SCOPES': {}, }
Resource Classes¶
Resources should all inherit from a base class that includes the provided mixin for OAuth2 support.
from djblets.webapi.resources.base import WebAPIResource as \
BaseWebAPIResource
from djblets.webapi.resources.mixins.oauth2_tokens import \
ResourceOAuth2TokenMixin
class WebAPIResource(ResourceOAuth2TokenMixin, BaseWebAPIResource):
"""The base resource class.
All resources should inherit from this.
"""
If you wish to disable access to a resource when using an OAuth2 token, you may
set the oauth2_token_access_allowed
attribute to False
.
Enabling Web API OAuth Scopes¶
Finally, to enable the web API scope dictionary, you must run
enable_webapi_scopes()
at runtime. This
should be run when your app is starting.
If you are on Django 1.7+, you should call this function in your
AppConfig.ready
method:
from django.apps import AppConfig
class WebApiAppConfig(AppConfig):
def ready(self):
"""Enable the WebAPI scopes dictionary."""
from djblets.webapi.oauth2_scopes import enable_webapi_scopes
enable_oauth2_scopes()
Otherwise if you are on Django 1.6, you may call it in your root
urls.py
:
from djblets.webapi.oauth2_scopes import enable_webapi_scopes
urlpatterns = [
# ...
]
enable_oauth2_scopes()