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 defined('MOODLE_INTERNAL') ||
die;
29 require_once($CFG->libdir
. '/externallib.php');
30 require_once($CFG->libdir
. '/authlib.php');
33 * Auth external functions
37 * @copyright 2016 Juan Leyva <juan@moodle.com>
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41 class core_auth_external
extends external_api
{
44 * Describes the parameters for confirm_user.
46 * @return external_function_parameters
49 public static function confirm_user_parameters() {
50 return new external_function_parameters(
52 'username' => new external_value(core_user
::get_property_type('username'), 'User name'),
53 'secret' => new external_value(core_user
::get_property_type('secret'), 'Confirmation secret'),
59 * Confirm a user account.
61 * @param string $username user name
62 * @param string $secret confirmation secret (random string) used for validating the confirm request
63 * @return array warnings and success status (true if the user was confirmed, false if he was already confirmed)
65 * @throws moodle_exception
67 public static function confirm_user($username, $secret) {
71 $params = self
::validate_parameters(
72 self
::confirm_user_parameters(),
74 'username' => $username,
79 $context = context_system
::instance();
80 $PAGE->set_context($context);
82 if (!$authplugin = signup_get_user_confirmation_authplugin()) {
83 throw new moodle_exception('confirmationnotenabled');
86 $confirmed = $authplugin->user_confirm($username, $secret);
88 if ($confirmed == AUTH_CONFIRM_ALREADY
) {
93 'warningcode' => 'alreadyconfirmed',
94 'message' => s(get_string('alreadyconfirmed'))
96 } else if ($confirmed == AUTH_CONFIRM_OK
) {
99 throw new moodle_exception('invalidconfirmdata');
103 'success' => $success,
104 'warnings' => $warnings,
110 * Describes the confirm_user return value.
112 * @return external_single_structure
115 public static function confirm_user_returns() {
117 return new external_single_structure(
119 'success' => new external_value(PARAM_BOOL
, 'True if the user was confirmed, false if he was already confirmed'),
120 'warnings' => new external_warnings(),
126 * Describes the parameters for request_password_reset.
128 * @return external_function_parameters
131 public static function request_password_reset_parameters() {
132 return new external_function_parameters(
134 'username' => new external_value(core_user
::get_property_type('username'), 'User name', VALUE_DEFAULT
, ''),
135 'email' => new external_value(core_user
::get_property_type('email'), 'User email', VALUE_DEFAULT
, ''),
141 * Requests a password reset.
143 * @param string $username user name
144 * @param string $email user email
145 * @return array warnings and success status (including notices and errors while processing)
147 * @throws moodle_exception
149 public static function request_password_reset($username = '', $email = '') {
151 require_once($CFG->dirroot
. '/login/lib.php');
154 $params = self
::validate_parameters(
155 self
::request_password_reset_parameters(),
157 'username' => $username,
162 $context = context_system
::instance();
163 $PAGE->set_context($context); // Needed by format_string calls.
165 // Check if an alternate forgotten password method is set.
166 if (!empty($CFG->forgottenpasswordurl
)) {
167 throw new moodle_exception('cannotmailconfirm');
170 $errors = core_login_validate_forgot_password_data($params);
171 if (!empty($errors)) {
172 $status = 'dataerror';
175 foreach ($errors as $itemname => $message) {
179 'warningcode' => 'fielderror',
180 'message' => s($message)
184 list($status, $notice, $url) = core_login_process_password_reset($params['username'], $params['email']);
190 'warnings' => $warnings,
195 * Describes the request_password_reset return value.
197 * @return external_single_structure
200 public static function request_password_reset_returns() {
202 return new external_single_structure(
204 'status' => new external_value(PARAM_ALPHANUMEXT
, 'The returned status of the process:
205 dataerror: Error in the sent data (username or email). More information in warnings field.
206 emailpasswordconfirmmaybesent: Email sent or not (depends on user found in database).
207 emailpasswordconfirmnotsent: Failure, user not found.
208 emailpasswordconfirmnoemail: Failure, email not found.
209 emailalreadysent: Email already sent.
210 emailpasswordconfirmsent: User pending confirmation.
211 emailresetconfirmsent: Email sent.
213 'notice' => new external_value(PARAM_RAW
, 'Important information for the user about the process.'),
214 'warnings' => new external_warnings(),
220 * Describes the parameters for the digital minor check.
222 * @return external_function_parameters
225 public static function is_minor_parameters() {
226 return new external_function_parameters(
228 'age' => new external_value(PARAM_INT
, 'Age'),
229 'country' => new external_value(PARAM_ALPHA
, 'Country of residence'),
235 * Requests a check if a user is digital minor.
237 * @param int $age User age
238 * @param string $country Country of residence
239 * @return array status (true if the user is a minor, false otherwise)
241 * @throws moodle_exception
243 public static function is_minor($age, $country) {
245 require_once($CFG->dirroot
. '/login/lib.php');
247 $params = self
::validate_parameters(
248 self
::is_minor_parameters(),
251 'country' => $country,
255 if (!array_key_exists($params['country'], get_string_manager()->get_list_of_countries())) {
256 throw new invalid_parameter_exception('Invalid value for country parameter (value: '.
257 $params['country'] .')');
260 $context = context_system
::instance();
261 $PAGE->set_context($context);
263 // Check if verification of age and location (minor check) is enabled.
264 if (!\core_auth\digital_consent
::is_age_digital_consent_verification_enabled()) {
265 throw new moodle_exception('nopermissions', 'error', '',
266 get_string('agelocationverificationdisabled', 'error'));
269 $status = \core_auth\digital_consent
::is_minor($params['age'], $params['country']);
277 * Describes the is_minor return value.
279 * @return external_single_structure
282 public static function is_minor_returns() {
283 return new external_single_structure(
285 'status' => new external_value(PARAM_BOOL
, 'True if the user is considered to be a digital minor,
292 * Describes the parameters for is_age_digital_consent_verification_enabled.
294 * @return external_function_parameters
297 public static function is_age_digital_consent_verification_enabled_parameters() {
298 return new external_function_parameters(array());
302 * Checks if age digital consent verification is enabled.
304 * @return array status (true if digital consent verification is enabled, false otherwise.)
306 * @throws moodle_exception
308 public static function is_age_digital_consent_verification_enabled() {
311 $context = context_system
::instance();
312 $PAGE->set_context($context);
315 // Check if verification is enabled.
316 if (\core_auth\digital_consent
::is_age_digital_consent_verification_enabled()) {
326 * Describes the is_age_digital_consent_verification_enabled return value.
328 * @return external_single_structure
331 public static function is_age_digital_consent_verification_enabled_returns() {
332 return new external_single_structure(
334 'status' => new external_value(PARAM_BOOL
, 'True if digital consent verification is enabled,