Writing Scripts that Use API calls

To handle IBM Security tasks programmatically, you can write programs that call IBM Security Windows API functions using any of the tools commonly used to write programs for Windows-based operating environments. Some of the most common of these tools include VBScript, PowerShell, and Visual Studio (C#).

To illustrate using these tools, the following sections describe how to create and run a program that uses the IBM Security objects to open a zone and lists all the users in it using VBScript and PowerShell. For more detailed examples of performing common tasks using these scripting languages, see the sample scripts included in the SDK package.

Using VBScript
Using PowerShell
Using Visual Studio C#

Using VBScript

In most cases, you can use VBScript to write scripts that call the IBM Security Windows API.

The following steps illustrate how to create and run a VBScript script that uses the IBM Security Windows API. This sample script opens a zone and lists all the users in it.

Verify that the computer you are using has Access Manager console or the IBM Security Windows API Runtime environment from the IBM Security SDK installed.
Verify that the computer you are using is a member of the Active Directory domain you want to work with.
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 the Access Manager console 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.
Use a text editor to create a file called zone-list.vbs.
Add the following text to zone-list.vbs, replacing the domain_name and the path to the zone with a domain name and zone location appropriate for your environment.

set cims = CreateObject("Centrify.DirectControl.Cims3")
set zone = cims.GetZone("domain_name/zone_path/zone_name")
set users = zone.GetUserUnixProfiles()

for each user in users
if (user.IsNameDefined) then
name = user.Name
else
name = "<Empty>"
end if

if (user.IsUidDefined) then
uid = user.Uid
else
uid = "<Empty>"
end if

wscript.echo name & " | " & uid
next

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

set zone = cims.getzone("test.acme.com/program data/centrify/zones/default")
for each user in users
wscript.echo user.name, user.Uid
next
Click Start > Run, then type cmd to open a command window.
Change directory to the location of the VBScript file and type:

cscript zone-list.vbs

You should see output similar to the following:

C:\>cscript zone-list.vbs
Microsoft (R) Windows Script Host Version 5.6
Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

jane 10000
jim.smit 10002
jimsmith 10003
joe 10004
paul 10006
rachel 10016

Using PowerShell

IBM Security 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 IBM Security 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.

Verify that the computer you are using has Access Manager or the IBM Security Windows API Runtime environment from the IBM Security SDK installed.
Verify that the computer you are using is a member of the Active Directory domain you want to work with.
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.
Use a text editor to open the sample script file util.ps1.
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 = "1234abcepassword";
Use a text editor to create a file called zone-list.ps1.
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");
Click Start > Run, then type cmd to open a command window.
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 IBM Security Windows API, see the Access Control and Privilege Management Scripting Guide.

Using Visual Studio C#

The following steps describe how to call the IBM Security Windows API when using Visual Studio 2010. Alternatively you can use the command line compilers that come in Microsoft .Net Framework SDK or the Visual Studio Express Edition. The example below is created using C#, however using vb.net is very similar.

Note that the .NET assemblies are not installed in the Global Assembly Cache, but they do have version numbers on them. This means that the calling applications are tied to using the same assembly versions they were compiled with. To avoid problems using the assemblies, you should install the assemblies and the applications that use the assemblies in the same directory.

Verify that the computer you are using has Access Manager or the IBM Security Windows API Runtime environment from the IBM Security SDK installed.
Verify that the computer you are using is a member of the Active Directory domain you want to work with.
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.
Start vs2010 and start a new project of type C# console application.
Click Project > Add reference.
Click the .NET tab, then click Browse.
Navigate to the directory where Access Manager or the SDK is installed. For example, browse to the default location C:\Program Files\Centrify\.
Select the following dynamic link libraries to add:

centrifydc.api.dll
interface.dll
nismap.api.dll
PropSheetHost.dll
util.dll
Add a reference to system.directory services. From the Project menu, select Add references. In the .NET tab scroll down to system.directoryservices.dll.
Open the class file that contains the application’s Main function. By default, Visual Studio creates this file as class1.cs.
Add the following code in the Main function, replacing the domain_name and the path to the zone with a domain controller and zone location appropriate for your environment:

Centrify.DirectControl.API.Cims cims = new
Centrify.DirectControl.API.Cims();
Centrify.DirectControl.API.IZone zone =
cims.GetZone("domain_name/zone_path/zone_name");
foreach (Centrify.DirectControl.API.IUserUnixProfile user in zone.GetUserUnixProfiles())
{
string name, uid;
if (zone.IsHierarchical &&
!
((Centrify.DirectControl.API.CDC50.UserUnixProfile)user).IsNameDefined)
{
name = "<Empty>";
}
else

if (zone.IsHierarchical &&
!
((Centrify.DirectControl.API.CDC50.UserUnixProfile)user).IsUidDefined)
{
uid = "<Empty>";
}
else

Console.WriteLine(name + " | " + uid);
}

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

Centrify.DirectControl.API.IZone zone =
cims.GetZone("dc2k.seattle.test/program data/centrify/zones/default");
Press F5 to compile and run the application.