View source for Oauth2 authentication

{{Infobox Project
|name = Oauth2 authentication plugins
|state = Specification consultation
|tracker = MDL-34426
|assignee = [[User:Jerome mouneyrac|Jerome mouneyrac]]
|discussion = http://moodle.org/mod/forum/discuss.php?d=212430
}}

This document describes the functional and technical specification of the Moodle Oauth2 plugin(s). Oauth2 plugin(s) will allow a user to authenticate in Moodle with their Google or Facebook account.

= Functional specification =

== What are the user's benefits ==
* Fast account creation: the new user form is pre-filled with information from the Google/Facebook account.
* Fast login: 1 click on a Google/Facebook button.
* The user does not need to remember a password for Moodle.

== User use cases ==
==== User already has an account ====
Pre condition:  the Google account email is matching a Moodle account[[{{ns:file}}:Login_page.jpeg|200px|thumb|right|Login page]]
# in the login section, the user clicks on Google button
# A Google page is opened asking the user to authorize  the Moodle site (happens only once)
# user is logged in

Pre condition:  the Google account email is not matching any Moodle account[[{{ns:file}}:Account_Not_Found.jpeg|200px|thumb|right|Account Not Found]]
# in the login section, the user clicks on Google button
# A Google page is opened asking the user to authorize  the Moodle site (happens only once)
# the login page is displayed with an error message saying that the user need to allow the Google login in his profile page.
# the user login as usual.
# the user goes on the edit profile page
# the user click on the Google button in the label "Allow login with:"
# the Google button is now highlighted indicating the user can connect with Google

==== User authenticates for the first time ====
Pre condition:  the Google account email is not matching any Moodle account
# in the "Is it your first time?" section, the user clicks on Google button
# A Google page is opened asking the user to authorize  the Moodle site (happens only once)
# The new user form is displayed. Most mandatory field are already pre-filled.


==== User wants to disallow login with Google ====
Pre condition: the user is login in the edit profile page.
Pre condition: the Google login is allowed (the Google button is highlighted in the profile page)
Pre condition: the user has a different way to connect in Moodle
# the user clicks on the Google button
# the Google button is not highlighted anymore

Pre condition: the user is login in the edit profile page.
Pre condition: the Google login is allowed (the Google button is highlighted in the profile page)
Pre condition: the user has no different way to connect in Moodle
# the user clicks on the Google button
# an alert is displayed saying that Moodle can not disallowed the login with Google as it's the last authentication method of the user.

== Administrator use cases ==
The administrator wants to:
* enable the plugin(s)
* set Oauth2 client id / Oauth2 client secret
* allow user account creation
* set lockable fields
* bypass the deny/allow email addresses global settings (for example allow hotmail registration by Oauth2 but disallow it for manual to avoid spammer)

= Technical specification =

