provider

provider.constants

provider.constants.RESPONSE_TYPE_CHOICES

Settings:OAUTH_RESPONSE_TYPE_CHOICES

The response types as outlined by Section 3.1.1

provider.constants.SCOPES

Settings:OAUTH_SCOPES

A choice of scopes. A detailed implementation is left to the developer. The current default implementation in provider.oauth2.scope makes use of bit shifting operations to combine read and write permissions.

provider.constants.EXPIRE_DELTA

Settings:OAUTH_EXPIRE_DELTA Default:datetime.timedelta(days=365)

The time to expiry for access tokens as outlined in Section 4.2.2 and Section 5.1.

provider.constants.EXPIRE_CODE_DELTA

Settings:OAUTH_EXPIRE_CODE_DELTA Default:datetime.timedelta(seconds=10*60)

The time to expiry for an authorization code grant as outlined in Section 4.1.2.

provider.constants.DELETE_EXPIRED

Settings:OAUTH_DELETE_EXPIRED Default:False

To remove expired tokens immediately instead of letting them persist, set to True.

provider.constants.ENFORCE_SECURE

Settings:OAUTH_ENFORCE_SECURE Default:False

To enforce secure communication on application level, set to True.

provider.constants.SESSION_KEY

Settings:OAUTH_SESSION_KEY Default:“oauth”

Session key prefix to store temporary data while the user is completing the authentication / authorization process.

provider.constants.SINGLE_ACCESS_TOKEN

Settings:OAUTH_SINGLE_ACCESS_TOKEN Default:False

To have the provider only create and retrieve one access token per user/client/scope combination, set to True.

provider.forms

class provider.forms.OAuthForm(*args, **kwargs)

Form class that creates shallow error dicts and exists early when a OAuthValidationError is raised.

The shallow error dict is reused when returning error responses to the client.

The different types of errors are outlined in Section 4.2.2.1 and Section 5.2.

exception provider.forms.OAuthValidationError

Exception to throw inside OAuthForm if any OAuth2 related errors are encountered such as invalid grant type, invalid client, etc.

OAuthValidationError expects a dictionary outlining the OAuth error as its first argument when instantiating.

Example:

class GrantValidationForm(OAuthForm):
    grant_type = forms.CharField()

    def clean_grant(self):
        if not self.cleaned_data.get('grant_type') == 'code':
            raise OAuthValidationError({
                'error': 'invalid_grant',
                'error_description': "%s is not a valid grant type" % (
                    self.cleaned_data.get('grant_type'))
            })

The different types of errors are outlined in Section 4.2.2.1 and Section 5.2.

provider.scope

Default scope implementation relying on bit shifting. See provider.constants.SCOPES for the list of available scopes.

Scopes can be combined, such as "read write". Note that a single "write" scope is not the same as "read write".

See provider.scope.to_int on how scopes are combined.

provider.scope.check(wants, has)

Check if a desired scope wants is part of an available scope has.

Returns False if not, return True if yes.

Example:

If a list of scopes such as

READ = 1 << 1
WRITE = 1 << 2
READ_WRITE = READ | WRITE

SCOPES = (
    (READ, 'read'),
    (WRITE, 'write'),
    (READ_WRITE, 'read+write'),
)

is defined, we can check if a given scope is part of another:

>>> from provider import scope
>>> scope.check(READ, READ)
True
>>> scope.check(WRITE, READ)
False
>>> scope.check(WRITE, WRITE)
True
>>> scope.check(READ, WRITE)
False
>>> scope.check(READ, READ_WRITE)
True
>>> scope.check(WRITE, READ_WRITE)
True

provider.scope.names(scope)

Returns a list of scope names as defined in provider.constants.SCOPES for a given scope integer.

>>> assert ['read', 'write'] == provider.scope.names(provider.constants.READ_WRITE)

provider.scope.to_int(*names, **kwargs)

Turns a list of scope names into an integer value.

>>> scope.to_int('read')
2
>>> scope.to_int('write')
6
>>> scope.to_int('read', 'write')
6
>>> scope.to_int('invalid')
0
>>> scope.to_int('invalid', default = 1)
1

provider.scope.to_names(scope)

Returns a list of scope names as defined in provider.constants.SCOPES for a given scope integer.

>>> assert ['read', 'write'] == provider.scope.names(provider.constants.READ_WRITE)

provider.templatetags.scope

provider.templatetags.scope.scopes(scope_int)

Wrapper around provider.scope.names to turn an int into a list of scope names in templates.

provider.utils

provider.utils.deserialize_instance(model, data={})

Translate raw data into a model instance.

provider.utils.get_code_expiry()

Return a datetime object indicating when an authorization code should expire. Can be customized by setting settings.OAUTH_EXPIRE_CODE_DELTA to a datetime.timedelta object.

provider.utils.get_token_expiry(public=True)

Return a datetime object indicating when an access token should expire. Can be customized by setting settings.OAUTH_EXPIRE_DELTA to a datetime.timedelta object.

provider.utils.long_token()

Generate a hash that can be used as an application secret

provider.utils.serialize_instance(instance)

Since Django 1.6 items added to the session are no longer pickled, but JSON encoded by default. We are storing partially complete models in the session (user, account, token, ...). We cannot use standard Django serialization, as these are models are not “complete” yet. Serialization will start complaining about missing relations et al.

