Script Authentication Using Tokens

Overview

Manipulating the Secret Server API via scripts is very handy and powerful but also potentially dangerous, so it is critical to follow best practices to ensure robust security. This topic discusses these best practices. We recommend the Secret Server Software Development Kit for DevOps for all automated or machine-to-machine scripts. If not using the SDK, we strongly recommend creating an application account for script access and limiting permissions via both roles and the secrets themselves.

Best Practices

For security, it is critical that you:

• Do not use admin accounts.
• Use a least-privilege account, limiting role and secret access permissions.
• Never store passwords or tokens in plain text. Use secure credentials instead—see below for details.
• Use a least-privilage application account. These are restricted from logging in the UI.
• Never use domain admin credentials in an automated script.
• Create a specific service account with only the permissions needed to get the task done.
• Always expire tokens. To expire tokens, navigate to the Admin > Configuration > Application and enable Session Timeout for Webservices, setting the timeout to a short period, the default is 20 mins.

Authentication Methods

Scripts Run by Automated Processes

Recommended methods:

• Secret Server Software Development Kit for DevOps (SDK). The SDK is a great way to limit access to a specific client with encrypted credentials and IP restrictions. See Secret Server Software Development Kit for DevOps for more information.

• Integrated Windows Authentication (IWA).

Specific User Use Cases with Script Augmentation

Recommended methods:

• Get credentials with two-factor authentication (2FA). This is a secure way to prompt users for credentials for manually run scripts.

• Prompt with 2FA. This prompts the user for script credentials.

• IWA.

• API token from the UI with 2FA.

Example Credential-Access Scripts

Recommended Methods

Get-Credential with 2FA

$application = "<Secret Server URL>"

function Get-Token
{
    [CmdletBinding()]
    param(
        $credentials,
        [Switch] $UseTwoFactor
    )

    $creds = @{
        username = $credentials.UserName
        password = $credentials.GetNetworkCredential().Password
        grant_type = "password"
    };

    $headers = $null
    If ($UseTwoFactor) {
        $headers = @{
            "OTP" = (Read-Host -Prompt "Enter your OTP for 2FA: ")
        }
    }

    try
    {
        $response = Invoke-RestMethod "$application/oauth2/token" -Method Post -Body $creds -Headers $headers;
        $token = $response.access_token;
        return $token;
    }
    catch
    {
        $result = $_.Exception.Response.GetResponseStream();
        $reader = New-Object System.IO.StreamReader($result);
        $reader.BaseStream.Position = 0;
        $reader.DiscardBufferedData();
        $responseBody = $reader.ReadToEnd() | ConvertFrom-Json
        Write-Host "ERROR: $($responseBody.error)"
        return;
    }
}

$token = Get-Token -credentials (Get-Credential) -UseTwoFactor 

Prompting for Credentials with 2FA

$application = "<Secret Server URL>"

function Get-Token
{
    [CmdletBinding()]
    param(
        [Switch] $UseTwoFactor
    )

    $creds = @{
        username = Read-Host -Prompt "Enter your username: "
        password = Read-Host -Prompt "Enter your password: "
        grant_type = "password"
    };

    $headers = $null
    If ($UseTwoFactor) {
        $headers = @{
            "OTP" = (Read-Host -Prompt "Enter your OTP for 2FA: ")
        }
    }

    try
    {
        $response = Invoke-RestMethod "$application/oauth2/token" -Method Post -Body $creds -Headers $headers;
        $token = $response.access_token;
        return $token;
    }
    catch
    {
        $result = $_.Exception.Response.GetResponseStream();
        $reader = New-Object System.IO.StreamReader($result);
        $reader.BaseStream.Position = 0;
        $reader.DiscardBufferedData();
        $responseBody = $reader.ReadToEnd() | ConvertFrom-Json
        Write-Host "ERROR: $($responseBody.error)"
        return;
    }
}

$token = Get-Token -UseTwoFactor 

Integrated Windows Authentication

$api = "<Secret Server URL>/winauthwebservices/api/v1"
$endpoint = "$api/secrets/3844"
$secret = Invoke-RestMethod $endpoint -UseDefaultCredentials

Deprecated Method

API token from the UI with 2FA

$application = "<Secret Server URL>"
$token = "<TOKEN>"

$headers = @{}
$headers.Add("Authorization", "Bearer $token")

1. From the Secret Server REST API page of your instance, select one of the following token authentication methods for user scripts:

   • Bearer token authentication

   • Token authentication

   • Windows integrated Authentication

2. Generate a token from your user preferences in Secret Server. Use this as a bearer token in user scripts.

3. Click the user-initials button on the top right of the page and select User Preferences. The User Preferences page appears:

   

4. In the API Token section, click on Generate API Token and Copy to Clipboard.

5. Paste the token text into the script.

Downloading Example Scripts

Example Scripts:

• PowerShell Examples