Skip to navigation
Platform On-PremControl accessSecretsHashiCorp Vault

Connect Platform to HashiCorp Vault

This page explains how to connect Itential Platform to HashiCorp Vault. When you connect Platform to Vault, you manage secrets in one place and keep credentials out of Platform configuration files.

Before you begin

Before you connect Platform to Vault, make sure you have the following.

HashiCorp Vault requirements

  • A running HashiCorp Vault installation. For instructions, see Install Vault in the HashiCorp documentation.
  • The kv-v2 secrets engine enabled. For instructions, see KV secrets engine version 2 in the HashiCorp documentation.
  • Authentication credentials, either a Vault token file or an AppRole role_id and secret_id.
  • Network connectivity between Platform and your Vault server.

Platform supports only the kv-v2 secrets engine.

Platform requirements

  • SSH access to the Platform servers.
  • Write access to the /etc/itential/platform.properties file, or permission to set environment variables.

Configure Platform

You can configure Platform to connect to Vault in any of the following ways:

Platform 6 supports all three methods. Platform 2023.2 supports only the server profile (properties.json) method.

Configuration parameters

Properties fileEnvironment variableServer profileDescription
vault_urlITENTIAL_VAULT_URLvaultProps.urlThe URL of the Vault server, including the hostname and port.
vault_auth_methodITENTIAL_VAULT_AUTH_METHODvaultProps.authMethodThe authentication method, either token or approle. The default is token.
vault_tokenITENTIAL_VAULT_TOKENvaultProps.tokenThe path to a file that contains the Vault authentication token. Required for token authentication.
vault_secrets_endpointITENTIAL_VAULT_SECRETS_ENDPOINTvaultProps.endpointThe secrets engine mount point with /data appended, for example kv-v2/data.
vault_read_onlyITENTIAL_VAULT_READ_ONLYvaultProps.readOnlyWhen true, Platform reads secrets from Vault but doesn’t write secrets back. The default is true.
vault_role_idITENTIAL_VAULT_ROLE_IDvaultProps.role_idThe AppRole role ID. Required for AppRole authentication.
vault_secret_idITENTIAL_VAULT_SECRET_IDvaultProps.secret_idThe AppRole secret ID. Required for AppRole authentication.
vault_approle_pathITENTIAL_VAULT_APPROLE_PATHNot availableThe Vault path where the AppRole auth method is enabled. Platform 6 only.
vault_connection_timeoutITENTIAL_VAULT_CONNECTION_TIMEOUTNot availableThe number of milliseconds to wait before a request to Vault times out. Platform 6 only.
vault_namespaceITENTIAL_VAULT_NAMESPACENot availableThe Vault Enterprise namespace. Required only for multi-tenant Vault Enterprise deployments. Platform 6 only.

The vault_secrets_endpoint value must include /data after the mount point. For example, if your kv-v2 engine is mounted at kv-v2, set the endpoint to kv-v2/data. Platform prepends /v1/ to build the full Vault API URL.

Configuration examples

vault_url=https://vault.company.com:8200
vault_auth_method=token
vault_token=/opt/vault/token.txt
vault_secrets_endpoint=kv-v2/data

Read-only mode

The readOnly property controls whether Platform can write secrets back to Vault.

When readOnly is true, which is the default:

  • Platform retrieves secrets from Vault but doesn’t write any values back.
  • Automatic property encryption is disabled.

When readOnly is false, Platform stores sensitive adapter and integration properties directly in Vault as it processes them. We don’t recommend this setting.

If you change readOnly from false to true after Platform stores secrets in Vault, those secrets become inaccessible. You must re-enter them manually in Itential.

Verify the connection

After you configure Platform, verify that it can connect to Vault.

1

Restart Platform

Restart Platform to apply your configuration changes.

2

View the configuration

In Admin Essentials, view the read-only Vault configuration:

  • Platform 6: Go to Admin Essentials > Configuration.
  • Platform 2023.2: Go to Admin Essentials > Profiles.
3

Check the Platform logs

Check the Platform logs for Vault messages:

# Platform 6
sudo journalctl -u itential-platform -f | grep -i vault
# Platform 2023.2
sudo journalctl -u automation-platform -f | grep -i vault

Confirm that the logs show successful authentication and no connection errors.

4

Test secret retrieval

Retrieve a test secret to validate your setup. For instructions, see Use secrets.

What’s next

Use secrets

Reference Vault secrets in your configurations.

Troubleshoot

Resolve common issues.