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 paricipant. 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'>)[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 and default are both None, 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.
- Scope.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.
Grant classes¶
- class oauth2.grant.AuthorizationCodeGrant(default_scope=None, scopes=None, scope_class=<class 'oauth2.grant.Scope'>)[source]¶
Bases: oauth2.grant.GrantHandlerFactory, oauth2.grant.ScopeGrant
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())
- class oauth2.grant.ImplicitGrant(default_scope=None, scopes=None, scope_class=<class 'oauth2.grant.Scope'>)[source]¶
Bases: oauth2.grant.GrantHandlerFactory, oauth2.grant.ScopeGrant
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())
- class oauth2.grant.ResourceOwnerGrant(default_scope=None, scopes=None, scope_class=<class 'oauth2.grant.Scope'>)[source]¶
Bases: oauth2.grant.GrantHandlerFactory, oauth2.grant.ScopeGrant
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())
- class oauth2.grant.RefreshToken(expires_in, default_scope=None, scopes=None, scope_class=<class 'oauth2.grant.Scope'>)[source]¶
Bases: oauth2.grant.GrantHandlerFactory, oauth2.grant.ScopeGrant
Handles requests for refresk 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(RefreshToken(expires_in=600))
will cause oauth2.grant.AuthorizationCodeGrant and oauth2.grant.ResourceOwnerGrant to include a refresh token and expiration in the response.