From 76e3cc6aac0be91b710f23799b5427869faba413 Mon Sep 17 00:00:00 2001
From: hc-github-team-secure-vault-core
 <82990506+hc-github-team-secure-vault-core@users.noreply.github.com>
Date: Fri, 14 Jan 2022 10:04:25 -0500
Subject: [PATCH] Backport of docs: update oracle tls examples into
 stable-website (#13665)

This pull request was automerged via backport-assistant
---
 .../content/docs/secrets/databases/oracle.mdx | 70 ++++++++++++++++++-
 1 file changed, 68 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/secrets/databases/oracle.mdx b/website/content/docs/secrets/databases/oracle.mdx
index bcdc6b9be6f2..718387afed18 100644
--- a/website/content/docs/secrets/databases/oracle.mdx
+++ b/website/content/docs/secrets/databases/oracle.mdx
@@ -106,13 +106,16 @@ pluggable databases rather than the container database in the `connection_url` f
 
 ### Connect Using SSL
 
+~> **Note**: The wallets used when connecting via SSL should be available on every Vault 
+server when using high availability clusters.
+
 If the Oracle server Vault is trying to connect to uses an SSL listener, the database
 plugin will require additional configuration using the `connection_url` parameter:
 
 ```shell
 vault write database/config/oracle \
   plugin_name=vault-plugin-database-oracle \
-  connection_url='{{ username }}/{{ password }}@tcps://<host>:port/<service_name>?param1=...&param2=...&...'\
+  connection_url='{{ username }}/{{ password }}@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=<host>(PORT=<port>))(CONNECT_DATA=(SERVICE_NAME=<service_name>))(SECURITY=(SSL_SERVER_CERT_DN="<cert_dn>")(MY_WALLET_DIRECTORY=<path_to_wallet>)))'
   allowed_roles="my-role" \
   username="admin" \
   password="password"
@@ -124,12 +127,75 @@ to use for connection and verification could be configured using:
 ```shell
 vault write database/config/oracle \
   plugin_name=vault-plugin-database-oracle \
-  connection_url='{{ username }}/{{ password }}@tcps://<host>:port/<service_name>?ssl_server_cert_dn="CN=hashicorp.com,OU=TestCA,O=HashiCorp=com"&wallet_location="/etc/oracle/wallets"' \
+  connection_url='{{ username }}/{{ password }}@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=hashicorp.com)(PORT=1523))(CONNECT_DATA=(SERVICE_NAME=ORCL))(SECURITY=(SSL_SERVER_CERT_DN="CN=hashicorp.com,OU=TestCA,O=HashiCorp=com")(MY_WALLET_DIRECTORY=/etc/oracle/wallets)))'
   allowed_roles="my-role" \
   username="admin" \
   password="password"
 ```
 
+### Using TNS Names
+
+~> **Note**: The `tnsnames.ora` file and environment variable used when connecting via SSL should 
+be available on every Vault server when using high availability clusters.
+
+Vault can optionally use TNS Names in the connection string when connecting to Oracle databases using a `tnsnames.ora` file. An example 
+of a `tnsnames.ora` file may look like the following:
+
+```shell
+AWSEAST=
+(DESCRIPTION =
+  (ADDRESS = (PROTOCOL = TCPS)(HOST = hashicorp.us-east-1.rds.amazonaws.com)(PORT = 1523))
+  (CONNECT_DATA =
+    (SERVER = DEDICATED)
+    (SID = ORCL)
+  )
+  (SECURITY =
+      (SSL_SERVER_CERT_DN = "CN=hashicorp.rds.amazonaws.com/OU=RDS/O=Amazon.com/L=Seattle/ST=Washington/C=US")
+      (MY_WALLET_DIRECTORY = /etc/oracle/wallet/east)
+  )
+)
+
+AWSWEST=
+(DESCRIPTION =
+  (ADDRESS = (PROTOCOL = TCPS)(HOST = hashicorp.us-west-1.rds.amazonaws.com)(PORT = 1523))
+  (CONNECT_DATA =
+    (SERVER = DEDICATED)
+    (SID = ORCL)
+  )
+  (SECURITY =
+      (SSL_SERVER_CERT_DN = "CN=hashicorp.rds.amazonaws.com/OU=RDS/O=Amazon.com/L=Seattle/ST=Washington/C=US")
+      (MY_WALLET_DIRECTORY = /etc/oracle/wallet/west)
+  )
+)
+```
+
+To configure Vault to use TNS names, set the following environment variable on the Vault server:
+
+```shell
+TNS_ADMIN=/path/to/tnsnames/directory
+```
+
+~> **Note**: If Vault returns a "could not open file" error, double check that this environment 
+variable is available to the Vault server.
+
+Finally, use the alias in the `connection_url` parameter on the database configuration:
+
+```
+vault write database/config/oracle-east \
+    plugin_name=vault-plugin-database-oracle \
+    connection_url="{{ username }}/{{ password }}@AWSEAST" \
+    allowed_roles="my-role" \
+    username="VAULT_SUPER_USER" \
+    password="myreallysecurepassword"
+
+vault write database/config/oracle-west \
+    plugin_name=vault-plugin-database-oracle \
+    connection_url="{{ username }}/{{ password }}@AWSWEST" \
+    allowed_roles="my-role" \
+    username="VAULT_SUPER_USER" \
+    password="myreallysecurepassword"
+```
+
 ## Usage
 
 ### Dynamic Credentials