Delinea Documentation - Secret Server - current

Secret Server Software Development Kit for DevOps


This Secret Server Software Development Kit (SDK) for DevOps tool, or simply SDK, was created for securing and streamlining DevOps processes with regard to Secret Server. The SDK for DevOps tool allows you to more efficiently engage Secret Server 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 Secret Server REST API. 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.

Note: You can download the current and legacy versions of the API on the Downloads for Secret Server Software Development Kit for DevOps page.

Note: The SDK can run on any version of .NET that supports .NET Standard 2.0 apps including .NET Core 2.0 plus, .NET Framework 4.6.1 plus, .NET 5 plus, and .NET 6 plus.

Note: See the Delinea SDK Integration Doc on GitHub for more information.

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:

Secret Server has user and application accounts. Both types can access Secret Server via the REST API. Application accounts are not counted for licensing purposes. Application account 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.

Note: Do not give an Application Account the Administrator Role or give it all of the Role permissions. It is recommended to only assign the minimum roles needed to complete the task, that means create a new Role with only the permissions it needs and only share the secrets needed.

Note: For REST API Client Generation (Advanced), please see REST API Client Generation with OpenAPI Swagger

Note: We have a Python SDK that is independent of the SDK .NET library. It allows a Python script to access secrets without requiring REST knowledge. It has access to a small subset of the REST API.

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

In summary, the SDK establishes secure access points so that power 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 the 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). Thus, once the client is initialized with the Secret Server and the rule name, that configuration is stored and encrypted on the client, ready for subsequent calls.

Out of the box, the SDK offers:

Note: We expect to expand the SDK's capabilities over time to allow even greater access to the REST API.

The SDK requires setup in two areas: Secret Server configuration and SDK installation on the DevOps system.

Required Roles and Permissions

Setup Procedure

Task 1: Configuring Secret Server

Configure Secret Server for communication with the SDK:

  1. Navigate to Admin > Configuration.

  2. Click the General tab.

  3. Click the Edit button.

  4. Click to select the Enable Webservices check box in the Application Settings section.

  5. Click the Save button.

  6. 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 > Users.

    2. Click the Create New button. The Edit User page appears:

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

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

    5. Click the Advanced link. The Advance section appears:

    6. Click to select the Application Account check box.

    7. Click the Save button. A confirmation popup appears.

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

  7. Create a new role:

    1. Go to Admin > Roles.

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

    3. Type the new role name in the Role Name text box.

    4. Assign the View Secret permission to that role. The permission appears in the Permissions Assigned text box. You can add additional permissions later as needed.

    5. Click the Save button. The new role appears in the Roles table.

  8. Enable SDK management:

    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:

    1. Click the Disabled toggle button to change it to Enabled.
  9. Set up a SDK client rule:

    1. Click the Client Onboarding tab.

    2. Click the + Rule link. A new rule appears:

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

    4. Type an IPV 4 address or address range (in CIDR notation) in the Details text box. 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.

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

    5. Click to select the application account you created earlier in the Assignment dropdown list. 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 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. Click to select the Require this generated onboarding key check box. Clients must provide a generated additional key string when authenticating. If not provided, Secret Server allow 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. The Show Key link appears.

    8. Click the Show Key link to save the generated onboarding key (something like TFyORLL1teQmD8OAMstqKGWkJGksFRtaelY0b2NnhsM=) for future use. It will not be visible again.

Note: If you cannot copy the key text after selecting it, you probably need to add the Secret Server Utilities extension for your browser. For now, just manually copy it.

Task 2: Installing the SDK Client

Note: This requires Secret Server version 10.4+ or Secret Server Cloud

Note: IWA is not supported by the SDK.

Note: The SDK can run on any version of .NET that supports .NET Standard 2.0 apps including .NET Core 2.0 plus, .NET Framework 4.6.1 plus, .NET 5 plus, and .NET 6 plus.

  1. Download the SDK for your platform.

  2. Unzip the SDK zip file you downloaded.

  3. To get the SDK Nuget packages, see our documentation on GitHub.

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

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

  6. To confirm the SDK client tool is installed and working, run the 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:

Run tss init --url <url> -r <rule> -k <key> using the parameters you recorded earlier for your Secret Server instance.

For example, if your parameters are:

Then you would run:

tss init --url https://myserver/SecretServer/ -r ProductionWebApp -k CNrQwRBscnq4qAZ6v3EIAcE27vQuLlz6KSpfRJHryyA=

Note: You can also start the SDK client in interactive mode (tss -i) and follow the prompts to run the init command.

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

Usage Examples

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

  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. Click the Accounts tab. A list of connected SDK clients SDK 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. Click the Client Onboarding tab to manage the onboarding rules.

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

    Note: 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 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


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:

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.


Important: Anytime you use a cached value, recent changes made to Secret Server may not be applied, including changes to the value itself, permissions, or other access control settings. Examine your organization's security policies and application requirements to determine the best cache settings to use.