Settings : | OAUTH_RESPONSE_TYPE_CHOICES |
---|
The response types as outlined by Section 3.1.1
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.
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.
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.
Settings : | OAUTH_ENFORCE_SECURE |
---|---|
Default : | False |
To enforce secure communication on application level, set to True.
Settings : | OAUTH_SESSION_KEY |
---|---|
Default : | “oauth” |
Session key prefix to store temporary data while the user is completing the authentication / authorization process.
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 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.
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.
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
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)
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
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)
Wrapper around provider.scope.names to turn an int into a list of scope names in templates.
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.
AccessToken handles creation and refreshing of access tokens.
Implementations must implement a number of methods:
The default implementation supports the grant types defined in grant_types.
According to Section 4.4.2 this endpoint too must support secure communication. For strict enforcement of secure communication at application level set settings.OAUTH_ENFORCE_SECURE to True.
According to Section 3.2 we can only accept POST requests.
Returns with a status code of 400 in case of errors. 200 in case of success.
Returns a successful response after creating the access token as defined in Section 5.1.
Authentication backends used to authenticate a particular client.
Handle grant_type=authorization_code requests as defined in Section 4.1.3.
Override to handle access token creation.
Returns: | object - Access token |
---|
Override to handle refresh token creation.
Returns: | object - Refresh token |
---|
Return an error response to the client with default status code of 400 stating the error as outlined in Section 5.2.
As per Section 3.2 the token endpoint only supports POST requests. Returns an error response.
Return the grant associated with this request or an error dict.
Returns: | tuple - (True or False, grant or error_dict) |
---|
Return a function or method that is capable handling the grant_type requested by the client or return None to indicate that this type of grant type is not supported, resulting in an error response.
Return a user associated with this request or an error dict.
Returns: | tuple - (True or False, user or error_dict) |
---|
Return the refresh token associated with this request or an error dict.
Returns: | tuple - (True or False, token or error_dict) |
---|
The default grant types supported by this view.
Override to handle access token invalidation. When a new access token is created from a refresh token, the old one is always invalidated.
Return None: |
---|
Override to handle grant invalidation. A grant is invalidated right after creating an access token from it.
Return None: |
---|
Override to handle refresh token invalidation. When requesting a new access token from a refresh token, the old one is always invalidated.
Return None: |
---|
Handle grant_type=password requests as defined in Section 4.3.
As per Section 3.2 the token endpoint only supports POST requests.
View to handle the client authorization as outlined in Section 4. Implementation must override a set of methods:
Authorize renders the provider/authorize.html template to display the authorization form.
On successful authorization, it redirects the user back to the defined client callback as defined in Section 4.1.2.
On authorization fail Authorize displays an error message to the user with a modified redirect URL to the callback including the error and possibly description of the error as defined in Section 4.1.2.1.
Return an error to be displayed to the resource owner if anything goes awry. Errors can include invalid clients, authorization denials and other edge cases such as a wrong redirect_uri in the authorization request.
Parameters: |
|
---|
Return a form that is capable of authorizing the client to the resource owner.
Returns: | django.forms.Form |
---|
Return a client object from a given client identifier. Return None if no client is found. An error will be displayed to the resource owner and presented to the client upon the final redirect.
Returns: | str - The client URL to display in the template after authorization succeeded or failed. |
---|
Return a form that is capable of validating the request data captured by the Capture view. The form must accept a keyword argument client.
Save the authorization that the user granted to the client, involving the creation of a time limited authorization code as outlined in Section 4.1.2.
Should return None in case authorization is not granted. Should return a string representing the authorization code grant.
Returns: | None, str |
---|
As stated in section Section 3.1.2.5 this view captures all the request parameters and redirects to another URL to avoid any leakage of request parameters to potentially harmful JavaScripts.
This application assumes that whatever web-server is used as front-end will handle SSL transport.
If you want strict enforcement of secure communication at application level, set settings.OAUTH_ENFORCE_SECURE to True.
The actual implementation is required to override get_redirect_url().
Mixin providing common methods required in the OAuth view defined in provider.views.
Authenticate a client against all the backends configured in authentication.
Exception to throw inside any views defined in provider.views.
Any OAuthError thrown will be signalled to the API consumer.
OAuthError expects a dictionary as its first argument outlining the type of error that occured.
Example : |
---|
raise OAuthError({'error': 'invalid_request'})
The different types of errors are outlined in Section 4.2.2.1 and Section 5.2.
Base class for any view dealing with the OAuth flow. This class overrides the dispatch method of TemplateView to add no-caching headers to every response as outlined in Section 5.1.
Check and return an authorization grant.
A form used to ask the resource owner for authorization of a given client.
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.
Section 3.1.1 Lists of values are space delimited.
Where the client would like to redirect the user back to. This has to match whatever value was saved while creating the client.
"code" or "token" depending on the grant type.
The scope that the authorization should include.
Opaque - just pass back to the client for validation.
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.
Form to create new consumers.
Validate the password of a user on a password grant request.
Checks and returns a refresh token.
Custom form field that seperates values on space as defined in Section 3.3.
Form mixin to clean scope fields.
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.
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.
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:
Expected methods:
expiry
Default client implementation.
Expected fields:
Clients are outlined in the Section 2 and its subsections.
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:
Default refresh token implementation. A refresh token can be swapped for a new access token when said token expires.
Expected fields:
The default implementation of the OAuth provider includes two public endpoints that are meant for client (as defined in Section 1) interaction.
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.
This is the URL where a client exchanges a grant for an access tokens.
This endpoint expects different parameters depending on the grant type:
This endpoint returns responses depending on the grant type:
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.
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.
Implementation of provider.views.Authorize.
Implementation of provider.views.Capture.
Implementation of provider.views.Redirect