Grant File Mode (Optional)
Grant File Mode is an optional configuration that enables the MID Server to retrieve credentials using a secure local grant file instead of making a direct API call to Secret Server. This mode is particularly useful in highly restricted or secure environments where outbound network access is limited or disallowed.
Enable Grant File Mode
To enable Grant File Mode, you must run a PowerShell script on the MID Server that generates the required oauth2_grant.json file.
The PowerShell scripts required for Grant File Mode are not included in the plugin or setup utility. You must manually create or obtain them.
To use Grant File Mode, you must create or obtain one of the following Power Shell scripts:
-
refresh-oauth2.ps1 – uses direct REST API call to get a token
-
refresh-oauth2_useSDK.ps1 – uses the Delinea Secret Server SDK to get a token
These scripts are essential for generating the oauth2_grant.json file, which is used by the MID Server during credential resolution in Grant File Mode.
Option 1: Using refresh-oauth2.ps1
To enable Grant file mode using refresh-oauth2.ps1, use the following setup:
-
Run the following PowerShell command to create a secure password file:
-
Create a PowerShell script named refresh-oauth2.ps1 with the following script:
-
Create a run.bat file and add the following script inside it:
Copy-NoProfile -ExecutionPolicy Bypass -Command "C:\\Delinea\\refresh-oauth2.ps1 -Path C:\\ServiceNow\\prod\\agent\\oauth2_grant.json –SecretServerUrl
'https://enterprisevault.com/SecretServer' -User midapp -PasswordFile
'C:\\Delinea\\passfile.xml' -
Double-click the recently created run.bat file. This will securely create the oauth2_grant.json file used by the Delinea MID Server.
-
Copy and paste the path of the oauth2_grant.json file.
This is required when running Delinea Mid Server Setup Utility.
-
'replace-with-your-password' | ConvertTo-SecureString -AsPlainText -Force | Export-Clixml -Path C:\Delinea\passfile.XML
Replace the placeholder with your actual password. This file will be used by refresh-oauth2.ps1 to fetch tokens securely.
param(
[string]$SecretServerUrl,
[string]$User,
[string]$PasswordFile,
[string]$Path
)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$password = Import-Clixml -Path $PasswordFile
$plainTextPwd = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($password))
$body = @{
"grant_type" = "password"
"username" = $User
"password" = $plainTextPwd
}
$value = Invoke-RestMethod -Method POST -Uri "$SecretServerUrl/oauth2/token" -Body $body | Select-Object -Expandproperty access_token
Set-Content -Path $Path -Encoding Ascii -Force -Value $value -NoNewlineOption 2: Using refresh-oauth2_useSDK.ps1
To enable Grant file mode using refresh-oauth2_useSDK.ps1, use the following setup:
-
Create a refresh-oauth2_useSDK.ps1 file and copy the following script inside it:
Copy[cmdletbinding()]
param(
[string]\$Path,
[string]\$SdkPath
)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
if (Test-Path \$SdkPath) {
Set-Location \$SdkPath
} else {
throw "Unable to find SDK Path: \$SdkPath"}
if (Test-Path '.\\tss.exe') {
try {
\$value = .\\tss.exe token
} catch {
throw "Unable to obtain token: \$(\$_.Exception.Message)"}
}
Set-Content -Path \$Path -Encoding Ascii -Force -Value \$value -NoNewline -
Download secretserver-sdk-1.5.9-win-x64. The sdk client can be downloaded as follows:
-
Linux x64 (including RHEL 7 to 9)
-
Unzip the sdk file, open a Command Prompt and navigate to the directory where secretserver-sdk-1.x.x-win-x64 is located. Use the SDK to connect to Secret Server using the onboarding key.
-
The rule name and onboarding key will be required. Go here to see how to create the SDK client rule.
-
Create a run.bat file and add the following script inside it:
- Double-click the recently created run.bat file. This will securely create the oauth2_grant.json file used by the Delinea MID Server
-NoProfile -ExecutionPolicy Bypass -Command "C:\\Delinea\\refresh-oauth2_useSDK.ps1 -Path C:\\ServiceNow\\prod\\agent\\oauth2_grant.json -SdkPath C:\\Delinea\\secretserver-sdk-1.5.0-win-x64"passfile.XML —Stores the encrypted password securely .
Run.bat —Triggers the PowerShell script.
refresh-oauth2_useSDK.ps1— Fetches token using the SDK and outputs JSON token.
Running PowerShell Script
After running the MID Server Setup Utility, your MID Server requires a valid OAuth2 token to authenticate with Secret Server’s API. Tokens expire regularly, so you must automate their renewal using a Scheduled Task that runs a PowerShell script.
The recommended method for generating the grant file is using a Scheduled Task. A task can be used to run a PowerShell script that requests a token using:
-
The Secret Server REST API (oauth2/token endpoint),
or
-
The Secret Server Client SDK (tss.exe)
Save one of the scripts below to a desired location on the Agent server and configure a task to call each one. The frequency that each one will be triggered should be based on the Web services session timeout value for Secret Server (for example, set to 20 minutes and trigger the task every 19 minutes).
Using refresh-oauth2.ps1
To securely provide the username and password needed for the OAuth2 endpoint, create a password file with an encrypted password. This step is unique per MID Server and must be done individually.
Run this command to create the password file:
Issue this command to create the password file:
'replace with the password' \| ConvertTo-SecureString -AsPlainText -Force \|
Export-Clixml -Path c:\\Delinea\\passfile.XML`
refresh-oauth2.ps1
param(
[string]$SecretServerUrl,
[string]$User,
[string]$PasswordFile,
[string]$Path
)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
\$password = Import-Clixml -Path \$PasswordFile
\$plainTextPwd =
[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR(\$password))
\$body = @{
"grant_type" = "password""username" = $User
"password" = $plainTextPwd
}
$value = Invoke-RestMethod -Method POST -Uri "$SecretServerUrl/oauth2/token"-Body \$body | Select-Object -Expandproperty access_token
Set-Content -Path $Path -Encoding Ascii -Force -Value $value -NoNewline
Argument Task Example:
\-NoProfile -ExecutionPolicy Bypass -Command "C:\\Delinea\\refresh-oauth2.ps1\-Path C:\\ServiceNow\prod\agent\\oauth2_grant.json –SecretServerUrl
'https://enterprisevault.com/SecretServer' -User midapp -PasswordFile
'C:\\Delinea\\passfile.xml'"refresh-oauth2_useSDK.ps1
[cmdletbinding()]
param(
[string]\$Path,
[string]\$SdkPath
)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
if (Test-Path \$SdkPath) {
Set-Location \$SdkPath
} else {
throw "Unable to find SDK Path: \$SdkPath"}
if (Test-Path '.\\tss.exe') {
try {
\$value = .\\tss.exe token
} catch {
throw "Unable to obtain token: \$(\$_.Exception.Message)"}
}
Set-Content -Path \$Path -Encoding Ascii -Force -Value \$value -NoNewline
Argument Task Example:
\-NoProfile -ExecutionPolicy Bypass -Command
"C:\\Delinea\\refresh-oauth2_useSDK.ps1 -Path
C:\\ServiceNow\\prod\\agent\\oauth2_grant.json -SdkPath
C:\\Delinea\\secretserver-sdk-1.4.1-win-x64" 
