# SailPoint HashiCorp Vault (On-Premise) Credential Provider Documentation

> HashiCorp Vault (On-Premise) Credential Provider Documentation

# Documentation

# Adding a New Credential Provider in SailPoint

Create a new credential provider integration in SailPoint to automatically rotate refreshed authentication credentials for configured sources.

To create a new credential provider:

1. Go to **Admin \> Connections \> Credential Providers**.
2. Select **Create New**.

   > **Screenshot**
   >
   > [![Credential Providers landing page with the Create New button highlighted](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/common/assets/img/landing_screen.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/common/assets/img/landing_screen.png>)
3. Search for the credential provider type and select **Configure**.

   > **Note**
   >
   > For a list of the available types of credential providers, as well as access to the documentation for each type, refer to the [Identity Security Connectors](<https://documentation.sailpoint.com/connectors/help/identity_security_connectors.html>) landing page.
4. Enter the following in the provided fields:

   - Enter a unique **Credential Provider Name** to help administrators differentiate it from others.
   - Enter a **Credential Provider Description**.
   - Select a **Credential Provider Owner** who is responsible for the credential provider's operations.
   - Select a **Virtual Appliance Cluster** with connectivity to the credential provider.
5. Select **Continue** to create the new credential provider with your selections.
6. (Optional) Enable credential caching. For more information, refer to [Caching Credentials](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/cred_caching.html>).

# Configure a Source to Use a Credential Provider

After you create a credential provider, you can begin configuring your sources to use it for authentication. When you use a credential provider in a source configuration, any authentication fields you need to configure allow you to use the credential provider or use static authentication credentials.

To configure your source to use a credential provider:

1. In the source's **Base Configuration** tab, select **Use a Credential Provider**.

   > **Note**
   >
   > Enabling a credential provider in your connector adds an additional 30-second timeout for each connector operation.
2. Toggle every secret field in the configuration pages which should use the credential provider to **Credential Path**. The field changes to accept the secret path expression for the credential provider instead of the static value.

   > **Screenshot**
   >
   > **Static Value**
   >
   > [![Static Value field selected](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/conn_field_static_2.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/conn_field_static_2.png>)
   >
   > **Credential Path**
   >
   > [![Credential Path field selected](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/conn_field_cred_path_2.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/conn_field_cred_path_2.png>)
3. Enter the secret path expression for the credential provider into the **Credential Path** field.

> [!NOTE]
>
> For a list of all available SailPoint credential provider path expressions, refer to [Credential Provider Secret Path Expressions](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/secret_path_expressions.html>).

# Configuring HashiCorp Vault (On-Premise)

## Base Configuration

Provide the base configuration parameters. Information you entered during the initial creation of the credential provider is automatically entered into the fields in the **Base Configuration** page. You can edit this information if necessary.

> [!NOTE]
>
> **Screenshot**
>
> [![Base Configuration](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/base_config.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/base_config.png>)

> [!NOTE]
>
> Ensure that the name and description of each credential provider is unique.

1. Go to **Admin \> Connections \> Credential Providers**.
2. Search for the credential provider you want to edit.
3. Enter a unique **Credential Provider Name**.
4. Enter a **Credential Provider Description** that provides details necessary to distinguish it from similar credential providers.
5. Select a **Credential Provider Owner** by typing the owner's name into the field provided. Matches display after you type at least two letters. Select the credential provider owner as required.
6. Select a **Virtual Appliance Cluster** with connectivity to the credential provider. For more information about configuring and deploying virtual appliances, refer to the [Virtual Appliance Reference Guide](<https://documentation.sailpoint.com/saas/help/va/index.html>).
7. Select **Save**.

## Connection Settings

Configure the authentication parameters to connect to and authenticate with the HashiCorp Vault (On-Premise) host.

> [!NOTE]
>
> **Screenshot**
>
> [![Connection Settings](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/connection_settings.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/connection_settings.png>)

1. Enter the **Host URL** for the HashiCorp Vault (On-Premise) secret server.
2. Enter the URL-encoded **Namespace** path to use for the HashiCorp Vault (On-Premise) secret server.

   > **Important**
   >
   > Don't encode the last slash (`/`) in your Namespace. For example, if your Namespace is `xyz/pqr abcd/`, then encode only `xyz/pqr abcd`.

   > **Tip**
   >
   > Use [urlencoder.org](<https://www.urlencoder.org/>) to encode your URL attributes.
3. Under **Authentication Type**, select either **Userpass**, **AppRole**, or **JWT**. Then, enter the supporting information required to complete the authentication. Select one of the following to complete the authentication setup:

   - [Userpass](<#userpass>)
   - [AppRole](<#approle>)
   - [JWT](<#jwt>)

### Userpass

Configure userpass authentication to complete the connection setup.

> [!NOTE]
>
> **Screenshot**
>
> [![Userpass](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/auth_userpass_2.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/auth_userpass_2.png>)

1. In the HashiCorp Vault (On-Premise) server, enable the Userpass authentication method and add the required users in it. The users should have permission to fetch the secrets.
2. In SailPoint, enter the configuration parameters to use the HashiCorp Userpass authentication.

   1. Enter the URL-encoded **Authentication Provider Path** used to authenticate with the HashiCorp Vault (On-Premise) secret server.

      > **Important**
      >
      > Don't encode the last slash (`/`) in your Authentication Provider path. For example, if your Authentication Provider path is `xyz/pqr abcd/`, then encode only `xyz/pqr abcd`.

      > **Tip**
      >
      > Use [urlencoder.org](<https://www.urlencoder.org/>) to encode your URL attributes.
   2. Enter the **Username** and **Password** to authenticate with HashiCorp Vault (On-Premise).
   3. (Optional) Enable credential caching. For more information, refer to [Caching Credentials](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/cred_caching.html>).
   4. Select **Save**.

### AppRole

Configure AppRole authentication to complete the connection setup.

> [!NOTE]
>
> The linked documents on this page are not maintained by SailPoint and are subject to change without notice.

> [!NOTE]
>
> **Screenshot**
>
> [![AppRole](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/auth_approle_2.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/auth_approle_2.png>)

1. Do the following in the HashiCorp Vault (On-Premise) server to configure the authentication role:

   1. Enable the AppRole authentication using the following command:

      ```text
      vault auth enable approle
      ```
   2. Create a new role for the AppRole authentication method using the HashiCorp API. Be sure to add the required policies for AppRole to access the secrets. For more information, refer to [Create/Update AppRole](<https://developer.hashicorp.com/vault/api-docs/auth/approle#create-update-approle>) in the HashiCorp documentation.
   3. Read the role ID for the new role using the HashiCorp API. For more information, refer to [Read AppRole role ID](<https://developer.hashicorp.com/vault/api-docs/auth/approle#read-approle-role-id>) in the HashiCorp documentation.
   4. Create a secret ID for the new role using the HashiCorp API. For more information, refer to [Generate new secret ID](<https://developer.hashicorp.com/vault/api-docs/auth/approle#generate-new-secret-id>) in the HashiCorp documentation.

      > **Important**
      >
      > While creating the secret ID, keep the values for `num_uses` and `ttl` set to `0`.
2. In SailPoint, enter the configuration parameters to use the HashiCorp AppRole authentication.

   1. Enter the URL-encoded **Authentication Provider Path** used to authenticate with the HashiCorp Vault (On-Premise) secret server.

      > **Important**
      >
      > Don't encode the last slash (`/`) in your Authentication Provider path. For example, if your Authentication Provider path is `xyz/pqr abcd/`, then encode only `xyz/pqr abcd`.

      > **Tip**
      >
      > Use [urlencoder.org](<https://www.urlencoder.org/>) to encode your URL attributes.
   2. Enter the **Role ID** and its **Secret ID** created in the HashiCorp Vault (On-Premise) server.
   3. (Optional) Enable credential caching. For more information, refer to [Caching Credentials](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/cred_caching.html>).
   4. Select **Save**.

### JWT

Configure JWT authentication to complete the connection setup.

> [!NOTE]
>
> The linked documents on this page are not maintained by SailPoint and are subject to change without notice.

> [!NOTE]
>
> **Screenshot**
>
> [![JWT](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/auth_jwt_2.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/auth_jwt_2.png>)

1. Do the following in the HashiCorp Vault (On-Premise) server to configure JWT authentication:

   1. Enable JWT authentication using the HashiCorp API. For more information, refer to [JWT/OIDC auth method (API)](<https://developer.hashicorp.com/vault/api-docs/auth/jwt>) in the HashiCorp documentation. Provide the following while enabling JWT:

      - `jwt_validation_pubkeys` - Public key required for JWT.
      - `bound_issuer` - Required issuer value.
      - `jwt_supported_algs` - `RS256`.

        > **Note**
        >
        > RS256 is the only supported algorithm.
   2. Create a role for JWT authentication using the HashiCorp API. For more information, refer to [Create/Update role](<https://developer.hashicorp.com/vault/api-docs/auth/jwt#create-update-role>) in the HashiCorp documentation. Provide the following values while configuring the role:

      - `bound_subject` - Required subject value for authentication.
      - `user_claim` - Required `user` claim.
      - `bound_audiences` - Required value for the `aud` claim.
      - `role_type` - `JWT`.
      - `policies` - Provide required policies to fetch the secrets.
   3. In SailPoint, enter the configuration parameters to use HashiCorp JWT authentication.
   4. Enter the URL-encoded **Authentication Provider Path** used to authenticate with the HashiCorp Vault (On-Premise) secret server.

      > **Important**
      >
      > Don't encode the last slash (`/`) in your Authentication Provider path. For example, if your Authentication Provider path is `xyz/pqr abcd/`, then encode only `xyz/pqr abcd`.

      > **Tip**
      >
      > Use [urlencoder.org](<https://www.urlencoder.org/>) to encode your URL attributes.
   5. Enter the name of the **JWT Role**.
   6. Enter the **User Claim for JWT**.
   7. Enter the **User Claim Value**.
   8. In the **Subject** field, enter the `bound_subject` value for the JWT role.
   9. In the **Issuer** field, enter the `bound_issuer` value for JWT authorization.
   10. In the **Audience** field, enter the `bound_audiences` value for the JWT role.
   11. Enter the **Private Key** used to assert the JWT.

       > **Note**
       >
       > The private key should be in standard PKCS \#1 format. Currently, SailPoint doesn't support private keys in PKCS \#8 format.
   12. Enter the **Private Key Password**.

       > **Note**
       >
       > This is only required if the private key is encrypted with a passphrase.

       1. (Optional) Enable credential caching. For more information, refer to [Caching Credentials](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/cred_caching.html>).
       2. Select **Save**.

## Additional Settings

Configure settings related to how the connector handles dynamic secrets, as well as additional encryption for secrets while in transport.

> [!NOTE]
>
> **Screenshot**
>
> [![Additional Settings](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/additional_settings.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/additional_settings.png>)

### Credential Wait Time

Some generated dynamic secrets may require additional time to activate at endpoint systems. These endpoint systems may include Microsoft Azure or Amazon Web Services, among others. To compensate for this additional time requirement, configure an additional wait time:

1. In the **Credential Wait Time in Seconds** field, enter the duration the credential provider should wait in seconds. The default is 10 seconds and the maximum is 90 seconds. The recommended value should be greater than 10 seconds, though the value may vary for end system configurations.
2. Select **Save**.

### Response Wrapping

Response wrapping adds an extra layer of security to the secret information during transport processes. To use response wrapping:

1. Select **Enable Response Wrapping**. The **Response Wrapping TTL in Seconds** field displays.
2. In the **Response Wrapping TTL in Seconds** field, define the response wrapping time-to-live in seconds. The default value is 10 seconds. The minimum value is 10 seconds and the maximum value is 30 seconds.
3. Select **Save**.

# Caching Credentials

SailPoint credential providers can save the credentials it receives from the systems they manage to cache. Cached credentials may expire after a period of time and need to be refreshed. Credential providers can't use expired credentials saved to cache.

> [!NOTE]
>
> **Screenshot**
>
> [![Enable Credentials Caching checkbox](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/cred_caching.png>)](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/img/cred_caching.png>)

To enable credential caching for credential providers:

1. Sign in to SailPoint.
2. Go to **Admin \> Connections \> Credential Providers**.
3. Search for the credential provider that you want to enable caching on and select its name.
4. Select **Edit Configuration**.
5. Select the **Enable Credentials Caching** checkbox.

   > **Note**
   >
   > The option to enable this feature may be in a different configuration tab depending on your selected credential provider.
6. Select **Save**.

## Credentials Expiration

Depending on the managed system the credential provider is connected to, the credentials may have an expiration time limit. The credential provider uses the following hierarchy to determine expiration, with the highest priority first and the lowest priority last:

1. If the credentials received from the managed system contain an expiration time, then they are cached until that expiration time.
2. If the credentials received from the managed system don't contain an expiration time, then you can add one by configuring the `expirationTimeInSeconds` attribute in the source of credential provider using APIs.

   > **Note**
   >
   > 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.
3. If the credentials received from the managed system don't contain an expiration time and you don't create one via APIs, then by default the credentials expire after one day.

# HashiCorp Vault (On-Premise) Credential Provider

The SailPoint HashiCorp Vault (On-Premise) credential provider offers credential cycling for added security in configured SailPoint connectors. This credential provider fetches refreshed, uncompromised authorization credentials from HashiCorp Vault (On-Premise) to authenticate sources in SailPoint.

This guide discusses how to manage a HashiCorp Vault (On-Premise) credential provider.

For information on creating a new HashiCorp Vault (On-Premise) credential provider, refer to [Adding a New Credential Provider in SailPoint](<https://documentation.sailpoint.com/connectors/credential_providers/hashicorp_onprem/help/config_new_cred_prov.html>).

## Prerequisites

Before you configure your credential provider, you must consider the following prerequisite items.

- Use a supported authentication type:

  - Userpass
  - AppRole
  - JWT (Static Key)
- If the HashiCorp Vault (On-Premise) secret server is configured to communicate using HTTPS, the required certificate needs to be in the VA server in `/home/sailpoint/certificates directory`.
- For VA-based Deep Governance connectors, the source and credential provider virtual appliances must be in the same cluster.
- VA-based Deep Governance connectors, SaaS-based Deep Governance, Discovery, and Quick Compliance connectors now support the use of credential providers.

## Supported Platforms

This credential provider supports the following platforms:

- HashiCorp Vault (On-Premise) version 1.16.2 or later

# HashiCorp Vault (On-Premise) Credential Provider Secret Path Expressions

Use the path expressions listed in this topic to use the HashiCorp Vault (On-Premise) credential provider in your source authentication configurations.

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 (On-Premise) supports static and dynamic secrets. Configure the required secret engines in the HashiCorp Vault (On-Premise) 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 (On-Premise) 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.