ServiceNow

Keeper credential storage integration with ServiceNow

About

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.

Features

• 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

Use Cases

On-demand Discovery

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).

Incident Response

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.

Custom Credential Provider

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.

Prerequisites

• 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 Keeper Secrets Manager Application with secrets shared to it

  • See the Quick Start Guide for instructions on creating an Application

• A ServiceNow instance with External Credential Storage plugin enabled

Setup

1. External Credential Storage (requires admin role)

• The External Credential Storage plugin must be active.

• The Enable External Credential Storage Discovery property is enabled.

System property:

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.

2. Installing Keeper Credential Resolver

• Download the latest version of Keeper Credential Resolver JAR file from here.

• 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

  • Set Name: ext.cred.keeper.ksm_config, Value: base64 version of the configuration generated for the corresponding KSM Application.

  • Optional: Set the property ext.cred.keeper.ksm_label_prefix to the desired prefix (by default resolver uses mid_ as a label prefix)

  • Optional: Set the property ext.cred.keeper.use_ksm_cache to "true" to enable caching (use when you expect at least a few thousand requests per 10 seconds)

Alternatively you can edit config.xml directly (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.

3. Configuring discovery credentials

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

Creating a secret in Keeper vault and mapping fields

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_credential table) 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 text, multiline or hidden depending 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.

Examples:

• 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 Login and manually add custom fields of type hidden with labels mid_ssh_private_key, and mid_ssh_passphrase (optional)

• Credential type gcp - map to Keeper record type File Attachment/Photo and manually add the required custom fields mid_email - text, mid_secret_key - hidden.

Finding credentials in Keeper vault

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:title The second format also allows searches by record type only or by title only (or both, but single ":" is invalid combination)

When using type:title format 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: ABCDABCDABCDABCDABCDAB

• Find by type and title - Credential ID: login:MyLogin

• Find by title - Credential ID: :MyLogin

• Find by type - Credential ID: login:

Configuring the resolver to use a secret

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 type:title or just :title and 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

Throttles and cache

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 ext.cred.keeper.use_ksm_cache parameter to "true" in config.xml and restarting the MID Server. Cached data is stored in an encrypted file ksm_cache.dat in MID Server's work folder. Cache is updated at most once every 5 minutes or with the next request.

Troubleshooting

Check the logs

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.

Use the Test credential feature

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.