aaearon / secretmanagement.cyberark

A SecretManagement extension for CyberArk.

SecretManagement.CyberArk

A SecretManagement extension for CyberArk. It supports connecting to the Vault by either the REST API, Credential Provider, or Central Credential Provider.

The psPAS or CredentialRetriever module is used to communicate with the Vault.

Prerequisities

• The psPAS Powershell module
• The CredentialRetriever Powershell module
• The SecretManagement Powershell module

Installation

From PowerShell Gallery

Install-Module SecretManagement.CyberArk

Registration

Once installed, it must be registered as an extension for SecretManagement. Depending on how you want to connect to the Vault, you will need to provide the appropriate parameters.

Credential Provider

Specify CredentialProvider as the ConnectionType, the AppID to authenticate as, and optionally a ClientPath to the Credential Provider executable (otherwise it will use the existing ClientPath previously set via Set-AIMConfiguration.)

$VaultParameters = @{
    ConnectionType = 'CredentialProvider'
    AppID          = 'windowsScript'
    ClientPath     = 'C:\Path\To\CLIPasswordSDK.exe'
}

Register-SecretVault -Name CyberArk -ModuleName SecretManagement.CyberArk -VaultParameters $VaultParameters

Central Credential Provider

Specify CentralCredentialProvider as the ConnectionType, the AppID to authenticate as, and the URL for the Central Credential Provider. Optionally, parameters such as SkipCertificateCheck, UseDefaultCredentials, Credential, CertificateThumbPrint, and Certificate can be specified.

$VaultParameters = @{
    ConnectionType       = 'CentralCredentialProvider'
    AppID                = 'windowsScript'
    URL                  = 'https://comp01.contoso.com'
    SkipCertificateCheck = $true
}

Register-SecretVault -Name CyberArk -ModuleName SecretManagement.CyberArk -VaultParameters $VaultParameters

REST API

Specify REST as the ConnectionType and an existing PASSession will be used.

$VaultParameters = @{
    ConnectionType = 'REST'
}

Register-SecretVault -Name CyberArk -ModuleName SecretManagement.CyberArk -VaultParameters $VaultParameters

Usage

You use the typical SecretManagement commands such as Get-Secret and Set-Secret.

Examples

To retrieve the password for an account named localAdmin01:

Get-Secret -Name localAdmin01 -VaultName CyberArk

or

Get-PASAccount -search localAdmin01 -safeName Windows | Get-Secret -VaultName CyberArk

Note: If multiple results are returned from CyberArk the first one is provided.

To retrieve the password for an account named linuxAdmin01 where policy requires a reason:

Get-Secret -Name localAdmin01 -AdditionalParameters @{Reason = 'To do things' } -VaultName CyberArk

To create a new credential in the Vault use:

$Secret = ConvertTo-SecureString 'verySecret!' -AsPlainText -Force

$NewCredentialProperties = @{
    platformId = 'WindowsDomainAccount'
    safeName   = 'Windows'
    address    = 'iosharp.lab'
    userName   = 'localAdmin10'
}

Set-Secret -VaultName CyberArk -Secret $Secret -AdditionalParameters $NewCredentialProperties

Note: The value passed to the Name argument will be used as the name property for the account in CyberArk. If you want CyberArk to generate the name for the account automatically, do not use the Name argument. This is not supported for the CentralCredentialProvider and CredentialProvider connection types.

secretmanagement.cyberark's Issues

Fixed version of Microsoft.PowerShell.Secretmanagement required

I've just tried to install this module and I got the following error;

PackageManagement\Install-Package : The following commands are already available on this
system:'Get-Secret,Get-SecretInfo,Remove-Secret,Set-Secret,Test-SecretVault'. This module 'SecretManagement.CyberArk'
may override the existing commands. If you still want to install this module 'SecretManagement.CyberArk', use
-AllowClobber parameter.

Checking the file SecretManagement.CyberArk.psd1 it has the follow required module set;

RequiredModules = @(
    'psPAS',
    @{
        ModuleName = 'Microsoft.Powershell.SecretManagement'
        ModuleVersion = '1.0.0'
    }
)

The current version on PSGallery is 1.1.1, which I has installed on my computer.

Would it be possible to remove the ModuleVersion or update it to allow more recent versions?

Handle multiple CyberArk Vaults

Right now we depend on the user to manage PASSession on their own. This makes it next to impossible to have users add multiple SecretManagement.CyberArk SecretVaults (use case: Multiple CyberArk environments, etc.)

We should handle the PASSession on behalf of the user and as long as they pass the needed parameters as part of VaultParameters when using Register-SecretVault.

