Troubleshooting
Problem
When using a TNS alias, the Vault Oracle Database Plugin relies on the Oracle Client libraries to resolve the alias through the Oracle network configuration files.
The issue typically occurs when one or more of the following conditions exist:
- The tnsnames.ora file is missing.
- The TNS alias is incorrectly defined.
- The TNS_ADMIN environment variable is not configured for the Vault process.
- The Vault service cannot access the Oracle network configuration directory.
- The Oracle Client installation is incomplete or incorrectly configured.
- The database host, port, or service name specified in the TNS entry is incorrect.
- Network connectivity between the Vault server and the Oracle database is unavailable.
Symptom
Users encounter connection failures when configuring the Vault Oracle Database Plugin using a TNS alias in the connection_url, such as:
connection_url="{{username}}/{{password}}@RDS_ORCL"
Common symptoms include:
- Vault fails to save or validate the database configuration.
- Dynamic credential generation fails.
- Oracle connection errors are returned during configuration or credential requests.
- Errors similar to the following may be observed in Vault logs:
ORA-12154: TNS:could not resolve the connect identifier specified
or
ORA-12514: TNS listener does not currently know of service requested
or
ORA-12541: TNS:no listener
Cause
Oracle TNS aliases instead of embedding full Oracle connection descriptors directly within the Vault database configuration. However, there is often uncertainty regarding whether the Vault Oracle Database Plugin can successfully resolve TNS aliases through Oracle client configuration files.
This validation was performed to verify that:
- The Vault Oracle Database Plugin can use a TNS alias defined in a tnsnames.ora file.
- The Oracle client configuration is properly inherited by the Vault process through the TNS_ADMIN environment variable.
- Dynamic credential generation functions correctly when a TNS alias is used in the connection_url.
- TNS-based connectivity can be used as an alternative to a full Oracle connection descriptor.
Environment
Applicable to UAT, DEV, and PROD environments.
Diagnosing The Problem
1. Verify the TNS Alias Definition
Check the contents of the tnsnames.ora file:
cat /opt/oracle/tns_admin/tnsnames.ora
Example:
RDS_ORCL =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = database.example.com)(PORT = 1521))
(CONNECT_DATA =
(SERVICE_NAME = ORCL)
)
)
Confirm that the alias used in Vault matches the alias defined in the file.
2. Verify TNS_ADMIN is Available to Vault
Identify the Vault process:
PID=$(pgrep -f vault)
Check the environment variables:
cat /proc/$PID/environ | tr '\0' '\n' | grep TNS_ADMIN
Expected output:
TNS_ADMIN=/opt/oracle/tns_admin
If no output is returned, Vault will not be able to locate the tnsnames.ora file.
3. Verify Oracle Client Connectivity
Use Oracle client tools from the Vault host.
sqlplus admin/password@RDS_ORCL
Successful connectivity confirms that the Oracle Client can resolve the TNS alias independently of Vault.
4. Verify Vault Database Configuration
Review the database configuration:
vault read database/config/my-oracle-database-tns
Confirm:
verify_connection = true
plugin_name = vault-plugin-database-oracle
5. Test Dynamic Credential Generation
Request credentials:
vault read database/creds/my-role-tns
If credentials are generated successfully, Vault can resolve the TNS alias and communicate with the database.
Resolving The Problem
Step 1: Create the Oracle Network Configuration
Create the TNS configuration directory:
mkdir -p /opt/oracle/tns_admin
Create the tnsnames.ora file containing the database connection information:
RDS_ORCL =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = database.example.com)(PORT = 1521))
(CONNECT_DATA =
(SERVICE_NAME = ORCL)
)
)
Step 2: Configure TNS_ADMIN for Vault
Add the following environment variable to the Vault service configuration:
Environment="TNS_ADMIN=/opt/oracle/tns_admin"
Reload systemd and restart Vault:
systemctl daemon-reload
systemctl restart vault
Step 3: Configure the Vault Database Connection
Configure the Oracle database using the TNS alias:
vault write database/config/my-oracle-database-tns \
plugin_name="vault-plugin-database-oracle" \
allowed_roles="my-role-tns" \
connection_url="{{username}}/{{password}}@RDS_ORCL" \
username="admin" \
password="<password>"
Step 4: Create a Dynamic Role
vault write database/roles/my-role-tns \
db_name="my-oracle-database-tns" \
default_ttl="1h" \
max_ttl="24h" \
creation_statements='CREATE USER {{username}} IDENTIFIED BY "{{password}}"; GRANT CONNECT TO {{username}}; GRANT CREATE SESSION TO {{username}};'
Step 5: Validate Functionality
Generate credentials:
vault read database/creds/my-role-tns
Successful credential generation confirms:
- The TNS alias is being resolved correctly.
- The Oracle Client is functioning properly.
- Vault can connect to the Oracle database.
- Dynamic user creation is working as expected.
Related Information
Document Location
Worldwide
Was this topic helpful?
Document Information
Modified date:
20 September 2026
UID
ibm17287745