Development Wiki

Authentication plugins

From phpBB Development Wiki

Revision as of 20:45, 4 May 2008 by Naderman (Talk | contribs)

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:

Function Called from
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 Validates the existing user session. Might be used to prematurely terminate phpBB user sessions in single-signon environments.


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.


Called from the includes/auth.php

Input parameters:

  • $username
  • $password

Return value:

 '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
LOGIN_ERROR_PASSWORD Password problems
NO_PASSWORD_SUPPLIED Password was not supplied
LOGIN_ERROR_USERNAME Username problems
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.
LOGIN_SUCCESS Successful login

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:

Field Meaning
username external username
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). See the login method for detailed description of the mandatory contents of the user_row array.
  • 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).

Input parameters:

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

No return value is expected from the logout method.


Validates the current session.

Input parameters:

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