Add ServiceNow credential resolver docs (#11996)

* Add ServiceNow credential resolver docs

* Add information about using system CAs

* Add field mappings and troubleshooting tips

website/content/docs/platform/servicenow/configuration.mdx

@@ -0,0 +1,85 @@
+---
+layout: docs
+page_title: Configure Vault ServiceNow Credential Resolver
+description: This section documents the configurables for the Vault ServiceNow Credential Resolver.
+---
+
+# Configuring the Vault Credential Resolver
+
+## MID server properties
+
+The following [properties] are supported by the Vault Credential Resolver:
+
+- `mid.external_credentials.vault.address` `(string: "")` - Address of Vault Agent as resolveable by the MID server.
+  For example, if Vault Agent is on the same server as the MID server it could be `https://127.0.0.1:8200`.
+
+- `mid.external_credentials.vault.ca` `(string: "")` - The CA certificate to trust for TLS in PEM format. If unset,
+  the system's trusted CAs will be used.
+
+- `mid.external_credentials.vault.tls_skip_verify` `(string: "")` - When set to true, skips verification of the Vault server
+  TLS certificiate. Setting this to true is not recommended for production.
+
+[properties]: https://docs.servicenow.com/bundle/quebec-servicenow-platform/page/product/mid-server/reference/r_MIDServerProperties.html#t_SetMIDServerProperties
+
+## Configuring discovery credentials
+
+To consume Vault credentials from your MID server, you will need to:
+
+* Create a secret in Vault
+* Configure the resolver to use that secret
+
+### Creating a secret in Vault
+
+The credential resolver supports reading credentials from the following secret engines:
+
+* [Active Directory](/docs/secrets/ad)
+* [AWS](/docs/secrets/aws)
+* [K/V v1](/docs/secrets/kv/kv-v1)
+* [K/V v2](/docs/secrets/kv/kv-v2)
+
+When creating K/V secrets, you must use the following keys for each component
+to ensure it is correctly mapped to ServiceNow's credential fields:
+
+Key         | Description                            | Supported aliases
+------------|----------------------------------------|------------------
+username    | The username                           | access_key
+password    | The password                           | secret_key, current_password
+private_key | The private SSH key                    |
+passphrase  | The passphrase for the private SSH key |
+
+Most ServiceNow credential types will expect at least a username and either
+a password or a private key. To help surface errors early, the credential
+resolver validates that a username and password are present for:
+
+* aws
+* basic
+* jdbc
+* jms
+* ssh_password
+* vmware
+* windows
+
+And the credential resolver expects the following types to specify at least
+a username and a private key:
+
+* api_key
+* cfg_chef_credentials
+* infoblox
+* sn_cfg_ansible
+* sn_disco_certmgmt_certificate_ca
+* ssh_private_key
+
+### Configuring the resolver to use a secret
+
+In the ServiceNow UI:
+
+* Navigate to "Discovery - Credentials" -> New
+  * Select a type from the list
+  * Tick "External credential store"
+  * Fill in a meaningful name
+  * Set "Credential ID" to the path in Vault where your secret is located, e.g.
+    for a KV v2 secret engine mounted at "secret", you might have a secret stored
+    under "ssh": `secret/data/ssh`. Check the [API docs](/api-docs/secret/) for
+    your secret engine if you are unsure of the path to use
+  * **Optional:** Click "Test credential" and select a MID server and a target
+    to test against to test everything is working

website/content/docs/platform/servicenow/index.mdx

@@ -0,0 +1,43 @@
+---
+layout: docs
+page_title: Vault ServiceNow Credential Resolver
+description: >-
+  The Vault Credential Resolver allows ServiceNow MID servers to use Vault as an enterprise-grade external secret store.
+---
+
+# Vault Credential Resolver
+
+ServiceNow® MID servers can use the Vault Credential Resolver to consume secrets
+directly from Vault for the purpose of performing discovery. See
+[installation](/docs/platform/servicenow/installation) and
+[configuration](/docs/platform/servicenow/configuration) for help getting started
+with the Vault Credential Resolver.
+
+## Overview
+
+ServiceNow uses MID servers deployed inside customer networks to perform
+agent-less discovery of their infrastructure. As infrastructure such as databases
+or servers are discovered, their attributes such as address and software versions
+are stored in a database. Naturally, this process requires a wide array of
+credentials. Customers can use ServiceNow's built-in credential storage, or install
+an external credential resolver to take advantage of their existing enterprise-grade
+secret storage solution.
+
+[![Architecture Overview](/img/servicenow-vault-credential-resolver-diagram.png)](/img/servicenow-vault-credential-resolver-diagram.png)
+
+The Vault Credential Resolver is one such resolver. The MID server will not
+store or cache any credentials marked as external, and will invoke the
+credential resolver each time it requires credentials.
+
+The Vault Credential Resolver is designed to communicate with a Vault Agent
+service installed on the same machine as the MID server. Authentication is
+handled between the Agent and Vault, and Vault Agent also handles caching and
+renewing leased secrets to ensure the load on Vault is minimized.
+
+### Features
+
+The following features are supported by the Vault Credential Resolver:
+
+- KV, Active Directory and AWS secret engines.
+- Communication with Vault via Vault Agent.
+- TLS communication with Vault Agent.

website/content/docs/platform/servicenow/installation.mdx

@@ -0,0 +1,88 @@
+---
+layout: docs
+page_title: Install Vault ServiceNow Credential Resolver
+description: Installation steps for the Vault ServiceNow Credential Resolver.
+---
+
+# Installing the Vault Credential Resolver
+
+## Prerequisites
+
+* ServiceNow version Quebec+ (untested on previous versions)
+* MID server version Quebec+ (untested on previous versions)
+* Discovery and external credential plugins activated on ServiceNow
+* Working Vault deployment accessible from the MID server
+
+## Installing Vault Agent
+
+* Select your desired auth method from Agent's [supported auth methods](/docs/agent/autoauth/methods)
+  and set it up in Vault
+  * For example, to set up AppRole auth and a role called `role1` with the `demo` policy attached:
+
+    ```bash
+    vault auth enable approle
+    vault write auth/approle/role/role1 bind_secret_id=true token_policies=demo
+    ```
+
+  * To get the files required for the example Agent config below, you can then
+    run:
+
+    ```bash
+    echo -n $(vault read -format json auth/approle/role/role1/role-id | jq -r '.data.role_id') > /path/to/roleID
+    echo -n $(vault write -format json -f auth/approle/role/role1/secret-id | jq -r '.data.secret_id') > /path/to/secretID
+    ```
+
+* Create an `agent.hcl` config file. Your exact configuration may vary, but you
+  must set `cache.use_auto_auth_token = true`, and the `listener`, `vault` and
+  `auto_auth` blocks are also required to set up a working Agent, e.g.:
+
+  ```
+  listener "tcp" {
+    address = "127.0.0.1:8200"
+    tls_disable = false
+    tls_cert_file = "/path/to/cert.pem"
+    tls_key_file = "/path/to/key.pem"
+  }
+
+  cache {
+    use_auto_auth_token = true
+  }
+
+  vault {
+    address = "http://vault.example.com:8200"
+  }
+
+  auto_auth {
+      method {
+          type = "approle"
+          config = {
+              role_id_file_path = "/path/to/roleID"
+              secret_id_file_path = "/path/to/secretID"
+              remove_secret_id_file_after_reading = false
+          }
+      }
+  }
+  ```
+
+* Install Vault Agent as a service running `vault agent -config=/path/to/agent.hcl`
+  * Documentation for Windows service installation [here](/docs/agent/winsvc)
+
+## Uploading JAR file to MID server
+
+* Download the latest version of the Vault Credential Resolver JAR file from
+  [releases.hashicorp.com](https://releases.hashicorp.com/vault-servicenow-credential-resolver/)
+* In ServiceNow, navigate to "MID server - JAR files" -> New
+  * Manage Attachments -> upload Vault Credential Resolver JAR
+  * Fill in name, version etc as desired
+  * Click Submit
+* Navigate to "MID server - Properties" -> New
+  * Set Name: `mid.external_credentials.vault.address`, Value: Address of Vault
+    Agent listener from previous step, e.g. `http://127.0.0.1:8200`
+  * **Optional:** Set the property `mid.external_credentials.vault.ca` to the
+    the trusted CA in PEM format if using TLS between the MID server and Vault
+    Agent with a self-signed certificate.
+
+## Next steps
+
+See [configuration](/docs/platform/servicenow/configuration) for details on
+configuring the resolver and using credentials for discovery.

website/content/docs/platform/servicenow/troubleshooting.mdx

@@ -0,0 +1,32 @@
+---
+layout: docs
+page_title: Troubleshooting the Vault ServiceNow Credential Resolver
+description: Troubleshooting tips for the Vault ServiceNow Credential Resolver.
+---
+
+# 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
+if it didn't find the minimum set of required fields as specified in
+[configuration](/docs/platform/servicenow/configuration#creating-a-secret-in-vault),
+or if it couldn't communicate with Vault.
+
+[log files]: https://docs.servicenow.com/bundle/quebec-servicenow-platform/page/product/mid-server/reference/r_MIDServerTroubleshooting.html
+
+## 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 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.

website/data/docs-nav-data.json

@@ -1334,6 +1334,10 @@
                 "title": "Overview",
                 "path": "platform/k8s/csi"
               },
+              {
+                "title": "Installation",
+                "path": "platform/k8s/csi/installation"
+              },
               {
                 "title": "Configurations",
                 "path": "platform/k8s/csi/configurations"
@@ -1341,10 +1345,6 @@
               {
                 "title": "Examples",
                 "path": "platform/k8s/csi/examples"
-              },
-              {
-                "title": "Installation",
-                "path": "platform/k8s/csi/installation"
               }
             ]
           }
@@ -1362,6 +1362,27 @@
             "path": "platform/aws-mp/run"
           }
         ]
+      },
+      {
+        "title": "ServiceNow",
+        "routes": [
+          {
+            "title": "Overview",
+            "path": "platform/servicenow"
+          },
+          {
+            "title": "Installation",
+            "path": "platform/servicenow/installation"
+          },
+          {
+            "title": "Configuration",
+            "path": "platform/servicenow/configuration"
+          },
+          {
+            "title": "Troubleshooting",
+            "path": "platform/servicenow/troubleshooting"
+          }
+        ]
       }
     ]
   },