Configuring Event-Driven Refresh in Secret Server

This topic describes how to configure Secret Server so that an Event Pipeline notifies Delinea Credentials Cache whenever a secret password changes. For the concept and the end-to-end flow, see Event-Driven Secret Refresh. Before you begin, complete the event-driven refresh requirements in Prerequisites, including enabling Event Pipelines: Allow Confidential Secret Fields to be used in Scripts.

Complete the following steps:

The pipeline task calls the POST /api/secretchanged endpoint of the Credentials Cache API. For the request format and expected response, see API Reference.

Step 1: Create an Application Account in Secret Server

The Delinea Credentials Cache integration requires an application account to authenticate with Secret Server. If you do not have an application account, create one. For more information, see Managing Local Accounts in the Secret Server documentation.

The application account's role in Secret Server must have the following permissions:

  • Administer Secret Server Pipelines - Required to create and manage Event Pipeline policies.

  • Administer Secret Server Scripts - Required to create and manage PowerShell scripts.

  • View Secret - Required for the Credentials Cache application to retrieve secrets.

To create a role with the required permissions and assign it to the application account:

  1. In Secret Server, navigate to Access > Roles.

  2. Select Create role.

  3. In the Create role dialog, provide a name and an optional description for the new role, and select Save.

  4. Go to the Permissions tab for the role.

  5. Select Edit and in the Scope dropdown list, select All.

  6. Search for the Administer Secret Server Pipelines permission by using the search box at the top.

  7. Select the checkbox next to the permission name and select Save.

  8. Repeat steps 6–7 to add the following permissions to the role:

    • Administer Secret Server Scripts

    • View Secret

    The Permissions tab shows the permissions added to the role.

  9. Assign the role to the application account:

    1. Navigate to Access > Users.

    2. On the User management page, search for and select the application account.

    3. On the user page, go to the Roles tab and select Edit.

    4. In the window that appears below, search for the role that you created and select the checkbox next to the role name.

    5. Select Save.

Step 2: Create a Secret in Secret Server

Create a secret that holds the values the pipeline script needs: the Secret Server URL, the application account credentials, and the Credentials Cache URL. You must also grant the application account the View permission for the secret.

To create the secret:

  1. In Secret Server, choose the folder to store the secret or create a folder for the secret.

    Make sure that the application account in Secret Server that you use for this integration has the View permission for the folder. If there are any folders above the folder, make sure that the application account also has the View permission for each of those parent folders. For information about creating folders and folder permissions, see Folders in the Secret Server documentation.

  2. On the Create New Secret page, select the template from which to create the secret.

    Create a custom template with the following fields, which the Script Args in Step 5 reference: URL (Secret Server URL), USERNAME and PASSWORD (the application account), CREDCACHEURL (the Credentials Cache base URL, for example https://your-host/DelineaCredCache), and DOMAIN (optional).

  3. Enter the values for each field and save the secret.

  4. Grant the application account the View permission for the secret:

    1. Go to the Sharing tab of the secret's page.

    2. Select Edit in the upper-right corner.

    3. Clear Inherit permissions.

    4. Search for the application account by using the search box at the top.

    5. Select the checkbox to the left of the application account name and then select View in the dropdown list under Secret Permissions.

    6. Select Save.

Step 3: Create a PowerShell Script in Secret Server

The script accepts the Secret ID as its first argument, obtains a Bearer token from the Delinea Credentials Cache /api/token endpoint, calls the /api/secretchanged endpoint, and logs the request and response for monitoring.

  1. In Secret Server, navigate to Settings.

  2. Select Scripts: PowerShell, SQL, SSH.

  3. Select Create script.

  4. Complete the script details:

    • Name: Name of the script.

    • Description: Optional description of the script.

    • Script Type: PowerShell

    • Category: Password Changing

    • Use PowerShell Core: Clear this checkbox.

    • Script: Paste the following PowerShell script into the script editor.

    The script contains the line [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }, which disables TLS certificate validation for every HTTPS call the script makes. This is acceptable only in a development or test environment with self-signed certificates. In production, remove that line (and, if not required, the SecurityProtocol line) and make sure that the Distributed Engine host trusts the certificate presented by the Credentials Cache.

    Copy 
    $ItemId = $Args[0]
      # ===============================
    # CONFIGURATION
    # ===============================
    $BaseUrl    = $Args[1]
    $Username   = $Args[2]
    $Password   = $Args[3]
    $ApiBaseURI = $Args[4]
    $Domain     = $Args[5]
    # ===============================
    # TLS + CERT FIX (DEV ONLY)
    # ===============================
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }
    # ===============================
    # STEP 1: GET JWT TOKEN
    # ===============================
    $TokenUrl = "$ApiBaseURI/api/token"
    $TokenBody = @{
        Username = $Username
        Password = $Password
        BaseUrl  = $BaseUrl
        Domain   = $Domain
    }
    try {
        Write-Host "Requesting JWT token..."
        $TokenResponse = Invoke-RestMethod `
            -Method Post `
            -Uri $TokenUrl `
            -ContentType "application/x-www-form-urlencoded" `
            -Body $TokenBody `
            -ErrorAction Stop
        $AccessToken = $TokenResponse.token
        if ([string]::IsNullOrWhiteSpace($AccessToken)) {
            throw "JWT token missing in response."
        }
        Write-Host "JWT token retrieved successfully."
    }
    catch {
        Write-Error "❌ Token request failed: $($_.Exception.Message)"
        exit 1
    }
    # ===============================
    # STEP 2: CALL SECRET CHANGED API
    # ===============================
    $SecretChangedUrl = "$ApiBaseURI/api/secretchanged"
    $Headers = @{
        Authorization = "Bearer $AccessToken"
        "Content-Type" = "application/json"
    }
    $Body = @{
        secretId = "$ItemId"
    } | ConvertTo-Json
    try {
        Write-Host "Calling SecretChanged API..."
        Invoke-RestMethod `
            -Method Post `
            -Uri $SecretChangedUrl `
            -Headers $Headers `
            -Body $Body `
            -ErrorAction Stop
        Write-Host "✅ Secret cached successfully."

    }
    catch {
        Write-Error "❌ SecretChanged API failed."
        Write-Error $_.Exception.Message
    }

  5. Select Save to store the PowerShell script.

