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