django-simple-socialauth 1.1.0

User Registration

If the user doesn’t exist in the system, django-simple-socialauth will create a new User and populate the first, last, email, and username fields with data it retrieves from the social provider’s API. If possible, django-simple-socialauth will skip the ‘completion form’ step if all required information was retrieved - otherwise it is shown to the user to collect email and username as needed prior to User creation.

It then creates a `SocialAccount <https://github.com/jaddison/django-simple-socialauth/blob/master/simple_socialauth/models.py>`__ instance representing the social provider’s (ie. Facebook, Twitter, etc.) unique ID and access/refresh token data for the user. This SocialAccount is obviously associated with the new User via a foreign key.

Lastly, a connect signal is sent. This is an opportunity for the developer to hook into the social user registration process.

User Log in

If the user does exist in the system, django-simple-socialauth retrieves the existing SocialAccount and associated User - and updates the SocialAccount with the new access/refresh token data as needed.

A ‘login’ signal is sent, allowing the developer to hook into the social user login process.

After Authentication

The user’s SocialAccount instance has a session property that sets up an appropriate OAuth1/2 authenticated requests session, which lets the developer access the social provider’s API using the user’s access_token, etc.

# assuming a Facebook SocialAccount object
r = social_account_obj.session.get('https://graph.facebook.com/me')
if r.ok:
    user_data = r.json()
    ...

OAuth Scope Advice

When selecting which OAuth scopes for your enabled providers in SIMPLE_SOCIALAUTH_PROVIDERS_SETTINGS, consider adding the scopes that get you both the username and email address for the authenticating user. This will allow the user to skip the cumbersome ‘completion form’ step that asks them to fill those fields in.

Included Social Providers

All are OAuth2 unless indicated:

• facebook: simple_socialauth.providers.facebook.FacebookProvider

• twitter: simple_socialauth.providers.twitter.TwitterProvider (OAuth1)

• github: simple_socialauth.providers.github.GithubProvider

• pinterest: simple_socialauth.providers.pinterest.PinterestProvider

• google: simple_socialauth.providers.google.GoogleProvider

• linkedin: simple_socialauth.providers.linkedin.LinkedinProvider

• angellist: simple_socialauth.providers.angellist.AngellistProvider

Creating Custom Providers

If the social provider you want to add is OAuth1 or OAuth2 based, then requests-oauthlib almost certainly supports it. There are some that aren’t fully OAuth1/2 compliant, and thus requests-oauthlib has a number of compliance fixes. This project uses the Facebook and LinkedIn fixes, for example.

Creating a custom provider is quite simple - let’s take a look at the Github provider to see what’s involved:

from .base import BaseProvider


class GithubProvider(BaseProvider):
    type = 'github'

    def __init__(self, **kwargs):
        self.authorization_url = 'https://github.com/login/oauth/authorize'
        self.access_token_url = 'https://github.com/login/oauth/access_token'
        super(GithubProvider, self).__init__(**kwargs)

    def get_social_user_info(self):
        r = self.session.get('https://api.github.com/user')
        if r.status_code == 200:
            data = r.json()
            uid = data.get('id')
            name = data.get('name', '')
            name_split = name.split(' ', 1)
            return {
                'source_data': data,
                'uid': uid,
                'username': data.get('login', ''),
                'email': data.get('email', ''),
                'company': data.get('company', ''),
                'organizations_url': data.get('organizations_url', ''),
                'repositories_url': data.get('repos_url', ''),
                'name': name,
                'first_name': name_split[0],
                'last_name': name_split[1] if len(name_split) > 1 else ''
            }
        return {}

Each provider must inherit from BaseProvider and requires a unique type value.

For display purposes, a name value can be optionally set, but will fall back on type. This is useful for providers whose names aren’t easily title-cased, such as “LinkedIn” (note the capital ‘I’).

The appropriate OAuth1/2 URLs must be set:

• authorization_url (OAuth1/2)

• access_token_url (OAuth1/2)

• request_token_url (OAuth1 only - see the Twitter provider)

Any compliance fixes ought to be done at the end of the provider’s __init__.

Upon successful user authentication via a provider, django-simple-socialauth calls the provider’s get_social_user_info() method, which retrieves key user-specific information from the social provider’s authenticated API. This method should return the following information (if available) in a dict:

• uid the social provider’s unique ID for the user in their system (required!)

• username

• email

• first_name

• last_name

This information is used to create the Django User.