.. _lino.socialauth: ===================== 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 :mod:`lino_book.projects.noi1e` demo project. If you have the :doc:`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**.): .. figure:: socialauth1.png :width: 80 % The Lino Team main page for anonymous users. Click on **github**. This will lead you to the GitHub website: .. figure:: socialauth2.png :width: 80 % 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). .. image:: socialauth3.png :width: 80 % Voilà. You you are now logged in into the Lino Noi running on your machine, authentified via your GitHub account. You can now edit your user profile by clicking on **[My settings]**: .. image:: socialauth4.png Here is how the confirmation page looks on Facebook: .. figure:: 20171215b.png :width: 80 % Facebook asking your permission to authenticate you at the "Lino authentication" app Or on WikiMedia: .. figure:: 20180731b.png :width: 80 % 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 site administrator, you must chose which authentication providers you want to offer to your users. 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 :xfile:`settings.py` you must set :attr:`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 :mod:`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 :menuselection:`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 :xfile:`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 :xfile:`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 :xfile:`settings.py` on your website. Exercises ========= - Note that your user type is "user" and that you cannot change this. Only administrators 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 :attr:`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 :class:`lino.modlib.users.SignIn` dialog window because you have no password set. - Sign in as robin (an administrator) and merge two users. Note that with Lino you do not need to set Django's :setting:`AUTHENTICATION_BACKENDS` setting yourself, Lino will do that for you, based on miscellaneous criteria (and :attr:`social_auth_backends ` is only one of them). User's friends ============== Once an user get authentified via one of official supported third-party by Lino, we can retrieve 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 :xfile:`settings.py` of :mod:`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 :mod:`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.