Change Auditor 7.5 - User Guide

Finding Change Auditor installations and coordinators

Finding Change Auditor installations and coordinators

The following commands allow you to find the Change Auditor installations and coordinators available in your Active Directory environment. Once connected, you can run additional commands to manage the deployment.

NOTE: The installations and coordinators that a search returns depends on your credentials and domain trusts.

•	Find-CAInstallations

•	Find-CACoordinators

•	Find-CASuitableCoordinator

Find-CAInstallations

Use this command to search Active Directory for all available Change Auditor installations. The default is the current computer’s forest, however, you can optionally specify a domain to search cross-forest for deployments.

NOTE: This command runs in the context of the current user running PowerShell. The user must have permission to search Active Directory in the specified domain.

Example: Find all Change Auditor installations in DomainName.com

Find-CAInstallations –DomainName ‘DomainName.com’

Find-CACoordinators

Use this command to search Active Directory for all available coordinators. The default is the current computers forest, however, you can optionally specify a domain to search cross-forest for deployments. This search returns all the information required to connect to the coordinator including ports.

NOTE: This command runs in the context of the current user running PowerShell. The user must have permission to search Active Directory in the specified domain.

Example: Find all available coordinators in DomainName.com

Find-CACoordinators -DomainName 'DomainName.com'

Find-CASuitableCoordinator

Use this command to search Active Directory for a coordinator to which a connection can be made. The default is the current computers forest; however, you can optionally specify a domain to search cross-forest for deployments.

If more than one Change Auditor installation is discovered, the call fails and the –InstallationName parameter is required.

Table 6. Available parameters

Parameter

Description

-Certificate (Optional)

When certificate authentication between the client and coordinator in environments is in place, this parameter specifies the thumbprint string copied from a certificate found in the certmgr.msc Certificate Manager for the current user in the Personal\Certificates folder. This certificate must be trusted, not expired, have a private key and at least the “Client Authentication” purpose. (“Proves your identity to a remote computer”).

Example: Find a coordinator in ‘DEFAULT’ installation that you have the credentials to connect to

Find-CASuitableCoordinator –InstallationName ‘DEFAULT’

 

Example: Find a coordinator in Domain that you have the credentials to connect to, when using certificate authentication

$creds = Get-Credential

$connection = Connect-CAClient -Credential $creds

Find-CASuitableCoordinator -Credential $creds -DomainName ‘DomainName.com'

Connecting to and disconnecting from Change Auditor installations and coordinators

Connecting to and disconnecting from Change Auditor installations and coordinators

•	Connect-CAClient

•	Disconnect-CAClient

Connect-CAClient

Most Change Auditor commands require a connection to a coordinator. This connection can be assigned to a variable and used for any command that requires it. This command searches for a suitable coordinator in a Change Auditor installation and creates a connection. Suitable coordinators are those to which you have access to and can be located by searching through Active Directory service connection points.

You can also connect to Change Auditor installations in untrusted domains or to a specific coordinator by specifying the -ComputerName and -Port parameters.

You can make multiple connections to different coordinators or deployments in the same script as long as the version of Change Auditor is the same.

NOTE: Connections are closed when the PowerShell session is ended or disconnected.

 

Table 7. Available parameters

Parameter	Description
-Credential (Optional)	Windows credentials specifying the user to connect to the Change Auditor installation. All operations using this connection will be authorized as this user. When not specified, the current client running PowerShell is used. NOTE: Credentials are required when certificate authentication is being used.
-CoordinatorConnectionPoint	Specify to use a specific coordinator found from a previous call to Find-CACoordinators.
-SelectLocalCoordinator	Create a connection to the local coordinator.
-InstallationName (Optional)	The installation name to connect to. If an installation cannot be found with this name, no connection is made. If more than one Change Auditor installation exists in the current forest, this parameter is mandatory. Omitting it results in a connection failure due to ambiguity.
-DomainName (Optional)	The name of the domain where the Change Auditor installation exists.
-ComputerName	The computer to connect to.
-Port	The port to connect to.
-WaitForServiceReady (Optional)	The number of seconds to wait for the connected coordinator service to be ready. NOTE: If not specified, when the Change Auditor coordinator is not ready for connections due to an in-progress install or upgrade, an error is returned. The maximum is 144,000 seconds, or 10 hours.
-UseCertificateAuth (Optional)	This parameter specifies that the coordinator is expected to be configured for certificate authentication. This parameter does not require an input value. When specified, this parameter is $true.
-DisableCertificateCrlCheck (Optional)	When certificate authentication between the client and coordinator in environments is in place, this parameter specifies that Certificate Revocation List checking is disabled. This parameter does not require an input value. When specified, this parameter is $true.
-Certificate (Optional)	When certificate authentication between the client and coordinator in environments is in place, this parameter specifies the thumbprint string copied from a certificate found in the certmgr.msc Certificate Manager for the current user in the Personal\Certificates folder. This certificate must be trusted, not expired, have a private key and at least the “Client Authentication” purpose. (“Proves your identity to a remote computer”).

 

Table 8. Supported parameter sets that enable a connection

