Social Authentication¶

In a Lino application you can easily enable third-party authentication thanks to Python Social Auth (PSA).

A working example¶

A working example is in the lino_book.projects.noi1e demo project. If you have the Lino developer environment installed, you can test the social auth functionality on your machine by doing:

$ go team
$ python manage.py prep
$ runserver

Now point your browser to http://127.0.0.1:8000/ and you should see something like this (note the message Or sign in using github, google-plus facebook mediawiki.):

../../_images/socialauth1.png — The Lino Team main page for anonymous users.¶

Click on github. This will lead you to the GitHub website:

../../_images/socialauth2.png — Github asking your permission to authenticate you at the “Lino auth tester” app¶

There you must click on the big green button to tell GitHub that they may communicate your contact data to the Social Auth Tester application at http://127.0.0.1:8000/ (IOW on you own computer).

You you are now logged in into the Lino Noi running on your machine, authenticated via your GitHub account. You can now edit your user settings by clicking on [My settings]:

Note that you cannot change your user type and that the Lino site is configured to not give too many permissions to a user who just drops in via some third-party authentication provider.

Here is how the confirmation page looks on Facebook:

../../_images/20171215b.png — Facebook asking your permission to authenticate you at the “Lino authentication” app¶

Or on WikiMedia:

../../_images/20180731b.png — WikiMedia asking your permission to authenticate you at the “Social Auth Tester” app¶

This works out of the box because we did the work of creating applications on GitHub, Google+, Facebook and WikiMedia. Details about how to do that see below.

How it works¶

As the server administrator you must chose which authentication providers you want to offer on this site. For each provider you will activate the corresponding “backend”.

Add the backend in your settings¶

Available backends are listed in the PSA documentation.

In your local settings.py you must set social_auth_backends to a list of the backends you want to offer on your site. If you want GitHub, the you will write:

class Site(Site):
    ...
    social_auth_backends = [
       'social_core.backends.github.GithubOAuth2']

We got the name of that backend (social_core.backends.github.GithubOAuth2) from the detailed instructions page for GitHub. For other backends we just looked at the code of social_core.backends.

Create a consumer¶

For OAuth backends you need to create a “consumer” or “application” on the provider’s website. You tell the provider that you run a site whose users will want to authenticate, and the provider will then give you a “key” and a “secret”.

Here are the parameters we used for creating the GitHub application:

Application name: Social Auth Tester
Homepage URL: http://127.0.0.1:8000/
Authorization callback URL: http://127.0.0.1:8000/oauth/complete/github

In Facebook you must go to Products ‣ Facebook Login ‣ Settings and enable the following:

Embedded Browser OAuth Login

Enables browser control redirect uri for OAuth client login.

For Wikimedia the instructions are in the PSA docs and on the mediawiki site.

You must then store these in your settings.py. For example:

SOCIAL_AUTH_GITHUB_KEY = '...'
SOCIAL_AUTH_GITHUB_SECRET = '...'

The client secrets of these applications we used for this toturial aren’t really secret anymore since they are stored in the settings.py of the team demo project (more exactly here). In a real setup you will of course give the public URL of your website, and you will write that secret only to the settings.py on your website.

Exercises¶

Note that your user type is “user” and that you cannot change this. Only a site manager can change the user type.
Sign out. Note that your user name is now listed below This demo site has 7 users:. This list does not show on a real site, it is there because is_demo_site is True.
Note that you exist as a user, but you can sign in only through GitHub. You can not sign in using the lino.modlib.users.SignIn dialog window because you have no password set.
Sign in as robin (an administrator) and merge the new user account to some existing user account.

Note that with Lino you do not need to set Django’s AUTHENTICATION_BACKENDS setting yourself, Lino does that for you, based on miscellaneous criteria (and social_auth_backends is only one of them).

User’s friends¶

Once an user has authenticated via one of official supported third-party by Lino, we can retrieve that user’s public “friends”.

The following is an example how you can try to see all your Google+ friends using Google People API after having authenticated using GooglePlus.

To be able to use this API, we need to install google-api-python-client:

pip install google-api-python-client

The demo settings.py of lino_book.projects.noi1e have the following things done:

We added more scopes to SOCIAL_AUTH_GOOGLE_PLUS_SCOPE:

SOCIAL_AUTH_GOOGLE_PLUS_SCOPE = [
    'profile',
    'https://www.googleapis.com/auth/plus.login',
    # Add at least one of the following scopes.
    'https://www.googleapis.com/auth/contacts.readonly', # To have just READ permission
    'https://www.googleapis.com/auth/contacts ', # To have WRITE/READ permissions
]

We added social_core.backends.google.GooglePlusAuth to social_auth_backends.

Run the web interface on your machine and log in via Google+ as described in A working example.

Run the following script from the lino_book.projects.noi1e project directory:

python manage.py run try_people_api.py

The script uses the Google People API alongside with the credentials captured during the user logging via GooglePlus.