The article covers how to deploy and run HashiCorp Vault and then how to build integration with ServiceNow.

HashiCorp and ServiceNow support integration that enables HashiCorp Vault to be used as an external credential resolver and centralized secrets store for ServiceNow Discovery (and workflows) to reduce secret sprawl while leveraging Vault’s granular access and audit capabilities. The setup of HashiCorp Vault can reside on the same server where MID is installed to achieve high performance and cashing between the MID Server and Vault.

I. Setup HashiCorp Vault

If you have Vault already installed, you can skip this chapter and jump to the next one where the related MID JAR file and plugin activation procedures are described.

1. Acquire the installation media files of Vault

Navigate to the official website of Vault by HashiCorp and click on the Download section. Below is a quick link to that location:

https://www.vaultproject.io/downloads

Select Windows binary download. After downloading, unpack the archive file and extract the “vault.exe” binary executable file. Move the binary to a directory available on PATH on Windows configuration.2.

2. Install Vault as a server

Open PowerShell or Command prompt session to the directory where the binary is placed. Firstly type “vault.exe”. That should list all available options as possible command choices:

$ vault
Usage: vault <command> [args]

Common commands:    
read        Read data and retrieves secrets    
write       Write data, configuration, and secrets    
delete      Delete secrets and configuration    
list        List data or secrets    
login       Authenticate locally    
agent       Start a Vault agent    
server      Start a Vault server    
status      Print seal and HA status    
unwrap      Unwrap a wrapped secret

Other commands:    
audit          Interact with audit devices    
auth           Interact with auth methods    
debug          Runs the debug command    
kv             Interact with Vault's Key-Value storage    
lease          Interact with leases    
monitor        Stream log messages from a Vault server    
namespace      Interact with namespaces    
operator       Perform operator-specific tasks    
path-help      Retrieve API help for paths    
plugin         Interact with Vault plugins and catalog    
policy         Interact with policies    
print          Prints runtime configurations    
secrets        Interact with secrets engines    
ssh            Initiate an SSH session    
token          Interact with tokens

If you get an error that the binary could not be found, then the Windows PATH environment variable is not set up properly for that location.

With the next command Vault server will run in development mode:

$ vault server -dev

Vault dev server is a built-in, pre-configured server with just the essential secure settings level. Once executed, Vault will continue to work in the foreground, and it will show on the command prompt a stream containing the Unseal Key value, the Root assess Token key, and Export VAULT_ADDR.

Open another prompt to the vault.exe location and run the Export VAULT_ADDR as it is printed on the stream on the first prompt. The host should be localhost (127.0.0.1) and port 8200. To set that environment variable via PowerShell, use $env operator:

$env:VAULT_ADDR="http://127.0.0.1:8200"

In the case of Command Prompt, use the set operator:

set VAULT_ADDR=http://127.0.0.1:8200

The execution of any of the command lines above will configure the Vault client to talk to the dev server.

The next step is to locate the Unseal Key available on the first prompt and Copy and Save that key somewhere for later usage.

Unseal Key: E4SqJuzdn7zj8wO82pRlWCelt6ileliODw/gDKpitY4=

Lastly, also copy the value of the Root Token

Root Token: s.bGDKO9578p0BD48DDqGrE92m

and then set the VAULT_TOKEN environment variable value to the generated Root Token value displayed in the terminal output. For example:

$ set VAULT_TOKEN="s.bGDKO9578p0BD48DDqGrE92m"

To verify if Vault is operating, check the status by running:

$ vault status

    Key               Value
     ---                 -----
Seal Type          shamir
Initialized          true
Sealed                false
Total Shares      1
Threshold          1
Version              1.10.0
Storage Type    inmem
Cluster Name    vault-cluster-ade0da85
Cluster ID          c93d9e90-4305-56aa-7382-84e4ff1bcc6f
HA Enabled      false

The above is a typical output of a Vault server up and running in dev mode.

At this point, you can open Vault UI via Internet Browser and start adding secrets in Vault. User Interface is accessible on the Vault address: http://127.0.0.1:8200

3. Running Vault in production mode

To deploy Vault into a production environment, use Ctrl+C to terminate the dev server that is running at http://127.0.0.1:8200

Right after that, unset the VAULT_TOKEN environment variable. The way to do that is to close the current Command Prompt and establish a new one. The closure of the opened Command Prompts will simply cause the environment variable VAULT_TOKEN to get cleared.

Create a Vault configuration file next to the vault.exe file. The configuration file should be named config.hcl.

Put the following JSON format content into that file. That is a sample configuration for Vault to run in production mode and integrate with ServiceNow.

storage "raft" {
  path    = "./vault/data"
  node_id = "vaultnode1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = "true"
}

cache {
  use_auto_auth_token = true
  }

vault {
  address = "http://127.0.0.1:8200"
  }

