Scripting Access Control and Privilege Management with PowerShell

Subject matter (not formatting) last updated December 2021 (release 2021.1).

Introduction

Overview

This topic discusses access control and privilege management using PowerShell-based command-line programs. This information is intended to help you develop scripts for creating and populating zones and performing other administrative tasks on Windows computers. With scripts, you can automate the administrative tasks you might otherwise perform using the Access Manager console.

Specifically, the topic describes the IBM Security authentication and privilege PowerShell-based command set. These PowerShell cmdlets run on Windows computers and can be used to automate access control and privilege management tasks, such as the creation of IBM Security zones, rights, and roles. You can also use the cmdlets to perform other administrative tasks. For example, you can write scripts to add UNIX profiles for Active Directory users and groups to IBM Security zones, assign UNIX and Windows users and groups to roles, and manage network information through NIS maps.

Intended audience

This topic provides information for Active Directory administrators who want to use PowerShell scripts to install or maintain IBM Security software. This document supplements the help provided within the PowerShell environment using the get-help function. Whereas the get-help function describes each cmdlet in detail, this document introduces the access module for Windows PowerShell objects and how you can use PowerShell cmdlets and scripts to perform access control and privilege management tasks.

This topic assumes general knowledge of Microsoft Active Directory, PowerShell scripts and syntax, and the Windows PowerShell modules used to write scripts for Active Directory. You should also understand the structure of Active Directory, including the Active Directory schema your organization is using.

In addition to scripting skills, you should be familiar with IBM Security architecture, terms, and concepts, and understand how to perform administrative tasks for authentication and privilege elevation and for the UNIX platforms you support.

Subtopics

This topic is divided into these subtopics:

• Developing Scripts for Administrative Tasks: An introduction to access control and privilege management using Windows PowerShell.

• Installing the PowerShell Access Module: How to download and install the module as a separate package.

• Managing IBM Security Objects using Windows PowerShell Scripts: How to use cmdlets to connect to Active Directory and perform access control and privilege management tasks.

• Objects and Properties: Lists the objects defined by the authentication and privilege-elevation PowerShell module and the properties of each object.

• Adding Users in a One-way Trust Environment: How to add a user in a one-way trust environment using the authentication and privilege-elevation PowerShell module.

• Using Predefined Scripts to Generate Reports: Describes predefined report scripts that are included with the authentication and privilege-elevation PowerShell module and how to configure report output files to generate HTML- and PDF-formatted report files.

Compatibility and Limitations

The information in this topic is intended for use with Verify Privilege Server Suite, version 5.1.x or later and Verify Privilege Server Suite 2017.2 or later. Although intended to be accurate and up to date, interfaces are subject to change without notice and can become incompatible or obsolete when a newer version of the software is released.

In general, APIs attempt to be backward-compatible but are not guaranteed to work with older versions of the software. Because the authentication and privilege elevation cmdlets are subject to change, enhancement, or replacement, the information in this topic can also become incomplete, obsolete, or unsupported in future versions. If you are unsure whether this topic is appropriate for your software version, consult the IBM Security Web site or IBM Security Support to find out if another, more appropriate, topic is available.

Developing Scripts for Administrative Tasks

This section introduces access control and privilege management using Windows PowerShell. It consists of the following:

• APIs in the form of PowerShell command-line programs, called cmdlets, that are packaged in Dynamic Link Libraries (DLLs).
• A PowerShell help file that includes complete cmdlet reference information and this scripting guide.
• Sample scripts to illustrate administrative tasks.
• Predefined scripts to generate reports.
• Individual help files for each predefined report script.

On Windows computers, you can use the authentication and privilege elevation module for Windows PowerShell to develop your own custom scripts that access, create, or modify IBM Security-specific data in Active Directory.

Getting Started with cmdlets for PowerShell

The access module for PowerShell consists of cmdlets that you can use to manage IBM Security-specific information in Active Directory. A cmdlet is a lightweight command‑line program that runs in the Windows PowerShell environment. In most cases, cmdlets perform a basic operation and return a Microsoft .NET Framework object to the next command in the pipeline.

The cmdlets in the IBM Security module enable you to access, create, modify, and remove information about IBM Security zones, including details for each zone about the defined user, group, and computer profiles; all aspects of the rights, roles, and role assignments; and the available NIS maps and NIS map entries. You can combine cmdlets and use them in scripts to automate administrative tasks, such as user or group profile provisioning or creating rights, roles, and role assignments.

In most cases, you can use cmdlets to manipulate IBM Security objects in any type of zone. However, because the implementation of authorization differs greatly in hierarchical zones from authorization in classic zones, the access module for Window PowerShell cmdlets that enable you to create and work with rights, roles, or role assignments are only applicable in hierarchical zones. You should not use the cmdlets for rights, roles, and role assignments in classic zones.

Managing UNIX information from a Windows Computer

