[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  *
   4  * This file is part of the phpBB Forum Software package.
   5  *
   6  * @copyright (c) phpBB Limited <https://www.phpbb.com>
   7  * @license GNU General Public License, version 2 (GPL-2.0)
   8  *
   9  * For full copyright and license information, please see
  10  * the docs/CREDITS.txt file.
  11  *
  12  */
  13  
  14  namespace phpbb\auth\provider;
  15  
  16  /**
  17  * The interface authentication provider classes have to implement.
  18  */
  19  interface provider_interface
  20  {
  21      /**
  22       * Checks whether the user is currently identified to the authentication
  23       * provider.
  24       * Called in acp_board while setting authentication plugins.
  25       * Changing to an authentication provider will not be permitted in acp_board
  26       * if there is an error.
  27       *
  28       * @return     boolean|string     False if the user is identified, otherwise an
  29       *                            error message, or null if not implemented.
  30       */
  31  	public function init();
  32  
  33      /**
  34       * Performs login.
  35       *
  36       * @param    string    $username     The name of the user being authenticated.
  37       * @param    string    $password    The password of the user.
  38       * @return    array    An associative array of the format:
  39       *                        array(
  40       *                            'status' => status constant
  41       *                            'error_msg' => string
  42       *                            'user_row' => array
  43       *                        )
  44       *                    A fourth key of the array may be present:
  45       *                    'redirect_data'    This key is only used when 'status' is
  46       *                    equal to LOGIN_SUCCESS_LINK_PROFILE and its value is an
  47       *                    associative array that is turned into GET variables on
  48       *                    the redirect url.
  49       */
  50  	public function login($username, $password);
  51  
  52      /**
  53       * Autologin function
  54       *
  55       * @return     array|null    containing the user row, empty if no auto login
  56       *                         should take place, or null if not impletmented.
  57       */
  58  	public function autologin();
  59  
  60      /**
  61       * This function is used to output any required fields in the authentication
  62       * admin panel. It also defines any required configuration table fields.
  63       *
  64       * @return    array|null    Returns null if not implemented or an array of the
  65       *                        configuration fields of the provider.
  66       */
  67  	public function acp();
  68  
  69      /**
  70       * This function updates the template with variables related to the acp
  71       * options with whatever configuraton values are passed to it as an array.
  72       * It then returns the name of the acp file related to this authentication
  73       * provider.
  74       * @param    array    $new_config Contains the new configuration values that
  75       *                                have been set in acp_board.
  76       * @return    array|null        Returns null if not implemented or an array with
  77       *                            the template file name and an array of the vars
  78       *                            that the template needs that must conform to the
  79       *                            following example:
  80       *                            array(
  81       *                                'TEMPLATE_FILE'    => string,
  82       *                                'TEMPLATE_VARS'    => array(...),
  83       *                            )
  84       *                            An optional third element may be added to this
  85       *                            array: 'BLOCK_VAR_NAME'. If this is present,
  86       *                            then its value should be a string that is used
  87       *                            to designate the name of the loop used in the
  88       *                            ACP template file. When this is present, an
  89       *                            additional key named 'BLOCK_VARS' is required.
  90       *                            This must be an array containing at least one
  91       *                            array of variables that will be assigned during
  92       *                            the loop in the template. An example of this is
  93       *                            presented below:
  94       *                            array(
  95       *                                'BLOCK_VAR_NAME'    => string,
  96       *                                'BLOCK_VARS'        => array(
  97       *                                    'KEY IS UNIMPORTANT' => array(...),
  98       *                                ),
  99       *                                'TEMPLATE_FILE'    => string,
 100       *                                'TEMPLATE_VARS'    => array(...),
 101       *                            )
 102       */
 103  	public function get_acp_template($new_config);
 104  
 105      /**
 106      * Returns an array of data necessary to build custom elements on the login
 107      * form.
 108      *
 109      * @return    array|null    If this function is not implemented on an auth
 110      *                        provider then it returns null. If it is implemented
 111      *                        it will return an array of up to four elements of
 112      *                        which only 'TEMPLATE_FILE'. If 'BLOCK_VAR_NAME' is
 113      *                        present then 'BLOCK_VARS' must also be present in
 114      *                        the array. The fourth element 'VARS' is also
 115      *                        optional. The array, with all four elements present
 116      *                        looks like the following:
 117      *                        array(
 118      *                            'TEMPLATE_FILE'        => string,
 119      *                            'BLOCK_VAR_NAME'    => string,
 120      *                            'BLOCK_VARS'        => array(...),
 121      *                            'VARS'                => array(...),
 122      *                        )
 123      */
 124  	public function get_login_data();
 125  
 126      /**
 127       * Performs additional actions during logout.
 128       *
 129       * @param     array    $data            An array corresponding to
 130       *                                    \phpbb\session::data
 131       * @param     boolean    $new_session    True for a new session, false for no new
 132       *                                    session.
 133       */
 134  	public function logout($data, $new_session);
 135  
 136      /**
 137       * The session validation function checks whether the user is still logged
 138       * into phpBB.
 139       *
 140       * @param     array     $user
 141       * @return     boolean    true if the given user is authenticated, false if the
 142       *                     session should be closed, or null if not implemented.
 143       */
 144  	public function validate_session($user);
 145  
 146      /**
 147      * Checks to see if $login_link_data contains all information except for the
 148      * user_id of an account needed to successfully link an external account to
 149      * a forum account.
 150      *
 151      * @param    array    $login_link_data    Any data needed to link a phpBB account to
 152      *                                an external account.
 153      * @return    string|null    Returns a string with a language constant if there
 154      *                        is data missing or null if there is no error.
 155      */
 156  	public function login_link_has_necessary_data($login_link_data);
 157  
 158      /**
 159      * Links an external account to a phpBB account.
 160      *
 161      * @param    array    $link_data    Any data needed to link a phpBB account to
 162      *                                an external account.
 163      */
 164  	public function link_account(array $link_data);
 165  
 166      /**
 167      * Returns an array of data necessary to build the ucp_auth_link page
 168      *
 169      * @param int $user_id User ID for whom the data should be retrieved.
 170      *                        defaults to 0, which is not a valid ID. The method
 171      *                        should fall back to the current user's ID in this
 172      *                        case.
 173      * @return    array|null    If this function is not implemented on an auth
 174      *                        provider then it returns null. If it is implemented
 175      *                        it will return an array of up to four elements of
 176      *                        which only 'TEMPLATE_FILE'. If 'BLOCK_VAR_NAME' is
 177      *                        present then 'BLOCK_VARS' must also be present in
 178      *                        the array. The fourth element 'VARS' is also
 179      *                        optional. The array, with all four elements present
 180      *                        looks like the following:
 181      *                        array(
 182      *                            'TEMPLATE_FILE'        => string,
 183      *                            'BLOCK_VAR_NAME'    => string,
 184      *                            'BLOCK_VARS'        => array(...),
 185      *                            'VARS'                => array(...),
 186      *                        )
 187      */
 188  	public function get_auth_link_data($user_id = 0);
 189  
 190      /**
 191      * Unlinks an external account from a phpBB account.
 192      *
 193      * @param    array    $link_data    Any data needed to unlink a phpBB account
 194      *                                from a phpbb account.
 195      */
 196  	public function unlink_account(array $link_data);
 197  }