== What is Oauth2 ==
OAuth2 is a security protocol that enables users to grant third-party access (i.e. Moodle) to their web resources (i.e Google/Facebook/...'s user data) without sharing their passwords.

==== See also ====
* [http://oauth.net/2/ Oauth2 specification]

== Why implementing Oauth2 which is still in Draft version==
The main reason we choose Oauth2 is that massive identity providers as Google already started to [https://developers.google.com/accounts/docs/OAuth deprecate Oauth1] or only use Oauth2 (Facebook). Oauth2 has also for benefit over Oauth1 to be simpler to implement for the client. However at the moment, Oauth2 is on a [http://hueniverse.com/2012/07/oauth-2-0-and-the-road-to-hell/ rocky road]. The specification are still marked as Draft, and major providers as Facebook or Google implement their own version. But at the end these implementations are globally similar, and we will be able to reuse a major part of our code for each providers.

==== See also ====
* [https://developers.google.com/accounts/docs/OAuth2 Google Oauth2]
* [https://developers.facebook.com/docs/authentication/ Facebook Oauth2]
* [http://msdn.microsoft.com/en-us/library/live/hh243647.aspx Microsoft Live Oauth2]
* [https://dev.twitter.com/docs/anywhere/welcome Twitter JS authentication]
* [https://developer.linkedin.com/documents/getting-started-javascript-api Linkedin JS authentication]

==What about Oauth1==
Actually we will have to implement it as well as some big identity provider as Twitter only offer Oauth1.

==== See also ====
* [https://developer.linkedin.com/documents/authentication LinkedinOauth1]
* [https://dev.twitter.com/docs/auth/oauth Twitter Oauth1]


== One plugin by provider or One plugin for all providers ==
There were some talk about having one plugin by provider (one for Google, one for Moodle, one for Facebook) or one plugin with all provider (Google/Moodle(s)/facebook in one page). Both choice can support multiple instances (For example when Moodle sites will be Oauth2 providers).  
=== One plugin by provider ===
As we go for multiple authentication, each providers should have it's own lockable fields. Lockable fields will be ignored if the Oauth2 auth method is not the primary auth method of the user. 
==== Pros ====
* it works nice with lang file and Amos without additional code. Each providers use its own vocabulary (client id/app id) and need its own explanation on how to set it up.
* clean setting page by providers
* can enable/disable each plugin without losing the settings
* easy overview of which authentication method is enabled

==== Cons ====

=== One plugin for all providers ===
==== Pros ====
* less click to setup for the administrator. Only enable one plugin.

==== Cons ====
* the settings page could become bigger and messier.
* need an additional "enable" checkbox for each providers (so the administrator can disable the plugin without losing the settings)
* administratosr do not know which Oauth2 provider is enabled without looking into the Oauth2 plugin.
* does not work well with AMOS

== Proposed design ==
<code language=php>
auth/oauth2SHORTNAME/auth.php
/**
 * Facebook Oauth2 authentication plugin.
 */
class auth_plugin_oauth2SHORTNAME extends auth_plugin_oauth2 {

    public function __construct() {
        global $CFG;

        $this->name = 'Human Name';
        $this->shortname = SHORTNAME;
        $this->clientlibpath = $CFG->libdir . '/facebookapi.php';
        $this->clientclassname = 'shortname_oauth';
        $this->clientscope = 'email';

        parent::__construct();
    }
}

lib/SHORTNAMEapi.php
/** OAuth 2.0 client for SHORTNAME Services */
class SHORTNAME_oauth extends oauth2_client {
    
    /** Returns the auth url for OAuth 2.0 request */
    protected function auth_url() {
        // ...
    }

    /** Returns the token url for OAuth 2.0 request */
    protected function token_url() {
        // ...
    }

    /** Resets headers and response for multiple requests */
    public function reset_state() {
        // ...
    }
    
    /** Retrieve user info from SHORTNAME api */
    public function retrieve_auth_user_info() {
        // Oauth2 API call to get user info

        // Store result into $this->oauth2user
    }
}

lib/oauth2/auth.php
/** Oauth2 authentication plugin. */
abstract class auth_plugin_oauth2 extends auth_plugin_base {

    public $name;
    public $shortname;
    public $logourl;
    public $oauth2client;
    public $clientclassname;
    public $clientlibpath;
    public $clientscope;

    public function __construct() {
        // - Check that the extending class is correctly located, named, constructed.
        // - Instanciate the oauth2 client
        // - Normal auth_plugin_base settings
    }

    function prevent_local_passwords() { return true;}

    function user_login($username, $password) {
        //retrieve the user matching username
        //username must exist
    }

    function is_internal() {return false;}

    function can_change_password() {return false;}

    /**
     * Authentication hook - is called every time user hit the login page
     * The code is run only if the param code is mentionned.
     */
    function loginpage_hook() {

        //check the authorization code and that we are the right oauth2 plugin
       
                // Load the authenticated user info
               
                //throw an error if the email address is not verified
              
                // Prohibit login if email belongs to the prohibited domain

                // Detect it's a linking call
                // If yes then redirect to the profile page
               
                    // Link the account
                   
                        // Redirect back to edit profile page
 
                // Check if a linked account already exist
           
                // Avoid to commit an incomplete new user if ever a crash appears
             
                //create the user if it doesn't exist
                                  
                    // Check the provider allow user creation                   
                    
                    // If the user didn't confirm creation, then redirect to confirmation page
                   
                    //get following incremented username
                  
                    //check the user doesn't exist
                   
                    //retrieve more information from the provider
                   
                    //retrieve country and city if the provider failed to give it
                  
                    // create user record

                    // link account

                //authenticate the user
                
                    //set a cookie to remember what auth provider was selected
                 
                    //prefill more user information if new user
                   
                    // Set URL redirection to the user edit page
                
                //We are going to redirect, it's time to commit the new user            
    }

    function loginpage_idp_list($wantsurl) {
        // List the different instance (mainly for Oauth2 Moodle)
    }

}
</code>

== Multiple authentication support ==
In order to support account linking we need a table to support multiple authentication.
=== New table:  mdl_user_auths ===

{| class="wikitable"
! id !! component !!  class="unsortable" |userid !!  class="unsortable" | provideruserid
|-
|  1 || auth_manual || 2 || null 
|-
|  1 || auth_oauth2google || 2 || 85134984 
|}

=== See also ===
* [https://docs.moodle.org/dev/Multi_authentication Multiple Authentication] (old)

= See also =
* MDL-34426