Synopsis

bool plexcel_is_member_of(resource $px, string $name)

Description

The plexcel_is_member_of function determines if the calling user is a member of the named group or if the name refers to the user's own account. The calling user is the last user to successfully authenticate using the supplied Plexcel context (or the HTTP service account if no such authentication has occurred).

The $px parameter is the Plexcel context resource representing the directory binding and context specific options.

The $name parameter specifies the account that should be compared to the calling user's list of groups. Just like the plexcel_get_account function, the $name parameter may be a CN, a traditional SAM account name, a SAM account name with a NetBIOS domain name prefix, a user principal name ³ or a full DN.

Note: It is recommended that a qualified name form be used. Specifying only a CN or a SAM account name without a domain may not uniquely identify the correct account.

Behavior Differences Between SSO and Explicit Logon

Due to how group information is retrieved, BUILTIN groups (e.g. Account Operators) and Domain Local Groups may not be included in the plexcel_is_member_of check depending on how the user is authenticated. If SSO is used, BUILTIN groups will not be included in the plexcel_is_member_of check and only Domain Local Groups in the same domain as the web server serivce account will be in scope. If explicit logon is used, only Domain Local Groups in the same domain as the user will be in scope.

Therefore, for consistent results, do not use BUILTIN groups and avoid Domain Local Groups unless you are certain they will always be in scope (e.g. the HTTP service account and users are all in the same domain).

Group Changes

If groups membership is changed this function may not recognize the change until the client logs off and back on to refresh their list of security groups.

Access Control Lists

The plexcel_is_member_of function is ideal for implementing ACLs in applications. After the objectSid for the named account has been cached, no additional network communication is necessary making these calls very efficient. Plexcel does not currently provide higher level ACL functions but they are easy to implement. Consider the following simple implementation that uses an array of names as an ACL.

function plexcel_access_check($px, $acl) { 
    foreach ($acl as $ace) {
        if (plexcel_is_member_of($px, $ace) == TRUE) {
            return TRUE;
        }
    }
    return FALSE;
}

// example usage
$acl = array('bcarter@example.com',
            'Managers',
            'EXAMPLE\QA Group 1',
            'example.com\CMS Beta Testers',
            'CN=Sales,OU=Europe,DC=example,DC=com');
if (plexcel_access_check($px, $acl)) {
    echo 'Access granted';
} else {
    echo 'Access denied';
}

Returns

The plexcel_is_member_of function returns TRUE if the calling user is determined to be a member of the named group or if the name refers to the user's own account. Otherwise FALSE is returned in which case plexcel_status should be tested to ensure that an error has not occurred – see example below.

Example

The following PHP fragment illustrates how to properly use the plexcel_is_member_of function.

        if (plexcel_is_member_of($px, 'Managers') == FALSE) {
      
    if (plexcel_status($px) != PLEXCEL_SUCCESS)
        die('<pre>' . plexcel_status($px) . '</pre>');
    echo 'You are not authorized to view this content.';
} else {
    echo 'You are in the Manager\'s group.'; 
}