7c083494a9d29cb2616cc0224b2132a6568665b0
[moodle.git] / auth / classes / external.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
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.
8 //
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.
13 //
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/>.
17 /**
18  * Auth external API
19  *
20  * @package    core_auth
21  * @category   external
22  * @copyright  2016 Juan Leyva <juan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 3.2
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once($CFG->libdir . '/externallib.php');
30 require_once($CFG->libdir . '/authlib.php');
32 /**
33  * Auth external functions
34  *
35  * @package    core_auth
36  * @category   external
37  * @copyright  2016 Juan Leyva <juan@moodle.com>
38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  * @since      Moodle 3.2
40  */
41 class core_auth_external extends external_api {
43     /**
44      * Describes the parameters for confirm_user.
45      *
46      * @return external_function_parameters
47      * @since Moodle 3.2
48      */
49     public static function confirm_user_parameters() {
50         return new external_function_parameters(
51             array(
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'),
54             )
55         );
56     }
58     /**
59      * Confirm a user account.
60      *
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)
64      * @since Moodle 3.2
65      * @throws moodle_exception
66      */
67     public static function confirm_user($username, $secret) {
68         global $PAGE;
70         $warnings = array();
71         $params = self::validate_parameters(
72             self::confirm_user_parameters(),
73             array(
74                 'username' => $username,
75                 'secret' => $secret,
76             )
77         );
79         $context = context_system::instance();
80         $PAGE->set_context($context);
82         if (!$authplugin = signup_get_user_confirmation_authplugin()) {
83             throw new moodle_exception('confirmationnotenabled');
84         }
86         $confirmed = $authplugin->user_confirm($username, $secret);
88         if ($confirmed == AUTH_CONFIRM_ALREADY) {
89             $success = false;
90             $warnings[] = array(
91                 'item' => 'user',
92                 'itemid' => 0,
93                 'warningcode' => 'alreadyconfirmed',
94                 'message' => s(get_string('alreadyconfirmed'))
95             );
96         } else if ($confirmed == AUTH_CONFIRM_OK) {
97             $success = true;
98         } else {
99             throw new moodle_exception('invalidconfirmdata');
100         }
102         $result = array(
103             'success' => $success,
104             'warnings' => $warnings,
105         );
106         return $result;
107     }
109     /**
110      * Describes the confirm_user return value.
111      *
112      * @return external_single_structure
113      * @since Moodle 3.2
114      */
115     public static function confirm_user_returns() {
117         return new external_single_structure(
118             array(
119                 'success' => new external_value(PARAM_BOOL, 'True if the user was confirmed, false if he was already confirmed'),
120                 'warnings'  => new external_warnings(),
121             )
122         );
123     }
125     /**
126      * Describes the parameters for request_password_reset.
127      *
128      * @return external_function_parameters
129      * @since Moodle 3.4
130      */
131     public static function request_password_reset_parameters() {
132         return new external_function_parameters(
133             array(
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, ''),
136             )
137         );
138     }
140     /**
141      * Requests a password reset.
142      *
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)
146      * @since Moodle 3.4
147      * @throws moodle_exception
148      */
149     public static function request_password_reset($username = '', $email = '') {
150         global $CFG, $PAGE;
151         require_once($CFG->dirroot . '/login/lib.php');
153         $warnings = array();
154         $params = self::validate_parameters(
155             self::request_password_reset_parameters(),
156             array(
157                 'username' => $username,
158                 'email' => $email,
159             )
160         );
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');
168         }
170         $errors = core_login_validate_forgot_password_data($params);
171         if (!empty($errors)) {
172             $status = 'dataerror';
173             $notice = '';
175             foreach ($errors as $itemname => $message) {
176                 $warnings[] = array(
177                     'item' => $itemname,
178                     'itemid' => 0,
179                     'warningcode' => 'fielderror',
180                     'message' => s($message)
181                 );
182             }
183         } else {
184             list($status, $notice, $url) = core_login_process_password_reset($params['username'], $params['email']);
185         }
187         return array(
188             'status' => $status,
189             'notice' => $notice,
190             'warnings' => $warnings,
191         );
192     }
194     /**
195      * Describes the request_password_reset return value.
196      *
197      * @return external_single_structure
198      * @since Moodle 3.4
199      */
200     public static function request_password_reset_returns() {
202         return new external_single_structure(
203             array(
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.
212                 '),
213                 'notice' => new external_value(PARAM_RAW, 'Important information for the user about the process.'),
214                 'warnings'  => new external_warnings(),
215             )
216         );
217     }
219     /**
220      * Describes the parameters for the digital minor check.
221      *
222      * @return external_function_parameters
223      * @since Moodle 3.4
224      */
225     public static function is_minor_parameters() {
226         return new external_function_parameters(
227             array(
228                 'age' => new external_value(PARAM_INT, 'Age'),
229                 'country' => new external_value(PARAM_ALPHA, 'Country of residence'),
230             )
231         );
232     }
234     /**
235      * Requests a check if a user is digital minor.
236      *
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)
240      * @since Moodle 3.4
241      * @throws moodle_exception
242      */
243     public static function is_minor($age, $country) {
244         global $CFG, $PAGE;
245         require_once($CFG->dirroot . '/login/lib.php');
247         $params = self::validate_parameters(
248             self::is_minor_parameters(),
249             array(
250                 'age' => $age,
251                 'country' => $country,
252             )
253         );
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'] .')');
258         }
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'));
267         }
269         $status = \core_auth\digital_consent::is_minor($params['age'], $params['country']);
271         return array(
272             'status' => $status
273         );
274     }
276     /**
277      * Describes the is_minor return value.
278      *
279      * @return external_single_structure
280      * @since Moodle 3.4
281      */
282     public static function is_minor_returns() {
283         return new external_single_structure(
284             array(
285                 'status' => new external_value(PARAM_BOOL, 'True if the user is considered to be a digital minor,
286                     false if not')
287             )
288         );
289     }
291     /**
292      * Describes the parameters for is_age_digital_consent_verification_enabled.
293      *
294      * @return external_function_parameters
295      * @since Moodle 3.3
296      */
297     public static function is_age_digital_consent_verification_enabled_parameters() {
298         return new external_function_parameters(array());
299     }
301     /**
302      * Checks if age digital consent verification is enabled.
303      *
304      * @return array status (true if digital consent verification is enabled, false otherwise.)
305      * @since Moodle 3.3
306      * @throws moodle_exception
307      */
308     public static function is_age_digital_consent_verification_enabled() {
309         global $PAGE;
311         $context = context_system::instance();
312         $PAGE->set_context($context);
314         $status = false;
315         // Check if verification is enabled.
316         if (\core_auth\digital_consent::is_age_digital_consent_verification_enabled()) {
317             $status = true;
318         }
320         return array(
321             'status' => $status
322         );
323     }
325     /**
326      * Describes the is_age_digital_consent_verification_enabled return value.
327      *
328      * @return external_single_structure
329      * @since Moodle 3.3
330      */
331     public static function is_age_digital_consent_verification_enabled_returns() {
332         return new external_single_structure(
333             array(
334                 'status' => new external_value(PARAM_BOOL, 'True if digital consent verification is enabled,
335                     false otherwise.')
336             )
337         );
338     }