Example	Enter the following command:
Recommended: Connect to the installation “XYZ” in the local forest. NOTE: This allows for fault tolerance if you have numerous coordinators by selecting the best option in the domain.	Connect-CAClient –InstallationName ‘XYZ’ -DomainName 'DomainName.com'
Connect to the first suitable coordinator found in any installation in any trusted domain.	$connection = Connect-CAClient
Connect to a specific coordinator by computer name and port.	Connect-CAClient –ComputerName ‘ca-cord.DomainName.com’ –Port 52289
Connect to the first suitable coordinator in the domain “DomainName.com”.	Connect-CAClient –DomainName ‘DomainName.com’
Connect to the first suitable coordinator in the domain “DomainName.com” with an installation name “DEFAULT”.	Connect-CAClient –DomainName ‘DomainName.com’ –InstallationName ‘DEFAULT’
Connect to a coordinator found from Find-CACoordinators.	$coordinators = Find-CACoordinators –DomainName ‘DomainName.com’ $connection = Connect-CAClient –CoordinatorConnectionPoint $coordinators[0]
Connect to a specific coordinator by computer name and port, when using certificate authentication.	$creds = Get-Credential Connect-CAClient -Credential $creds -ComputerName ‘ca-coordinator.DomainName.com’ –Port 52289 -UseCertificateAuth

Disconnect-CAClient

Use this command to disconnect from Change Auditor. (This is the equivalent of closing the Change Auditor client.)

Example: Connect to a Change Auditor deployment, and then close the connection

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

# perform some actions

Disconnect-CAClient $connection

Importing and exporting configuration settings

Importing and exporting configuration settings

•	Import-CAConfigurations

•	Export-CAConfigurations

 

Import-CAConfigurations

Use this command to import Change Auditor configuration settings.

NOTE: All settings contained in the specified import file are imported by default when using this command except for Application User Interface and Coordinator configurations which can be included by using the provided optional parameters.

Table 9. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-ConfigurationSettings	An XML document (Xml.XmlDocument object) that contains the configuration settings to import.
-IncludeCoordinatorConfig (Optional)	Imports the coordinator configuration if present in the exported file. NOTE:   • This will overwrite existing settings, including SMTP Mail Server and Alert settings. • Scheduled task settings will not be applied when selected coordinators are missing.
-IncludeAppUserInterfaceConfig (Optional)	Imports the Application User Interface configuration. NOTE: This will overwrite existing coordinator user role settings and assignments which may require a restart of the coordinator in order to regain access.
-Force (Optional)	Suppresses warning y/n prompts from the -IncludeCoordinatorConfig and -IncludeAppUserInterfaceConfig parameters.

Example: Importing configuration settings

$connection = Connect-CAClient -Credential $creds

[xml] $xmld = Get-Content 'C:\DataFolder\CAConfig.xml'

Import-CAConfigurations -Connection $connection -ConfigurationSettings $xmld

Export-CAConfigurations

Use this command to export Change Auditor configuration settings.

NOTE: All settings that can be exported with the Windows client interface are included by default when exporting configuration settings using this command, including settings for Application User Interface and Coordinator configurations.

Table 10. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.

Example: Exporting Change Auditor configuration settings

$connection = Connect-CAClient -Credential $creds

$xmlDoc = Export-CAConfigurations $connection

$xmlDoc.Save(“C:\Configurations\CAconfig.xml”)

Managing client authentication options

Managing client authentication options

Change Auditor has two authentication method:

•	Windows Forms Authentication (enabled by default)

When users log in, they must enter a Windows user account and a password.

•	Active Directory Client Certificate Authentication

When users log in, they must specify a smart card or certificate. User account and password are not required.

These commands allow you to manage the authentication used in your Change Auditor deployment.

Get-CAAuthenticationOptions

Use this command to view the authentication profile Change Auditor coordinators use in a particular installation.

Returns: An object containing the options for authentication for the specified installation.

Table 11. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-InstallationName (Optional)	The installation name to connect to. If an installation cannot be found with this name, no connection is made. If more than one Change Auditor installation exists in the current forest, this parameter is mandatory. Omitting it results in a connection failure due to ambiguity.
-DomainName (Optional)	The name of the domain where the Change Auditor installation exists.

Example

Get-CAAuthenticationOptions –InstallationName ‘DEFAULT’ –DomainName ‘DomainName.com’

Get-CAAuthenticationOptions -Connection $connection

Set-CAAuthenticationOptions

Use this command to alter the authentication profile the Change Auditor coordinators use in a particular installation.

Returns: An object containing the options for authentication for the specified installation.

Table 12. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-AlwaysChallengeForCredential (Optional)	When specified, instructs the coordinator to disallow any connection that is not accompanied by credentials. For PowerShell clients, this means that the Connect-CAClient command will not connect without the use of the -Credential parameter.
-AllowActiveDirectoryCertificateAuthentication (Optional)	When specified, instructs the coordinator to allow certificate authentication via a web client. This switch has no meaning for the Win32 client.
-AllowWindowsFormsAuthentication (Optional)	When specified, instructs the coordinator to accept default username/password style of credentials.
-AuthenticationOptions (Optional)	This parameter allows the caller to pass directly the result of the Get-CAAuthenticationOptions without having to break down the options into their constituent flag values.

Example

Set-CAAuthenticationOptions -Connection $connection -AlwaysChallengeForCredential
-AllowActiveDirectoryCertificateAuthentication -AllowWindowsFormsAuthentication

Set-CAAuthenticationOptions -Connection $connection -AuthenticationOptions $AuthenticationOptions