Using the Verify Privilege Vault SDK for DevOps

Overview

This Verify Privilege Vault Software Development Kit (SDK) for DevOps tool, or simply SDK, was created for securing and streamlining DevOps processes with regard to Verify Privilege Vault. The SDK for DevOps tool allows you to more efficiently engage Verify Privilege Vault via a Command Line Interface (CLI) without compromising security. It allows you to securely retrieve credentials from and track access to a secure vault.

The SDK uses the REST API Reference Download. The SDK is a .NET library (available via a NuGet package), which you can use in a custom application. The SDK .NET library exposes a limited subset of the REST API.

There is also a .NET Core CLI SDK Client that uses the SDK .NET library. The SDK Client was created to allow customers to write automation scripts to access secrets without having to write code to directly access the REST API.

The .NET SDK library and the .NET Core CLI client both:

• Automatically store the credentials and remote server in an encrypted file used to acquire an OAUTH token. The token is then used to make subsequent API calls. OAUTH tokens have an expiration time, which is configurable in the UI on the configuration page via the Session Timeout for Webservices value.
• Get the contents of a secret.
• Provide client-side caching (SDK client caching).

Verify Privilege Vault has user and application accounts. Both types can access Verify Privilege Vault via the REST API. Application accounts are not counted for licensing purposes. Application accounts can only access Verify Privilege Vault via the REST API. Both account types never expire. Verify Privilege Vault provides security for automated clients. SDK rules manage permissions. Client IDs are created when SecretServerClient.Configure() or tss init is called. The client ID is used to reference SDK client instances.

How it Works

The SDK is a console application written in .NET Core that wires up its own credentials based on the machine it is installed on. Those credentials, called DevOps Users, do not have any rights in Verify Privilege Vault but can be assigned to other Verify Privilege Vault users or application user accounts, mimicking permissions to access secrets.

This removes the widespread DevOps issues with hard coding credentials into scripts and configuration files. Instead, the target system is registered via IP address that is white listed, which provides REST authentication without entering user credentials. You can use the SDK to retrieve a REST user token for our REST API, or you can use the SDK to perform direct queries on Verify Privilege Vault.

In summary, the SDK establishes secure access points so that power users can employ the Verify Privilege Vault API directly from the CLI, without wasting time entering privileged account passwords.

Configuration Overview

Verify Privilege Vault exposes a REST API interface that is used by the SDK client. When the SDK sends a REST request, Verify Privilege Vault determines where the request came from (via IP address) and what permissions it should be granted (via a rule set in Verify Privilege Vault). Hence, once the client is initialized with Verify Privilege Vault and the rule name, that configuration is stored and encrypted on the client machine, ready for subsequent calls.

Out of the box, the SDK offers:

• Token retrieval
• Secret retrieval
• Secret field retrieval

The SDK requires setup in two areas: Verify Privilege Vault configuration and SDK installation on the DevOps system.

Required Roles and Permissions

• Administer Configuration: Allows a user to enable SDK functionality in Verify Privilege Vault, that is, to enable webservices and enable the SDK itself.
• Administer Create Users: Allows a user to access the Admin > SDK Client Management page in Verify Privilege Vault.
• Administer scripts: This permission is required to be able to create an SDK Client Onboarding rule. It allows a user to view and edit PowerShell, SQL, and SSH scripts on the Scripts Administration page.
• Administer Users: Allows a user to use the SDK to retrieve account credentials on client machines. Alternatively, you can be the owner of the application account used by the SDK.
• View Launcher Password: Allows a user to unmask the password on the view screen of secrets with a launcher. Typically, this includes Web Passwords, Active Directory accounts, Local Windows accounts, and Linux accounts.

Setup Procedure

Task 1: Configuring Verify Privilege Vault

Configure Verify Privilege Vault for communication with the SDK:

1. Navigate to Admin > Configuration.

2. Under the General tab, click the Edit button at the bottom of the screen.

3. Select the Enable Webservices check box in the Application Settings section.

4. Click the Save button.

