Configuring External Vault Integration: Azure Key Vault - ServiceNow Discovery

Ivonne Nirich
ServiceNow Employee
ServiceNow Employee

‎05-28-2024 08:13 AM - edited ‎07-02-2024 04:10 AM

Hi ITOM Community,

 

I am sharing a working-progress guide to configure the integration between ServiceNow Discovery/MID Server and Azure Key Vault, using the AKV as an external credential vault for validating users and passwords for the discovery of the infrastructure.

 

In the following link, you will find the ServiceNow documentation that supports the integration:

 

Link: https://docs.servicenow.com/bundle/vancouver-platform-security/page/product/credentials/concept/c_Ex...

 

The architecture of the integration:

 

IvonneNirich_0-1716907941054.png

 

 

This document is shared with the permission of the leading collaborative authors, Spyros Antoniou and Ioannis Soukas from Performance Technologies, a partner from Greece.

 

Main steps to follow:

 

  1. Plug-in & Software Requisites.
  2. Download and prepare the Multi Secret Credential Resolver Vault jar file from GitHub.
  3. Network Requisites.
  4. ServiceNow Instance Configuration.
  5. Azure Key Vault Configuration.
  6. MID Server Configuration.

 

1.   Required Plug-in on the ServiceNow instance.

  • ServiceNow required Plugins.

It is needed the following two ServiceNow plugins:

 

Plugin 1:   

 

Plugin 2:

 

Note: On DEV instances, both plugins are free of charge.

2.   Download the Multi Secret Vault Credential Resolver Jar file from GitHub.

The Credential Resolver is the main file for generating an external credential vault. The Credential Resolver file contains the link between the external Vault and the MID Server/Instance.

 

It is needed to download the following file:

 

  • servicenow-ecs-multi-secret-vault-ecs-multi-secret-vault-credential-resolver-2.0.2.jar

From this link to Github:

 

Always check the version to have the latest version:

There are complement documentation that can support the understanding of the use of the Credential Resolver file and its role on the integration:

 

3.   Network Requisites.

All the involved MID Servers need direct network access to execute the queries to the Azure Key Vault, either through the Public endpoint (not advisable) or through the Customer to Azure link to the AKV private endpoint.

4.   ServiceNow Instance configuration.

4.1 Upload the Credential Resolver jar file (ecs-multi-secret-vault-credential-resolver-2.0.2.jar) on the MID server:

  • Navigate to All > MID Server > JAR Files.
  • Click New.
  • Complete the following fields:
    1. Name: ecs-multi-secret-vault
    2. Version: 2.0.2
    3. Source: It will be filled automatically.
    4. Description: Add any description.
    5. Active: (Y)
  • Attach the jar file and click “Update” to upload the file to the ServiceNow instance.

IvonneNirich_1-1716907941058.png

 

4.2   Add Credential Entries referring to AKV.

Create Discovery Credentials by using the New button:

 

IvonneNirich_2-1716907941060.png

 

Select the type of credential, i.e. SSH credentials:

 

IvonneNirich_3-1716907941063.png

 

Then populate the Name, and Credential ID with the Azure key vault secret’s Name, check the “External credential store” checkbox, and also (optionally) select the credential storage vault.

 

IvonneNirich_0-1719918639354.png

 

Save or Update the credential form.

Then you can check the credentials by using an IP of a i.e. unix/linux machine that uses the credentials supplied in the key vault:

 

Screenshot 2024-07-02 at 13.00.01.png

 

 

IvonneNirich_6-1716907941067.png

5.   Azure Key Vault configuration

5.1 Create App Registration

Using Azure Entra ID (AD) a new app registration needs to be created:

 

IvonneNirich_7-1716907941070.png

 

 

Create a secret and copy:

 

  • AZURE_CLIENT_ID (app registration id)
  • AZURE_CLIENT_SECRET
  • AZURE_TENANT_ID

 

Use them in 4.3, and add them in the MID Server Environment Settings

5.2 Assign rights to App registration to Key Vault

The new app registration needs to have the following rights:

 

Go to the Azure key vault and open Access Control (IAM):

 

  • Add role assignment of Key Vault Secrets User to the actual app registration:

 

IvonneNirich_8-1716907941073.png

 

5.3 Configure Key Vault Entries

The Key Vault type that will be used to store the credentials is the “Secret” Type:

 

