plexcel_preamble

Printer Friendly Format

Synopsis

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

array plexcel_preamble(array $options=NULL)

Description

The plexcel_preamble function abstracts all of the normal authentication related work (the “preamble”) into a single easy-to-use function. It allows for a specific domain controller to be selected and abstracts error handling, parameter handling and client logoff.

It is recommended that scripts requiring general purpose authentication use this function or create their own customized version of it.

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: It is strongly recommended that https:// be used when submitting client credentials to the server in plain text.

The optional $options parameter specifies the following possible options.

Option	Description
`base`	The LDAP URL base DN used as a the default base with plexcel_search_objects (e.g. `DefaultNamingContext,` `OU=Asia,DC=example,DC=com`, etc).
`authority`	A domain or specific domain controller (e.g. `example.com`, `ad1.example.com`, etc).
`auth_type`	One of `PLEXCEL_AUTH_SSO`, `PLEXCEL_AUTH_LOGON` or `PLEXCEL_AUTH_SSO_LOGON` as described in the plexcel_authenticate documentation.
`logonurl`	The URL of the logon form if it is different from the current script. See the plexcel_authenticate documentation.
`putenv_krb5ccname`	If set to `TRUE`, this allows non-Plexcel clients that support Kerberos such as ldap_sasl_bind , pgsql_connect and curl_open to initiate authentication with other servers using the client's delegated credential. See the plexcel_new documentation for more information.

This function requires that specific HTTP request parameters are used. The following table describes these parameters in detail.

Request Parameter	Description
`p_action`	This parameter controls the action of the plexcel_preamble function. There are currently three possible actions – `default`, `logoff`, and `change_authority`. If no `p_action` parameter is sent, the action will be `default`. The `default` action is to authenticate the client with plexcel_authenticate . The `logoff` action logs off the client with plexcel_logoff . The `change_authority` action causes plexcel_preamble to do nothing but return `NULL` for the authority element (see the Returns section below).
`p_authority`	This parameter specifies a target domain in which to find a domain controller or the FQDN of a specific domain controller to which the Plexcel context resource should be bound. The script must ensure that this parameter is resent with each request (e.g. with a hidden form element). If it is not, and a different domain controller is selected, querying objects in the directory may not yield consistent results if attributes are not been replicated or are in the process of being replicated. If no p_authority parameter is sent, an authority will be located using plexcel_find_authorities_by_domain and returned in the authority element (see the Returns section below).
`p_username`	If this parameter is sent, plexcel_preamble will attempt an explicit logon ( plexcel_preamble calls plexcel_authenticate calls plexcel_logon ). If no `p_username` parameter is sent, plexcel_preamble will attempt SSO authentication ( plexcel_preamble calls plexcel_authenticate calls plexcel_sso ).
`p_password`	This parameter specifies the password to be used when an explicit logon is performed.

Returns

The plexcel_preamble function returns an array containing several elements. These elements, which may be accessed by index and by name, are described further in the following table.

By Index	By Name	Description
`0`	`authority`	The domain controller to which the Plexcel context resource ( `px`) is bound. If the `p_action` request parameter was `change_authority`, this element will be `NULL`. This allows the script to allow the user to specify an explicit authority (see the `plexcel/examples/preamble.php` example).
`1`	`bindstr`	The binding string used to construct the Plexcel context resource ( `px`).
`2`	`px`	The Plexcel context resource. The `authority` element is the domain controller to which the context is bound. The `bindstr` element is the binding string used to construct the context.
`3`	`err`	The error string if an error occurred. If no error has occurred, this value is `NULL`.
`4`	`action`	The action performed (see description of `p_action`) unless the action was `logoff` in which case the action is changed to `default`.
`5`	`is_authenticated`	Set to `TRUE` if the client was successfully authenticated. Otherwise, this element is set to `FALSE`.

Tip: Use PHP's list construct to dereference this array directly into variables for use within scripts.

$preamble = plexcel_preamble();
list($authority, $bindstr, $px, $err, $action, $is_authenticated) = $preamble;

Using PHP's list construct to dereference the $preamble array into variables

Example

The following is a highly simplified version of the plexcel/examples/preamble.php script. Notice that this example is significantly simpler than the plexcel_authenticate example and yet it provides the same features.

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


        $preamble = plexcel_preamble();
      
list($authority, $bindstr, $px, $err, $action, $is_authenticated) = $preamble;

echo "<form name='f' method='POST'>";
echo "<input type='hidden' name='p_action' value='$action'/>";
echo "<input type='hidden' name='p_authority' value='$authority'/>";

$username = plexcel_get_param('p_username');
if ($err)
    echo $err;

if ($is_authenticated == FALSE) {
    echo "<p/>Username: <input type='text' name='p_username' value='" .
            htmlspecialchars($username) . "'/> must be UPN<br/>";
    echo "Password: <input type='password' name='p_password'/>";
} else {
    echo "<input type='hidden' name='p_username' value='" .
            htmlspecialchars($username) . "'/>";
    echo "<a href=\"javascript:document.f.p_action.value='logoff';document.f.submit();\">Logoff</a>";
    echo '<p/>You are successfully logged on.';
}
echo "<p/><input type='submit'/>";
echo "</form>";
?>

A complete plexcel_preamble example with logon form