From phpBB Development Wiki
phpBB3 supports external authentication plugins that can be used to replace the traditional database-based user authentication which is still available as the db authentication method.
The plugins are implemented as dynamically loadable PHP modules in the includes/auth/ directory. Each module is identified by its method identifier. The identifier is used in the module name and it is a suffix of every function declared in the module.
To add a new authentication method (let’s call it foo), you have to create the source file auth_method.php (auth_foo.php in our example) in the includes/auth/ directory. This source file should provide a number of functions. The only mandatory function in the authentication module is the login_method() function (login_foo() in our example). All other methods are optional.
As soon as the new authentication module has been created in the includes/auth/ directory, it can be selected as the desired authentication method in the Administration Control Panel under Client communication/Authentication settings.
The following table explains where the authentication module is invoked:
|init_method||ACP calls this method after the authentication method is selected. The init method can return an error prompting the administrator to change various parameter settings.|
|autologin_method||Called from includes/session.php at the time a new user session is created. This function is called prior to the phpBB autologin processing and can log a user in without further interaction. (Note: You can change the user id stored in the persistent phpBB cookie here, assuming phpBB autologin has been enabled).|
|login_method||Called from includes/auth.php to check the username and password provided by the user in the login form.|
|logout_method||Called from includes/session.php during the session termination phase (for example, when the user clicks the logout link).|
|validate_session_method||Called from includes/session.php at the time a new user session is created. Determines if the existing session is still valid.|
The function is called from the Administrator Control Panel once the authentication method is selected and the various parameters are entered in the setup form.
Input parameters: none
Global variables: setup parameters specified in the ACP form are stored in the $config array
- false: successful execution
- status-message(text): error message to display to the user. Usually a predefined message from the $user->lang array.
Called from the includes/auth.php
array( 'status' => status-code(int), 'error_msg'=> status-message-id(text), 'user_row'=> user-row(array), );
The login_method performs the actual external authentication and returns the authentication status in an array with three values:
- status: integer status code, defined in constants.php
- error_msg: text string identifying the status message in the ucp.php language file. The error message returned on a successful external authentication should be an empty string.
- user_row: user row array (see below).
The various status codes and commonly associated error messages are displayed in the following table:
|Status code||Status message ID||Explanation|
|NO_PASSWORD_SUPPLIED||Password was not supplied|
|LOGIN_ERROR_USERNAME||Incorrect username was specified|
|LOGIN_ERROR_EXTERNAL_AUTH||External authentication has failed|
|LOGIN_ERROR_ACTIVE||User is not active|
|ACTIVE_ERROR||The specified username is inactive|
|LOGIN_SUCCESS_CREATE_PROFILE||User authenticated, but not yet in phpBB. Create the user profile.|
At the very minimum, the user_row array should the user_id. The anonymous user is identified with the following user_row array:
'user_row' => array('user_id' => ANONYMOUS)
This array should also be returned with all non-successful status codes.
The usual flow of the login method is as follows:
- perform various sanity checks on username (not empty), password (not empty) and availability of external authentication method.
- Authenticate the user with the external method
- Search for the user in the USERS_TABLE.
- If the user is found, check whether the user is disabled in phpBB ($user_row['user_type'] equals to USER_INACTIVE or USER_IGNORE). Otherwise return the LOGIN_SUCCESS code and the user_row returned by the SQL query.
- If the user is not found in USERS_TABLE, return the LOGIN_SUCCESS_CREATE_PROFILE code and a user_row for the new user created from the external data.
The user_row created from the external data should contain the following fields:
|user_password||phpbb_hash of the external password|
|user_email||E-mail of the new user if available from the external method, blank otherwise.|
|Group_id||Group ID, usually the default group ID, but could also be deduced from external data|
|user_type||User type, defined in constants.php, usually USER_NORMAL.|
Called from the includes/session.php when a new session is about to be created. Allows the external authentication method to log in an already authenticated user automatically (replaces the phpBB autologin mechanism).
Input parameters: none
- user_row array on successful autologin;
- array() on failure.
The typical flow of the autologin method is as follows:
- Try to get external username from the external log-in information, return array() on failure.
- Try to find the phpBB user matching the external username. Return the $user_row array or empty array if the phpBB user is disabled (USER_INACTIVE or USER_IGNORE, see login method).
- Create a new user with the user_add function (which takes user_row of the new user as the argument).
- Note that for autologin the user_row array should return all fields from the user table for that user, unlike the login method which only needs the mandated ones documented above.
- Return the $user_row array for the newly created user.
Called from includes/session.php when the user session is terminated (for example, the user presses the logout link).
- $user_row: User Session row array (a join of the USERS_TABLE and SESSIONS_TABLE)
- $new_session: Boolean stating whether a new anonymous session will be created after the current session is terminated
Return value: none
No return value is expected from the logout method.
Validates the current session.
- $user_row: User+Session row array (a join of the USERS_TABLE and SESSIONS_TABLE)
- True if the external authentication method thinks the session is still valid, False otherwise.
- phpBB session expiration is performed independently from the external session validation.
- A session expires if either the internal or the external mechanism invalidates it.