oauth_dropins

Reference documentation.

blogger_v2

Blogger v2 GData API OAuth drop-in.

Blogger API docs: https://developers.google.com/blogger/docs/2.0/developers_guide_protocol

Python GData API docs: http://gdata-python-client.googlecode.com/hg/pydocs/gdata.blogger.data.html

Uses requests-oauthlib to auth via Google Sign-In’s OAuth 2: https://requests-oauthlib.readthedocs.io/

class oauth_dropins.blogger_v2.BloggerV2Auth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Blogger user.

Provides methods that return information about this user (or page) and make OAuth-signed requests to the Blogger API. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Blogger-specific details: implements api() but not urlopen(). api() returns a gdata.blogger.client.BloggerClient. The datastore entity key name is the Blogger user id.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s Blogger username.

access_token()[source]

Returns the OAuth access token string.

modify_request(http_request)[source]

Makes this class usable as an auth_token object in a gdata Client.

Background in gdata.client.GDClient and gdata.client.GDClient.request(). Other similar classes include gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken.

class oauth_dropins.blogger_v2.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.blogger_v2.Scopes, oauth_dropins.handlers.StartHandler

Connects a Blogger account. Authenticates via OAuth.

handle_exception(e, debug)

A webapp2 exception handler that propagates HTTP exceptions into the response.

Use this as a webapp2.RequestHandler.handle_exception() method by adding this line to your handler class definition:

handle_exception = handlers.handle_exception

I originally tried to put this in a webapp2.RequestHandler subclass, but it gave me this exception:

File ".../webapp2-2.5.1/webapp2_extras/local.py", line 136, in _get_current_object
  raise RuntimeError('no object bound to %s' % self.__name__) RuntimeError: no object bound to app

These are probably related:

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
class oauth_dropins.blogger_v2.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.blogger_v2.Scopes, oauth_dropins.handlers.CallbackHandler

Finishes the OAuth flow.

disqus

Disqus OAuth drop-in.

Disqus API docs: https://disqus.com/api/docs/

This drop-in is even more similar to Instagram than Instagram is to Facebook. Differences:

  • urlopen must pass the api_key with each request (in addition to the access_token)
  • Response to access_token does not give much information about the user, so we additionally fetch /user/details before saving
  • Deny appears to be broken on Disqus’s side (clicking “No Thanks” has no effect), so we ignore that possibility for now.

TODO unify Disqus, Facebook, and Instagram

class oauth_dropins.disqus.DisqusAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Disqus user.

Provides methods that return information about this user (or page) and make OAuth-signed requests to Instagram’s HTTP-based APIs. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Disqus-specific details: implements urlopen() but not api(). The key name is the Disqus user id.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s name.

access_token()[source]

Returns the OAuth access token string.

urlopen(url, **kwargs)[source]

Wraps urlopen() and adds OAuth credentials to the request.

class oauth_dropins.disqus.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts Disqus auth. Requests an auth code and expects a redirect back.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
class oauth_dropins.disqus.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The auth callback. Fetches an access token, stores it, and redirects home.

handle_error()[source]

Handles any error reported in the callback query parameters.

Parameters:handler – CallbackHandler
Returns:True if there was an error, False otherwise.

dropbox

Dropbox OAuth drop-in.

Standard OAuth 2.0 flow. Docs: https://www.dropbox.com/developers/core/docs https://www.dropbox.com/developers/reference/oauthguide

class oauth_dropins.dropbox.DropboxAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Dropbox user or page.

Provides methods that return information about this user (or page) and make OAuth-signed requests to Dropbox’s HTTP-based APIs. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Implements urlopen() but not api().

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the Dropbox user id.

access_token()[source]

Returns the OAuth access token string.

urlopen(url, **kwargs)[source]

Wraps urlopen() and adds OAuth credentials to the request.

class oauth_dropins.dropbox.DropboxCsrf(**kwargs)[source]

Bases: google.cloud.ndb.model.Model

Stores a CSRF token for the Dropbox OAuth2 flow.

class oauth_dropins.dropbox.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts Dropbox auth. Requests an auth code and expects a redirect back.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.dropbox.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The auth callback. Fetches an access token, stores it, and redirects home.

facebook

Facebook OAuth drop-in.

https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow

TODO: implement client state param TODO: unify this with instagram. see file docstring comment there.