IvonneNirich_9-1716907941075.png

 

The secrets that will be accessed by ServiceNow need to have the AKV prefix as shown above.

The below configuration needs to be performed for each of the following credential types:

 

5.3.1 Windows Credentials in Secrets:

  • Name always start with akv
  • Mandatory Tags:

Tag Name

Tag Value

type

windows

username

<localuser>

or for domain use

<DOMAIN>\<user>
  • Secret: <password>

5.3.2 Linux/Unix SSH Password Credentials in Secrets:

  • Name always start with akv
  • Mandatory Tags:

Tag Name

Tag Value

type

ssh_password

username

<localuser>
  • Secret: <password>

5.3.3 VMware (vCenter) / jdbc / jms / basic Credentials in Secrets:

  • Name always start with akv
  • Mandatory Tags:

Tag Name

Tag Value

type

vmware or jdbc or jms or basic

username

<localuser>
  • Secret: <password>

5.3.4 Linux/Unix SSH Key Credentials in Secrets:

  • Name always start with akv
  • Mandatory Tags:

Tag Name

Tag Value

type

ssh_private_key

username

<localuser>
  • Secret: <private_key>

5.3.5 Azure API Credentials in Secrets:

  • Name always start with akv
  • Mandatory Tags:

Tag Name

Tag Value

type

azure

azure_client_id

<azure_client_id>

azure_tenant_id

<azure_tenant_id>
  • Secret: <azure_client_secret>

5.3.6 AWS Credentials in Secrets:

  • Name always start with akv
  • Mandatory Tags:

Tag Name

Tag Value

type

aws

aws_access_key

<aws_access_key>
  • Secret: <aws_secret_key>

5.3.7 SNMP v2 Credentials in Secrets:

  • Name always start with akv
  • Mandatory Tags:

Tag Name

Tag Value

type

snmp
  • Secret: <password>

5.3.8 SNMP v3 Credentials in Secrets:

  • Name always start with akv
  • Mandatory Tags:

Tag Name

Tag Value

type

snmpv3

username

<username>

snmpv3_auth_protocol

<snmpv3_auth_protocol>

snmpv3_privacy_protocol

<snmpv3_privacy_protocol>
  • Secret: <snmpv3_privacy_key>

6.   MID Server Configuration

6.1 Download and install Java JDK on the MID server

  •        Java JDK (optional for development purposes only – extending functionality)
    •    Download the Java Development Kit

 

On the MID-server download and install the JRE:

Link:

https://www.openlogic.com/openjdk-downloads?field_java_parent_version_target_id=416&field_operating_...

 

Install the JRE in a folder of your choice. Check the following image as an example:

 

IvonneNirich_13-1716908746676.png

 

6.2 Create an Environment variable to the JAVA bin

We need to create an environment Variable named “Path”, to the JAVA bin. In the ‘Control Panel/System/Advanced system settings/Advanced/Environment Variable’ create a new System Variable named ‘’PATH” and the Value “C:\Program Files\OpenLogic\jdk-8.0.392.08-hotspot\bin” (or your path to the java bin folder).

 

6.3 MID Server Deployed and validated

A MID server needs to be installed, connected to the Service-Now instance, and validated.

 

6.4 Restart the MID Server windows service to trigger the jar file download

Go to the MID server system and restart the MID server windows service, then check the below directory if the file exists:

 

IvonneNirich_14-1716908773090.png

 

6.5 Edit config.xml and add Azure Key Vault’s URL

On the MID server under the agent directory, edit the config.xml and add the following lines under LESS COMMON OPTIONAL Parameters:

 

    <!--

     AZURE KEY VAULT

    Azure Key Vault configuration to point to AZ key vault URL

     AZURE KEY VAULT

    -->

     <parameter name="ext.cred.azure.vault.name" value="azkeyvaultxyz.vault.azure.net"/>

 <!-- # get the vault name without https:// from vault URL. Eg., https://xxx.vault.azure.net/ -->

     <parameter name="ext.cred.azure.vault.proxy.host" value=""/>

     <parameter name="ext.cred.azure.vault.proxy.port" value=""/> <!-- # 8080 -->

 

Adding the above lines the jar files knows to which key vault to connect to.

 

6.6 Set the environment variable on the Mid Server

Set the following SYSTEM environment variables on the MID server machine with values the appropriate IDs/Secrets:

 

  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
  • AZURE_TENANT_ID

