A better SDK for Delinea Secret Server.
This is an SDK and CLI for interacting with Delinea Secret Server. The CLI uses Typer, and the SDK uses httpx. Both use Pydantic for data serialization from the Delinea APIs.
To install, ensure Python 3.8+ is installed and run:
pip install dss-sdkor
pip install --user dss-sdkdepending on available permissions.
This small package contains two-fold purpose. The first is a command line tool you can use to interact with your Delinea
Secret Server. This is done via the dss tool in your terminal. The second purpose is for those wanting to perform a
bit more automation or complicated tasks with Delinea SS. This is done via import dss in your Python code.
After installation, the tool should immediately be available in your terminal. If not, you either need to close your
terminal and re-open, or ensure your python Scripts path is in your PATH.
Running dss --help gives you the following:
Usage: dss [OPTIONS] COMMAND [ARGS]...
Delinea Secret Server CLI.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * --server TEXT The FQDN of your Delinea Secret Server. [env var: DELINEA_SERVER] [default: None] [required] │
│ --client-id TEXT The client ID registered with your Delinea server. [env var: DELINEA_CLIENT_ID] [default: None] │
│ --client-secret TEXT The client secret for the specified client ID registered with your Delinea server. [env var: DELINEA_CLIENT_SECRET] [default: None] │
│ --windows-credential TEXT The name of a Windows Credential containing the Client ID and Client Secret [env var: DELINEA_WINDOWS_CREDENTIAL] [default: None] │
│ --version │
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ get-secret Gets a secret. │
│ register-client Registers a new client with your server. │
│ search-secrets Search available secrets using various parameters. │
│ store-windows-credential Stores Client ID and Client Secret in Windows Credential Manager. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯The --server option is required, or you can specify an environment variable called DELINEA_SERVER that is the name
of your Delinea instance. Let's assume it's test.secretservercloud.com. You can either use it like:
dss --server test.secretservercloud.comor you can export the environment variable:
# Mac / Linux
export DELINEA_SERVER='test.secretservercloud.com'# Windows
$env:DELINEA_SERVER='test.secretservercloud.com'If you export the environment variable, you do not need to provide the --server option in the command line.
When using these options, they're both required to be set. You can acquire a Client ID and Secret using the
register-client command. Just like with --server, you can specify the options before
the command, or export the environment variables:
dss --client-id test-id --client-secret some-test-super-secretor you can export the environment variable:
# Mac / Linux
export DELINEA_CLIENT_ID='test-id'
export DELINEA_CLIENT_SECRET='some-test-super-secret'# Windows
$env:DELINEA_CLIENT_ID='test-id'
$env:DELINEA_CLIENT_SECRET='some-test-super-secret'This is what the CLI will use to acquire an OAuth2 token from your Delinea instance and subsequently use the token to auth the API calls.
NOTE: This will ONLY work on a Windows machine.
When providing this option, you don't need to provide the Client ID or Client Secret via the command line or environment
variables, as it will access them via a Windows Credential. You can store your credentials in Windows Credential Manager
using the store-windows-credential command.
The commands are how you interact with the Delinea Secret Server from the CLI.
Usage: dss register-client [OPTIONS]
Registers a new client with your server.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * --service-account TEXT [default: None] [required] │
│ * --onboarding-key TEXT [default: None] [required] │
│ --description TEXT [default: Delinea Python SDK] │
│ --store-in-windows Store the registered client ID and secret as Windows credentials. │
│ --output-format [table|json|clipboard] [default: clipboard] │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯You need to get your service account and onboarding key from your security team or create them in Delinea, if you have access. Then you can use them to create a Client ID and Client Secret via:
dss register-client --service-account myServiceAccount --onboarding-key 1234567890abcdefgYou can specify a --description which will show up in Delinea as a registered client. It's Delinea Python SDK by
default. If you specify the --store-in-windows boolean flag, it will store it as a Windows Credential under the name
dss-cli-client.
By default, all secrets are exported to your clipboard and are not printed in the console. You can change this behavior
by specifying and --output-format of json for a JSON output or table to print them in a pretty table.
Usage: dss store-windows-credential [OPTIONS]
Stores Client ID and Client Secret in Windows Credential Manager.
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * --client-id TEXT The client ID registered with your Delinea server. [default: None] [required] │
│ * --client-secret TEXT The client secret for the specified client ID registered with your Delinea server. [default: None] [required] │
│ --name TEXT The name to use in Windows credentials. [default: dss-cli-client] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯This command can be used to store your Client ID and Client Secret in Windows Credential Manager via:
dss store-windows-credential --client-id test-id --client-secret some-test-super-secretYou can also change the name by using the --name option, like: --name MyDelineaCreds. Just be sure to provide that
name when specifying --windows-credential or DELINEA_WINDOWS_CREDENTIAL.
You could also use it to store any credential in the Windows Credential Manager, just remember that the --client-id is
the username and --client-secret is the password.
Usage: dss search-secrets [OPTIONS]
Search available secrets using various parameters.
╭─ Options ──────────────────────────────────────────────────────────╮
│ --recent │
│ --search-text TEXT [default: None] │
│ --folder-id INTEGER [default: None] │
│ --secret-template-ids INTEGER [default: None] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────╯You can specify no other options, and it will output a table of all the secrets to which the service account has access.
However, you can provide the --recent boolean flag to search only through the recently used secrets, the --folder-id
to search for secrets only in that folder, --secret-template-ids to search only for secrets that use a specific
template (you can specify it multiple times for multiple template IDs), or --search-text to look for secrets that
contain text in various places (name, attribute, slug, etc.).
Usage: dss get-secret [OPTIONS] SECRET_ID
Gets a secret.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * secret_id INTEGER [default: None] [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --include-username Include the username in the output (Does not copy username to clipboard). │
│ --output-format [table|json|clipboard] Output as a table, JSON, or copy to clipboard. [default: clipboard] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯This is self-explanatory. Provide the SECRET_ID to get that secret. You can add the --include-username boolean flag
to have it print out the username tied to the secret, otherwise it just gets the "password" value. You can specify the
output here, as well, just like in the register-client command.
For those that need to do complex logic, or automation, the SDK can provide the same means as the CLI, but in Python classes.
from dss_sdk.server import SecretServerClient
from dss_sdk.models import SearchSecretsParams
search_text = "Some Text"
username = "my-user"
ss = SecretServerClient()
params = SearchSecretsParams(search_text=search_text)
secrets = ss.search_secrets(params=params)
for secret in secrets.records:
print(secret.name, secret.secret_id)from dss_sdk.server import SecretServerClient
secret_id = 12345
ss = SecretServerClient()
secret = ss.get_secret(secret_id=secret_id)
# Do something with the secret
...- Create tests
- For SDK
- And CLI
- Build
Asyncclient - Implement
set_secret()- For SDK
- And CLI
- Support
passwordgrant type - ?
If you'd like to contribute, please for the repo and create a pull request!