Using the Secret Server SDK for DevOps

Overview

The Secret Server Software Development Kit for DevOps tool, was created for securing and streamlining DevOps processes in regard to Secret Server. The SDK for DevOps tool allows you to efficiently engage Secret Server via a Command Line Interface (CLI) without compromising security. It allows for secure retrieval of credentials from, as well as tracking 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).

Secret Server has user and application accounts. Both types of accounts can access Secret Server via the REST API. Application accounts are not counted for licensing purposes. Application accounts can only access Secret Server via the REST API. Both account types never expire. Secret Server 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 Secret Server but can be assigned to other Secret Server 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 which is whitelisted, providing 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 Secret Server.

The SDK establishes secure access points so that PowerShell users can employ the Secret Server API directly from the CLI, without wasting time entering privileged account passwords.

Configuration Overview

Secret Server exposes a REST API interface that is used by the SDK client. When the SDK sends a REST request, Secret Server determines where the request came from (via IP address) and what permissions it should be granted (via a rule set in Secret Server). Once the client is initialized with Secret Server and the rule name, this 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: Secret Server configuration and SDK installation on the DevOps system.

Required Roles and Permissions

• Administer Configuration: Allows a user to enable SDK functionality in Secret Server, that is, to enable webservices and the SDK itself.
• Administer Create Users: Allows a user to access the Settings > All settings > Tools and integrations > SDK client page in Secret Server.
• 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 operate 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 accounts, Active Directory accounts, Local Windows accounts, and Linux accounts.

Setup Procedure

Task 1: Configuring Secret Server

Configure Secret Server for communication with the SDK

1. Search for "SDK" in universal search bar.

2. Select the SDK Client result.

3. Under the Configuration tab of the SDK Client Management page, click Edit to enable SDK Configuration and then click Save:

4. Go to Settings > All settings, and under the Configuration > General categories select Application.

5. On the Application page click Edit and select the Enable Webservices check box:

6. Leave the default settings for webservices and click the Save button that appears at the bottom of the screen.

Select or Setup Application Accounts

Select or 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 application account with the needed permissions:

1. Go to Access > Users, the User Management page appears.

2. Click the Create User button. The Add User popup appears.

3. Fill in the following fields:

   1. Username: the account name.

   2. Display Name: the searchable name for the account of your choice, can the same as the username.

   3. Domain: leave it as the default Local value.

   4. New Password and Confirm Password: a password of your choice.

   5. Email: type in an email, this is optional.

   6. Select the Application Account checkbox.

   7. Multifactor authentication: leave as is with the default <None> option.

   8. Make sure the Enabled checkbox is selected.

4. Click the Add User button.

5. Create a new role:

   1. Go to Access > Roles.

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

      

   3. Type in a Name and make sure the Enabled checkbox is selected.

   4. Click Create Role. The page for the new role appears.

   5. Assign the View Secret permission to this role:

      1. Select the Permissions tab.

      2. Click Edit, change the Scope selection to All and search for the View Secret permission with the search box.

      3. Select it and click Save.

6. Assign the role you just created to the application user created above:

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

      

   2. Select Edit, the Scope option appears. Change its value to All.

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

   4. Add the user by selecting the checkbox by its name and clicking Save:

7. 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. Use the same steps for assigning this permission as described for View Secret in the previous steps:

Set up an SDK client rule

1. Search for SDK in the top search bar, and select SDK client. This will lead you to the SDK Client Management page.

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

   

3. The New Rule page appears:

   

4. Type in a relevant name in the Name field without any spaces. For example: ProductionWebApp.

5. Optionally, in the Allowed IP Ranges (CIDR) field, leave it blank or type in an IPV4 address, or use CIDR notation.

   Secret Server will only allow clients to use this rule if they connect from a valid IP address. If not provided, Secret Server 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.
   IPv6 addresses are not supported.

6. For the User drop-down list leave the default All value selected.

