# HashiCorp Vault (Cloud) Secret Path Expressions

For information on how to configure the HashiCorp Vault (Cloud) credential provider, refer to [HashiCorp Vault (Cloud) Credential Provider](</connectors/credential_providers/hashicorp_cloud/help/index.html>).

Path syntax: `{path_to_secret}/{secretKey}`

Secret URL: `secrets://{HashiCorp_Source_Name}/{path_to_secret}/{secretKey}`

> [!IMPORTANT]
>
> The URL path should always start with the prefix, `secrets://`. Each URL should also be URL-encoded. Each URL attribute in the path is case-sensitive.

HashiCorp Vault (Cloud) supports static and dynamic secrets. Configure the required secret engines in the HashiCorp Vault (Cloud) server and provide their secret paths in the source.

1. Go to your HashiCorp secret engine's API document and locate the Get or Generate Credentials API section.
2. Configure the API path to get credentials.

   > **Note**
   >
   > Everything after the API version in the URL should be used in place of `<path to secret>`. For example, if the URL to fetch secrets is as follows:
   >
   > ```text
   > http://<vault host>/v1/azure/creds/my-role
   > ```
   >
   > Then the `<path to secret>` is as follows:
   >
   > ```text
   > azure/creds/my-role
   > ```
3. Define the key whose value needs to be read from the getCredentials API response for the `<secretKey>`. For example, consider the API response for getCredentials as follows:

   ```json
   {
       "data": {
           "client_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
           "client_secret": "9PfdaDP9qcf98ggw8WSttfVreFcN4q9c4m4x",
           ...
       }
   }
   ```

   If the secret expression wants the Client ID field from the connector source, then `<secretKey>` should be set to `client_id`.

Secret URL example:

**Before Encoding**

```text
secrets://<HashiCorp Source>/<mysecret/Admin User>/<Admin username>
```

Where:

- `<HashiCorp Source>` - Configured Credential Provider in the Credential Provider Section.
- `<mysecret/Admin User>` - Path to the secret.
- `<Admin username>` - Key to retrieve from the secret path.

**After Encoding**

```text
secrets://HashiCorp%20Source/mysecret%2FAdmin%20User/Admin%20username
```

> [!TIP]
>
> Use [urlencoder.org](<https://www.urlencoder.org/>) to encode your URL attributes.

> [!NOTE]
>
> By default, the HashiCorp Vault (Cloud) credential provider checks the `{secretKey}` in response to the following paths by default:
>
> - `$.`
> - `$.data`
> - `$.data.data`
>
> If any getCredentials API response returns `{secretKey}` from another path, then add the following entry key into the HashiCorp source XML for all those paths:
>
> ```text
> <entry key="secretPaths" value="path1,path2"/>
> ```
>
> For example:
>
> ```text
> <entry key="secretPaths" value="data.data.data,data.path1"/>
> ```
>
> For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication](<https://developer.sailpoint.com/docs/api/authentication/>) and [REST API - Update Source (Partial)](<https://developer.sailpoint.com/docs/api/update-source-v-1/>) in the SailPoint Developer Community.

## Example Configuration: Generating a Secret Expression for the K/V Version 2 Engine

You can fetch secrets from the K/V version 2 engine. For more information, refer to [Read secret version](<https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#read-secret-version>) in the *KV secrets engine - version 2 (API)* section of the HashiCorp developer documentation.

> [!NOTE]
>
> The linked document is not maintained by SailPoint and is subject to change without notice.

Path syntax: `{secret-mount-path/data/path to secret}/{secretKey}{?version=<versionNumber>}`

For example:

**Before Encoding**

```text
secrets://HashiCorp Source/StaticSecrets-v2/data/Active Directory/PASSWORD/Pass word
```

**After Encoding**

```text
secrets://HashiCorp%20Source/StaticSecrets-v2%2Fdata%2FActive%20Directory%2FPASSWORD/Pass%20word
```

Where:

- `HashiCorp Source` - Configured Credential Provider in the Credential Provider Section.
- `StaticSecrets-v2` - `secret-mount-path`.
- `Active Directory/PASSWORD` - Path to the secret.
- `Pass word` - Key to retrieve from the secret path.

Read Secret with version number example, after encoding:

```text
secrets://HashiCorp%20Source/StaticSecrets-v2%2Fdata%2FActive%20Directory%2FPASSWORD/Pass%20word?version=3
```

## Prefixes and Suffixes

If any secret paths have a prefix or a suffix, you must append a query parameter to the secret path as follows:

- To add a prefix - `?prefix=<prefix>`. For example, if the secret value returned after evaluation is `LocalAdmin`, but the complete value required by the secret field is `DomainOne\LocalAdmin` then the secret path expression will be as follows to add the required prefix:

  ```text
  secrets://HashiCorp%20Source/StaticSecrets-v2%2Fdata%2FActive%20Directory%2FPASSWORD/Pass%20word?prefix=DomainOne%5C
  ```
- To add a suffix - `?suffix=<suffix>`. For example, if the secret value returned after evaluation is `localadministrator`, but the complete value required by the secret field is `localadminstrator@sp.com` then the secret path expression will be as follows to add the required suffix:

  ```text
  secrets://HashiCorp%20Source/StaticSecrets-v2%2Fdata%2FActive%20Directory%2FPASSWORD/Pass%20word?suffix=%40sp.com
  ```

> [!IMPORTANT]
>
> All input parameters must be encoded.