oauth2.grant
— Grant classes and helpers¶
Grants are the heart of OAuth 2.0. Each Grant defines one way for a client to retrieve an authorization. They are defined in Section 4 of the OAuth 2.0 spec.
OAuth 2.0 comes in two flavours of how an access token is issued: two-legged and three-legged auth. To avoid confusion they are explained in short here.
Three-legged OAuth¶
The “three” symbolizes the parties that are involved:
- The client that wants to access a resource on behalf of the user.
- The user who grants access to her resources.
- The server that issues the access token if the user allows it.
Two-legged OAuth¶
The two-legged OAuth process differs from the three-legged process by one missing participant. The user cannot allow or deny access.
So there are two remaining parties:
- The client that wants to access a resource.
- The server that issues the access.
Helpers and base classes¶
-
class
oauth2.grant.
GrantHandlerFactory
[source]¶ Base class every handler factory can extend.
This class defines the basic interface of each Grant.
-
class
oauth2.grant.
ScopeGrant
(default_scope=None, scopes=None, scope_class=<class 'oauth2.grant.Scope'>, **kwargs)[source]¶ Handling of scopes in the OAuth 2.0 flow.
Inherited by all grants that need to support scopes.
Parameters: - default_scope – The scope identifier that is returned by default. (optional)
- scopes – A list of strings identifying the scopes that the grant supports.
- scope_class – The class that does the actual handling in a request.
Default:
oauth2.grant.Scope
.
-
class
oauth2.grant.
Scope
(available=None, default=None)[source]¶ Handling of the “scope” parameter in a request.
If
available
anddefault
are bothNone
, the “scope” parameter is ignored (the default).Parameters: - available – A list of strings each defining one supported scope.
- default – Value to fall back to in case no scope is present in a request.
-
parse
(request, source)[source]¶ Parses scope value in given request.
Expects the value of the “scope” parameter in request to be a string where each requested scope is separated by a white space:
# One scope requested "profile_read" # Multiple scopes "profile_read profile_write"
Parameters: - request – An instance of
oauth2.web.Request
. - source – Where to read the scope from. Pass “body” in case of a application/x-www-form-urlencoded body and “query” in case the scope is supplied as a query parameter in the URL of a request.
- request – An instance of
Grant classes¶
-
class
oauth2.grant.
AuthorizationCodeGrant
(unique_token=False, expires_in=0, **kwargs)[source]¶ Bases:
oauth2.grant.GrantHandlerFactory
,oauth2.grant.ScopeGrant
,oauth2.grant.SiteAdapterMixin
Implementation of the Authorization Code Grant auth flow.
This is a three-legged OAuth process.
Register an instance of this class with
oauth2.AuthorizationController
like this:auth_controller = AuthorizationController() auth_controller.add_grant_type(AuthorizationCodeGrant())
Changed in version 1.0.0: Require parameter
site_adapter
.
-
class
oauth2.grant.
ImplicitGrant
(default_scope=None, scopes=None, scope_class=<class 'oauth2.grant.Scope'>, **kwargs)[source]¶ Bases:
oauth2.grant.GrantHandlerFactory
,oauth2.grant.ScopeGrant
,oauth2.grant.SiteAdapterMixin
Implementation of the Implicit Grant auth flow.
This is a three-legged OAuth process.
Register an instance of this class with
oauth2.AuthorizationController
like this:auth_controller = AuthorizationController() auth_controller.add_grant_type(ImplicitGrant())
Changed in version 1.0.0: Require parameter
site_adapter
.
-
class
oauth2.grant.
ResourceOwnerGrant
(unique_token=False, expires_in=0, **kwargs)[source]¶ Bases:
oauth2.grant.GrantHandlerFactory
,oauth2.grant.ScopeGrant
,oauth2.grant.SiteAdapterMixin
Implementation of the Resource Owner Password Credentials Grant auth flow.
In this Grant a user provides a user name and a password. An access token is issued if the auth server was able to verify the user by her credentials.
Register an instance of this class with
oauth2.AuthorizationController
like this:auth_controller = AuthorizationController() auth_controller.add_grant_type(ResourceOwnerGrant())
Changed in version 1.0.0: Require parameter
site_adapter
.
-
class
oauth2.grant.
RefreshToken
(expires_in, reissue_refresh_tokens=False, **kwargs)[source]¶ Bases:
oauth2.grant.GrantHandlerFactory
,oauth2.grant.ScopeGrant
Handles requests for refresh tokens as defined in http://tools.ietf.org/html/rfc6749#section-6.
Adding a Refresh Token to the
oauth2.AuthorizationController
like this:auth_controller = AuthorizationController() auth_controller.add_grant_type(ResourceOwnerGrant(tokens_expire=600)) auth_controller.add_grant_type(RefreshToken(tokens_expire=1200))
will cause
oauth2.grant.AuthorizationCodeGrant
andoauth2.grant.ResourceOwnerGrant
to include a refresh token and expiration in the response. If tokens_expire == 0, the tokens will never expire.