diff --git a/website/content/docs/platform/servicenow/configuration.mdx b/website/content/docs/platform/servicenow/configuration.mdx new file mode 100644 index 0000000000..e9d9aeac88 --- /dev/null +++ b/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 diff --git a/website/content/docs/platform/servicenow/index.mdx b/website/content/docs/platform/servicenow/index.mdx new file mode 100644 index 0000000000..a440f126de --- /dev/null +++ b/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. diff --git a/website/content/docs/platform/servicenow/installation.mdx b/website/content/docs/platform/servicenow/installation.mdx new file mode 100644 index 0000000000..fd95764e21 --- /dev/null +++ b/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. diff --git a/website/content/docs/platform/servicenow/troubleshooting.mdx b/website/content/docs/platform/servicenow/troubleshooting.mdx new file mode 100644 index 0000000000..4eacd8db50 --- /dev/null +++ b/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. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 30adf1d746..c8c93df886 100644 --- a/website/data/docs-nav-data.json +++ b/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" + } + ] } ] }, diff --git a/website/public/img/servicenow-vault-credential-resolver-diagram.png b/website/public/img/servicenow-vault-credential-resolver-diagram.png new file mode 100644 index 0000000000..f7abed4501 Binary files /dev/null and b/website/public/img/servicenow-vault-credential-resolver-diagram.png differ