Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Oauth2 authentication: Difference between revisions

From MoodleDocs
Line 85: Line 85:
* does not work well with AMOS
* 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 google_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
    }
}
</code>


== Multiple authentication support ==
== Multiple authentication support ==

Revision as of 05:39, 14 August 2012

This document describes the functional and technical specification of Moodle Oauth2 plugin(s). Oauth2 plugin(s) will allow a user to authenticate in Moodle with a identity provider that implement Oauth2, like Google or Facebook.

What is Oauth2

OAuth 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

What are the user's benefits

  • The user can connect in Moodle with a Google/Facebook/... account.
  • Login is fast: 1 click on a Google/Facebook/... button.
  • The user does not need to remember a password for Moodle.
  • The user can link an existing Moodle account to an Oauth2 identity provider. Thus the user benefits of the above points.
  • When the user is new, the creation process is faster: in the best case, which is the case for Facebook/Google, every mandatory user fields are pre filled.

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 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 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

What about Oauth1

Actually we will have to implement it as well as some big identity provider as Twitter or Linkedin only offer Oauth1.

See also

Functional specification

User

User authenticates for the first time in Moodle

  1. user clicks on Google button
  2. A Google page is opened asking the user to authorize the Moodle site (happens only once)
  3. Pre-filled profile page is displayed. The user can update the information.

User already has an account

The email address sent by the identity provider is known by Moodle

  1. user clicks on Google button
  2. A Google page is opened asking the user to authorize the Moodle site (happens only once)
  3. user is logged in

The email address is unknown

  1. user clicks on Google button
  2. A Google page is opened asking the user to authorize the Moodle site (happens only once)
  3. a page asks if the user already have an account. There is one "create account / continue" button, and some authentication forms similar to the ones on the login page.
    • user has no accounts: the user clicks on continue. The pre-filled profile page is displayed. The user can update the information
    • user has an account: the user authenticates with the forms. The user arrive on a page asking to link Google account. The user clicks on Google account. The user is logged in. The account has been linked.

Administration

The administrator wants to:

  • enable the plugin(s)
  • set Oauth2 client id / Oauth2 client secret
  • allow user account creation
  • set lockable fields
  • deny email addresses
  • bypass the deny email addresses global settings (for example allow hotmail registration by Oauth2 but disallow it for manual to avoid spammer)
  • allow email addresses
  • allow the user to remove the authentication method (if not primary)

Technical specification

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

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 google_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
   }

}

Multiple authentication support

There is a previous page on the subject: Multiple Authentication.

New table: mdl_user_auths

id component userid provideruserid
1 auth_manual 2 null
1 auth_oauth2google 2 85134984

See also