Development Wiki

Authentication plugins

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.


Invocation origins

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

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
user_id user identifier
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).
  • 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).

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.


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.