Chat now with support
Chat with Support

Identity Manager 9.2 - Password Capture Agent Administration Guide

The One Identity Manager Password Capture Agent Managing the Password Capture Agent Fine-tuning automated password synchronization The Password Capture Agent Windows PowerShell module Event log for the Password Capture Agent Customizing security for the Password Capture Agent service Achieving high availability for the web service with Windows Network Load Balancing Installing the Password Capture Agent with MSIEXEC Certificate lookup options Known error codes

Installing the Password Capture Agent Windows PowerShell module

To install the Password Capture Agent Windows PowerShell module

  • Copy the OneIM-PasswordCaptureAgentMgmt folder, including content, to C:\Windows\System32\WindowsPowerShell\v1.0\Modules\ - the systems global Password Capture Agent Windows PowerShell module path.

    - OR -

  • Copy the OneIM-PasswordCaptureAgentMgmt folder to any path on your host, and add this path to the environment variable PSModulePath.

Before installing Password Capture Agent on a domain controller:

  • Ensure that the web service is installed and configured.

  • Ensure that the certificate to decrypt passwords with is installed with a private key in the LocalMachine\My\ certificate store on the server hosting the web service.

  • Ensure that the certificate to encrypt passwords with is installed with a private key in the LocalMachine\My\ certificate store on all domain controllers.

You should have prepared:

  • The thumbprint of the certificate for password encryption, for example:

    1800b62e8cf19d1c4bcdcd2b6e435c3c85e04188

  • The URL to the web service, for example:

    https://<servername.domain.com>/Appserver/

Using the Password Capture Agent Windows PowerShell module

Using the Password Capture Agent Windows PowerShell module to install Password Capture Agent on a specific domain controller

  1. Sign on to the workstation where the Password Capture Agent Windows PowerShell module is installed as a member of the Domain Admins group.

  2. Copy One Identity Manager Password Capture Agent.msi to a network share that can be accessed by you on all domain controllers, for example, \\StorageServer\SHARE\One Identity Manager Password Capture Agent.msi.

  3. Open an elevated Windows PowerShell prompt.

  4. Run the following command:

    Import-Module OneIM-PasswordCaptureAgentMgmt

  5. Run the following commands to define your configuration profile:

    $ConfigProfile = New-PCAConfigProfile

    $ConfigProfile['WebClient.WebServiceURL'].ConfigValue = 'https://<server.domain.com>/AppServer/'

    $ConfigProfile['WebClient.WebServiceType'].ConfigValue = 'REST'

    $ConfigProfile['Backend.Credential'].ConfigValue = Get-Credential viCaptureAgent

    $ConfigProfile['Backend.CertificateThumbprint'].ConfigValue = '1800b62e8cf19d1c4bcdcd2b6e435c3c85e04188'

  6. Run the following command:

    Install-PasswordCaptureAgent`

    -ComputerName "DC01.DEMOCORP.COM"`

    -Setup "\\StorageServer\SHARE\One Identity Manager Password Capture Agent.msi"`

    -ConfigurationProfile $ConfigProfile

    By running this command, you install the Password Capture Agent on DC01.DEMOCORP.COM. The installation runs off a network location, and the WebServiceURL parameter and the CertificateThumbprint parameter are passed to the setup.

    Because the -Restart switch is not specified, the domain controllers do not automatically reboot after successful installation.

Using the Password Capture Agent Windows PowerShell module to install Password Capture Agent on all domain controllers

  1. Sign on to workstation where the Password Capture Agent Windows PowerShell module is installed as a member of the Domain Admins group.

  2. Copy One Identity Manager Password Capture Agent.msi to a network share that can be accessed by you on all domain controllers, for example, \\StorageServer\SHARE\One Identity Manager Password Capture Agent.msi.

  3. Open an elevated Windows PowerShell prompt.

  4. Run the following command:

    Import-Module OneIM-PasswordCaptureAgentMgmt

  5. Run the following commands to define your configuration profile:

    $ConfigProfile = New-PCAConfigProfile

    $ConfigProfile['WebClient.WebServiceURL'].ConfigValue = 'https://<server.domain.com>/AppServer/'

    $ConfigProfile['WebClient.WebServiceType'].ConfigValue = 'REST'

    $ConfigProfile['Backend.Credential'].ConfigValue = Get-Credential viCaptureAgent

    $ConfigProfile['Backend.CertificateThumbprint'].ConfigValue = '1800b62e8cf19d1c4bcdcd2b6e435c3c85e04188'

  6. Run the following command:

    Get-DomainController | Install-PasswordCaptureAgent`

    -Setup \\StorageServer\SHARE\One Identity Manager Password Capture Agent.msi`

    -ConfigurationProfile $ConfigProfile

    -Restart

    By running this command, you receive a list of domain controllers and sequentially start the install on each one. The install runs off a network location, and the WebServiceURL parameter and the CertificateThumbprint parameter are passed to the setup.

    Because the -Restart switch is specified, the domain controllers automatically reboot after successful installation.

Working with configuration profiles

The Password Capture Agent Windows PowerShell module includes functions to create, show, get, set, import, and export a Password Capture Agent configuration profile.

NOTE: The Show-PCAConfigProfile function may also be used to get an overview of all parameters and read their descriptions or destinations.

Getting and setting the configuration profile is only possible if the Password Capture Agent is installed and running. It is not possible to access the secured configuration parameters without it.

Example: Create new profile and edit it

Import-Module OneIM-PasswordCaptureAgentMgmt

$ConfigProfile = New-PCAConfigProfile

$ConfigProfile['WebClient.WebServiceURL'].ConfigValue = 'https://<server.domain.com>/AppServer/'

$ConfigProfile['WebClient.AuthenticationType'].ConfigValue = 'WindowsIntegrated'

$ConfigProfile['Backend.AuthenticationModule'].ConfigValue = 'DialogUser'

$ConfigProfile['Backend.Credential'].ConfigValue = Get-Credential viCaptureAgent

$ConfigProfile['Backend.CertificateThumbprint'].ConfigValue = '0123456789ABCED0123456789ABCED0123456789'

Example: Read current profile and show it using GUI

Import-Module OneIM-PasswordCaptureAgentMgmt

$ConfigProfile = Get-PCAConfigProfile

Show-PCAConfigProfile -ConfigurationProfile $ConfigProfile

Example: Read current profile and export it to XML

Import-Module OneIM-PasswordCaptureAgentMgmt

$ConfigProfile = Get-PCAConfigProfile

Export-PCAConfigProfile -ConfigurationProfile $ConfigProfile -FilePath C:\tmp\CurrentPCAConfig.xml

Example: Import profile, edit, and set it

Import-Module OneIM-PasswordCaptureAgentMgmt

$ConfigProfile = Import-PCAConfigProfile -Filepath C:\tmp\CurrentPCAConfig.xml

$ConfigProfile['Backend.CertificateThumbprint'].ConfigValue = '0123456789ABCED0123456789ABCED0123456780'

Set-PCAConfigProfile -ConfigurationProfile $ConfigProfile

Example: Import profile and install Password Capture Agent

Import-Module OneIM-PasswordCaptureAgentMgmt

$ConfigProfile = Import-PCAConfigProfile -Filepath C:\CurrentPCAConfig.xml

Install-PasswordCaptureAgent`

