Utilize PowerShell’s Secret Management module to access secrets with the Keeper Secrets Manager PowerShell Plugin
Plugins are enabled in appsettings.json or through environment variables. See App Settings for information on where to configure these options. Any changes made to the configuration will require a restart of the PowerShell Universal service.
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
For a complete list of Keeper Secrets Manager features see the Overview
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.
This plugin is one of two available for PowerShell. Make sure to choose the correct version depending on your requirements:
Currently only PowerShell v7 is supported for these plugins
Run custom PowerShell scripts to retrieve and enhance data. This is useful for accessing third-party APIs and non-trivially manipulating the data you retrieve, beyond the capability of the Web API plugin.
OpenTelemetry is a collection of APIs, SDKs, and tools. Use it to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) to help you analyze your software’s performance and behavior.
The plugin enables integration with the technology. You can use App Settings to configure where to send data. PowerShell Universal currently only exposes a single OTLP endpoint configuration. The below configuration would work with Prometheus.
This page documents the Secrets Manager PowerShell integration. In order to utilize this integration, you will need:
Secrets Manager requires PowerShell version 6 or greater. Microsoft distributes PowerShell version 6+ as a separate application from versions 5 and earlier.
See Microsoft’s Documentation for installation details
PowerShell Version 6.0 or later
Secrets Manager addon enabled for your Keeper account
Membership in a Role with the Secrets Manager enforcement policy enabled
Find descriptions and examples of the most common usage of the Keeper Secrets Manager PowerShell plugin below.
Use the name set for your Keeper secrets vault, in the examples above we use Keeper.
Getting a Single Secret
Get information and values of a single secret
Wrap the record name in quotation marks when there is a space in it.
-AsPlainText Shows the actual values of the secrets. Otherwise PowerShell shows them as a SecureString
Get a Value From a Secret
Utilize Keeper Dot Notation to identify a field to access. Note that you do not need the ‘keeper://’ prefix.
Set a Value to a Secret
Update the value of a single secret field
If the Keeper vault is not set as the default secret vault add
-Vault <keeper vault name> to the command
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.
The specified file will be downloaded to the path location given to Set-Content
1. Install PowerShell Secret Management Module
Keeper Secrets Manager uses the Microsoft.PowerShell.SecretManagement module to manage secrets in PowerShell.
Install using PowerShell:
See PowerShell Gallery for other installation options
2. Install Keeper Secrets Manager for PowerShell
Install the Keeper Secrets Manager PowerShell extension from the PowerShell Gallery.
To update SecretManagement, use the command: Update-Module -Name SecretManagement.Keeper
3. Install a PowerShell Secret Management Extension
If you already have a local secrets extension that you would like to use, you can skip this step
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 or SecretManagement.KeyChain
4. Register a Vault to use for Configuration Storage
If you already have a local secrets vault registered that you would like to use, you can skip this step
Register a secret vault for the previously installed secret management extension, so that the Keeper Secrets Manager plugin configuration can be stored.
The name of this vault will be used to register the Keeper extension. We used LocalStore in this example.
The Secret Management extension that you use for local storage may ask you to create a password for securely accessing the local vault.
Depending on your system settings, you may need to allow PowerShell to trust external modules. To do this, run the command:
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.
Register-KeeperVault -Name Keeper `
-LocalVaultName LocalStore `
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.
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 Set-Secret commands
The Keeper Secrets Manager PowerShell Plugin is now ready to be used
Find the Keeper Secrets Manager PowerShell Plugin source code in the GitHub repository.
C# API Environment
This plugin creates a C#-based environment that can be used to create API endpoints with C# code. APIs created with C# are much faster than PowerShell-based endpoints. Endpoints run directly in the PowerShell Universal service. Any exception thrown from your endpoint will be handled and a valid status code will be returned to the caller.
You must create endpoints with the -Path parameter and specify the C# environment for the endpoint to function properly.
Defining an Endpoint
Within the C# endpoint, there are two classes that are of interest. The first is the request variable that is passed to the endpoint. It is an ApiRequest object.
In your endpoint, you can access this variable automatically.
// Do some stuff with JSON
You can return a response by creating a new object and returning it from your endpoint.
You can access the PowerShell Universal service container within your endpoint by accessing the ServiceProvider property in your endpoint. We currently do not document the internal services of PowerShell Universal.
Plugins
Plugins that extend the PowerShell Universal platform.
Plugins are functionality that are not enabled by default. A publicly available plugin API is currently being developed and will be released with a future version of PowerShell Universal. Below are a list of the plugins that are shipped with PowerShell Universal v4.2 and later.
How to add a PowerShell data source
To add a data source click on the + next to Data Sources on the left-hand menu in SquaredUp. Search for the data source and click on it to open the Configure data source page.
Display Name:
Enter a name for your data source. This helps you to identify this data source in the list of your data sources.- Variables:
Optionally, click Add new variable to create a variable that can be added into your PowerShell data stream scripts. Variables are created as key value pairs, and the value can be encrypted (for example, when creating a variable for an API key) by clicking the padlock icon next to the entry field. Additional variables can be created by clicking Add another variable.
See Using the PowerShell data streams for more information on using PowerShell variables. Optionally, select whether you would like to restrict access to this data source instance. By default, restricted access is set to off.
Use the Restrict access to this data source dropdown to control who has access to the workspace:
- By default, the user setting the permissions for the data source will be given Full Control and the Everyone group will be given Link to workspace permissions.
- Tailor access to the data source, as required, by selecting individual users or user groups from the dropdown and giving them Link to workspace or Full Control permissions.
- If the user is not available from the dropdown, you are able to invite them to the data source by typing in their email address and then clicking Add. The new user will then receive an email inviting them to create an account on SquaredUp. Once the account has been created, they will gain access to the organization.
- At least one user or group must be given Full Control.
- Admin users can edit the configuration, modify the Access Control List (ACL) and delete the data source, regardless of the ACL chosen.
- Click Add.
Using the PowerShell data streams
Data streams standardize data from all the different shapes and formats your tools use into a straightforward tabular format. While creating a tile you can tweak data streams by grouping or aggregating specific columns. Depending on the kind of data, SquaredUp will automatically suggest how to visualize the result, for example as a table or line graph.
Data streams can be either global or scoped:
- Global data streams are unscoped and return information of a general nature (e.g. “Get the current number of unused hosts”).
- A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. “Get the current session count for these hosts”).
Data streams
This data stream allows you to enter and run custom PoweShell scripts. This is the only data stream installed with the plugin.
- Select the Run Script data stream. Click Next to go to the Query tab.
- Script:
Enter or paste your PowerShell script into this field. You can use the variables you defined when adding the data source (see How to add a PowerShell data source) by entering$variable.variableName. For example,$variable.apiKeyor$variable.password. - JSON Depth:
Enter the number of nested object levels required in the return payload. This option is useful if the return payload contains a significantly large number of nested objects. - Click Test to execute the script. The Result box will show an example of the resulting payload.
Tips for using the PowerShell data stream
The only data stream installed with this plugin is Run Script, which provides an expansive toolkit to interact with the data you retrieve. Here you’ll find tips and ideas for using the data stream to enhance and display the data you’re interested in.
This plugin enables you to go beyond simple web requests provided by the Web API plugin. Use cases for choosing the PowerShell plugin over Web API include:
- Making requests to third-party APIs that require the timeframe variable a format different to ISO 8601 or Unix, you can manipulate the start and end times of the timeframe so that it matches the expected format.
- Making calls to multiple third-party APIs and then combining the results.
$variable: A dictionary of the variables entered in the plugin configuration (see How to add a PowerShell data source). For example, to access the value of a variable entered there named foo, you must enter$variable['foo']or$variable.foo.$timeframe: An object containing properties about the dashboard timeframe in force, for example:}Tiles can be configured to:
- Use dashboard timeframe (default). For these tiles the data shown will change when the user changes the dashboard timeframe.
- Use a fixed timeframe from the options available. These tiles show a clock icon and hovering shows the fixed timeframe configured. The data will not change when the dashboard timeframe is changed.
If the dashboard timeframe is unavailable, such as when all the tiles on that dashboard are using a fixed timeframe, then the button is disabled. Likewise, if a specific timeframe is unsupported then it is disabled in the timeframe picker.
Set a default dashboard timeframe
To set the default dashboard timeframe, click the pin icon
$targetNodes: The objects from the knowledge graph in scope. Intended for advanced users.
Returning data to tiles
Typically, PowerShell scripts supplied to this plugin are used to call third-party APIs to retrieve data, which can then be enhanced for visualization.
If the data returned from the script is a primitive scalar, it is only suitable for use with the Scalar visualization.
Otherwise, if the data is structured, it can always be used with the table visualization. Other visualizations will also be suitable if appropriate columns (object properties) are present.