Example of how this could look

$Parameters = @{ 
    BaseURI="https://cyberark-production.example.com"
    type="CyberArk"
    Credential="$Credentials"
    concurrentSession=$true 
}

Register-SecretVault -Name ProductionVault -ModuleName SecretManagement.CyberArk -VaultParameters $Parameters -DefaultVault

Convert `$AdditionalParameters` values to full parameters.

Great job on this extension!

After looking through the module functions, I wanted to suggest instead of passing in a hashtable with some cyberark-specific lingo to AdditionalParameters, instead add those values as parameters.

For example, in Set-Secret, you have a -VaultName parameter, but it is not actually used, as the function assumes you are passing in the safeName value via the -AdditionalParameters hashtable.

SecretManagement.CyberArk/SecretManagement.CyberArk.Extension/SecretManagement.CyberArk.Extension.psm1

Lines 104 to 123 in f820808

	function Set-Secret {
	[CmdletBinding()]
	param (
	[string] $Name,
	[object] $Secret,
	[string] $VaultName,
	[hashtable] $AdditionalParameters
	)
	Test-PASSession
	$AddPASAccountParameters = @{}
	if ($Name) { $AddPASAccountParameters.Add("name", $Name) }
	if ($AdditionalParameters.userName) { $AddPASAccountParameters.Add("userName", $AdditionalParameters.userName) }
	if ($AdditionalParameters.address) { $AddPASAccountParameters.Add("address", $AdditionalParameters.address) }
	if ($AdditionalParameters.safeName) { $AddPASAccountParameters.Add("safeName", $AdditionalParameters.safeName) }
	if ($AdditionalParameters.platformId) { $AddPASAccountParameters.Add("platformId", $AdditionalParameters.platformId) }
	Add-PASAccount @AddPASAccountParameters -secret $Secret
	}

You could create an alias on VaultName to be safeName so that either value could be passed in via a splatted hashtable to the function itself, and not only a parameter.

Additionally, you could pass in some of these other values like address, platformID, etc... to a -Metadata hashtable parameter, which would give your cmdlets the same behavior as the official Microsoft.PowerShell.SecretManagement cmdlets.

Thoughts?

Allow Get-SecretInfo to allow more than a single secret

Right now Get-SecretInfo only will return a single secret. Allow it to return all that match.

Allow for authentication to be done by psPAS or CredentialRetriever

Suggested in #1 (comment)

Right now the user has to use psPAS and a PASSession in order to authenticate to the CyberArk Vault. The extension should be flexible enough to allow authentication via CredentialRetriever.

Invoke-GetCCPCredential Should Support all VaultParameters that Get-CCPCredential Does

Invoke-GetCCPCredential doesn't allow using all of the parameters available with Get-CCPCredential. In particular, the following parameters are ignored, but some are absolutely necessary in non-standard CCP setups.

These all are used to build the query (or supply a raw query in the case of Query) and would help to select the correct secret.
Safe
Folder
Object
UserName
Address
Database
PolicyID
Reason
Query

These are used to setup the connection and WebServiceName is absolutely necessary if the authentication method isn't setup with the default AIMService context.
ConnectionTimeout
WebServiceName

It would probably be good to just allow any parameters to be supplied as part of VaultParameters and let the Get-CCPCredential function tell the user if they have specified something that doesn't work.

I will try to get a PR submitted to cover this soon.

Improve flexibility to grab an account credential via Get-Secret

Problem

Get-PASAccount -search is used to get an account ID that is later passed to Get-PASAccountPassword to retrieve the credential. Get-Secret is meant to return only a single Secret but depending on the search Get-PASAccount can return more than one result so we just return the first one. As an account's name property is, by default, not searchable via the CyberArk API it can be very difficult to craft a search query that returns exactly one account.

Ideas

psPAS.CyberArk.Vault.Account.V10 in pipeline

It would be convenient to be able to pass a [psPAS.CyberArk.Vault.Account.V10] to Get-Secret which would then get the credential for that account.

Example

Get-PASAccount -search root | Where-Object {$_.address -eq 'specificServer2'} | Get-Secret -AdditionalParameters @{Reason='Maintenance task'}

Allow Get-PASAccount parameters to be passed in AdditionalParameters for Get-Secret

Get-PASAccount enables a person to pass multiple parameters that could result in a single account being returned. We should enable users to pass the same parameters they are familiar with from Get-PASAccount in AdditionalParameters.

Example

Get-Secret -Name admin -AdditionalParameters @{searchType='startswith'}