–LogFile <Full UNC path to the log file on the remote server>`

-Setup <UNC path for Password Capture Agent MSI>`

-ConfigurationProfile $ConfigProfile

Example: Change parts of the configuration

Import-Module OneIM-PasswordCaptureAgentMgmt

$ConfigProfile = Get-PCAConfigProfile

$ConfigProfile['Backend.Credential'].ConfigValue = Get-Credential viCaptureAgent

Set-PCAConfigProfile -ConfigurationProfile $ConfigProfile

Example: Change parts of the configuration on all domain controllers

Get-DomainController | Foreach-Object {

$ConfigurationProfile = Get-PCAConfigProfile -ComputerName $_

$ConfigurationProfile['Backend.CertificateThumbprint'].ConfigValue = '1800b62e8cf19d1c4bcdcd2b6e435c3c85e04188'

Set-PCAConfigProfile -ComputerName $_ -ConfigurationProfile $ConfigurationProfile -RestartService

}

Troubleshooting

I am unable to import the Password Capture Agent Windows PowerShell module.

Windows PowerShell has an execution policy to restrict what may run. For more information about troubleshooting, see the Microsoft documentation (About Remote Troubleshooting).

  • Is the OneIM-PasswordCaptureAgentMgmt folder in any folder listed in $env:PSModulePath?

I am unable to establish a connection to the domain controllers.

The connection to the domain controllers requires Windows PowerShell remoting to be configured and enabled. The firewall may also block this connection by default. For more information about troubleshooting, see the Microsoft documentation (About Remote Troubleshooting).

I am experiencing problems installing the Password Capture Agent. Is there a way to get a log file?

Yes. Both Install-PasswordCaptureAgent and Uninstall-PasswordCaptureAgent have parameters that allow you to specify a log file and if logging should be verbose. The log file will be used by msiexec.exe.

Example:

Uninstall-PasswordCaptureAgent`

-ComputerName "DC01.DEMOCORP.COM"

-LogFile \\StorageServer\SHARE\DC01.uninstall.log`

-LogVerbose

Example:

Install-PasswordCaptureAgent`

-ComputerName "DC01.DEMOCORP.COM"`

-LogFile \\StorageServer\SHARE\DC01.install.log`

-LogVerbose`

-Setup "\\StorageServer\SHARE\One Identity Manager Password Capture Agent.msi"

Is it possible to automatically reboot the domain controllers after installing/uninstalling Password Capture Agent?

Yes. Both Install-PasswordCaptureAgent and Uninstall-PasswordCaptureAgent have a switch called restart that will do exactly this. It is $False by default.

Example:

Uninstall-PasswordCaptureAgent -ComputerName "DC01.DEMOCORP.COM" -Reboot

Example:

Uninstall-PasswordCaptureAgent -ComputerName "DC01.DEMOCORP.COM" -Reboot:$True

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating