Authentication plugins

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.

Invocation origins
The following table explains where the authentication module is invoked:

init_method
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

Return values:


 * false: successful execution
 * status-message(text): error message to display to the user. Usually a predefined message from the $user->lang array.

login_method
Called from the includes/auth.php

Input parameters:


 * $username
 * $password

Return value:

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: 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:

autologin_method
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

Returns:


 * 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.

logout_method
Called from includes/session.php when the user session is terminated (for example, the user presses the logout link).

Input parameters:


 * $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.

validate_session_method
Validates the current session.

Input parameters:


 * $user_row: User+Session row array (a join of the USERS_TABLE and SESSIONS_TABLE)

Returns:


 * True if the external authentication method thinks the session is still valid, False otherwise.

Notes:


 * phpBB session expiration is performed independently from the external session validation.
 * A session expires if either the internal or the external mechanism invalidates it.