5. Select and setup any application accounts that you want for use by SDK clients. Make sure these application accounts have appropriate permissions to access any secrets or execute any operations the client host needs to perform. To create a new account with the needed permissions:

   1. Go to Admin > User Management.

   2. Click the Create User button. The Add User page appears:

      

   3. Type the account name in the User Name and Display Name text boxes.

   4. Type a password in the New Password and Confirm Password text boxes. Record the password for future use.

   5. Select the Application Account check box.

   6. Click the Add User button.

   7. Click the OK button. The View User page appears:

   

6. Create a new role:

   1. Go to Admin > Roles.

   2. Click the Create Role button. The Create Role page appears:

      

   3. Type the new role name in the Name text box and select Create Role. The View Role page appears.

   4. Assign the View Secret permission to that role:

      1. Select the Permissions tab.

      2. Find the View Secret role with the search box, select it and click Save.

         1. The permission appears in the Permissions Assigned list. You can add additional permissions later as needed.

      

   5. The new role now can be found in the Roles list:

      

7. Assign the Role to the User you created:

   1. Access the role you just created, it has no users assigned:

      

   2. Select Edit and in the drop-down showing Assigned change the value to All:

      

   3. Search for the user you previously created, toggle the domains as needed to show all users:

      

   4. Add the user and click Save:

      

8. Enable SDK management:

   1. Go Admin > SDK Client Management. The SDK Client Management page appears. Under the Configuration tab, select Edit, check the Enabled. check box, and click Save.

      

9. Assign the View Launcher Password role permission to the application user previously created if this account requires access to secrets with launchers associated to them.

10. Set up an SDK client rule:

    1. Under the Client Onboarding tab, click Create Rule:

       

    2. A new rule page appears:

       

    3. Type a short, unique name in the Name text box. Clients must provide a valid rule name when connecting. For example: ProductionWebApp.

    4. Type an IPv4 address or address range (in CIDR notation) in the Allowed IP Ranges (CIDR) text box. Verify Privilege Vault will only allow clients to use this rule if they connect from a valid IP address. If not provided, Verify Privilege Vault will not enforce IP address restrictions on this rule. We strongly recommend using this feature.

       There is a 250-character limit, so you can only add a few dozen IP addresses unless you use CIDR notation.

    5. Select the application account you created earlier in the User drop-down list. Clients are granted the same permissions as this account within Verify Privilege Vault. If not provided, an account will be automatically created for clients, but will have no default permissions. You must use an application account (the one you created) for a rule. Application accounts are restricted from logging into the system through the normal user interface and do not count towards your license quota.

    6. Select the Require Onboarding Key check box. Clients must provide a generated additional key string when authenticating. If not provided, Verify Privilege Vault allows any client to use the rule if its IP address is within the specified range. We strongly recommend using this feature.

    7. Click the Save button.

    8. Return to Admin > SDK Client Management, and under the Client Onboarding tab select the rule that you have just created, the rule details will expand to the right.

    9. Select Show Key, then copy and save the generated onboarding key value, e.g. TFyORLL1teQmD8OAMstqKGWkJGksFRtaelY0b2NnhsM=, for future use.

    

Task 2: Installing the SDK Client

1. Access Downloads for the Verify Privilege Vault SDK for DevOps and choose the right kit for your platform.

2. Unzip the SDK zip file you downloaded.

   1. Optionally, to get the SDK NuGet packages, see our documentation on GitHub.

3. On non-Windows systems, you must make the tss program executable by running chmod u+x tss.

4. On Linux systems, you must install libunwind as follows:

   • On Red Hat or Centos, run sudo yum install libunwind libicu
   • On Ubuntu, run sudo apt-get install libunwind-dev

5. To confirm the SDK client tool is installed and working, run help:

   • On Windows, run tss --help
   • On non-Windows systems, run ./tss --help

Task 3: Connecting to Verify Privilege Vault

Before the client can retrieve data from Verify Privilege Vault, it must be initialized to connect to the Verify Privilege Vault instance. This is a one-time operation on the client machine.