class oauth_dropins.facebook.FacebookAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Facebook user or page.

Provides methods that return information about this user (or page) and make OAuth-signed requests to Facebook’s HTTP-based APIs. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Facebook-specific details: implements urlopen() but not api(). The key name is the user’s or page’s Facebook ID.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s or page’s name.

access_token()[source]

Returns the OAuth access token string.

urlopen(url, **kwargs)[source]

Wraps urlopen() and adds OAuth credentials to the request.

for_page(page_id)[source]

Returns a new, unsaved FacebookAuth entity for a page in pages_json.

The returned entity’s properties will be populated with the page’s data. access_token will be the page access token, user_json will be the page object, and pages_json will be a single-element list with the page.

If page_id is not in pages_json, returns None.

Parameters:page_id – string, Facebook page id
is_authority_for(key)[source]

Additionally check if the key represents a Page that this user has authority over.

Parameters:auth_entity_key – ndb.Key
Returns:true if key represents this user or one of the user’s pages.
Return type:boolean
class oauth_dropins.facebook.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts Facebook auth. Requests an auth code and expects a redirect back.

redirect_url(state=None, app_id=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
class oauth_dropins.facebook.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The auth callback. Fetches an access token, stores it, and redirects home.

static handle_error(handler)[source]

Handles any error reported in the callback query parameters.

Parameters:handler – CallbackHandler
Returns:True if there was an error, False otherwise.

flickr

Flickr OAuth drop-in.

Uses oauthlib directly to authenticate and sign requests with OAuth 1.0 credentials. https://www.flickr.com/services/api/auth.oauth.html

Note that when users decline Flickr’s OAuth prompt by clicking the Cancel button, Flickr redirects them to its home page, not to us.

class oauth_dropins.flickr.FlickrAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Flickr user.

Provides methods that return information about this user and make OAuth-signed requests to the Flickr API. Stores OAuth credentials in the datastore. Key is the Flickr user ID. See models.BaseAuth for usage details.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user id.

access_token()[source]

Returns the OAuth access token as a (string key, string secret) tuple.

urlopen(url, **kwargs)[source]

Wraps urllib.request.urlopen() and adds OAuth credentials to the request.

Use this for making direct HTTP REST request to a site’s API. Not guaranteed to be implemented by all sites.

The arguments, return value (urllib.request.Response), and exceptions raised (urllib.error.URLError) are the same as urllib2.urlopen.

class oauth_dropins.flickr.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts three-legged OAuth with Flickr.

Fetches an OAuth request token, then redirects to Flickr’s auth page to request an access token.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.flickr.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The OAuth callback. Fetches an access token and redirects to the front page.

flickr_auth

Utility functions for calling signed Flickr API methods.

Supports Python 3. Should not depend on App Engine API or SDK packages.

oauth_dropins.flickr_auth.signed_urlopen(url, token_key, token_secret, **kwargs)[source]

Call urllib.request.urlopen(), signing the request with Flickr credentials.

Parameters:
  • url (string) – the url to open
  • token_key (string) – user’s access token
  • token_secret (string) – the user’s access token secret
  • timeout (Optional[int]) – the request timeout, falls back to HTTP_TIMEOUT if not specified
Returns:

the file-like object that is the result of urllib.request.urlopen()

oauth_dropins.flickr_auth.call_api_method(method, params, token_key, token_secret)[source]

Call a Flickr API method.

Flickr has one API endpoint, where different methods are called by name.

If the “stat” field contains “fail”, then this method creates an artificial HTTPError 400 or 401 depending on the type of failure.

Parameters:
  • method (string) – the API method name (e.g. flickr.photos.getInfo)
  • params (dict) – the parameters to send to the API method
  • token_key (string) – the user’s API access token
  • token_secret (string) – the user’s API access token secret
Returns:

json object response from the API

oauth_dropins.flickr_auth.upload(params, file, token_key, token_secret)[source]

Upload a photo or video to this user’s Flickr account.

Flickr uploads use their own API endpoint, that returns only XML. https://www.flickr.com/services/api/upload.api.html

Unlike call_api_method(), this uses the requests library because urllib doesn’t support multi-part POSTs on its own.

Parameters:
  • params (dict) – the parameters to send to the API method
  • file (file-like object) – the image or video to upload
  • token_key (string) – the user’s API access token
  • token_secret (string) – the user’s API access token secret
Returns:

dict containing the photo id (as ‘id’)

Raises:

github

GitHub OAuth drop-in.

API docs: https://developer.github.com/v4/ https://developer.github.com/apps/building-oauth-apps/authorization-options-for-oauth-apps/#web-application-flow

class oauth_dropins.github.GitHubAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated GitHub user.

Provides methods that return information about this user and make OAuth-signed requests to the GitHub REST API. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

GitHub-specific details: implements get() but not urlopen(), or api(). The key name is the username.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s full name or username.

access_token()[source]

Returns the OAuth access token string.

get(*args, **kwargs)[source]

Wraps requests.get() and adds the Bearer token header.

TODO: unify with medium.py.

post(*args, **kwargs)[source]

Wraps requests.post() and adds the Bearer token header.

TODO: unify with medium.py.

class oauth_dropins.github.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts GitHub auth. Requests an auth code and expects a redirect back.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.github.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The OAuth callback. Fetches an access token and stores it.

google_signin

Google Sign-In OAuth drop-in.

Google Sign-In API docs: https://developers.google.com/identity/protocols/OAuth2WebServer Python API client docs: https://developers.google.com/api-client-library/python/ requests-oauthlib docs:

class oauth_dropins.google_signin.GoogleUser(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Google user.

Provides methods that return information about this user and make OAuth-signed requests to Google APIs. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

To make Google API calls: https://google-auth.readthedocs.io/

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s name.

access_token()[source]

Returns the OAuth access token string.

class oauth_dropins.google_signin.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.google_signin.Scopes, oauth_dropins.handlers.StartHandler

Starts the OAuth flow.

handle_exception(e, debug)

A webapp2 exception handler that propagates HTTP exceptions into the response.

Use this as a webapp2.RequestHandler.handle_exception() method by adding this line to your handler class definition:

handle_exception = handlers.handle_exception

I originally tried to put this in a webapp2.RequestHandler subclass, but it gave me this exception:

File ".../webapp2-2.5.1/webapp2_extras/local.py", line 136, in _get_current_object
  raise RuntimeError('no object bound to %s' % self.__name__) RuntimeError: no object bound to app

These are probably related:

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
class oauth_dropins.google_signin.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.google_signin.Scopes, oauth_dropins.handlers.CallbackHandler

Finishes the OAuth flow.

handlers

Based flow request handlers. Clients should use the individual site modules.

Example usage:

application = webapp2.WSGIApplication([
(‘/oauth_start’, facebook.StartHandler.to(‘/oauth_callback’)), (‘/oauth_callback’, facebook.CallbackHandler.to(‘/done’)), (‘/done’, AuthenticatedHandler), … ]
class oauth_dropins.handlers.BaseHandler(request=None, response=None)[source]

Bases: webapp2.RequestHandler

Base request handler class. Provides the to() factory method.

Attributes (some may be overridden by subclasses):
DEFAULT_SCOPE: string, default OAuth scope(s) to request SCOPE_SEPARATOR: string, used to separate multiple scopes LABEL: string, human-readable label, eg ‘Blogger’ NAME: string module name; usually same as __name__.split(‘.’)[-1]
handle_exception(e, debug)

A webapp2 exception handler that propagates HTTP exceptions into the response.

Use this as a webapp2.RequestHandler.handle_exception() method by adding this line to your handler class definition:

handle_exception = handlers.handle_exception

I originally tried to put this in a webapp2.RequestHandler subclass, but it gave me this exception:

File ".../webapp2-2.5.1/webapp2_extras/local.py", line 136, in _get_current_object
  raise RuntimeError('no object bound to %s' % self.__name__) RuntimeError: no object bound to app

These are probably related:

classmethod make_scope_str(extra)[source]

Returns an OAuth scopes query parameter value.

Combines DEFAULT_SCOPE and extra.

Parameters:extra – string, sequence of strings, or None
to_url(state=None)[source]

Returns a fully qualified callback URL based on to_path.

Includes scheme, host, and optional state.

request_url_with_state()[source]

Returns the current request URL, with the state query param if provided.

class oauth_dropins.handlers.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.BaseHandler

Base class for starting an OAuth flow.

Users should use the to() class method when using this request handler in a WSGI application. See the file docstring for details.

If the ‘state’ query parameter is provided in the request data, it will be returned to the client in the OAuth callback handler. If the ‘scope’ query parameter is provided, it will be added to the existing OAuth scopes.

Alternatively, clients may call redirect_url() and HTTP 302 redirect to it manually, which will start the same OAuth flow.

__init__(*args, **kwargs)[source]

Initializes this request handler with the given WSGI application, Request and Response.

When instantiated by webapp.WSGIApplication, request and response are not set on instantiation. Instead, initialize() is called right after the handler is created to set them.

Also in webapp dispatching is done by the WSGI app, while webapp2 does it here to allow more flexibility in extended classes: handlers can wrap dispatch() to check for conditions before executing the requested method and/or post-process the response.

Note

Parameters are optional only to support webapp’s constructor which doesn’t take any arguments. Consider them as required.

Parameters:
  • request – A Request instance.
  • response – A Response instance.
redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(to_path, form_classes='', form_method='post', form_extra='', image_prefix='', image_file=None, input_style='', scopes='', outer_classes='')[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.handlers.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.BaseHandler

Base OAuth callback request handler.

Users can use the to() class method when using this request handler in a WSGI application to make it redirect to a given URL path on completion. See the file docstring for details.

Alternatively, you can subclass it and implement finish(), which will be called in the OAuth callback request directly, after the user has been authenticated.

The auth entity and optional state parameter provided to StartHandler will be passed to finish() or as query parameters to the redirect URL.

finish(auth_entity, state=None)[source]

Called when the OAuth flow is complete. Clients may override.

Parameters:
  • auth_entity – a site-specific subclass of models.BaseAuth, or None if the user declined the site’s OAuth authorization request.
  • state – the string passed to StartHandler.redirect_url()

indieauth

IndieAuth drop-in.

https://indieauth.com/developers

oauth_dropins.indieauth.discover_authorization_endpoint(me, resp=None)[source]

Fetch a URL and look for authorization_endpoint Link header or rel-value.

Parameters:
  • me – string, URL to fetch
  • resprequests.Response (optional), re-use response if it’s already been fetched
Returns:

string, the discovered indieauth URL or the default indieauth.com URL

oauth_dropins.indieauth.build_user_json(me, resp=None)[source]

user_json contains an h-card, rel-me links, and “me”

Parameters:
  • me – string, URL of the user, returned by
  • resprequests.Response (optional), re-use response if it’s already been fetched
Returns:

dict, with ‘me’, the URL for this person; ‘h-card’, the representative h-card

for this page; ‘rel-me’, a list of rel-me URLs found at this page

class oauth_dropins.indieauth.IndieAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated IndieAuth user.

Provides methods that return information about this user. Stores credentials in the datastore. Key is the domain name. See models.BaseAuth for usage details.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s domain.

access_token()[source]

Return the access token, N/A for IndieAuth

class oauth_dropins.indieauth.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts the IndieAuth flow. Requires the ‘me’ parameter with the user URL that we want to authenticate.

redirect_url(state=None, me=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.indieauth.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The callback handler from the IndieAuth request. POSTs back to the auth endpoint to verify the authentication code.

instagram

Instagram OAuth drop-in.

Instagram API docs: http://instagram.com/developer/endpoints/

Almost identical to Facebook, except the access token request has code and grant_type query parameters instead of just auth_code, the response has a user object instead of id, and the call to GET_ACCESS_TOKEN_URL is a POST instead of a GET. TODO: unify them.

class oauth_dropins.instagram.InstagramAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Instagram user or page.

Provides methods that return information about this user (or page) and make OAuth-signed requests to Instagram’s HTTP-based APIs. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Instagram-specific details: implements urlopen() but not api(). The key name is the Instagram username.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the Instagram username.

access_token()[source]

Returns the OAuth access token string.

urlopen(url, **kwargs)[source]

Wraps urlopen() and adds OAuth credentials to the request.

class oauth_dropins.instagram.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts Instagram auth. Requests an auth code and expects a redirect back.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.instagram.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The auth callback. Fetches an access token, stores it, and redirects home.

linkedin

LinkedIn OAuth drop-in.

API docs: https://www.linkedin.com/developers/ https://docs.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin

class oauth_dropins.linkedin.LinkedInAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated LinkedIn user.

Provides methods that return information about this user and make OAuth-signed requests to the LinkedIn REST API. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Implements get() but not urlopen() or api(). The key name is the ID (a URN).

Note that LI access tokens can be over 500 chars (up to 1k!), so they need to be TextProperty instead of StringProperty. https://docs.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?context=linkedin/consumer/context#access-token-response

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s first and last name.

access_token()[source]

Returns the OAuth access token string.

get(*args, **kwargs)[source]

Wraps requests.get() and adds the Bearer token header.

TODO: unify with github.py, medium.py.

post(*args, **kwargs)[source]

Wraps requests.post() and adds the Bearer token header.

TODO: unify with github.py, medium.py.

class oauth_dropins.linkedin.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts LinkedIn auth. Requests an auth code and expects a redirect back.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.linkedin.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The OAuth callback. Fetches an access token and stores it.

mastodon

Mastodon OAuth drop-in.

Mastodon is an ActivityPub implementation, but it also has a REST + OAuth 2 API independent of AP. Uh, ok, sure.

API docs: https://docs.joinmastodon.org/api/

Interestingly: as usual w/OAuth, they require registering apps beforehand…but since AP and Mastodon are decentralized, there’s no single place to register an app. So they have an API for registering apps, per instance: https://docs.joinmastodon.org/api/authentication/ Surprising, and unusual, but makes sense.

class oauth_dropins.mastodon.MastodonApp(**kwargs)[source]

Bases: google.cloud.ndb.model.Model

A Mastodon API OAuth2 app registered with a specific instance.

class oauth_dropins.mastodon.MastodonAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Mastodon user.

Provides methods that return information about this user and make OAuth-signed requests to the Mastodon REST API. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Key name is the fully qualified actor address, ie @username@instance.tld.

Implements get() and post() but not urlopen() or api().

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s full ActivityPub address, eg @ryan@mastodon.social.

instance()[source]

Returns the instance base URL, eg https://mastodon.social/.

username()[source]

Returns the user’s username, eg ryan.

user_id()[source]

Returns the user’s id, eg 123.

access_token()[source]

Returns the OAuth access token string.

get(*args, **kwargs)[source]

Wraps requests.get() and adds instance base URL and Bearer token header.

post(*args, **kwargs)[source]

Wraps requests.post() and adds the Bearer token header.

class oauth_dropins.mastodon.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts Mastodon auth. Requests an auth code and expects a redirect back.

APP_NAME

string, user-visible name of this application. Displayed in Mastodon’s OAuth prompt.

APP_URL

string, this application’s web site

DEFAULT_SCOPE

string, default OAuth scope(s) to request

REDIRECT_PATHS

sequence of string URL paths (on this host) to register as OAuth callback (aka redirect) URIs in the OAuth app

SCOPE_SEPARATOR

string, used to separate multiple scopes

redirect_url(state=None, instance=None)[source]

Returns the local URL for Mastodon to redirect back to after OAuth prompt.

Parameters:
  • state – string, user-provided value to be returned as a query parameter in the return redirect
  • instance – string, Mastodon instance base URL, e.g. ‘https://mastodon.social’. May also be provided in the ‘instance’ request as a URL query parameter or POST body.

Raises: ValueError if instance isn’t a Mastodon instance.

classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.mastodon.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The OAuth callback. Fetches an access token and stores it.

medium

Medium OAuth drop-in.

API docs: https://github.com/Medium/medium-api-docs#contents https://medium.com/developers/welcome-to-the-medium-api-3418f956552

Medium doesn’t let you use a localhost redirect URL. :/ A common workaround is to map an arbitrary host to localhost in your /etc/hosts, e.g.:

127.0.0.1 my.dev.com

You can then test on your local machine by running dev_appserver and opening http://my.dev.com:8080/ instead of http://localhost:8080/ .

class oauth_dropins.medium.MediumAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Medium user.

Provides methods that return information about this user and make OAuth-signed requests to the Medium REST API. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Medium-specific details: implements get() but not urlopen() or api(). The key name is the user id (not username).

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the user’s full name or username.

access_token()[source]

Returns the OAuth access token string.

get(*args, **kwargs)[source]

Wraps requests.get() and adds the Bearer token header.

class oauth_dropins.medium.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts Medium auth. Requests an auth code and expects a redirect back.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
class oauth_dropins.medium.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The OAuth callback. Fetches an access token and stores it.

models

Base datastore model class for an authenticated account.

class oauth_dropins.models.BaseAuth(**kwargs)[source]

Bases: oauth_dropins.webutil.models.StringIdModel

Datastore base model class for an authenticated user.

Provides methods that return information about this user and make OAuth-signed requests to the site’s API(s). Stores OAuth credentials in the datastore. The key name is usually the user’s username or id.

Many sites provide additional methods and store additional user information in a JSON property.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns a string user identifier, e.g. ‘Ryan Barrett’ or ‘snarfed’.

api()[source]

Returns the site-specific Python API object, if any.

Returns None if the site doesn’t have a Python API. Only some do, currently Blogger, Instagram, Google, and Tumblr.

access_token()[source]

Returns the OAuth access token.

This is a string for OAuth 2 sites or a (string key, string secret) tuple for OAuth 1.1 sites (currently just Twitter and Tumblr).

urlopen(url, **kwargs)[source]

Wraps urllib.request.urlopen() and adds OAuth credentials to the request.

Use this for making direct HTTP REST request to a site’s API. Not guaranteed to be implemented by all sites.

The arguments, return value (urllib.request.Response), and exceptions raised (urllib.error.URLError) are the same as urllib2.urlopen.

is_authority_for(key)[source]

When disabling or modifying an account, it’s useful to re-auth the user to make sure they have have permission to modify that account. Typically this means the auth entity represents the exact same user, but in some cases (e.g., Facebook Pages), a user may control several unique identities. So authenticating as a user should give you authority over their pages.

Parameters:key – ndb.Key
Returns:boolean, true if key represents the same account as this entity
static urlopen_access_token(url, access_token, api_key=None, **kwargs)[source]

Wraps urllib.request.urlopen() and adds an access_token query parameter.

Kwargs are passed through to urlopen().

http()[source]

Returns an httplib2.Http that adds OAuth credentials to requests.

Use this for making direct HTTP REST request to a site’s API. Not guaranteed to be implemented by all sites.

class oauth_dropins.models.OAuthRequestToken(**kwargs)[source]

Bases: oauth_dropins.webutil.models.StringIdModel

Datastore model class for an OAuth 1.1 request token.

This is only intermediate data. Client should use BaseAuth subclasses to make API calls.

The key name is the token key.

tumblr

Tumblr OAuth drop-in.

API docs: http://www.tumblr.com/docs/en/api/v2 http://www.tumblr.com/oauth/apps

class oauth_dropins.tumblr.TumblrAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Tumblr user.

Provides methods that return information about this user and make OAuth-signed requests to the Tumblr API. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Tumblr-specific details: implements api() but not urlopen(). api() returns a tumblpy.Tumblpy. The datastore entity key name is the Tumblr username.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the username.

access_token()[source]

Returns the OAuth access token as a (string key, string secret) tuple.

oauth_dropins.tumblr.handle_exception(self, e, debug)[source]

Exception handler that handles Tweepy errors.

class oauth_dropins.tumblr.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts Tumblr auth. Requests an auth code and expects a redirect back.

handle_exception(e, debug)

Exception handler that handles Tweepy errors.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.tumblr.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

OAuth callback. Fetches the user’s blogs and stores the credentials.

handle_exception(e, debug)

Exception handler that handles Tweepy errors.

twitter

Twitter OAuth drop-in.

TODO: port to http://code.google.com/p/oauth/source/browse/#svn%2Fcode%2Fpython . tweepy is just a wrapper around that anyway.

class oauth_dropins.twitter.TwitterAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated Twitter user.

Provides methods that return information about this user and make OAuth-signed requests to the Twitter v1.1 API. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

Twitter-specific details: implements api(), get(), and post(). api() returns a tweepy.API; get() and post() wrap the corresponding requests methods. The datastore entity key name is the Twitter username.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the username.

access_token()[source]

Returns the OAuth access token as a (string key, string secret) tuple.

urlopen(url, **kwargs)[source]

Wraps urllib.request.urlopen() and adds an OAuth signature.

get(*args, **kwargs)[source]

Wraps requests.get() and adds an OAuth signature.

post(*args, **kwargs)[source]

Wraps requests.post() and adds an OAuth signature.

api()[source]

Returns a tweepy.API.

oauth_dropins.twitter.handle_exception(self, e, debug)[source]

Exception handler that handles Tweepy errors.

class oauth_dropins.twitter.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts three-legged OAuth with Twitter.

Fetches an OAuth request token, then redirects to Twitter’s auth page to request an access token.

access_type

optional, ‘read’ or ‘write’. Passed through to Twitter as x_auth_access_type. If the twitter app has read/write or read/write/dm permissions, this lets you request a read-only token. Details: https://dev.twitter.com/docs/api/1/post/oauth/request_token

handle_exception(e, debug)

Exception handler that handles Tweepy errors.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
class oauth_dropins.twitter.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The OAuth callback. Fetches an access token and redirects to the front page.

handle_exception(e, debug)

Exception handler that handles Tweepy errors.

twitter_auth

Utility functions for generating Twitter OAuth headers and making API calls.

This is a separate module from twitter.py so that projects like granary can use it without pulling in App Engine dependencies.

Supports Python 3. Should not depend on App Engine API or SDK packages.

oauth_dropins.twitter_auth.auth_header(url, token_key, token_secret, method='GET')[source]

Generates an Authorization header and returns it in a header dict.

Parameters:
  • url – string
  • token_key – string
  • token_secret – string
  • method – string
Returns:

single element with key ‘Authorization’

Return type:

dict

oauth_dropins.twitter_auth.signed_urlopen(url, token_key, token_secret, headers=None, **kwargs)[source]

Wraps urllib.request.urlopen() and adds an OAuth signature.

oauth_dropins.twitter_auth.tweepy_auth(token_key, token_secret)[source]

Returns a tweepy.OAuthHandler.

wordpress_rest

WordPress.com OAuth drop-in.

API docs: https://developer.wordpress.com/docs/api/ https://developer.wordpress.com/docs/oauth2/

Note that unlike Blogger and Tumblr, WordPress.com’s OAuth tokens are per blog. It asks you which blog to use on its authorization page.

Also, wordpress.com doesn’t let you use an oauth redirect URL with “local” or “localhost” anywhere in it. : / A common workaround is to map an arbitrary host to localhost in your /etc/hosts, e.g.:

127.0.0.1 my.dev.com

You can then test on your local machine by running dev_appserver and opening http://my.dev.com:8080/ instead of http://localhost:8080/ .

class oauth_dropins.wordpress_rest.WordPressAuth(**kwargs)[source]

Bases: oauth_dropins.models.BaseAuth

An authenticated WordPress user or page.

Provides methods that return information about this user (or page) and make OAuth-signed requests to the WordPress REST API. Stores OAuth credentials in the datastore. See models.BaseAuth for usage details.

WordPress-specific details: implements urlopen() but not api(). The key name is the blog hostname.

site_name()[source]

Returns the string name of the site, e.g. ‘Facebook’.

user_display_name()[source]

Returns the blog hostname.

access_token()[source]

Returns the OAuth access token string.

urlopen(url, **kwargs)[source]

Wraps urllib.request.urlopen() and adds OAuth credentials to the request.

class oauth_dropins.wordpress_rest.StartHandler(*args, **kwargs)[source]

Bases: oauth_dropins.handlers.StartHandler

Starts WordPress auth. Requests an auth code and expects a redirect back.

redirect_url(state=None)[source]

Returns the local URL for the OAuth service to redirect back to.

oauth-dropin subclasses must implement this.

Parameters:state – string, user-provided value to be returned as a query parameter in the return redirect
classmethod button_html(*args, **kwargs)[source]

Returns an HTML string with a login form and button for this site.

Parameters:
  • to_path – string, path or URL for the form to POST to
  • form_classes – string, optional, HTML classes to add to the <form>
  • form_classes – string, optional, HTML classes to add to the outer <div>
  • form_method – string, optional, form action ie HTTP method, eg ‘get’; defaults to ‘post’
  • form_extra – string, optional, extra HTML to insert inside the <form> before the button
  • scopes – string, optional, OAuth scopes to override site’s default(s)
  • image_prefix – string, optional, prefix to add to the beginning of image URL path, eg ‘/oauth_dropins/’
  • image_file – string, optional, image filename. defaults to [cls.NAME].png
  • input_style – string, optional, inline style to apply to the button <input>

Returns: string

class oauth_dropins.wordpress_rest.CallbackHandler(request=None, response=None)[source]

Bases: oauth_dropins.handlers.CallbackHandler

The OAuth callback. Fetches an access token and stores it.