6.7 Restart Mid Server OS

To read and use the Environment settings and also read the config.xml entries.

 

IvonneNirich_15-1716908789292.png

 

+++++++++++++++++++++++++++++

You can contact me for any further information by replying to this article.

This is an on going document.

Thanks for reading!

+++++++++++++++++++++++++++++

  • 6,338 Views
Comments
rafi438
Tera Contributor
‎07-02-2024 02:08 AM

Hi,

 

Thanks for the nice article, it really helps!

Can we use the same setup to store our keys,certificates in AKV and retrieve them(may be using custom flow action calls) and use the keys in any other simple REST integrations which we do?(if we don't use it for discovery for eg)

If yes, what are the points which we can skip from the above.

 

Thanks in advance.

Ivonne Nirich
ServiceNow Employee
ServiceNow Employee
‎07-02-2024 04:14 AM

Hi Rafi,

 

Many thanks for your response! Nice it was useful to you.

You mean, use custom flow actions from the Now Platform to call the vault?

 

Kind regards,

 

Ivonne

0 Helpfuls
KRafi
Tera Contributor
‎07-03-2024 03:55 AM

Hi @Ivonne Nirich 

Yes, you are correct.
Have all our integration secrets to be stored in Azure(not only discovery) and retrieve them when call is being made to external tools/integrations instead of storing them locally in servicenow using flows.

0 Helpfuls
Ivonne Nirich
ServiceNow Employee
ServiceNow Employee
‎08-08-2024 03:20 AM

Hi Readers!

 

Good news!

 

There is a new release of the ServiceNow Store that includes the External Credential AKZ Integration.

 

IvonneNirich_0-1723112240208.png

IvonneNirich_1-1723112264342.png

 

 

ServiceNow Link: https://store.servicenow.com/sn_appstore_store.do#!/store/application/072a714493acce1003a6fc4e1dba10...

 

ServiceNow Doc: https://docs.servicenow.com/bundle/xanadu-servicenow-platform/page/product/mid-server/task/mid-azure...

 

Have a look at it.

 

Kind regards,

 

Ivonne

0 Helpfuls
sampathkasi
ServiceNow Employee
ServiceNow Employee
‎02-17-2025 03:28 AM

Hello @Ivonne Nirich

 

Good day!

 

The article is very informative.

 

I just want to check at 6.7th step we have to enter the values of the below

------------------

Set the following SYSTEM environment variables on the MID server machine with values the appropriate IDs/Secrets:

 

  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
  • AZURE_TENANT_ID

 

If we are entering those values here, then what is the point of having Azure Key vault in place and keeping the credentials in it.

Could you please let me know on the same. 

 

Regards,
Sampath

0 Helpfuls
Ivonne Nirich
ServiceNow Employee
ServiceNow Employee
‎02-17-2025 06:59 AM

Hi @sampathkasi ,

 

Thank you for your email.

 

Remember that from August 2024, there is an OOB feature to cover this integration.

Did you check on those links?

 

Link: https://store.servicenow.com/sn_appstore_store.do#!/store/application/072a714493acce1003a6fc4e1dba10...

 

ServiceNow Doc: https://docs.servicenow.com/bundle/xanadu-servicenow-platform/page/product/mid-server/task/mid-azure...

 

Or in your case, the customer is not able to upgrade?

 

Many thanks!

 

Ivonne

 
0 Helpfuls
pranavkonga
ServiceNow Employee
ServiceNow Employee
‎03-31-2025 12:56 PM

​When integrating ServiceNow with Azure Key Vault for credential storage, it's essential to ensure that each secret is properly configured with the correct tags and values. A common issue arises when the secret's value is not formatted as a JSON object, leading to integration failures.

Solution:

Ensure that the value of each secret in Azure Key Vault is a JSON object containing the necessary credential information. For example, for SSH credentials, the secret's value should be structured as follows:

{
  "type": "ssh",
  "user": "your_username",
  "password": "your_password"
}

By structuring the secret's value as a JSON object ServiceNow's MID Server can accurately retrieve and utilize the credentials stored in Azure Key Vault.

Implementing this approach resolved the integration issue in our case, and we hope it assists others facing similar challenges.

 

Version history
Last update:
‎07-02-2024 04:10 AM
Updated by:
ServiceNow Employee
Contributors