# PowerShell Plugin

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-Mkx-lxHNSwOix9K5_-J%2F-Mkx9u3Z-bE-LQokynFC%2Fpowershell-plugin-header.jpg?alt=media\&token=ff821ba5-92f0-43b6-8768-198012a8450d)

## Features

* Retrieve secrets from the Keeper Vault to use in PowerShell
* Integrate Keeper vault with PowerShell Secrets Manager
* Update secret values in the Keeper Vault from PowerShell
* Get files from the Keeper vault

{% hint style="info" %}
For a complete list of Keeper Secrets Manager features see the [Overview ](https://docs.keeper.io/en/keeperpam/secrets-manager/overview)
{% endhint %}

## Prerequisites

This page documents the Secrets Manager PowerShell integration.  In order to utilize this integration, you will need:

{% hint style="warning" %}
Secrets Manager requires **PowerShell version 6 or greater**. Microsoft distributes PowerShell version 6+ as a separate application from versions 5 and earlier. &#x20;

See [Microsoft's Documentation](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.1) for installation details
{% endhint %}

* **PowerShell Version 6.0 or later**
  * See [Microsoft's Documentation](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.1) for installation details
* Keeper Secrets Manager access (See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/secrets-manager/quick-start-guide) for more details)
  * Secrets Manager addon enabled for your Keeper account
  * Membership in a Role with the Secrets Manager enforcement policy enabled
* A Keeper [Secrets Manager Application](https://docs.keeper.io/en/keeperpam/about/terminology#application) with secrets shared to it&#x20;
  * See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/quick-start-guide#2.-create-an-application) for instructions on creating an Application
* [A One Time Access Token](https://docs.keeper.io/en/keeperpam/secrets-manager/about/one-time-token)

## About

The Keeper Secrets Manager PowerShell plugin utilizes Microsoft PowerShell's Secret Management module to inject secrets from the Keeper Vault into your PowerShell scripts.

The Keeper Secrets Manager extension can be easily configured added as a secret vault into new or existing PowerShell Secret Management workflows.

For more information about PowerShell Secret Management, see the [PowerShell docs](https://github.com/powershell/SecretManagement) on their GitHub page.&#x20;

## Installation

#### 1. Install PowerShell Secret Management Module

Keeper Secrets Manager uses the Microsoft.PowerShell.SecretManagement module to manage secrets in PowerShell.

Install using PowerShell:

```bash
Install-Module -Name Microsoft.PowerShell.SecretManagement
```

See [PowerShell Gallery](https://www.powershellgallery.com/packages/Microsoft.PowerShell.SecretManagement/1.1.0) for other installation options

#### 2. Install Keeper Secrets Manager for PowerShell

Install the Keeper Secrets Manager PowerShell extension from the PowerShell Gallery.

```bash
Install-Module -Name SecretManagement.Keeper
```

See the [PowerShell Gallery page](https://www.powershellgallery.com/packages/SecretManagement.Keeper) for more installation options, or find the source code in [GitHub](https://github.com/Keeper-Security/secrets-manager/tree/master/sdk/dotNet/SecretManagement.Keeper).

{% hint style="info" %}
To update SecretManagement, use the command: `Update-Module -Name SecretManagement.Keeper`
{% endhint %}

#### 3. Install a PowerShell Secret Management Extension

{% hint style="info" %}
If you already have a local secrets extension that you would like to use, you can skip this step
{% endhint %}

The Keeper Secrets Manager PowerShell plugin will need a secret management extension to store the plugin configuration locally to your machine.

Keeper recommends  [Microsoft.Powershell.SecretStore](https://www.powershellgallery.com/packages/Microsoft.PowerShell.SecretStore) or [SecretManagement.KeyChain](https://www.powershellgallery.com/packages/SecretManagement.KeyChain)

{% tabs %}
{% tab title="SecretStore" %}

```bash
Install-Module -Name Microsoft.Powershell.SecretStore
```

{% endtab %}

{% tab title="KeyChain" %}

```bash
Install-Module -Name SecretManagement.KeyChain
```

{% endtab %}
{% endtabs %}

#### 4. Register a Vault to use for Configuration Storage

{% hint style="info" %}
If you already have a local secrets vault registered that you would like to use, you can skip this step
{% endhint %}

Register a secret vault for the previously installed secret management extension, so that the Keeper Secrets Manager plugin configuration can be stored.

{% tabs %}
{% tab title="SecretStore" %}

```bash
Register-SecretVault -Name LocalStore -ModuleName Microsoft.Powershell.SecretStore
```

{% endtab %}

{% tab title="KeyChain" %}

```bash
Register-SecretVault -Name LocalStore -ModuleName SecretManagement.KeyChain
```

{% endtab %}
{% endtabs %}

The name of this vault will be used to register the Keeper extension. We used `LocalStore` in this example.&#x20;

The Secret Management extension that you use for local storage may ask you to create a password for securely accessing the local vault.

{% hint style="warning" %}
Depending on your system settings, you may need to allow PowerShell to trust external modules.  To do this, run the command:

`set-executionpolicy remotesigned`
{% endhint %}

#### 5. Register the Keeper Vault

Register the Keeper Secrets Manager Vault using the local vault registered above to save your credentials, and a one time token to connect to Keeper.

Replace 'XXX' below with a one time token.

<pre class="language-aspnet"><code class="lang-aspnet"><strong>Register-KeeperVault -Name Keeper -LocalVaultName LocalStore -OneTimeToken XXX 
</strong></code></pre>

Alternatively you can use already generated config - replace 'XXX' below with a base64 encoded config.

<pre class="language-aspnet"><code class="lang-aspnet"><strong>Register-KeeperVault -Name Keeper -LocalVaultName LocalStore -Config XXX 
</strong></code></pre>

#### 6. Set Keeper Vault as Default Secret Storage (Optional)

Set the Keeper vault you just added as the default secret storage.  This will tell the PowerShell SecretsManagement module to use your Keeper vault when getting and setting secrets.

```
Set-SecretVaultDefault Keeper
```

This step is optional, but if you choose not to do it, you may receive secrets from your default vault if they have the same name, and you will need to add `-Vault <keeper vault name>`  (e.g. `-Vault keeper` ) to `Get-Secret, Set-Secret` commands

{% hint style="success" %}
The Keeper Secrets Manager PowerShell Plugin is now ready to be used
{% endhint %}

### Source Code

Find the Keeper Secrets Manager PowerShell Plugin source code in the [GitHub repository](https://github.com/Keeper-Security/secrets-manager/tree/master/sdk/dotNet/SecretManagement.Keeper).

## Usage

Find descriptions and examples of the most common usage of the Keeper Secrets Manager PowerShell plugin below.

For more information about PowerShell Secret Management commands, see the [PowerShell docs](https://github.com/powershell/SecretManagement) on their GitHub page.&#x20;

{% hint style="warning" %}
Starting with version 16.6.6 `Get/Set` commands allow use of `\` as and escape character for dots in title. Use escape character only if there's dot in title, and escape both `.` and `\` (*ex.* `\.`, `\\`)
{% endhint %}

### Listing Secrets

Run the following PowerShell command to see a list of secrets from Keeper

{% tabs %}
{% tab title="Command" %}

```bash
Get-SecretInfo -Vault <KEEPER VAULT NAME>
```

{% endtab %}

{% tab title="Example" %}

```bash
PS> Get-SecretInfo -Vault Keeper

Name                                  Type      VaultName
----                                  ----      ---------
bf3dg-99-Juh3feswgtFxg Home SSH       Hashtable Keeper
_3zT0HvBtRdYzKTMw1IySA ACME Login     Hashtable Keeper
```

{% endtab %}
{% endtabs %}

Use the name set for your Keeper secrets vault, in the examples above we use `Keeper`.

The secrets shown are any records shared with the Secrets Manager Application.  The Name column  displays each record's UID and title.

### Getting a Single Secret

Get information and values of a single secret

{% tabs %}
{% tab title="Command" %}

```bash
Get-Secret -Vault <KEEPER VAULT NAME> <RECORD NAME or UID> -AsPlainText
```

{% endtab %}

{% tab title="Example" %}

```bash
PS> Get-Secret -Vault Keeper "ACME Login" -AsPlainText

Name                           Value
----                           -----
login                          user2
password                       123
Files                          {file1.json, file2.zip}
```

{% endtab %}
{% endtabs %}

Wrap the record name in quotation marks when there is a space in it.

{% hint style="info" %}
`-AsPlainText` Shows the actual values of the secrets.  Otherwise PowerShell shows them as a `SecureString`
{% endhint %}

### Get a Value From a Secret

Utilize [Keeper Dot Notation](https://docs.keeper.io/en/keeperpam/secrets-manager/about/keeper-notation) to identify a field to access.  Note that you do not need the 'keeper://' prefix.

{% tabs %}
{% tab title="Command" %}

```bash
Get-Secret -Vault <KEEPER VAULT NAME> <RECORD NAME OR UID>.<FIELD> -AsPlainText
```

{% endtab %}

{% tab title="Example" %}

```bash
PS> Get-Secret -Vault Keeper "ACME Login.password" -AsPlainText
gmzN6E8@9E97%xPB6Pg0
```

{% endtab %}
{% endtabs %}

### Set a Value to a Secret

Update the value of a single secret field&#x20;

{% tabs %}
{% tab title="Command" %}

```bash
Set-Secret -Vault <KEEPER VAULT NAME> <RECORD NAME OR UID>.<FIELD> <VALUE TO SET>
```

{% endtab %}

{% tab title="Example" %}

#### Keeper Vault is set as Default Vault

```bash
PS> Set-Secret -Vault Keeper "ACME Login.url" "acme.com"
```

#### Keeper Vault is not Default Vault

```powershell
PS> Set-Secret -Vault Keeper "ACME Login.url" "acme.com" -Vault keeper
```

{% endtab %}
{% endtabs %}

### Download a File

Use dot notation to specify a file attached to a secret in the Keeper vault.  Then pass that file to the `Set-Content` command to download it.

{% tabs %}
{% tab title="Command" %}

```bash
Get-Secret -Vault <KEEPER VAULT NAME> <RECORD NAME OR UID>.files[<FILENAME>] `
| Set-Content -Path <FILE PATH> -AsByteStream
```

{% endtab %}

{% tab title="Example" %}

```bash
PS> Get-Secret -Vault Keeper my_record.files[file1.json] `
| Set-Content -Path ./file1.json -AsByteStream
```

{% endtab %}
{% endtabs %}

The specified file will be downloaded to the path location given to `Set-Content`