provider.utils.short_token()

Generate a hash that can be used as an application identifier

provider.views

provider.oauth2

provider.oauth2.forms

class provider.oauth2.forms.AuthorizationCodeGrantForm(*args, **kwargs)

Check and return an authorization grant.

clean()

Make sure that the scope is less or equal to the scope allowed on the grant!

class provider.oauth2.forms.AuthorizationForm(*args, **kwargs)

A form used to ask the resource owner for authorization of a given client.

class provider.oauth2.forms.AuthorizationRequestForm(*args, **kwargs)

This form is used to validate the request data that the authorization endpoint receives from clients.

Included data is specified in Section 4.1.1.

clean_redirect_uri()

Section 3.1.2 The redirect value has to match what was saved on the

authorization server.

clean_response_type()

Section 3.1.1 Lists of values are space delimited.

redirect_uri = None

Where the client would like to redirect the user back to. This has to match whatever value was saved while creating the client.

response_type = None

"code" or "token" depending on the grant type.

scope = None

The scope that the authorization should include.

state = None

Opaque - just pass back to the client for validation.

class provider.oauth2.forms.ClientAuthForm(data=None, files=None, auto_id=u'id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False)

Client authentication form. Required to make sure that we’re dealing with a real client. Form is used in provider.oauth2.backends to validate the client.

class provider.oauth2.forms.ClientForm(data=None, files=None, auto_id=u'id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, instance=None)

Form to create new consumers.

class provider.oauth2.forms.PasswordGrantForm(*args, **kwargs)

Validate the password of a user on a password grant request.

class provider.oauth2.forms.RefreshTokenGrantForm(*args, **kwargs)

Checks and returns a refresh token.

clean()

Make sure that the scope is less or equal to the previous scope!

class provider.oauth2.forms.ScopeChoiceField(choices=(), required=True, widget=None, label=None, initial=None, help_text=u'', *args, **kwargs)

Custom form field that seperates values on space as defined in Section 3.3.

validate(value)

Validates that the input is a list or tuple.

class provider.oauth2.forms.ScopeMixin

Form mixin to clean scope fields.

clean_scope()

The scope is assembled by combining all the set flags into a single integer value which we can later check again for set bits.

If no scope is set, we return the default scope which is the first defined scope in provider.constants.SCOPES.

provider.oauth2.models

Default model implementations. Custom database or OAuth backends need to implement these models with fields and and methods to be compatible with the views in provider.views.

class provider.oauth2.models.AccessToken(*args, **kwargs)

Default access token implementation. An access token is a time limited token to access a user’s resources.

Access tokens are outlined Section 5.

Expected fields:

• user
• token
• client - Client
• expires - datetime.datetime
• scope

Expected methods:

• get_expire_delta() - returns an integer representing seconds to

  expiry

get_expire_delta(reference=None)

Return the number of seconds until this token expires.

class provider.oauth2.models.Client(*args, **kwargs)

Default client implementation.

Expected fields:

• user
• name
• url
• redirect_url
• client_id
• client_secret
• client_type

Clients are outlined in the Section 2 and its subsections.

class provider.oauth2.models.Grant(*args, **kwargs)

Default grant implementation. A grant is a code that can be swapped for an access token. Grants have a limited lifetime as defined by provider.constants.EXPIRE_CODE_DELTA and outlined in Section 4.1.2

Expected fields:

• user
• client - Client
• code
• expires - datetime.datetime
• redirect_uri
• scope

class provider.oauth2.models.RefreshToken(*args, **kwargs)

Default refresh token implementation. A refresh token can be swapped for a new access token when said token expires.

Expected fields:

• user
• token
• access_token - AccessToken
• client - Client
• expired - boolean

provider.oauth2.urls

The default implementation of the OAuth provider includes two public endpoints that are meant for client (as defined in Section 1) interaction.

^authorize/$

This is the URL where a client should redirect a user to for authorization.

This endpoint expects the parameters defined in Section 4.1.1 and returns responses as defined in Section 4.1.2 and Section 4.1.2.1.

^access_token/$

This is the URL where a client exchanges a grant for an access tokens.

This endpoint expects different parameters depending on the grant type:

• Access tokens: Section 4.1.3
• Refresh tokens: Section 6
• Password grant: Section 4.3.2

This endpoint returns responses depending on the grant type:

• Access tokens: Section 4.1.4 and Section 5.1
• Refresh tokens: Section 4.1.4 and Section 5.1
• Password grant: Section 5.1

To override, remove or add grant types, override the appropriate methods on provider.views.AccessToken and / or provider.oauth2.views.AccessTokenView.

Errors are outlined in Section 5.2.

provider.oauth2.views

class provider.oauth2.views.AccessTokenView(**kwargs)

Implementation of provider.views.AccessToken.

Note

This implementation does provide all default grant types defined in provider.views.AccessToken.grant_types. If you wish to disable any, you can override the get_handler() method or the grant_types list.

class provider.oauth2.views.Authorize(**kwargs)

Implementation of provider.views.Authorize.

class provider.oauth2.views.Capture(**kwargs)

Implementation of provider.views.Capture.

class provider.oauth2.views.Redirect(**kwargs)

Implementation of provider.views.Redirect