phpBB

Development Wiki

Difference between revisions of "Authentication plugins"

From phpBB Development Wiki

(sso -> foo)
(Some language changes, making a few things a tiny bit more clear)
Line 1: Line 1:
The release 3 of the phpBB bulleting board system supports external authentication plug-ins that can be used to replace the traditional database-based user authentication (still available as the '''db '''authentication method).
+
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.
  
<big>'''This documentation has been reverse-engineered from the PHP sources, please feel free to correct it'''</big>
+
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.
  
The plug-ins are implemented as dynamically loadable PHP modules in the '''includes/auth''' directory. Each module is identified by its ''method'', which is part of the module name and the suffix of the 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.
  
To add a new authentication method (let’s call it '''foo'''), you have to create the source file '''auth_''method''.php''' ('''auth_foo '''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 the 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 [[ACP_Client_communication|Client communication]]/Authentication settings.
  
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 Administrator Control Panel (''Client communications/Authentication'' settings).
+
The following table explains where the authentication module is invoked:
 
+
The authentication functions are called from the following modules:
+
 
{| class="prettytable" cellspacing='4' style='border: 1px solid;'
 
{| class="prettytable" cellspacing='4' style='border: 1px solid;'
 
! Function
 
! Function
Line 15: Line 13:
 
|-
 
|-
 
| init_''method''
 
| init_''method''
| Administrator Control Panel calls this method once the new authentication method is selected. The '''init''' method could return an error prompting the administrator to change various parameter settings.
+
| [[Administration Control Panel|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''
 
| autologin_''method''
| Called from the '''includes/session.php''' module at the time a new user session is created. This function is called prior to the phpBB autologin processing and can thus change the user-id stored in the persistent phpBB cookie (assuming phpBB autologin has been enabled by the administrator).
+
| 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''
 
| login_''method''
| Called from the '''includes/auth.php '''module to check the username and password provided by the user in the login form.
+
| Called from '''includes/auth.php''' to check the username and password provided by the user in the login form.
 
|-
 
|-
 
| logout_''method''
 
| logout_''method''
| Called from the '''includes/session.php '''module during the session termination phase (for example, when the user clicks the ''logout ''link).
+
| Called from '''includes/session.php''' during the session termination phase (for example, when the user clicks the ''logout ''link).
 
|-
 
|-
 
| validate_session_''method''
 
| validate_session_''method''

Revision as of 20:45, 4 May 2008

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.

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

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

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.