2 // This file is part of Moodle - http://moodle.org/
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
22 * @copyright 2016 Juan Leyva <juan@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 use core_external\external_api
;
28 use core_external\external_function_parameters
;
29 use core_external\external_single_structure
;
30 use core_external\external_value
;
31 use core_external\external_warnings
;
33 defined('MOODLE_INTERNAL') ||
die;
35 require_once($CFG->libdir
. '/authlib.php');
38 * Auth external functions
42 * @copyright 2016 Juan Leyva <juan@moodle.com>
43 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
46 class core_auth_external
extends external_api
{
49 * Describes the parameters for confirm_user.
51 * @return external_function_parameters
54 public static function confirm_user_parameters() {
55 return new external_function_parameters(
57 'username' => new external_value(core_user
::get_property_type('username'), 'User name'),
58 'secret' => new external_value(core_user
::get_property_type('secret'), 'Confirmation secret'),
64 * Confirm a user account.
66 * @param string $username user name
67 * @param string $secret confirmation secret (random string) used for validating the confirm request
68 * @return array warnings and success status (true if the user was confirmed, false if he was already confirmed)
70 * @throws moodle_exception
72 public static function confirm_user($username, $secret) {
76 $params = self
::validate_parameters(
77 self
::confirm_user_parameters(),
79 'username' => $username,
84 $context = context_system
::instance();
85 $PAGE->set_context($context);
87 if (!$authplugin = signup_get_user_confirmation_authplugin()) {
88 throw new moodle_exception('confirmationnotenabled');
91 $confirmed = $authplugin->user_confirm($username, $secret);
93 if ($confirmed == AUTH_CONFIRM_ALREADY
) {
98 'warningcode' => 'alreadyconfirmed',
99 'message' => s(get_string('alreadyconfirmed'))
101 } else if ($confirmed == AUTH_CONFIRM_OK
) {
104 throw new moodle_exception('invalidconfirmdata');
108 'success' => $success,
109 'warnings' => $warnings,
115 * Describes the confirm_user return value.
117 * @return external_single_structure
120 public static function confirm_user_returns() {
122 return new external_single_structure(
124 'success' => new external_value(PARAM_BOOL
, 'True if the user was confirmed, false if he was already confirmed'),
125 'warnings' => new external_warnings(),
131 * Describes the parameters for request_password_reset.
133 * @return external_function_parameters
136 public static function request_password_reset_parameters() {
137 return new external_function_parameters(
139 'username' => new external_value(core_user
::get_property_type('username'), 'User name', VALUE_DEFAULT
, ''),
140 'email' => new external_value(core_user
::get_property_type('email'), 'User email', VALUE_DEFAULT
, ''),
146 * Requests a password reset.
148 * @param string $username user name
149 * @param string $email user email
150 * @return array warnings and success status (including notices and errors while processing)
152 * @throws moodle_exception
154 public static function request_password_reset($username = '', $email = '') {
156 require_once($CFG->dirroot
. '/login/lib.php');
159 $params = self
::validate_parameters(
160 self
::request_password_reset_parameters(),
162 'username' => $username,
167 $context = context_system
::instance();
168 $PAGE->set_context($context); // Needed by format_string calls.
170 // Check if an alternate forgotten password method is set.
171 if (!empty($CFG->forgottenpasswordurl
)) {
172 throw new moodle_exception('cannotmailconfirm');
175 $errors = core_login_validate_forgot_password_data($params);
176 if (!empty($errors)) {
177 $status = 'dataerror';
180 foreach ($errors as $itemname => $message) {
184 'warningcode' => 'fielderror',
185 'message' => s($message)
189 list($status, $notice, $url) = core_login_process_password_reset($params['username'], $params['email']);
195 'warnings' => $warnings,
200 * Describes the request_password_reset return value.
202 * @return external_single_structure
205 public static function request_password_reset_returns() {
207 return new external_single_structure(
209 'status' => new external_value(PARAM_ALPHANUMEXT
, 'The returned status of the process:
210 dataerror: Error in the sent data (username or email). More information in warnings field.
211 emailpasswordconfirmmaybesent: Email sent or not (depends on user found in database).
212 emailpasswordconfirmnotsent: Failure, user not found.
213 emailpasswordconfirmnoemail: Failure, email not found.
214 emailalreadysent: Email already sent.
215 emailpasswordconfirmsent: User pending confirmation.
216 emailresetconfirmsent: Email sent.
218 'notice' => new external_value(PARAM_RAW
, 'Important information for the user about the process.'),
219 'warnings' => new external_warnings(),
225 * Describes the parameters for the digital minor check.
227 * @return external_function_parameters
230 public static function is_minor_parameters() {
231 return new external_function_parameters(
233 'age' => new external_value(PARAM_INT
, 'Age'),
234 'country' => new external_value(PARAM_ALPHA
, 'Country of residence'),
240 * Requests a check if a user is digital minor.
242 * @param int $age User age
243 * @param string $country Country of residence
244 * @return array status (true if the user is a minor, false otherwise)
246 * @throws moodle_exception
248 public static function is_minor($age, $country) {
250 require_once($CFG->dirroot
. '/login/lib.php');
252 $params = self
::validate_parameters(
253 self
::is_minor_parameters(),
256 'country' => $country,
260 if (!array_key_exists($params['country'], get_string_manager()->get_list_of_countries())) {
261 throw new invalid_parameter_exception('Invalid value for country parameter (value: '.
262 $params['country'] .')');
265 $context = context_system
::instance();
266 $PAGE->set_context($context);
268 // Check if verification of age and location (minor check) is enabled.
269 if (!\core_auth\digital_consent
::is_age_digital_consent_verification_enabled()) {
270 throw new moodle_exception('nopermissions', 'error', '',
271 get_string('agelocationverificationdisabled', 'error'));
274 $status = \core_auth\digital_consent
::is_minor($params['age'], $params['country']);
282 * Describes the is_minor return value.
284 * @return external_single_structure
287 public static function is_minor_returns() {
288 return new external_single_structure(
290 'status' => new external_value(PARAM_BOOL
, 'True if the user is considered to be a digital minor,
297 * Describes the parameters for is_age_digital_consent_verification_enabled.
299 * @return external_function_parameters
302 public static function is_age_digital_consent_verification_enabled_parameters() {
303 return new external_function_parameters(array());
307 * Checks if age digital consent verification is enabled.
309 * @return array status (true if digital consent verification is enabled, false otherwise.)
311 * @throws moodle_exception
313 public static function is_age_digital_consent_verification_enabled() {
316 $context = context_system
::instance();
317 $PAGE->set_context($context);
320 // Check if verification is enabled.
321 if (\core_auth\digital_consent
::is_age_digital_consent_verification_enabled()) {
331 * Describes the is_age_digital_consent_verification_enabled return value.
333 * @return external_single_structure
336 public static function is_age_digital_consent_verification_enabled_returns() {
337 return new external_single_structure(
339 'status' => new external_value(PARAM_BOOL
, 'True if digital consent verification is enabled,
346 * Describes the parameters for resend_confirmation_email.
348 * @return external_function_parameters
351 public static function resend_confirmation_email_parameters() {
352 return new external_function_parameters(
354 'username' => new external_value(core_user
::get_property_type('username'), 'Username.'),
355 'password' => new external_value(core_user
::get_property_type('password'), 'Plain text password.'),
356 'redirect' => new external_value(PARAM_LOCALURL
, 'Redirect the user to this site url after confirmation.',
363 * Requests resend the confirmation email.
365 * @param string $username user name
366 * @param string $password plain text password
367 * @param string $redirect redirect the user to this site url after confirmation
368 * @return array warnings and success status
370 * @throws moodle_exception
372 public static function resend_confirmation_email($username, $password, $redirect = '') {
376 $params = self
::validate_parameters(
377 self
::resend_confirmation_email_parameters(),
379 'username' => $username,
380 'password' => $password,
381 'redirect' => $redirect,
385 $context = context_system
::instance();
386 $PAGE->set_context($context); // Need by internal APIs.
387 $username = trim(core_text
::strtolower($params['username']));
388 $password = $params['password'];
390 if (is_restored_user($username)) {
391 throw new moodle_exception('restoredaccountresetpassword', 'webservice');
394 $user = authenticate_user_login($username, $password);
397 throw new moodle_exception('invalidlogin');
400 if ($user->confirmed
) {
401 throw new moodle_exception('alreadyconfirmed');
404 // Check if we should redirect the user once the user is confirmed.
405 $confirmationurl = null;
406 if (!empty($params['redirect'])) {
407 // Pass via moodle_url to fix thinks like admin links.
408 $redirect = new moodle_url($params['redirect']);
410 $confirmationurl = new moodle_url('/login/confirm.php', array('redirect' => $redirect->out()));
412 $status = send_confirmation_email($user, $confirmationurl);
416 'warnings' => $warnings,
421 * Describes the resend_confirmation_email return value.
423 * @return external_single_structure
426 public static function resend_confirmation_email_returns() {
428 return new external_single_structure(
430 'status' => new external_value(PARAM_BOOL
, 'True if the confirmation email was sent, false otherwise.'),
431 'warnings' => new external_warnings(),