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

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)

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)

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.

parse(request, 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.

class oauth2.grant.SiteAdapterMixin(site_adapter, **kwargs)

Mixed in by Grant classes that require a site adapter.

A concrete class must set the class attribute site_adapter_class that contains a reference to the site adapter class that this class expects.

Grant classes

class oauth2.grant.AuthorizationCodeGrant(unique_token=False, expires_in=0, **kwargs)

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())

class oauth2.grant.ImplicitGrant(default_scope=None, scopes=None, scope_class=<class 'oauth2.grant.Scope'>, **kwargs)

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())

class oauth2.grant.ResourceOwnerGrant(unique_token=False, expires_in=0, **kwargs)

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())

class oauth2.grant.RefreshToken(expires_in, reissue_refresh_tokens=False, **kwargs)

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 and oauth2.grant.ResourceOwnerGrant to include a refresh token and expiration in the response. If tokens_expire == 0, the tokens will never expire.