How to develop a custom external storage connector

[Benoit Crestey]

Introduction

This article explains how to create a custom connector for "External Credential Storage" plugin.

If the vault is not supported by ServiceNow, then it is possible to develop a custom connector.

For more generic information on the plugin :

• Official Documentation : https://docs.servicenow.com/csh?topicname=c_ExternalCredentialStorage.html&version=latest
• I created a more generic article on the vaults topic : https://www.servicenow.com/community/itom-articles/password-vaults-implementation/ta-p/2424263
• Also you will need this article to deploy and test the connector : https://www.servicenow.com/community/itom-articles/how-to-deploy-and-test-external-storage-connector...

Principle

• The connector is a Java JAR file, that will be deployed in ServiceNow
• The connector is deployed on each MID, and a specific "resolve" function will be called when the MID will request the credentials
• the "resolve" function will take in parameters and return the credentials

 

Technical requirements of the Java Class to develop :

It is necessary to create a JAR File, containing a specific Java Class

• public Class com.snc.discovery.CredentialResolver
  • Containing a Java function resolve(Maps args)

• For other types of credentials, please refer to the credential table. Most of the time it is the same that in ServiceNow.
  • Examples
    • api_key : api_key
    • azure : tenant_id, client_id, secret_key
    • basic_auth : user, pswd
    • snmpv3 : authprotocol, authkey, privprotocol, privkey, contextname

Structure of the classes

Here is an example of implementation :

• CredentialResolver.java
  • Contains the resolve() function that will be called by ServiceNow
  • Can also implement cache depending on implementation
  • Can implement code that will read configuration parameters
    • Configuration parameters (like vault API URL) are usually configured in MID Server config.xml file, but it is also possible to deploy it in a specific configuration file
• CustomResolver.java
  • I prefer to create a custom class for the vault, to keep CredentialResolver.java standard
• CustomResolverTest.java
  • I like to create a specific class to trigger tests. Most of the time I won't package it in the final JAR file
• Vault API Librairies
  • Depending of the vault, it is easiest to use the provided Java APIs

 

Logging tips

If you want to write logs in agent0.log.0 instead of the wrapper.log.0, I advise you to create a logger class and use MID logging capabilities

import com.snc.core_automation_common.logging.Logger;
import com.snc.core_automation_common.logging.LoggerFactory;

/** **/
private static final Logger fLogger = LoggerFactory.getLogger(CredentialResolver.class);

/** **/
public void logInfo(String message){
fLogger.info(message);
}

Creation of the custom connector

Note : Here is an example, of course you can use any procedure or tools

Note 2 : In order to test directly without deploying in ServiceNow each time, it might be interesting to have access to the vault from the computer of developer, or to develop directly on the VM that is containing the MID.

Steps :

• Step 1 : Create a new Java project
• Step 2 : Import external librairies and base java classe
• Step 3 : Develop and Test
• Step 4 : Deploy in ServiceNow

 Step 1 : Create a new Java project

• You can use Eclipse IDE, that is free
  
  • New Java Project
• For compiler version, best is to align to MID Server JRE version

Step 2 : Import external libraries and base java class

• Set the "\lib" folder of a MID Server, and import it as external Libraries to your project
  • If working without of a MID Server, you will need to get the files from a deployed MID
  • If you have a MID Server deployed, no need to copy the files, you can reference it directly
• Import the sample CredentialResolver.java file from ServiceNow in src (source) folder

 

Step 3 : Develop and Test

• It is possible to test with or without ServiceNow
  • To test with ServiceNow, export the JAR and please refer to the dedicated article
  • If you are able to reach the vault API from your computer, it is easier to test directly from your Java IDE
    • It is possible to reuse the following custom code to trigger the call

Example of function to simulate a call that I developed :

package com.snc.discovery_test;

import java.util.HashMap;
import java.util.Map;
import com.snc.discovery.CredentialResolver;

public class CredentialResolverTest {

	public static void main(String args[]) {
		System.out.println("testing the custom vault");
		
		Map<String, String> args2 = new HashMap<String, String>();
		args2.put("type", "windows");
		args2.put("id", "myVaultID");
		args2.put("ip", "10.0.0.18");
		
		CredentialResolver helper = new CredentialResolver();
		
		try {
			helper.resolve(args2);
		} catch (Exception e) {
			System.out.println("It failed...");
			e.printStackTrace();
		}	
	}
}

More advanced Example setting MID parameters :

ackage com.snc.discovery_test;

import java.util.HashMap;
import java.util.Map;
import com.service_now.mid.services.Config;
import com.snc.discovery.CredentialResolver;

public class CredentialResolverTest {

	public static void main(String args[]) {
		System.out.println("testing connector");
		
		Config.get().setProperty("mid.property.credential_resolver.azure_vault_token_mode", "service_principal");
		Config.get().setProperty("mid.property.credential_resolver.azure_vault_mapping_mode", "dynamic");
		
		Map<String, String> args2 = new HashMap<String, String>();
		args2.put("type", "azure");
		args2.put("id", "azkv.myServicePrincipal");
		
		CredentialResolver helper = new CredentialResolver();
		
		try {
			helper.resolve(args2);
		} catch (Exception e) {
			System.out.println("custom connector failed");
			e.printStackTrace();
		}
	}	
}

Step 4 : Deploy and test in ServiceNow

• In Eclipse, you can use export option to generate the JAR file
• To deploy and test in ServiceNow, please refer to my dedicated article