auto_auth {
    method {
        type = "approle"
        config = {
            role_id_file_path = "./vault/role_ID"
            secret_id_file_path = "./vault/secret_ID"
            remove_secret_id_file_after_reading = false
        }
    }
}

disable_mlock = true
api_addr = "http://127.0.0.1:8200"
cluster_addr = "https://127.0.0.1:8201"
ui = true

Next are some of the configuration key attribute details:

storage ([StorageBackend][storage-backend]: <required>) – Configures the storage backend where Vault data is stored. Dev server uses “inmem” (in memory), but the example above uses integrated storage (raft), a much more production-ready backend.

disable_mlock (bool: false) – Disables the server from executing the mlock, which prevents memory from being swapped to disk

cluster_addr – Indicates the address and port to be used for communication between the Vault nodes in a cluster.

api_addr – Specifies the address to advertise to route client requests.

listener ([Listener][listener]: <required>) – Configures how Vault is listening for API requests.

Some other useful parameters are:

disable_cache (bool: false) – Disables all caches within Vault, including the read cache used by the physical storage subsystem.

cache_size (string: "131072") – Specifies the size of the read cache used by the physical storage subsystem

cluster_name (string: <generated>) – Specifies the identifier for the Vault cluster.

seal ([Seal][seal]: nil) – Configures the seal type to use for auto-unsealing

listener ([Listener][listener]: <required>) – Configures how Vault is listening for API requests

The next step is to create a storage directory, which is set on the config.hcl configuration file:

$ md .\vault\data\

Lastly, start the server by using the prepared configuration file:

$ vault server -config=config.hcl

Vault is now started, but it will still require VAULT_ADDR  to be set on the Command Prompt for later usage if the Vault has to be unsealed. As of this point, launch a new Command Prompt session and set VAULT_ADDR environment variable:

$ set VAULT_ADDR=http://127.0.0.1:8200

On brand new Vault without any existing data, start the initialize Vault by running:

$ vault operator init

Executing the command line will resolve the missing core seal configuration. Next launches of the Vault server will not need that initialization to be run. Per the initial execution, it will generate five Unseal Keys and one Initial Root Token key. Those should be saved somewhere by Vault administrators, and they can be used if Vault needs to be unsealed to access the UI interface in production. To unseal Vault and access UI, run the next operator three times in a row by providing three different Unseal Keys:

$ vault operator unseal

Once you login to UI you can enable the AppRole method or other for authentication purposes, set secrets, add users, and create policies.

II. Plugin activation and uploading JAR file to MID server

1. Add credential resolver plugin

Visit the ServiceNow Store and get the application installed on your instance.

That application requires the ServiceNow External Credential Storage plugin to be activated.

Once the plugin is installed, that will add the option “Externa Credential Store” on the ServiceNow credential table.

2. Login to the ServiceNow instance and go to MID server > JAR files via the navigation menu

Check if any jar file is automatically uploaded after the store app has been installed. If by chance, the jar file is missing, you can create a new record and attach the extracted jar file. The JAR file can be acquired from the vendor’s official location site: https://releases.hashicorp.com/vault-servicenow-credential-resolver/

The direct link to the latest preconfigured and only version uploaded jar file is: https://releases.hashicorp.com/vault-servicenow-credential-resolver/0.1.0/vault-servicenow-credential-resolver_0.1.0_all_all.zip

After the download is completed, extract the jar file, and return it to ServiceNow MID server > JAR files.

Next, visit MID server > Properties using the ServiceNow navigation menu. On this page, create a new record by setting “mid.external_credentials.vault.address” as a Name value and the IP address of the Vault Agent listener (e.g. http://0.0.0.0:8200). Lastly, set the MID server where the properties are to be added.

Optionality: two more properties could be added to the MID servers:

mid.external_credentials.vault.ca (string: “”) – The CA certificate to trust for TLS in PEM format. If not used, the system’s trusted CA certificates would be used.

mid.external_credentials.vault.tls_skip_verify (string: “”) – When set to true, it will skip the verification of the Vault server TLS certificates. It is not recommended for production.

III. Setting up credentials

1. ServiceNow Credentials setup

Navigate to Credentials and add a new record. Select the type of Credentials, then enter a Name and put a tick in front of “Externa credential store”. After the tick selection, the user will be able to insert the Credential ID provided by the Vault administrators. For example:

From the same place the credential record could be tested (“Test credentials” link).

IV. Other useful documentation sources

For more details on how to install Vault, visit the website: https://www.vaultproject.io/docs/install

For more details on ServiceNow External credential storage, check the ServiceNow official documentation https://docs.servicenow.com and search for HashiCorp Vault Credential Resolver.

If you want to know more tips and tricks about ServiceNow, check out our article “Binary search: a performance tweak” by Zdravko Vergiulov, Senior ServiceNow Developer.