From 83523757643503c46ee420be997a24cb4c0653a9 Mon Sep 17 00:00:00 2001
From: aphorise <aphorise@gmail.com>
Date: Fri, 1 Jul 2022 11:47:03 +0200
Subject: [PATCH] Docs/ekm sql provider corrections and troubleshooting
 (#15968)

---
 .../docs/platform/mssql/installation.mdx      |  9 +++++++--
 .../docs/platform/mssql/troubleshooting.mdx   | 20 +++++++++++++++++++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/platform/mssql/installation.mdx b/website/content/docs/platform/mssql/installation.mdx
index 5508b380ea..562ec964bf 100644
--- a/website/content/docs/platform/mssql/installation.mdx
+++ b/website/content/docs/platform/mssql/installation.mdx
@@ -12,6 +12,7 @@ For upgrade instructions, see [upgrading](/docs/platform/mssql/upgrading).
 ## Prerequisites
 
 * Vault Enterprise server 1.9+ with a license for the Advanced Data Protection Key Management module
+* Microsoft Windows Server operating system
 * Microsoft SQL Server for Windows (SQL Server for Linux [does not support EKM][linux-ekm])
 * An authenticated Vault client
 
@@ -40,7 +41,7 @@ EKM provider to use it.
 
     ```bash
     vault auth enable approle
-    vault write auth/approle/role/tde-role \
+    vault write auth/approle/role/ekm-encryption-key-role \
         token_ttl=20m \
         max_token_ttl=30m \
         token_policies=tde-policy
@@ -158,6 +159,10 @@ installation.
     PROVIDER_KEY_NAME = 'ekm-encryption-key';
     ```
 
+    -> **Note:** This is the first step at which the EKM provider will communicate with Vault. If
+    Vault is misconfigured, this step is likely to fail. See
+    [troubleshooting](/docs/platform/mssql/troubleshooting) for tips on specific error codes.
+
 1. Create another login from the new asymmetric key:
 
     ```sql
@@ -244,4 +249,4 @@ GO
 ALTER DATABASE ENCRYPTION KEY
 ENCRYPTION BY SERVER ASYMMETRIC KEY TransitVaultAsymmetric;
 GO
-```
\ No newline at end of file
+```
diff --git a/website/content/docs/platform/mssql/troubleshooting.mdx b/website/content/docs/platform/mssql/troubleshooting.mdx
index 7766e7d8d2..e1bb6ca794 100644
--- a/website/content/docs/platform/mssql/troubleshooting.mdx
+++ b/website/content/docs/platform/mssql/troubleshooting.mdx
@@ -18,3 +18,23 @@ your issue, you can [enable trace logging](/docs/platform/mssql/configuration#en
 
 Restart SQL Server for the config change to take effect, and you should see more
 detailed logs in the same section of Windows Event Viewer.
+
+## Error Codes
+
+During installation, the EKM provider registers a manifest of coded event logs to aid debugging. You may see the following error codes during operation.
+
+### 2050 License Error
+
+The EKM provider was unable to verify that Vault has the correct license features. This
+could be due to:
+
+- An incompatible Vault Enterprise license - see the installation [prerequisites](/docs/platform/mssql/installation#prerequisites) for the required license feature.
+- Lack of network connectivity - Check Vault's audit logs to see if any requests are made to
+   authenticate via AppRole or query the `/sys/license/status` API.
+- Misconfigured AppRole auth - Ensure you provided the correct Role ID and Secret ID when
+   configuring the SQL Server `CREDENTIAL`. See the
+   [installation instructions](/docs/platform/mssql/installation) for an end-to-end working example.
+- Incorrect policy permissions - The EKM provider requires the `read` capability
+   on the path `sys/license/status`. See the `tde-policy` created in the
+   [installation instructions](/docs/platform/mssql/installation#configuring-vault)
+   for an example of a working policy.