7. In the search box next to the dropdown, look for the application user you just created and select it.

   Clients are granted the same permissions as this account within Secret Server. 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 the rule. Application accounts are restricted from logging into the system through the normal user interface and do not count towards your license quota.

8. Select the Require Onboarding Key checkbox.

   Clients must provide a generated additional key string when authenticating. If not provided, Secret Server allows any client to use the rule if its IP address is within the specified range. We strongly recommend using this feature.

9. Click the Save button:

   

   The page for the new rule you just created will load automatically.

10. Return to the SDK Client Management page, and under the Client Onboarding tab click on the rule that you have just created, the rule details will expand to the right of the screen.

11. Select Show Key, then copy and save the generated onboarding key value, e.g. U9Ue9PsMYknfoskQvd/0BYMTaTTx2vtWbB/tHI3exDE=, for future use:

Task 2: Installing the SDK Client

1. Access Downloads for the Secret Server SDK for DevOps and choose the right kit for your platform. We recommend always using the latest version available.

2. Extract/unzip the SDK zip file you downloaded.

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

3. For Linux systems, you must make the tss program executable by running chmod u+x tss.

4. On Linux systems, you must install libunwind:

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

5. For Windows, open a console window by clicking the Start menu and searching for cmd.

6. Inside the Command Prompt type cd [location of the downloaded zip file]/[location of extraction folder].

   E.g. cd downloads/secretserver-sdk-1.5.9-win-x64

7. 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 Secret Server

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

To initialize your connection:

1. Click the Start menu and search for cmd.

2. Inside the Command Prompt type cd [location of the downloaded zip file]\[location of extraction folder].

   E.g. cd downloads\secretserver-sdk-1.5.9-win-x64

3. Run tss -i to use interactive mode:

   

4. Type init and press enter.

5. When prompted for the URL, copy and paste the URL of your Secret Server instance, and press enter.

   E.g. https://[secret server url].

6. You are then prompted to specify the rule you created previously in the SDK Client Management page. Type in the rule name and press enter. E.g ProductionWebApp.

7. You are now asked if you wish to specify an onboarding key. Enter yes.

8. The prompt to specify the key appears. The key was copied after you created the rule. E.g.: CNrQwRBscnq4qAZ6v3EIAcE27vQuLlz6KSpfRJHryyA=. You need to paste it in the Command Prompt window and press enter:

   

9. The "Your SDK Client account registration is complete" message appears. Keep this window open, do not exit.

10. Return to your Secret Server instance and to the SDK Client Management page.

11. In the Accounts tab, click on the account that now appears after performing SDK initialization. The side menu appears with information about the account.

12. Click View details:

    

13. Inside the SDK account page, click Edit.

14. Search for the application account/user you previously created in Task 1, e.g:

    

15. Add the application account username in the box for the User search field, it will return a list of users. Pick the one you need and click Save.

    If this is not done the SDK Client will return this error: invalid_client.

16. Return to the Command Prompt window you kept open. You will now enter the command to view your secret ID tss secret -s [secret id]:

    

17. The prompt to specify a field appears, enter no.

18. The Secret will successfully display in the tss application.

Secret Server verifies the client’s credentials and IP address restriction (if specified). Once validated, the client and server establish a connection allowing the client to retrieve data from Secret Server.

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 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 Secret Server:

1. Type "SDK" in the main search box at the top of your screen in Secret Serverand select SDK client from the results. The SDK Client Management page appears.

2. In the Accounts tab a list of connected SDK clients appears for all users if available. You can remove or rename them. You can also filter clients by User.

3. Select the Client Onboarding tab to create and manage client onboarding rules.

4. Select the Configuration tab to disable or enable all SDK client activity.

5. Select the Audit tab to see date and time-stamped SDK client activity concerning onboarding rules and client secrets.

6. To remove the Secret Server connection from a client machine, run the tss remove command. This deletes the connection, and the client can no longer retrieve Secret Server 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 Secret Server 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 Secret Server data. All data requests result in a query directly against the Secret Server 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 connection to Secret Server.
• 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 Secret Server.
• 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