To initialize your connection:

1. Run tss init --url <url> -r <rule> -k <key> using the parameters you recorded earlier for your Verify Privilege Vault instance.

   1. Example parameters:

      1. Verify Privilege Vault is hosted at https://myserver/SecretServer/
      2. You created a rule named ProductionWebApp.
      3. Your onboarding key is CNrQwRBscnq4qAZ6v3EIAcE27vQuLlz6KSpfRJHryyA=
   2. Then you would run something similar to this example: tss init --url https://myserver/SecretServer/ -r ProductionWebApp -k CNrQwRBscnq4qAZ6v3EIAcE27vQuLlz6KSpfRJHryyA=

Verify Privilege Vault will validate that the client-provided information is correct and that the IP address matches the configured restrictions. If successful, the client and server have established the connection, and the client can now be used to retrieve Verify Privilege Vault data.

Usage Examples

• Retrieving a secret by ID (returns a JSON structure describing the entire secret record): tss secret -s 4
• Retrieving all secret field values for a secret by ID: tss secret -s 4 -ad
• Retrieving only the value of a particular secret field by secret ID: tss secret -s 4 -f password
• Writing a secret field value to a file: tss secret -s 4 -f password -o passwordfile.txt
• Retrieving an access token for use in other REST API requests: tss token

• Retrieving a secret by ID when that Secret requires a comment: tss secret -s 4 -c comment

The SDK client also includes an interactive mode (tss -i) that allows you to input multiple commands into a series of prompts. To exit interactive mode, run the exit command.

SDK Client Management

To view and manage a list of connected SDK clients from within Verify Privilege Vault:

1. Go Admin > See All. The admin panel appears.

2. Type SDK in the Search text box and select SDK Client Management. The SDK Client Management page appears.

3. Select the Accounts tab. A list of connected SDK clients appears. You can remove or rename them. You can use the Enable/Disable button at the top of the page to disable and re-enable all SDK client activity.

4. Select the Client Onboarding tab to manage the onboarding rules.

5. Select the Audit tab. A list of SDK client activity appears.

   If you remove a connected client, it may be able to reconnect unless you alter or remove the rule that it used. You can use the button above the grid to disable and re-enable all SDK client activity.

6. To remove the Verify Privilege Vault connection from a client machine, run the tss remove command. This deletes the connection, and the client can no longer retrieve Verify Privilege Vault data without being re-initialized.

SDK Client Caching

Overview

To increase performance and reliability, you can configure the SDK client to cache values retrieved from Verify Privilege Vault on the client machine. Cached values are stored encrypted on disk. You can configure client caching in one of four ways:

• Never (0): With this default setting, the client never caches Verify Privilege Vault data. All data requests result in a query directly against the Verify Privilege Vault instance. If the instance is unavailable, the requests fail.
• Server Then Cache (1): With this setting, the client first attempts to retrieve the value from the server. If the server is unavailable, it checks to see if the same value has been previously fetched within a given period, and if so, it will return the cached value. Use this setting to guard against losing the connection to Verify Privilege Vault.
• Cache Then Server (2): With this setting, the client first checks to see if the same value has been previously fetched within a given period. If so, it returns the value without consulting the server. If not, it fetches, caches, and returns the value from the server. Use this setting for increased performance by reducing requests sent to Verify Privilege Vault.
• Cache Then Server Fallback on Expired Cache (3): This strategy operates similarly to "Cache Then Server," but if the server is unavailable and an expired value exists in the cache, the client returns that value as a last resort. Use this strategy for increased performance and reliability.

All these cache strategies have a configurable age, in minutes, after which the value is considered expired and not used (except in Cache Then Server Fallback mode). Cache settings are set using the client application, see the examples below for more details.

Examples

• Turn off caching: tss cache --strategy 0
• Turn on the Cache Then Server setting with a cache age of five minutes: tss cache --strategy 2 --age 5
• Immediately clear all cached values: tss cache --bust
• Show the current cache settings: tss cache --current