Running Delinea MidServer Setup Utility for Secret Server
After establishing the basic requirements for creating a service account and a discovery secret, you need to run the Delinea MidServer Setup Utility. This utility is designed to generate all necessary parameters while providing a secure and reliable method for storing user credentials, avoiding the use of plain text in the MidServer configuration file. It facilitates the configuration of the connection between your MID Server and Secret Server.
To run the Delinea MidServer Setup Utility:
-
Open the command prompt to run
DelineaMidServerSetupUtility jar
. -
Run the command
Java -jar DelineaMidServerSetupUtility.jar
. -
For additional information, enter the command
--help
for each question.
It is important to run this utility on each MID Server and ensure the Java version is at least 11. If not done correctly, the encryption and decryption process may not work as intended.
To set the complete configuration, enter the following information:
-
Do you want to setup the complete configuration ?(y/n)
-
Yes – Complete configuration setup (All parameters)
-
No – Only encrypts the credentials
-
-
Enter vault type (SS (Secret Server) or PAS (Privileged Access Service)): SS
-
Enter Secret Server or Platform URL: Provide SS URL
-
Using oauth2 grant file for token ?(y/n)
-
Yes – Provide the oauth2 grant file path in next question
-
No – Provide SS credentials in next questions
-
-
Enter the Secret Server or Platform username: Provide the SS username.
-
Enter the Secret Server or Platform password: Provide the SS password.
-
Do you want to use proxy ?(y/n)
-
Yes – Provide proxy details in the next questions.
-
No – Parameters generated without Proxy.
-
Find and copy the generated parameters from a configuration.txt file within the same folder and paste it into the config.xml file of the ServiceNow MID Server (Go to Mid Server path> agent folder and look for the file named config.xml).
DelineaMidServerSetupUtility validates Secret Server credentials at runtime. If the credentials are not validated, the process will stop.
Update MidServer config.xml
The config.xml file contains the necessary configuration settings to establish the communication between the MID Server and Secret Server. Update the config.xml with the correct server URLs, authentication details, and any relevant settings for your credential storage.
(Optional) Running Delinea MidServer SetupUtility with Command Line Arguments
This is not needed when running the setup utility manually.
It is also possible to run the MidServer SetupUtility using command line arguments for automation.
To run the Delinea MidServer Setup Utility using command line arguments:
-
Open the command prompt.
-
Run the
java -jar DelineaMidServerSetupUtility.jar vault_type ss_or_platform_url username password proxy_host proxy_port proxy_username proxy_password
command. -
Specify the following parameters:
-
vault_type
: The type of the Secret Server vault. -
ss_or_platform_url
: The Secret Server URL. -
username
: The Secret Server username. -
password
: The password of the configured Secret Server. -
proxy_host
: Proxy Server IP (if required) -
proxy_port
: Proxy Server port (if required) -
proxy_username
: Proxy username (if required). -
proxy_password
: Proxy password (if required).
-
The command will only generate the ss_auth_str
and proxy_auth_str
parameters. You need to copy the remaining parameters manually into the config.xml file.
The Delinea MidServer Setup Utility.jar can only be run from the command line if the usernames and passwords contain no spaces. The password will be visible after you enter it in the command line.
Editing Agent Config
The config.xml file will be modified to add additional elements for the credential resolver’s parameters. These are added at the end of the file just before the closing tag . To update the config file, follow the steps below:
-
Edit the
config.xml
configuration file for your MID Server. -
Copy and paste the associated contents (based on the mode chosen) just before the </parameter> tag at the end of the file.
-
Adjust the values accordingly.
-
Save the
config.xml
file and close your editor. -
Go to the MID Server > Servers in the ServiceNow portal.
-
Restart the recently updated MID Server.
Authentication Modes to Establish a Connection of Secret Server with Servicenow
When authenticating Secret Server with ServiceNow there are two ways to establish a connection. You can use your Secret Server username and password to authenticate or generate a token in the file.
Choose from the following modes:
Just In Time Mode
Attribute | Value Description |
---|---|
ss_or_platform_url
|
URL for your Secret Server. |
ss_or_platform_auth_str
|
This parameter is set to an encrypted string generated by the encryption utility, which contains the Secret Server's username and password. |
allow_self_signed_certificate
|
Set to true if you are using a self-signed cert for Secret Server instance. |
vault_type
|
This parameter should be set to Secret Server to validate the credentials with Secret Server. |
is_logging
|
This parameter can be set to either true or false to enable additional logging other than the default one. |
log_level
|
|
proxy_host
|
This field will likely be blank, unless you know a proxy to be used to get out to the internet from your MidServer. |
proxy_port
|
This field will likely be blank, unless you know a proxy to be used to get out to the internet from your MidServer. |
proxy_auth_str
|
This parameter is set to an encrypted string generated by the encryption utility containing the username and password of the Proxy Server. |
search_secret_by_name
|
This field can be set as true/false. In case you want to validate credentials using secret name, set this field as true. |
auto_comment
|
This parameter is set as a string. |
cache_url
|
Delinea Credentials Cache URL. Required format for URL: url:port. |
Copy/paste this information into the config.xml file:
\<parameter name="ss_or_platform_url" value="\<replace\>"/>
\<parameter name=" ss_or_platform_auth_str" value="\<replace\>"/>
\<parameter name="allow_self_signed_certificates" value="false"/>
\<parameter name="vault_type" value="ss"/>
\<parameter name="is_logging" value="true/false"/>
\<parameter name="log_level" value="1/2/3/4"/>
<parameter name="proxy_port" value=""/>
<parameter name="proxy_host" value=""/>
<parameter name=" proxy_auth_str" value=""/>
<parameter name="search_secret_by_name" value="true/false"/>
<parameter name="auto_comment" value=""/>
<parameter name="cache_url" value=""/>
If the user does not provide an is_logging and log_level parameter in the config file, the default value will be true and 3.
Grant File Mode
Attribute | Value Description |
---|---|
ss_or_platform_url
|
URL for your Secret Server. |
auto_comment
|
This parameter is set as a string. Go here to find out more about how to format the auto-comment parameter. |
cache_url
|
Delinea Credentials Cache URL. Required format for URL: url:port. Go here to find out more about how to format the cache URL value. |
oauth2_grant_file
|
Path of oauth2_grant.json file. |
allow_self_signed_certificate
|
Set to true if you are using a self-signed cert for Secret Server instance. |
vault_type
|
This parameter should be set to Secret Server to validate the credentials with SecretServer. |
is_logging
|
This field can be set as true/false to enable additional logging other than the default one. |
log_level
|
|
proxy_host
|
This field will likely be blank, unless you know a proxy to be used to get out to the internet from your MidServer. |
proxy_port
|
This field will likely be blank, unless you know a proxy to be used to get out to the internet from your MidServer. |
proxy_auth_str
|
This parameter is set to an encrypted string generated by the encryption utility containing the username and password of the Proxy Server. |
search_secret_by_name
|
This field can be set as true/false. If you want to validate credentials using the secret name, set this field as true. Go here to find out more about how to format the format for the search secret by name. |
Copy/paste this information into the config.xml file:
\<parameter name="ss_or_platform_url" value="\<replace\>"/>
\<parameter name="oauth2_grant_file" value="oauth2_grant.json"/>
\<parameter name="allow_self_signed_certificates" value="false"/>
\<parameter name="vault_type" value="ss"/>
\<parameter name="is_logging" value="\<replace\>"/>
\<parameter name="log_level" value="1/2/3/4"/>
<parameter name="proxy_port" value=""/>
<parameter name="proxy_host" value=""/>
<parameter name=" proxy_auth_str" value=""/>
<parameter name="search_secret_by_name" value="true/false"/>
<parameter name="auto_comment" value=""/>
<parameter name="cache_url" value=""/>
If the user does not provide is_logging and log_level parameters in the config file, the default value will be true and 3.
If any of the proxy-related settings are blank, the plugin will not use the proxy server.
Running 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 oauth2/token endpoint or using the ss utility with the Secret Server Client SDK.
- 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).
- refresh-oauth2.ps1.
To provide a secure method for the username/password required for the OAuth2 endpoint, a password file is used where the value is encrypted. This process is unique to MID Server and must be created individually on each MID Server.
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"
Enabling the Search Secret by Name
-
Set the following parameter as true in the MID Server config.xml file to enable secret search by name.
\<parameter name="**search_secret_by_name**" value="true"/\>
-
Pass the secret name from the ServiceNow MID Server in the Credential ID field.
-
Provide a complete name of the secret because a partial name will not work.
Searching for the secret by name is not recommended because Secret Server can have the same name for two different secrets. This functionality will not work correctly if multiple secrets have the same name.
Enabling the Auto Comment
-
In Secret Server, select your secret.
-
Go to the Security tab.
-
In the Other security section, select the edit pencil icon and select the Require comment checkbox. Select Save.
-
The Require comment field is now set to Yes.
-
In the
Mid Server config.xml
file, set the following parameter as a string as follows:<parameter name="auto_comment " value="Enter your comment"/>
.
If the auto_comment
parameter is empty, it will not provide any comment while viewing the secret.
Enabling Delinea Credentials Cache
To enable Delinea Credentials Cache, open the Mid Server config.xml
file and set the cache URL
(URL format should be url:port) parameter as follows: <parameter name="cache_url" value="https://10.XX.XX.XXX:80XX"/>
. For more details, see Delinea Credentials Cache.
The Delinea Cred Cache does not support validating credentials using a secret name. Users can only validate the credentials using the secret ID. Also, it does not support SSH private key credentials.