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 Script Authentication Using Tokens 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.

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

Downloading Example Scripts

Example Scripts:

• Script Authentication Using Tokens