plexcel_authenticate

Printer Friendly Format

Synopsis

session_start();
require_once('plexcel.php');

bool plexcel_authenticate(resource $px,
        string $ssn_id,
        array $options=NULL)

Description

The plexcel_authenticate function authenticates a web client using Kerberos Single Sign-On (SSO) but it will also explicitly logon the client if adequate credentials are sent. If the client does not support SSO, the script can also fall-back to an explicit logon.

Note: Because this function may call plexcel_sso and because plexcel_sso needs to be called twice for each authentication, this function should be invoked before any code that is not absolutely necessary.

Note: If the same domain controller is not used, querying objects in the directory may not yield consistent results if attributes are not or have not yet been replicated. Use plexcel_preamble instead or copy it's use of plexcel_find_authorities_by_domain to locate and reuse the same domain controller.

Explicit Logon by Form

If a p_username HTTP request parameter is sent, the plexcel_logon function will be used to explicitly logon the client with the supplied $ssn_id and the p_username and p_password request parameters as described in plexcel_logon documentation.

Note: It is strongly recommended that https:// be used when submitting client credentials to the server in plain text.

SSO Authentcation

If a p_username HTTP request parameter is not sent, SSO is attempted. If SSO authentication fails, plexcel_authenticate will return FALSE and set plexcel_status to PLEXCEL_NO_CREDS. This indicates that the script should fall-back to a logon form through which the p_username and p_password request parameters canl be submitted.

The $px parameter is the Plexcel context resource being authenticated.

The $ssn_id parameter is the session id used with the plexcel_logon function. The string returned by PHP's builtin session_id function is ideal for this purpose.

The $options parameter is an array of options. The following table lists the permitted options.

Option	Description
`auth_type`	This option can limit the permitted types of authentication to SSO only or logon only. The default behavior is to allow both types – see table below.
`logonurl`	This option may be set to a URL or relative URL specifying the location of the application's logon form. This is only used by the JavaScript redirect invoked by clients that do not support SSO authentication.

The following table lists the possible values for the auth_type option.

Value for `auth_type` option	Description
`PLEXCEL_AUTH_SSO`	If set, only SSO authentication will be performed. The plexcel_logon function will not be called.
`PLEXCEL_AUTH_LOGON`	If set, only explicit logon with `p_username` and `p_password` parameters will be performed. The plexcel_sso function will not be called.
`PLEXCEL_AUTH_SSO_LOGON`	If set, both SSO and explicit logon will be performed. This is the default value.

Returns

The plexcel_authenticate function returns TRUE if the client was successfully authenticated. Otherwise, FALSE is returned in which case plexcel_status should be consulted.

Example

The following PHP script illustrates how to properly authenticate a web client using the plexcel_authenticate function. This example has been carefully crafted to exhibit the following properties.

Every request is authenticated. The plexcel_authenticate function handles credential caching. If SSO authentication is successful, no logon form is presented. Even if SSO is successful, the logoff link allows the user to get to the logon form and enter alternative credentials. The PLEXCEL_NO_CREDS error indicates that the script should present the user with the logon form. After the client has successfully logged in with the form, resubmitting the page does not require logging on. The session id and hidden p_username parameter are sufficient to utilize any cached credential. If the client is logging off, they should still be authenticated so as to prevent any possibility of unauthenticated clients from maliciously logging off other users. Logging off is a privileged operation. Not calling plexcel_logoff will not affect the performance of the application however, it is a security risk to abandon credentials on the server. Always call plexcel_logoff if the client will no longer need their cached credential.

<?php 
session_start();
require_once('../plexcel.php');

$username = plexcel_get_param('p_username');
$logoff = plexcel_get_param('logoff');
$is_authenticated = FALSE;
$err = NULL; 

$px = plexcel_new(NULL, NULL);

        $is_authenticated = plexcel_authenticate($px, session_id());
      
if ($is_authenticated == FALSE) {
    if (plexcel_status($px) == PLEXCEL_NO_CREDS) {
        // fall through to logon form
    } else if (plexcel_status($px) == PLEXCEL_PRINCIPAL_UNKNOWN) {
        $err = 'Bad username';
    } else if (plexcel_status($px) == PLEXCEL_LOGON_FAILED) {
        $err = 'Logon failed (e.g. bad password)';
    } else {
        $err = 'Error: <pre>' . plexcel_status($px) . '</pre>';
    }
}    

if ($logoff == '1') {
    if ($username)
        plexcel_logoff($px, session_id(), $username);
    $is_authenticated = FALSE;
    $err = 'You are logged off.';
}    

if ($err)
    echo $err;

echo "<form name='f' method='POST'>";
if ($is_authenticated == FALSE) {
    echo "<p/>Username: <input name='p_username' type='text'/> (must be UPN)<br/>";
    echo "Password: <input name='p_password' type='password'/>";
} else {
    echo "<input name='p_username' type='hidden' value='" .
         htmlspecialchars($username) . "'/>";
    echo "<input name='logoff' type='hidden' value='0'/>";
    echo "<p/>You have been successfully authenticated.";
    echo "<p/><a href='javascript:document.f.logoff.value=1;document.f.submit();'>logoff</a>";
}    
echo "<p/><input type='submit'/>";
echo "</form>\n";
?>

A complete plexcel_authenticate example with error handling and logon form