Using PowerShell

Centrify provides a separate Access Module for PowerShell that includes predefined “cmdlets” for performing a broad range of administrative tasks without requiring any knowledge of the underlying API calls. If you prefer, however, you can write PowerShell scripts that call the Centrify Windows API directly. The following steps illustrate how to create and run a sample script that opens a zone and lists all the users in it.

  1. Verify that the computer you are using has Access Manager or the Centrify Windows API Runtime environment from the Centrify SDK installed.
  2. Verify that the computer you are using is a member of the Active Directory domain you want to work with.
  3. Log in as a domain user with permission to read the zone data for the zone you will be listing.

    If you can list the users in the zone using Access Manager with the credentials provided, you have the correct permissions. For information about configuring a user’s rights to read zone data, see the Planning and Deployment Guide.

  4. Use a text editor to open the sample script file util.ps1.
  5. Modify the util.ps1 script to specify a user name and password with administrative access to the Active Directory domain.

    For example, replace the “*****” string with an administrator user name and password:

    $usrname = "administrator";
    $passwd = "password";
  6. Use a text editor to create a file called zone-list.ps1.
  7. Add the following text to zone-list.ps1, replacing the domain_name and the path to the zone with a domain controller and zone location appropriate for your environment.

    $api = "Centrify.DirectControl.API.{0}";
    $cims = New-Object($api -f "Cims");
    $objZone = $cims.GetZone("domain_name/zone_path/zone_name");
    $users = $objZone.GetUserUnixProfiles();

    foreach ($user in $users)
    {
    if ($objZone.IsHierarchical)
    {
    if ($user.IsNameDefined)
    {
    $name = $user.Name;
    }
    else
    {
    $name = "<Empty>";
    }
    if ($user.IsUidDefined)
    {
    $uid = $user.UID;
    }
    else
    {
    $uid = "<Empty>";
    }
    }
    else
    {
    $name = $user.Name;
    $uid = $user.UID;
    }

    write-Host ("{0} | {1}" -f $name, $uid);
    }

    For example if you are using the domain test.acme.com and want to list users in the “global” zone in its default container location:

    var zone = cims.getzone("test.acme.com/program data/centrify/zones/global");
  8. Click Start > Run, then type cmd to open a command window.
  9. Change directory to the location of the script file and type the following to run the script using Windows Script Host:

    cscript zone-list.ps1

    You should see output similar to the output for the VBScript sample script. For information about using the Access Module for PowerShell instead of writing scripts that call the Centrify Windows API, see the Access Control and Privilege Management Scripting Guide.