Step 4: Create an Event Pipeline Policy

  1. In Secret Server, navigate to Settings.

  2. Select Event pipeline policy.

  3. Select Add policy.

  4. In the Add policy window, type the name of your policy and select Secret as the policy type.

  5. Select Create to create the event policy.

Step 5: Configure a Pipeline Task

To configure the pipeline task:

  1. Select the pipeline policy you created.

  2. Open the pipeline and select Trigger.

  3. From Add Secret Triggers, select Secret Password Change.

  4. (Optional) Add secret filters if you want to trigger the pipeline only for specific secrets or folders. Only secrets that match the policy are refreshed in the cache.

  5. Select Tasks and from Add Secret tasks, select Run script.

  6. In the Task settings dialog, provide the following information:

    • Script: Select the name of the PowerShell script you created in Step 3.

    • Use site run as secret: Select this checkbox.

    • Script Args: Enter $ItemId $[ADD:1]$URL $[ADD:1]$USERNAME $[ADD:1]$PASSWORD $[ADD:1]$CREDCACHEURL $[ADD:1]$DOMAIN.

      $ItemId contains the Secret ID passed to the script when the pipeline runs. The $[ADD:1] tokens read fields from Additional secret 1, the secret you created in Step 2.

      The arguments map to the script's input parameters as follows:

      • $ItemId — Secret ID (automatically passed by Secret Server)

      • $URL — Secret Server URL

      • $USERNAME — Secret Server application account username

      • $PASSWORD — Password of the application account

      • $CREDCACHEURL — Credentials Cache base URL

      • $DOMAIN — Secret Server domain (optional)

    • Run Site: Select the Site whose Distributed Engine can reach the Credentials Cache.

    • Additional secret 1: Select the secret containing the application account credentials (created in Step 2).

  7. Select Save.

Secret Server automatically passes the Secret ID to the script during execution. If a pipeline task fails, subsequent tasks in the same pipeline do not run.

If Delinea Credentials Cache is deployed as several instances, add one Run script task per instance (each with an Additional secret whose CREDCACHEURL points at that instance), so that every instance receives the update trigger and refreshes its local cache.

Next Steps

Change a password on a secret covered by the policy and confirm that the pipeline succeeded and the cache was updated: Verifying the Deployment. If the pipeline fails or the cache is not refreshed, see Troubleshooting.