Comment on page
Keeper credential storage integration with ServiceNow
The Management, Instrumentation, and Discovery (MID) Server integration with the Keeper Vault enables ServiceNow Orchestration, ServiceNow Discovery, and ServiceNow Service Mapping to dynamically retrieve credentials from the Keeper Vault without storing any credentials on the instance.
The instance maintains an unique identifier for every credential, along with its credential type (e.g., SSH, SNMP, or Windows) and any associated credential affinities. The MID Server obtains the credential identifier, credential type, and IP address from the instance, and then uses Keeper vault to resolve these elements into a usable credential.
- Use secrets from the Keeper vault as credentials for ServiceNow Orchestration, Discovery, and Service Mapping
- Supports External Credential Storage for Discovery and Orchestration
- Allows usage as a Custom Credential Provider
- 1.Trigger: An admin in ServiceNow initiates a discovery process for newly added infrastructure.
- 2.Action: ServiceNow sends a request to the MID Server to start the discovery.
- 3.MID Server: Retrieves the necessary credentials (SSH, SNMP, etc.) from Keeper Vault and performs the discovery.
- 4.Result: The discovered assets are added to the ServiceNow Configuration Management Database (CMDB).
- 1.Trigger: An incident is created in ServiceNow, requiring immediate action on a specific server.
- 2.Action: ServiceNow triggers an orchestration workflow that involves the MID Server.
- 3.MID Server: Fetches the required credentials from Keeper Vault to log into the affected server and execute predefined remediation steps.
- 4.Result: The incident is resolved, and the actions taken are logged in ServiceNow.
- 1.Trigger: A custom application integrated with ServiceNow requires specific credentials for operation.
- 2.Action: The application queries ServiceNow for the required credentials.
- 3.MID Server: Intercepts the request, fetches the credentials from Keeper Vault, and provides them to the custom application.
- 4.Result: The custom application can proceed with its operation, using the credentials securely fetched from Keeper Vault.
- Keeper Secrets Manager access (See the Quick Start Guide for more details)
- Secrets Manager add-on enabled for your Keeper subscription
- Membership in a Role with the Secrets Manager enforcement policy enabled
A property called Enable External Credential Storage
[com.snc.use_external_credentials]enables or disables the External Credential Storage plugin after it is activated. This property is located in Discovery Definition > Properties and Orchestration > MID Server Properties, and is enabled when you activate the plugin.
If you disable external credential storage with the system property, the system automatically sets all the external credentials to inactive in the instance. If you re-enable the feature with this property, the system does not reset the external credential records to active. You must reactivate each credential record manually.
- In ServiceNow, navigate to "MID server - JAR files" -> New
- Manage Attachments -> upload Keeper Credential Resolver JAR
- Fill in name, version etc. as desired
- Click Submit
- Navigate to "MID server - Properties" -> New
- Optional: Set the property
ext.cred.keeper.ksm_label_prefixto the desired prefix (by default resolver uses
mid_as a label prefix)
- Optional: Set the property
"true"to enable caching (use when you expect at least a few thousand requests per 10 seconds)
Alternatively you can edit
config.xmldirectly (by default in
/opt/servicenow/mid/agent/)add the keys and restart the server (setting the label prefix is optional - the default prefix is shown below)
<parameter name="ext.cred.keeper.ksm_config" secure="true" value="[KSM_CONFIG_BASE64_STRING]"/>
<!-- optional --> <parameter name="ext.cred.keeper.ksm_label_prefix" value="mid_"/>
<!-- optional -->
<parameter name="ext.cred.keeper.use_ksm_cache" value="true"/>
Use secure="true" option for all sensitive parameters and remember to restart the server to encrypt the values.
To consume Keeper vault credentials from your MID server, you will need to:
- Create a secret in Keeper vault and share it to the corresponding KSM Application
- Configure the resolver to use that secret
Keeper record types are dynamic and easy to customize, and there are no specific record types matching corresponding credential types in ServiceNow. Keeper External Credential Resolver uses custom field labels to match record data with MID Server's table columns (
discovery_credentialtable) just label all required custom fields to match the table columns for a given credential type and prefix that label with "mid_" (see below how to configure custom prefix) Credential types that require username/password should use records of type Login, and add any custom fields required by the credential type - ex. type=hidden, label="mid_pkey" Any other types that may not have username/password is best to use File/Photo records which don't have any standard fields and that makes it easier to navigate the custom fields. To change the custom field labels prefix update the config.xml in MID Server with the parameters below and restart the MID Server.
<parameter name="ext.cred.keeper.ksm_label_prefix" value="mid_"/>
Use custom fields with type
hiddendepending on the visibility you want in your Keeper Vault.
When Login record type is used any custom fields for username/password are ignored (even if properly labeled mid_user, mid_pswd) as these values always come from the Login record type standard fields - Login/Password.
When used with "External credential store" option the map keys returned from resolve method must conform to IExternalCredential interface from
snc-automation-api.jar(values start with VAL_ prefix). Supported key values in current version (Utah): user, pswd, passphrase, pkey, authprotocol, authkey, privprotocol, privkey, secret_key, client_id, tenant_id, email - corresponding field labels should be prefixed with
mid_in Keeper records to be extracted and mapped properly.
When used as Custom External Credential Resolver any custom field could be mapped if properly prefixed in Keeper vault and present in corresponding credential type. The credential map returned from the resolve method is expected to have keys matching with the column names in discovery_credential table ex. sn_cfg_ansible, sn_disco_certmgmt_certificate_ca, cfg_chef_credentials, etc.
- Credential type
jdbc- map to Keeper record type
Login(using standard Login/Password fields, no additional setup required)
- Credential type
api_key- map to Keeper record type
Loginand manually add custom fields of type
- Credential type
gcp- map to Keeper record type
File Attachment/Photoand manually add the required custom fields
Credential ID passed from MID Server to Credential Resolver must be either a valid record UID (22 alphanumeric characters incl. "-" and "_") or in the following format
type:titleThe second format also allows searches by record type only or by title only (or both, but single ":" is invalid combination)
type:titleformat for the credential make sure there's only one matching record, since multiple matches result in error.
Using record UID is recommended to guarantee a single record match, and to avoid downloading all records with every single request to do local searches by type:title (due to the zero knowledge nature of the Keeper vault - searches must be local).
Examples (zero or two or more matches result in an error)
- Find by Record UID - Credential ID:
- Find by type and title - Credential ID:
- Find by title - Credential ID:
- Find by type - Credential ID:
In the ServiceNow UI:
- Navigate to "Discovery - Credentials" -> New
- Select a credential type from the list
- Tick "External credential store" check box. The Username and Password fields disappear, and the Credential ID field and Credential storage vault menu appear.
- Fill in a meaningful name
- Set "Credential ID" to the record UID of your secret or provide a search string in the form
:titleand make sure it resolves to a single record
- From the Credential storage vault menu, you can select either None, the Keeper vault, or a custom external credential storage vault.
- 1.To use a custom external credential storage vault, navigate to Vault Configurations
[vault_configuration.list]in the instance.
- 2.Create a new record using a name associated with an imported JAR file for a custom credential resolver.
- Optional: Click "Test credential" and select a MID server and a target to test against to test everything is working
The plugin will try to resolve "throttled" errors by default by adding a random delays and retrying later, which works well for up to 1000-3000 requests per 10 sec interval (throttles start after 300-600 requests/10 sec) If you expect 5000+ requests in less than 10 seconds we recommend to enable caching by setting
"true"in config.xml and restarting the MID Server. Cached data is stored in an encrypted file
ksm_cache.datin MID Server's work folder. Cache is updated at most once every 5 minutes or with the next request.
Check the log files inside
logs/in the agent installation folder for logs and errors. The resolver logs a line for each credential ID that it successfully queries, and also logs the fields that the credentials were extracted from.
If a particular credential ID is failing, search for that ID in the logs, and check that it is successfully queried and that the credentials were extracted from the fields you expected.
You will also find any exceptions that the resolver throws in the logs, including errors locating a record or finding fields, or if it couldn't communicate with Keeper vault.
When creating or configuring a credential in the ServiceNow UI, you should be able to click "Test credential" to perform a quick targeted test. Select the MID server that should query Keeper vault, and select a target that the credential should work for to check that everything works as expected. If it doesn't, check the logs for errors and debug information as detailed above.