You can use the cmdlets to work with information for any IBM Security-managed computer and to manage UNIX profiles and access rights. However, you can only run the cmdlets on Windows-based computers that have the Windows PowerShell command-line shell available. If you want to develop scripts that run on UNIX computers, you can use the ADEdit program (adedit). The ADEdit application provides functionality similar to the cmdlets. For detailed information about using ADEdit, see the ADEdit Command Reference and Scripting topic.

Writing Programs in Other Languages

If you want to develop programs or scripts that run on Windows but outside of the Windows PowerShell environment, you can use any language that supports the Component Object Model (COM) interface. The IBM Security COM-based interface is available as part of the IBM Security Windows Software Development Kit (SDK). The SDK package is a completely separate API that provides reusable objects that you can call in programs written in .NET or COM-enabled languages. You can, therefore, create or modify your own applications to use these objects in VBScript and JScript or in .NET‑compliant (such as C#) languages. For more information about using the COM-based API, see the Windows API Programmer’s Guide.

Accessing information stored in Active Directory

The IBM Security access module for PowerShell cmdlets connect to Active Directory to access all of the IBM Security-specific information stored there. You can, therefore, write PowerShell scripts to automate procedures that you would otherwise have to perform using access manager.

The cmdlets rely on the underlying interfaces provided by Microsoft Active Directory Service Interfaces (ADSI) and the IBM Security Windows API. The ADSI layer provides low‑level functions that permit applications to read and write data in Active Directory. The cmdlets provide a task and object-based level of abstraction for retrieving and manipulating IBM Security-specific information so that you do not need to know the details of how the data is stored or how to use any of the underlying ADSI functions directly.

The following figure illustrates how the IBM Security access module for PowerShell provides an abstraction layer between the data stored in Active Directory and your scripting environment.

Figure: PowerShell Abstraction Layer

The Active Directory schema defines how all of the objects and attributes in the database are stored. When you add IBM Security objects to the Active Directory database, how that data is stored depends on the Active Directory schema you have installed. The IBM Security access module for PowerShell, however, provides a logical view of the data, eliminating the need to know the details of how data is stored in different schemas when performing common administrative tasks. The cmdlets also provide a simple and IBM Security-focused method for accessing subject UNIX objects.

Using the cmdlets, you can write scripts that automatically create and manage zones or update user, group, or computer properties. In most cases, the cmdlets enable you to perform exactly the same tasks from the command line that you would otherwise perform interactively using access manager.

Installing the PowerShell Access Module

This section explains how to download and install the module as a separate package. You can install the authentication and privilege elevation module for PowerShell from the Verify Privilege Server Suite setup program or as a separate package. This section includes the access control and privilege management cmdlets for Windows PowerShell, sample scripts, and documentation for performing common administrative tasks using PowerShell scripts. This section describes how to install the software if you download it as a separate package or run the package-specific setup program on a Windows computer.

Selecting and Downloading a Standalone Package

The cmdlets that run in Windows PowerShell are defined in DLLs that can be installed on any computer where you install other Windows-based components, such as the Access Manager console. You can also download these libraries separately, along with sample scripts and documentation, onto computers where access manager is not installed.

You can download the access module for PowerShell as a separate package from the IBM Security Download Center under Software Development Kits. However, you must obtain an unlocking code or license key from your IBM Security sales representative to access the module.

Running the Setup program

After you have downloaded the compressed file to your computer, you can extract the files and run the setup program to install the access module for PowerShell files.

To use the authentication and privilege elevation module for Windows PowerShell on a Windows Server server-core computer, you must have Windows PowerShell, version 2.0 or later, installed first. Also, install the authentication and privilege elevation module for Windows PowerShell on a Windows Server Core environment in silent mode, due to a user interface limitation. Please check the process exit code to see whether the installation succeeded or failed.

Server core is a minimal installation option that is available when you are deploying Windows Server. Server core includes most but not all server roles. Server Core has a smaller attack surface due to a smaller code base.

To run the standalone setup program:

1. Download the file.

2. Right-click downloaded file and select Extract All to extract the compressed files to a folder.

3. Double-click the standalone executable to start the setup program. For example, for the 64-bit version of the file, double click the CentrifyDC_PowerShell‑5.2.0-win64.exe file.

   Alternatively, you can install from the Microsoft Installer (.msi) file. For example, you might run the following command: msiexec.exe /i "CentrifyDC_PowerShell-5.2.0-win64.msi" /norestart.

   The Welcome page appears.

4. Click the Next button. The License Agreement page appears.

5. Click to select the I accept the terms in the License Agreement check box.

6. Click the Next button. The Location page appears.

7. Accept the default location or click Change to choose a different one. If you accept the default location, the authentication and privilege elevation cmdlets are in a separate authentication and privilege elevation for Windows PowerShell console. If you want the authentication and privilege elevation cmdlets to be available in the default Windows PowerShell console with other PowerShell modules, select the following location:

   C:\Windows\System32\WindowsPowerShell\v1.0\Modules\Centrify.DirectControl.PowerShell

8. Click the Next button.

9. Click the Install button.

10. Click the Finish button to complete the installation.

Importing cmdlets into the Windows PowerShell Console

If you install the authentication and privilege elevation module for Windows PowerShell in the default location, it is a self-contained Windows PowerShell console. If you install the files in the location for system modules so that cmdlets from other modules are available in the same console, you should import the authentication and privilege elevation module into your default Windows PowerShell console.

To import the authentication and privilege elevation module:

1. On the Start menu, select Windows PowerShell to display a menu extension with a list of tasks.

2. On the tasks menu, select Import System Modules to import the authentication and privilege elevation module and open the Windows PowerShell console.

3. Verify the installation and import completed successfully by typing the following command at the PowerShell prompt:

   get-command -Cdm

   You should see a listing of the authentication and privilege elevation cmdlets, similar to the following partial list:

CommandType   Name                        Definition
-----------   ----                      ----------
 Cmdlet       Add-CdmApplicationRight   Add-CdmApplicationRight -Right ...
 Cmdlet       Add-CdmCommandRight       Add-CdmCommandRight -Right <Cdm...
 Cmdlet       Add-CdmDesktopRight       Add-CdmDesktopRight -Right <Cdm...
 Cmdlet       Add-CdmNetworkAccessRight Add-CdmNetworkAccessRight -Righ...
 Cmdlet       Add-CdmPamRight           Add-CdmPamRight -Right <CdmPamR...
 Cmdlet       Add-CdmSshRight           Add-CdmSshRight -Right <CdmSshR...
 Cmdlet       Get-CdmApplicationRight   Get-CdmApplicationRight [-Zone ...
 Cmdlet       Get-CdmCommandRight       Get-CdmCommandRight [-Zone <Cdm...
 Cmdlet       Get-CdmComputerRole       Get-CdmComputerRole -Zone <CdmZ...
 Cmdlet       Get-CdmDesktopRight       Get-CdmDesktopRight [-Zone <Cdm...
 Cmdlet       Get-CdmGroupProfile       Get-CdmGroupProfile [-Zone <Cdm...
 ...

See Using the Default Windows PowerShell Console for more information..

Managing

This section provides an overview of how to use cmdlets to access and manage authentication and privilege elevation information stored in Active Directory using Windows PowerShell scripts. It provides a summary of the operations you can perform using cmdlets and how to establish a connection to Active Directory. For more examples of how to perform common administrative tasks using the cmdlets, see the samples included with the software.

Using cmdlets to Manage Access

The IBM Security access module for PowerShell provides cmdlets that perform operations on objects that correspond to the core elements of IBM Security data. Those core elements are:

• Computer role definitions
• Computers
• Groups and group profiles
• NIS network maps and map entries
• Role assignments
• UNIX and Windows rights
• User role definitions
• Users and user profiles
• Zones and zone properties

In most cases, cmdlets can manipulate IBM Security information in any type of zone. However, because authorization differs greatly between hierarchical and classic zones, the cmdlets that enable you to work with rights, roles, or role assignments are only applicable in hierarchical zones. You should not use the cmdlets for rights, roles, and role assignments in classic zones. Other than this limitation, you can use the cmdlets to create, access, modify, and remove information associated with any of the core elements of IBM Security data for access control and privilege management.

Most of the cmdlets perform one of the following basic operations:

• Add-CdmXxx cmdlets add a right to a specified role.
• Get-CdmXxx cmdlets get the properties of a specified object.
• New-CdmXxx cmdlets create new IBM Security objects, such as a new zone or a new role definition.
• Remove-CdmXxx cmdlets delete a specified object or remove a right from a specified role.
• Set-CdmXxx cmdlets set or change the properties of a specified object.

In addition to these basic operations, there are cmdlets for exporting and importing rights and roles from one zone to another and for establishing connections with Active Directory.

For descriptions of the use and parameters for each cmdlet, use the get-help command within the PowerShell console. For example, if you want to see a description and syntax summary for the New-CdmZone cmdlet, type the following command in the PowerShell console:

get-help New-CdmZone

To see detailed information about a cmdlet’s parameters and code examples, you can use the -detailed or -full option. For example, type the following command in the PowerShell console:

get-help New-CdmZone -detailed

Creating and Using a Connection

Because the IBM Security access module for PowerShell cmdlets manipulate objects in Active Directory, you must establish a connection with Active Directory before using cmdlets to perform other tasks. To do that, you must specify a target domain or domain controller and the credentials to use when connecting to that domain or domain controller.

Once the credentials are set, all subsequent calls share that information—you do not have to provide the credential or the domain controller for any subsequent calls.

The following example illustrates how to use the administrator account to connect to the finance.acme domain, then add the user joe.doe to the Engineering zone:

PS C:\> Set-CdmCredential "finance.acme" "administrator"
PS C:\> Get-CdmCredential
Target         Type   User
------         ----   ----
finance.acme   Forest administrator@finance.acme
PS C:\> $zone = Get-CdmZone -Name "Engineering"
PS C:\> New-CdmUserProfile -Zone $zone -User "joe.doe@finance.acme" -Login "jdoe"

In this example, the cmdlets that get the zone and create the user profile use the credential that is cached by the Set-CdmCredential command. The Get-CdmCredential cmdlet shows what credentials are currently cached.

Managing Connections

You can use the following cmdlets to manage connections to Active Directory by adding, modifying, or using cached credentials or specifying domain-controller-to-domain mappings:

• Set-CdmCredential to add or modify a credential in the cache.

• Get-CdmCredential to list the credentials currently cached.

• Set-CdmPreferredServer to specify a domain controller to use for a domain.

• Get-CdmPreferredServer to list all previously defined domain mappings.

Specifying Credentials

You can use the Set-CdmCredential cmdlet to specify a credential that you want to cache as a PSCredential object. Create the PSCredential object using the Get‑Credential cmdlet. The Get-Credential cmdlet prompts users to specify a username and password. You can also pass the username as a parameter to the Get-Credential cmdlet to have the cmdlet prompt the user for the password.

Organizing cmdlet Operations in a Sequence

There is no fixed sequence for calling cmdlets. There is, however, a logical sequence to follow to pass data from one cmdlet to another. For example, to get all of the user UNIX profiles in a zone, you must first identify the zone object before you call the Get-CdmUserProfile cmdlet, To accomplish this, you could organize the calls in the following sequence:

$zone = Get-CdmZone -Name "myZone"
Get-CdmUserProfile -Zone $zone

Similarly, to get all of the UNIX user profiles for a computer, you must first identify the computer object:

$computer = Get-CdmManagedComputer -Name "myComputer"
Get-CdmUserProfile -Computer $computer

In most cases, you can determine from the parameters of a cmdlet whether you need to call another cmdlet first. For example, if you want to add a right to a role, you must have created the role first so it can be specified as a parameter to the Add-CdmXxx cmdlet.

For most Set-CdmXxx or Remove-CdmXxx cmdlets, you must call the corresponding Get‑CdmXxx or Add-CdmXxx cmdlet to obtain the object first. For example, to delete role1 from zone1, you might call the cmdlets as follows:

Get-CdmRole -Zone "cn=zone1,cn=Zones,dc=acme,dc=com" -Name "role1" | Remove‑CdmRole

In this example, the Get-CdmRole cmdlet retrieves “role1” from the specified zone and passes it to the Remove-CdmRole cmdlet via a PowerShell pipe.

Confirming Licenses

All of the authentication and privilege elevation cmdlets check for a valid license before performing the requested action. The license check succeeds only if there is at least one evaluation, workstation, or server license that has not expired.

If the license check fails, the cmdlet displays an error and stops running. Otherwise, the result is cached. The next time a cmdlet tries to access the same forest, it uses the cached result rather than performing the license check again.

The cache is only effective in one PowerShell console. If another PowerShell console runs a cmdlet accessing the same forest, the cmdlet in that console must perform a separate license check.

Working with Sample Scripts

Introduction

There are several sample scripts included with the software to demonstrate a few common administrative tasks. You can copy and modify these samples to use them in your environment or study them as examples for writing your own custom scripts. The sample scripts include detailed comments about the operations performed to accomplish the following tasks.

Table: Sample Scripts for Administrative Tasks

Running a Sample Script

To run a sample script:

1. Open the IBM Security access module for PowerShell.

2. Verify you have permission to execute scripts by running Get-ExecutionPolicy. In most cases, the permission to execute scripts is restricted.

3. If necessary, use Set‑ExecutionPolicy to allow execution. For example:

   Set-ExecutionPolicy Unrestricted

   For more about execution policies and the options available, run the get‑help command.

4. Verify you are in the directory where the scripts are located.

5. Execute the sample script. For example:

   .\RemoveAllOrphans

Modifying the Backup and Restore Scripts for Your Needs

If you want to use the sample backup and restore scripts to backup self-contained IBM Security zones, you must modify the content of the scripts before executing them. To run a modified sample backup script:

1. Open the backup.ps1 file in a text editor.

2. Modify the path to the zone you want to back up and the path to the backup file at the start of the sample script. For example:

   Copy

    $zoneDn = "CN=Headquarters,CN=Zones,OU=Acme Sales,DC=pistolas,DC=org"
    $xmlPath = "C:\Program Files\Centrify\HQ-test.xml"
   

3. Modify the confirmation message at the end of the script to display the path to the backup file. For example:

   Write-Host "Backup to C:\Program Files\Centrify\HQ-test.xml is done."

4. Save your changes with a new file name, for example, HQbackup.ps1, to keep the sample backup.ps1 script unchanged.

5. Open the IBM Security access module for PowerShell.

Using the Default Windows PowerShell Console

Alternatively, you can use the default Windows PowerShell console. If you choose to use that console, run import-module with the path to the access module for PowerShell libraries before performing the above procedure. For example, if you installed the module in the default location, run the following command to import the IBM Security access module for PowerShell:

import-module “C:\Program Files\Centrify\PowerShell\Centrify.DirectControl.PowerShell.dll”

Creating New Zones with the Sample CreateZoneAndDelegate Script

You can use the CreateZoneAndDelegate.ps1 sample script to automate creating new zones and assigning an Active Directory user or group as the zone administrator. By default, the script delegates all administrative tasks to the user or group you specify. To use the script without modification, simply specify the Active Directory container where you want to create the zone, the zone name, and the user or group designated as the zone administrator.

To create new zone using the sample script:

1. Open the IBM Security access module for PowerShell.

2. Verify you are in the directory where the scripts are located.

3. Execute the sample script with the required command line arguments. For example:

   .\CreateZoneAndDelegate -Container “cn=Zones,ou=Acme Sales,dc=pistolas,dc=org” -ZoneName seattle -trustee frank.smith@pistolas.org

4. Open Access Manager.

5. Right click Zones and select Open Zone to search for and select the new zone.

6. If you want to delegate specific administrative tasks, copy the sample script and modify the Set-CdmDelegation call to specify a list of tasks. For example:

   Copy

   Set-CdmDelegation -Zone $zone -Task "AddUsers",”AddGroups” -Trustee $trustee;
   Write-Host "$trustee is delegated the rights to add users and groups.";
   

Generating Reports from Predefined Scripts

Most of the predefined reports in access manager report center have a corresponding PowerShell script that you can use to generate reports from the PowerShell console. See Using Predefined Scripts to Generate Reports for details.

Writing Custom Scripts

Most cmdlets and scripts return information efficiently without any special handling or any noticeable effect on performance. If you plan to write custom scripts that may return large data sets, you should consider ways to improve performance. For example, if you are writing a script that exports a large number of zones or reports on a large number of users, you might want to use the following recommendations as guidelines:

• When testing the performance of the script, use the standard Measure-Command cmdlet to accurately measure cmdlet and script performance.

The Measure-Command cmdlet ignores the time it takes to print all of the results returned to the PowerShell console. In many cases, the execution of a script is efficient, but rendering the results in the PowerShell console might make the cmdlet or script performance seem unacceptable.

• Consider how you want to balance memory usage and performance when using the PowerShell pipeline if your cmdlet or script returns large data collections.

  For example, you might use foreach in a script instead of using the pipeline to improve performance. Use syntax similar to this:

  foreach ($cmd in Get-CdmUserProfile -Zone $z) { action_on_each_cmd }

  Instead of:

  Get-CdmUserProfile -Zone $z | action_on_each_cmd

  However, if you choose not to use the pipeline, all of the returned objects stay in memory and might cause an out-of-memory error. Therefore, you should try to maintain balance between the scripts memory usage and performance.

• Cache the data, if possible, by writing the results to a file.

  For example, to add 1000 users to a zone use syntax similar to this to get a zone once:

  $zone = Get-CdmZone -Dn "cn=QA,cn=Zones,dc=ajax,dc=org"$profile1 = New-CdmUserProfile -Zone $zone -User user1@ajax.org -Uid 10001 ... $profile1000 = New-CdmUserProfile -Zone $zone -User user1000@ajax.org -Uid 11000

  Instead of using syntax like this, which gets the zone from its distinguished name (DN) for every user:

  $profile1 = New-CdmUserProfile -Zone "cn=QA,cn=Zones,dc=ajax,dc=org" ‑User user1@domain.com -Uid 10001 ... $profile1000 = New-CdmUserProfile -Zone "cn=QA,cn=Zones,dc=ajax,dc=org" ‑User user1000@domain.com -Uid 11000

• Use Export-Csv instead of Out-File if possible. The Export-Csv cmdlet writes results to a file faster than the Out-File cmdlet.

• If you are writing a script that generates a very large data set—for example, reporting information for a global zone—you might want to use the native .NET FileStream function. The FileStream function is the fastest way to write content to a file.

  For example, you might use a code snipper like this:

  Copy

  $fs = New-Object IO.FileStream <file>, 'Append','Write','Read'
     $fw = New-Object System.IO.StreamWriter $fs
       $zone = Get-CdmZone -Dn "cn=global,cn=Zones,dc=ajax,dc=org"
      foreach ($cz in $zone) {$fw.WriteLine("{0} {1}", $cz.Name, $cz.Type)}
    $fw.Close()
   $fs.Dispose()
  

Enabling Logging for cmdlets

For performance, logging for cmdlets is disabled by default. To enable logging, you must modify the registry on the computer where you are running the access module for Windows PowerShell.

To enable logging:

1. Run regedit to open the Registry Editor

2. Select the HKEY_CURRENT_USER > Software > IBM Security registry key.

3. Right-click, then select New > Key and type CIMS.

4. Select the new CIMS key, right-click, then select New > String Value with the name of LogPath.

5. Specify the path to the log file as the value. For example, set the value to C: \Temp\Log.

6. Select the new CIMS key, right-click, then select New > DWORD (32-bit) Value with the name of TraceLevel.

7. Specify the level of detail to write to the log file as the value. The valid settings are:

   0 to disable logging. 1 to only log error messages. 2 to log errors and warning messages. 3 to log errors, warnings, and informational messages. 4 to log all debugging and tracing messages.

   For example, set the value to 4 to enable detailed logging of all messages.

Viewing a Summary of cmdlet Commands

You can use the get-help command with different options to get summary about the cmdlets available in the IBM Security access module for PowerShell or detailed information about the specific cmdlets you want to use. For example, you can use get-help with the ‑full command-line option to see complete reference information for a specified cmdlet or get-help -example to display only the examples for a specified cmdlet.

To see the current list of cmdlets available open the IBM Security access module for PowerShell, run the get-help cdm command. This command displays a summary of the access module for PowerShell cmdlets similar to the following table (rendered as ASCII characters):

Table: Summary of cmdlet Commands Output by the get-help cdm Command

Objects and Properties

This section lists the objects defined by the authentication and privilege-elevation PowerShell module and the properties of each object.

This chapter provides an alphabetical listing of the objects and the properties of each object defined in the Access module for PowerShell. Note that not all properties are available as parameters in the PowerShell cmdlets.

CdmAdObject Object

Represents an Active Directory object. The following properties are defined for this object.

Table: CdmAdObject Properties

CdmAdPrincipal Object

Represents an Active Directory account principal. The following properties are defined for this object.

Table: CdmAdPrincipal Properties

CdmApplicationRight Object

Represents a Windows application access right. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmApplicationRight Properties

CdmCommandRight Object

Represents a UNIX command right. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmCommandRight Properties

CdmComputer Object

Represents an Active Directory computer object. The following properties are defined for this object.

Table: CdmComputer Properties

CdmComputerRole Object

Represents a IBM Security computer role. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmComputerRole Properties

CdmDesktopRight Object

Represents a Windows desktop access right. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmDesktopRight Properties

CdmEffectiveUnixRights Object

Represents the UNIX rights assigned to a user that are in effect on a Linux or UNIX computer in a zone. The following properties are defined for this object.

Table: CdmEffectiveUnixRights Properties

CdmEffectiveWindowsRights Object

Represents the Windows rights assigned to a user that are in effect on a Windows computer in a zone. The following properties are defined for this object.

Table: CdmEffectiveWindowsRights Properties

CdmGroup Object

Represents an Active Directory group. The following properties are defined for this object.

Table: CdmGroup Properties

CdmGroupProfile Object

Represents a UNIX group profile. The following properties are defined for this object.

Table: CdmGroupProfile Properties

CdmLocalGroupProfile Object

Represents a local UNIX group profile. The following properties are defined for this object.

Table: CdmLocalGroupProfile Properties

CdmLocalUserProfile Object

Represents a local UNIX user profile. The following properties are defined for this object.

Table: CdmLocalUserProfile Properties

CdmLocalWindowsGroup Object

Represents a local Windows group account. The following properties are defined for this object.

Table: CdmLocalWindowsGroup Properties

CdmLocalWindowsUser Object

Represents a local Windows user account. The following properties are defined for this object.

Table: CdmLocalWindowsUser Properties

CdmManagedComputer Object

Represents a computer managed by authentication and privilege elevation. The following properties are defined for this object.

Table: CdmManagedComputer Properties

CdmMatchCriteria Object

Represents an application right match criteria object defined using the application rights match criteria filters. The following properties are defined for this object.

Table: CdmMatchCriteria Properties

CdmNetworkRight Object

Represents a Windows network access right. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmNetworkRight Properties

CdmPamRight Object

Represents a PAM application access right. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmPamRight Properties

CdmRole Object

Represents a authentication and privilege elevation role. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmRole Properties

CdmRoleAssignment Object

Represents a authentication and privilege elevation role assignment. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmRoleAssignment Properties

CdmSshRight Object

Represents an SSH application access right. This object is only applicable in hierarchical zones. The following properties are defined for this object.

Table: CdmSshRight Properties

CdmUser Object

Represents an Active Directory user. The following properties are defined for this object.

Table: CdmUser Properties

CdmUserProfile Object

Represents a UNIX user profile. The following properties are defined for this object.

Table: CdmUserProfile Properties

CdmZone Object

Represents a IBM Security zone. The following properties are defined for this object.

Table: CdmZone Properties

Adding Users in a One-Way Trust Environment

This section explains how to add a user in a one-way trust environment using the authentication and privilege-elevation PowerShell module.

Some operations, such as adding a user to a zone, may require more than one credential. For example, if you want to add a user from one forest to a zone in another forest when there is a one-way trust between the forest, you might need to specify credentials for each forest. This section explains how to add a user in a one-way trust environment when using PowerShell cmdlets.

Using One Account Credential

If you want to add the user targetuser, who has a domain user account in forest2.net to the zone1 in forest1.net, where forest1.net trusts forest2.net (a one-way trust), you must use an account that has the following permissions:

• Permission to add a user to zone1 in forest1.net.

• Permission to read accounts in forest2.net.

If you have a single account with the appropriate permissions—for example, superuser in forest2.net—you can add the targetuser from forest2.net to the zone1 in forest1.net as follows:

Set-CdmCredential "forest1.net" "forest2\superuser"
New-CdmUserProfile -Zone "cn=zone1,cn=Zones,dc=forest1,dc=net" -User "cn=targetuser,cn=Users,dc=forest2,dc=net" -login "UNIXname" -uid nnnnn

where UNIXname is the UNIX login name of targetuser and nnnn is the UID of the targetuser.

Using Two Account Credentials

If you do not have a single account with the appropriate permissions in the two forests, adding the targetuser to a zone in another forest will require two account credentials. For example, you must identify accounts with the following permissions:

• An account in forest1.netthat has permission to add a user to zone1 (user1).

• An account in forest2.net that has read permission on forest2.net (user2).

After you identify the accounts with the appropriate permissions—for example, user1 in forest1.net and user2 in forest2.net—you can add the targetuser from forest2.net to the zone1 in forest1.net as follows:

Set-CdmCredential "forest1.net" "forest1\user1"
Set-CdmCredential "forest2.net" "forest2\user2"
New-CdmUserProfile -Zone "cn=zone1,cn=Zones,dc=forest1,dc=net" -User "targetUser@forest2.net" -login "UNIXname" -uid nnnnn

where UNIXname is the UNIX login name of targetuser and nnnn is the user’s UID.

Using Predefined Scripts to Generate Reports

This section describes the predefined report scripts that are included with the authentication and privilege-elevation PowerShell module and how to configure report output files to generate HTML- and PDF-formatted report files.

Most of the predefined reports in Access Manager Report Center have a corresponding PowerShell script to generate reports from the PowerShell console. When you use a PowerShell script to generate a report, the report content displays as text in the PowerShell console window. You can optionally format the report content as an HTML or PDF file using third-party tools.

Provided Report Scripts

The following report scripts are included with authentication and privilege elevation PowerShell. The scripts are typically installed in the following folder:

C:\Program Files\Centrify\PowerShell\Centrify.DirectControl.PowerShell\Reports

For details about script syntax, parameters, and examples, see the script help files. Execute the PowerShell Get-Help command to display the help for a script. For example, to display help details for the ZonesReport.ps1 script, execute the following command from the PowerShell command line:

PS> Get-Help .\ZonesReport.ps1 -Detailed

Running Report Scripts

When you perform the steps described in this section, the report content displays as text in the PowerShell console window. To generate formatted reports, see Formatting Reports.

To run a report script:

1. Open the IBM Security access module for PowerShell reports.

2. Verify you have permission to execute scripts by running Get-ExecutionPolicy. In most cases, the permission to execute scripts is restricted. You can use the Set‑ExecutionPolicy to allow execution. For example:

   Set-ExecutionPolicy Unrestricted

   For more information about execution policies and the options available, use the get‑help function.

3. Verify that you are in the directory where the report scripts are located. For example:

   C:\Program Files\Centrify\PowerShell\Centrify.DirectControl.PowerShell\Reports

4. Execute the report script. For example:

   .\ZonesReport.ps1

Formatting Reports

You can use the following cmdlets to format report output so it can be displayed or processed by third-party tools:

• Export-Csv

• Out-GridView

• Format-Table

• ConvertTo-Html

The following sections describe these cmdlets in detail.

Export-Csv cmdlet

Use this cmdlet to format report output as a CSV file. For example, execute the following command to format the output from the UsersReport.ps1 script as a CSV file:

PS> ./UsersReport.ps1 | Export-Csv C:\Report\UsersReport.csv -NoTypeInformation

In this example, the output file C:\Report\UsersReport.csv is created, and no type information for the input object is provided. After the CSV file is created, you can open it with third-party applications such as Microsoft Excel.

Out-GridView cmdlet

Use this cmdlet to format report output as an interactive table in a grid view window. For example, execute the following command to format the output from the UsersReport.ps1 script:

PS> ./UsersReport.ps1 | Out-GridView

Format-Table cmdlet

Use this cmdlet to format report output as a table that is displayed in the PowerShell console window with the selected properties of the object in each column. The object type determines the default layout and properties that are displayed in each column, but you can use the property parameter to select the properties that you want to display. You can specify any of the following parameters on the command line:

• AD User
• Home Directory
• Is Enabled
• Is Orphan
• Primary Group
• Shell
• UID
• UNIX User Name
• Zone

For example, the following command displays the output of UsersReport.ps1 in a table. The -GroupBy option shown here specifies that separate tables are displayed for each zone. Each zone table contains columns for AD User, UNIX User Name, UID, Shell, Home Directory, Is Enabled, Primary Group, and Is Orphan.

. PS> ./UsersReport.ps1 | Format-Table "AD User", "UNIX User Name", "UID", "Shell", "Home Directory", "Is Enabled", "Primary Group", "Is Orphan" -GroupBy Zone

Depending on your site’s zone configuration, this command would result in output similar to the following:

If the results are too wide to display in the PowerShell console default window size, you can change the PowerShell screen size, and enable some arguments (such as wrap or autosize) provided by this cmdlet.

ConvertTo-Html cmdlet

Use this cmdlet to format report output as an HTML file. This cmdlet returns the result to the PowerShell console window. You can then redirect the result to an HTML file by using the cmdlet Out-File, so that you can read the output using a Web browser. The HTML file created by this cmdlet uses the style sheet defined in the report.css file that is included with authentication and privilege elevation PowerShell.

For example, the following command converts the results of the UsersReport.ps1 script into HTML using the style defined in report.css, and writes the resulting HTML to the output file C:\Report\UsersReport.html.

PS> .\UsersReport.ps1 | ConvertTo-Html -CssUri report.css | Out-File C:\Report\UsersReport.html

Generating a PDF report

Overview

This section describes how to use the PDFCreator third-party tool to generate PDF output from a report script. The general steps are as follows:

1. ​ Install the PDFCreator third-party tool.

2. ​ Generate HTML output from a report script using the ConvertTo-Html cmdlet.

3. ​ Configure the PDFCreator printer that will convert the HTML output file into a PDF file.

4. ​ Direct the HTML output file to the PDFCreator printer to generate the PDF file.

Procedure Details

The following steps describe how to generate PDF output from the ZonesReport.ps1 script.

1. Note the following

   • You must have administrator privileges to perform these steps.
   • Unless otherwise noted, you perform the steps described here in the PowerShell console window.
   • In this example, the PDF printer that converts HTML to PDF is named "PDFCreator." If the printer has a different name in your environment, use your printer’s name.

2. Install PDFCreator from pdfforge.

3. Generate HTML output from the ZonesReport.ps1 script by executing the following command in the PowerShell console:

   .\ZonesReport.ps1 | ConvertTo-Html -Head "<Style>$(Get-Content .\Report.css)</Style>" | Out-File c:\Reports\ZonesReport.html

   When you execute this command, the file c:\Reports\ZonesReport.html is created using the styles in Report.css.

4. Specify PDFCreator as the default printer:

   1. Execute the following command to get all installed printers:

      $printers = gwmi win32_printer

   2. Run the following variable to list the printers:

      $printers

   3. In the list of printers, note the position of the PDFCreator printer in the list. For example, in the following list of printers, PDFCreator is the sixth printer listed:

      

   4. Make PDFCreator the default printer. In this example, because PDFCreator is the sixth printer on the list, you would execute the following command:

      $printers[5].SetDefaultPrinter()

   5. Ensure PDFCreator is the default printer by clicking Devices and Printers on the Windows Start Menu. If PDFCreator is not the default printer, you can make it the default printer there.

5. Configure the auto-save printer settings as follows:

   1. Change the auto-save directory to C:\Reports.

   2. Change the auto-save file name to ZonesReport.

   3. Enable the auto-save feature so that there will be no dialog prompts asking for which file name to save.

6. Perform the following steps to configure the registry to implement these changes. These steps assume that the default registry path is HKCU:\Software\PDFCreator\Program. If your registry path is different, change these commands as appropriate for your environment.

   1. Execute the following command to change the auto-save directory to C:\Reports:

      Set-ItemProperty -Path "HKCU:\Software\PDFCreator\Program" -Name "AutoSaveDirectory" -Value "C:\Reports"

   2. Execute the following command to change the auto-save file name to ZonesReport:

      Set-ItemProperty -Path "HKCU:\Software\PDFCreator\Program" -Name "AutoSaveFileName" -Value "ZonesReport"

   3. Execute the following command to enable the auto-save feature:

      Set-ItemProperty -Path "HKCU:\Software\PDFCreator\Program" -Name "UseAutoSave" -Value "1"

7. Use Windows Internet Explorer to print the HTML file that you created with the default (PDFCreator) printer. This creates the PDF file.

8. Create and run the following script in the PowerShell console window. The script performs the following tasks:

   1. Creates an IE object and stores it into the $ie variable.
   2. Sets IE output to not display on the screen. This part is optional—if you want IE output to display, you can omit this in the script.
   3. Instructs the $ie object to read the HTML content from the location C:\Reports\ZonesReport.html (the HTML file that you created earlier).
   4. Prints the content of $ie using default printer (PDFCreator), resulting in the generation of the PDF file.

9. The recommended script is as follows:

   Copy

   $ie = New-Object -com "InternetExplorer.Application"
   $ie.Visible = $false`
   $ie.Navigate("C:\Reports\ZonesReport.html")
   while ( $ie.busy ) { Start-Sleep -second 1 }
     $ie.ExecWB(6,2)
   while ( $ie.busy ) { Start-Sleep -second 1 }
     $ie.quit()
   

   This script is specific to the example used in this procedure. If you changed any of the steps in this procedure because of differences in your environment, you might have to make corresponding changes in the script shown.