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

This script Reports this Equivalent report
AuthorizationReportForComputers.ps1 Lists each computer in the zone and indicates which users are allowed to access each computer. This report applies to classic zones only. This report includes details from the user's UNIX profile for each user listed, including the user's Active Directory user name, UNIX user name, zone, UID, shell, home directory, and primary group. Classic Zone – Authorization Report for Computers
AuthorizationReportForUsers.ps1 Lists each user account in the zone and indicates which computers each user can access. This report applies to classic zones only. This report includes details from the user's UNIX profile for each user listed, including the user's UNIX user name, zone, UID, shell, home directory, and primary group. Classic Zone – Authorization Report for Users
ComputerEffectiveAuditLevelReport.ps1 Lists the audit level in effect for all authorized users on computers in each zone. This report applies to hierarchical zones only. Hierarchical Zone – Computer Effective Audit Level
ComputerEffectiveRightsReport.ps1 Lists the privileges granted on each computer. This report applies to hierarchical zones only. Hierarchical Zone – Computer Effective Rights
ComputerEffectiveRolesReport.ps1 Lists the roles assigned on each computer. This report applies to hierarchical zones only. Hierarchical Zone – Computer Effective Roles
ComputerRoleAssignmentsReport.ps1 Lists the computer roles that are defined for each zone. The report includes the users and groups and their associated roles. This report applies to hierarchical zones only. Hierarchical Zone – Computer Role Assignments
ComputerRoleMembershipReport.ps1 Lists the computer roles that are defined for each computer and the zone to which they belong. This report applies to hierarchical zones only. Hierarchical Zone – Computer Role Membership Report
ComputersReport.ps1 Lists computer account information for each computer in each zone. The information displayed includes the computer account name in Active Directory, the computer's DNS name, the computer's operating system, and the version of the Delinea Agent for *NIX installed on the computer, if available. Computers Report
GroupsReport.ps1 Lists group information for each group in each zone. The information that is displayed includes the Active Directory group name, the UNIX group name, the UNIX group identifier (GID), and whether the group is an orphan. Groups Report
StaleComputersReport.ps1 Lists information about all authentication service-enabled computers that have not changed their password in a specified number of days (90 days by default). Stale Computers Report
UnixUserEffectiveRightsReport.ps1 Lists the effective rights for each UNIX user on each computer. The report shows the name of the right, its type, and where it is defined. This report applies to hierarchical zones only. Hierarchical Zone – UNIX User Effective Rights
UserAccountReport.ps1 Lists Active Directory account details for the users that have UNIX profiles in each zone. The report includes the Active Directory display name, logon name, and domain for the account. It also includes the account status, such as the date and time of the account's last logon and whether the account is configured to expire, locked out, or disabled. User Account Report
UsersReport.ps1 Lists information from the UNIX profile for each user in each zone. The report includes the user's Active Directory user name, UNIX user name, UID, shell, home directory, and primary group. Users Report
WindowsUserEffectiveRightsReport.ps1 Lists the effective rights for each Windows user on each computer. The report shows the name of the right, its type, and where it is defined. This report applies to hierarchical zones only. Hierarchical Zone – Windows User Effective Rights
ZoneDelegationReport.ps1 Lists the administrative tasks for each zone and the users or groups (trustees) that have been delegated to perform each task. When you grant administrative rights to designated users and groups, you make them "trustees" with permission to perform specific operations. This report indicates which users or groups have permission to perform specific tasks, such as add groups, join computers to a zone, or change zone properties. Zone Delegation Report
ZoneRolePrivilegesReport.ps1 Lists the roles that are defined for each hierarchical zone and the rights granted by each of these roles, including where each right is defined. Hierarchical Zone – Zone Role Privileges Report
ZonesReport.ps1 Lists the zone UNIX properties for each zone. This report includes the zone name, list of available shells, the default shell, the default home directory path, the default primary group, the next available UID, reserved UIDs, the next available GID, and reserved GIDs. Zones Report

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 Server Suite 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

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.

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:

      img

    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.