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:

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.

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:

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.

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.