# SailPoint HashiCorp Vault Integration (Cloud) Connector Documentation > HashiCorp Vault Integration (Cloud) Connector Documentation # Documentation # Connecting SailPoint and HashiCorp Vault Integration (Cloud) To connect SailPoint with HCP Vault Dedicated, perform the following tasks: ## Adding the Source in SailPoint To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs. 1. Sign in to SailPoint. 2. Go to **Admin \> Connections \> Sources**. 3. Select **Create New**. 4. Search for the connector by entering the name in the search box, and then select **Actions**. 5. In the **Actions** dropdown list, select the setup method: - [**Express Setup**](<#configuring-a-source-using-express-setup>) - Quickly create a read-only connection to your target system by providing minimal configurations and authentication. On completion, aggregation is automatically started. > **Note** > > Express Setup supports Credential Providers. For information on supported credential providers and configuration, refer to [Credential Providers](). For more information, contact your SailPoint Customer Service Manager. - [**Standard Setup**](<#configuring-a-source-using-standard-setup>) - Provide detailed basic configuration to create the source. Once the source is created, continue with source setup. ### Configuring a Source Using Express Setup Express Setup minimizes the initial configuration process so you can quickly connect the application and immediately begin aggregating user account and entitlement data. 1. Review the directions and select **Start Express Setup**. 2. Review the pre-populated **Source Name**, **Source Owner**, and **Description**. To update, select **Edit**. > **Note** > > The source name must be unique. You can change these settings later in the source configuration. 3. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider. > **Note** > > To add a Credential Provider in SailPoint, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](). 4. Configure the authentication to allow SailPoint to connect to the source. For more information, refer to the **Connection Settings** section. 5. Select **Finish**. After a successful test connection, the system creates your source and prompts you to run an aggregation. - If you want to aggregate now, select **Aggregate**. - To see the latest account aggregation history, go to **Account Management \> Account Aggregation**. - To see the list of aggregated source accounts, go to **Account Management \> Accounts**. - If you want to aggregate later, select **Exit**. This returns you to the **Sources** page. Your new source is listed, but contains no accounts or aggregation history yet. ### Configuring a Source Using Standard Setup Use Standard Setup to configure the connector for full feature support. 1. In the **Source Name** field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters. 2. In the **Description** field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters. 3. In the **Source Owner** field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to [Assigning a Source Owner](). 4. (Optional) Select a governance group to grant its members [source]() or [role]() sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](). 5. If this source represents a primary system containing your organization's personnel records, select the **Authoritative Source** checkbox. For more information, refer to [Creating Identity Profiles](). 6. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there. ## Base Configuration Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary. 1. Enter a unique name and description for the source. 2. In the **Source Owner** dropdown list, select the identity that owns this source. - To find a source owner, begin entering their name. 3. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider. > **Note** > > To add a credential provider, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](). 4. Configure the authentication to allow SailPoint to connect to the source. Refer to [Connection Settings](<#connection-settings>) for more information. 5. (Optional) In the **Governance Group for Source Management** dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to [Associating Governance Groups with a Source](). 6. (Optional) Select **Create Manual Work Items** to allow the connector to create manual work items for certain operations. You can also enable this option so the source supports additional source management features such as creating accounts and access profile management. > **Important** > > Once you enable this feature, you cannot disable it. For more information on manual work items in SailPoint, refer to [Work Items](). For more information on SailPoint features, refer to [SailPoint Identity Services](). 7. Select **Save**. ## Connection Settings Enter the values required to connect to the target HCP Vault Dedicated namespace. | Field | Description | | --- | --- | | **Vault Cluster URL** | Enter the HTTPS URL for the HCP Vault Dedicated cluster. | | **Vault Namespace** | Enter the target Vault namespace. The connector accesses one namespace. | | **Role ID** | Enter the Role ID that you generated for the AppRole in Vault. | | **Secret ID** | Enter the Secret ID that you generated in Vault. | When you save the source, SailPoint exchanges the Role ID and Secret ID for a namespace-scoped client token. The connector uses the client token to read metadata through the Vault REST APIs. ## Review and Test Perform a test to confirm the connection to SailPoint. 1. Go to **Review and Test**. 2. Confirm that the entries in each field are correct. If you note any mistakes, return to the section and make corrections. 3. Select **Test Connection**. # Dataset Management Dataset Management lets you review the object types a source collects and control how the source aggregates those objects into SailPoint. Use Dataset Management to view and manage resource attributes, datasets and their resources, enable dataset aggregation schedules, perform manual aggregation, and view aggregation history. > [!NOTE] > > Datasets are also available in SailPoint Agentic Fabric. Contact your Customer Success team and refer to [SailPoint Agentic Fabric]() for more information. For more information, refer to [Managing Datasets and Resources]() for datasets, resources, owner correlation, and aggregation. ## Datasets A *dataset* is a named group of one or more related resources that the source aggregates together. When aggregation runs for a dataset, the source collects all resources in that dataset from the managed system in one aggregation job. Activate or deactivate aggregation at the dataset level, not for individual resources. > [!NOTE] > > Each resource belongs to exactly one dataset for that source. The source defines which resources belong to each dataset. You can enable aggregation and review associated resources, but you cannot create or delete datasets or move resources between them. ### Dataset Aggregation Configure aggregation on the **Dataset Aggregations** tab for each dataset. Configure each dataset separately. During aggregation, your owner correlation rules are automatically applied to link machine identities to their human owners. For more information, refer to [Configuring Dataset Aggregations](). ## Resources A resource defines an object type from the managed system. It specifies the kind of object, the attributes the source collects, and how the source identifies and displays each object. Resources form the building blocks of the data model. In the UI, each resource appears under **Dataset Management** \> **Resources** with its schema. A resource does not run aggregation by itself. The dataset that owns the resource collects it during aggregation. For more information, refer to [Managing Resources](). ### Owner Correlation Configure owner correlation on each resource to link aggregated objects to human owners. If you do not configure owner correlation, or if the mapping produces no match, an owner is not assigned. For more information, refer to [Configuring Owner Correlation](). ## Supported Datasets Go to **Dataset Management \> Datasets** on your HashiCorp Vault Integration (Cloud) source to view the datasets the connector aggregates. Select a dataset to review its associated resources and configure aggregation. > [!NOTE] > > Configure aggregation for each dataset separately. For more information, refer to [Dataset Aggregation](). | Dataset name | Associated resources | Description | Aggregation schedule | | --- | --- | --- | --- | | **Vault Accounts** | [Vault Agent and Machine](<#vault-agent-and-machine>), [Vault Service Account](<#vault-service-account>) | AppRole and Kubernetes authentication roles resolved to Vault identity entities, including owners, policies, and groups. Emits agent-machine rows for AppRole roles and service-account rows for Kubernetes roles. | Disabled | | **Vault Secrets** | [Vault Secret](<#vault-secret>) | KV v2 secret metadata. The connector does not collect secret payloads. Ownership is resolved from the writing entity. | Disabled | | **Vault API Keys** | [Vault API Key](<#vault-api-key>) | Dynamic cloud secret-engine roles (AWS, Azure, and GCP) that issue credentials. Ownership is resolved from the granting policy and entity. | Disabled | | **Vault Tokens / PATs** | [Vault Token / PAT](<#vault-token-pat>) | Token accessor metadata (never token strings): policies, TTL/lifecycle, owner tags. Sourced from LIST auth/token/accessors + POST auth/token/lookup-accessor. | Disabled | The aggregation schedule is disabled until you enable it. Set the schedule in **Dataset Management \> Datasets**. For resource details, refer to [Supported Resources](<#supported-resources>). ## Supported Resources A resource represents a type of object the connector collects from HashiCorp Vault. Each resource defines the attributes collected for that object type and how each object appears in SailPoint. For more information, refer to [Managing Resources](). > [!NOTE] > > When you enable dataset aggregation for a selected dataset, all resources in that dataset are collected at once. Activate or deactivate aggregation at the dataset level, not for individual resources. Go to **Dataset Management \> Resources** on your HashiCorp Vault Integration (Cloud) source to view each object type the connector aggregates. Select a resource to review its schema on the **Schema** tab. | Resource name | Resource type | Resource ID | | --- | --- | --- | | **[Vault Secret](<#vault-secret>)** | Credential | `hashicorp-vault:secret` | | **[Vault API Key](<#vault-api-key>)** | Credential | `hashicorp-vault:api-key` | | **[Vault Agent and Machine](<#vault-agent-and-machine>)** | Account | `hashicorp-vault:agent-machine` | | **[Vault Service Account](<#vault-service-account>)** | Account | `hashicorp-vault:service-account` | | **[Vault Token / PAT](<#vault-token-pat>)** | Credential | `hashicorp-vault:token` | **To review attribute names and descriptions after you create the source:** 1. Go to **Admin \> Connections \> Sources**. 2. Open your **HashiCorp Vault Integration (Cloud)** source. 3. Select **Dataset Management \> Resources**. 4. Select a resource. 5. Open the **Schema** tab. Connector-specific attributes are read-only. You can add, edit, or delete custom attributes. ## Vault Secret Resource ID: `hashicorp-vault:secret` Type: Credential Associated dataset: Vault Secrets Connector-specific attributes are read-only. Custom attributes can be added, edited, or deleted from this schema. | Attribute | Type | Entitlement | Multi-Valued | Description | | --- | --- | --- | --- | --- | | `casRequired` | boolean | No | No | Indicates whether the secret requires a Check-And-Set (CAS) parameter on writes. | | `identity` | string | No | No | The stable non-human identity key for the Vault KV v2 secret. This attribute is the Resource ID. | | `mountPath` | string | No | No | The KV v2 mount path with a trailing slash, such as secret/. | | `name` | string | No | No | The final path segment, or leaf name, of the secret within its mount. | | `namespace` | string | No | No | The Vault namespace ID where this secret lives. | | `orphaned_nhi` | boolean | No | No | Indicates whether Vault entity metadata identifies a human owner for this secret. | | `policies` | string | No | Yes | The Vault policies attached to the entity that last wrote this secret. | | `secretPath` | string | No | No | The full path of the secret within its KV v2 mount, such as data/secret/my-app. This attribute is the Resource Name. | ## Vault API Key Resource ID: `hashicorp-vault:api-key` Type: Credential Associated dataset: Vault API Keys Connector-specific attributes are read-only. Custom attributes can be added, edited, or deleted from this schema. | Attribute | Type | Entitlement | Multi-Valued | Description | | --- | --- | --- | --- | --- | | `engineType` | string | No | No | The secret-engine type, either aws, gcp, or azure. | | `identity` | string | No | No | The stable non-human identity key for the dynamic secret-engine role. This attribute is the Resource ID. | | `keyType` | string | No | No | The credential key type issued by the role, such as iam\_user or service\_account. | | `mountPath` | string | No | No | The secret-engine mount path with a trailing slash, such as aws/. | | `namespace` | string | No | No | The Vault namespace ID where this role lives. | | `orphaned_nhi` | boolean | No | No | Indicates whether Vault entity metadata identifies a human owner for this role. | | `roleName` | string | No | No | The name of the dynamic secret-engine role that issues cloud credentials. This attribute is the Resource Name. | ## Vault Agent and Machine Resource ID: `hashicorp-vault:agent-machine` Type: Account Associated dataset: Vault Accounts Connector-specific attributes are read-only. Custom attributes can be added, edited, or deleted from this schema. | Attribute | Type | Entitlement | Multi-Valued | Description | | --- | --- | --- | --- | --- | | `classification` | string | No | No | Non-human classification, always 'machine'. | | `createdAt` | string | No | No | The date and time the owning entity was created, in ISO 8601 format. | | `directGroupIds` | string | No | Yes | The IDs of the groups that the owning entity directly belongs to. | | `disabled` | boolean | No | No | Indicates whether the owning Vault entity is disabled. The value is false for active entities and unbound roles. | | `entityId` | string | No | No | The ID of the owning Vault identity entity. This value is empty for unbound roles. | | `entityName` | string | No | No | The display name of the owning Vault identity entity. This value is empty for unbound roles. | | `groupIds` | string | No | Yes | The IDs of the direct and inherited groups that the owning entity belongs to. | | `identity` | string | No | No | The stable non-human identity key in {mount accessor}:{roleName} format. The namespace is intentionally omitted. This attribute is the Resource ID. | | `inheritedGroupIds` | string | No | Yes | The IDs of the groups that the owning entity inherits through other group memberships. | | `lastModifiedDate` | string | No | No | The date and time the owning entity was last updated, in ISO 8601 format. | | `mountAccessor` | string | No | No | The globally unique mount accessor issued by Vault for the AppRole authentication method, such as auth\_approle\_1bc68a20. | | `mountPath` | string | No | No | The AppRole authentication method mount path with a trailing slash, such as approle/. | | `mountType` | string | No | No | The mount type, approle. | | `namespace` | string | No | No | The Vault namespace ID from the entity. If the entity has no namespace ID, the connector uses the source's configured namespace. | | `orphaned_nhi` | boolean | No | No | Indicates whether Vault entity metadata identifies a human owner. | | `ownerEmail` | string | No | No | The resolved human owner email from a metadata or custom metadata owner key lookup. | | `policies` | string | No | Yes | The Vault policies attached to the owning entity. | | `roleName` | string | No | No | The AppRole authentication method role name. This attribute is the Resource Name. | ## Vault Service Account Resource ID: `hashicorp-vault:service-account` Type: Account Associated dataset: Vault Accounts Connector-specific attributes are read-only. Custom attributes can be added, edited, or deleted from this schema. | Attribute | Type | Entitlement | Multi-Valued | Description | | --- | --- | --- | --- | --- | | `classification` | string | No | No | Non-human classification, always 'machine'. | | `createdAt` | string | No | No | The date and time the owning entity was created, in ISO 8601 format. | | `directGroupIds` | string | No | Yes | The IDs of the groups that the owning entity directly belongs to. | | `disabled` | boolean | No | No | Indicates whether the owning Vault entity is disabled. The value is false for active entities and unbound roles. | | `entityId` | string | No | No | The ID of the owning Vault identity entity. This value is empty for unbound roles. | | `entityName` | string | No | No | The display name of the owning Vault identity entity. This value is empty for unbound roles. | | `groupIds` | string | No | Yes | The IDs of the direct and inherited groups that the owning entity belongs to. | | `identity` | string | No | No | The stable non-human identity key in {mount accessor}:{roleName} format. The namespace is intentionally omitted. This attribute is the Resource ID. | | `inheritedGroupIds` | string | No | Yes | The IDs of the groups that the owning entity inherits through other group memberships. | | `lastModifiedDate` | string | No | No | The date and time the owning entity was last updated, in ISO 8601 format. | | `mountAccessor` | string | No | No | The globally unique mount accessor issued by Vault for the Kubernetes authentication method. | | `mountPath` | string | No | No | The Kubernetes authentication method mount path with a trailing slash, such as kubernetes/. | | `mountType` | string | No | No | The mount type, kubernetes. | | `namespace` | string | No | No | The Vault namespace ID from the entity. If the entity has no namespace ID, the connector uses the source's configured namespace. | | `orphaned_nhi` | boolean | No | No | Indicates whether Vault entity metadata identifies a human owner. | | `ownerEmail` | string | No | No | The resolved human owner email from a metadata or custom metadata owner key lookup. | | `policies` | string | No | Yes | The Vault policies attached to the owning entity. | | `roleName` | string | No | No | The Kubernetes authentication method role name. This attribute is the Resource Name. | ## Vault Token / PAT Resource ID: `hashicorp-vault:token` Type: Credential Associated dataset: Vault Tokens / PATs Connector-specific attributes are read-only. Custom attributes can be added, edited, or deleted from this schema. | Attribute | Type | Entitlement | Multi-Valued | Description | | --- | --- | --- | --- | --- | | `accessor` | string | No | No | The globally unique token accessor issued by Vault. The raw token value is never surfaced. | | `createdAt` | string | No | No | The date and time the token was created, in ISO 8601 format. | | `creationTtl` | int | No | No | The initial time-to-live assigned when the token was created, in seconds. | | `deleted` | boolean | No | No | Indicates whether this row represents a tombstone. Always false for active tokens. | | `entityId` | string | No | No | The ID of the Vault identity entity that owns this token. | | `expireTime` | string | No | No | The date and time the token expires, in ISO 8601 format. | | `explicitMaxTtl` | int | No | No | The explicit maximum time-to-live for the token, in seconds. A value of zero means no explicit cap. | | `identity` | string | No | No | The stable non-human identity key for the Vault token. This attribute is the Resource ID. | | `issueTime` | string | No | No | The date and time the token was issued, in ISO 8601 format. | | `namespace` | string | No | No | The Vault namespace ID where this token lives. | | `numUses` | int | No | No | The remaining number of uses for the token. A value of zero means unlimited uses. | | `orphan` | boolean | No | No | Indicates whether the token has no parent and is therefore not revoked when its parent is revoked. | | `orphaned_nhi` | boolean | No | No | Indicates whether the token metadata identifies a human owner. | | `ownerEmail` | string | No | No | The resolved human owner email from the token's meta.owner\_email field. | | `path` | string | No | No | The Vault authentication path where the token was issued, such as auth/token/create. | | `policies` | string | No | Yes | The Vault policies attached to the token. | | `renewable` | boolean | No | No | Indicates whether the token can be renewed. | | `tokenDisplayName` | string | No | No | The display name assigned to the token, such as token-my-app. This attribute is the Resource Name. | | `tokenType` | string | No | No | The token type, either service or batch. | ## Configuring Owner Metadata The connector reads the `owner_email` metadata key to resolve the human owner of each NHI. Add the `owner_email` key to the NHI metadata when you create the NHI in Vault. Set its value to the owner's email address. If the connector cannot find the `owner_email` key, the NHI is orphaned. # Integrating SailPoint with HashiCorp Vault Integration (Cloud) Use the HashiCorp Vault Integration (Cloud) connector to discover and aggregate non-human identities (NHIs) from HCP Vault Dedicated into SailPoint. The connector supports HCP Vault Dedicated Essentials and Standard tiers. The connector authenticates to one Vault namespace through AppRole and aggregates metadata for the following NHI types: - Agents and machines - Service accounts - Personal access tokens (PATs) and tokens - Secrets - API keys The connector provides read-only discovery. It does not retrieve secret values. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Features | Feature | Description | | --- | --- | | Test connection | Validates the connection to HashiCorp Community Vault. | | Dataset aggregation | Aggregates HashiCorp configuration and metadata into the datasets. | ### Non-Human Identity Discovery - Aggregate Vault agents and machines, service accounts, tokens and PATs, secrets, and API keys Refer to Dataset Management for more information. Refer to [Discovering Potential Non-Human Accounts]() for more information. ### Supported Platform The connector supports HCP Vault Dedicated Essentials and Standard tiers. ## Prerequisites Before you configure the HashiCorp Vault Integration (Cloud) source for HCP Vault Dedicated Essentials or Standard, prepare the target Vault namespace and AppRole. - Use an HTTPS Vault cluster URL with a valid certificate. - Use a Vault account that can create a policy and AppRole in the target namespace. > [!IMPORTANT] > > Create the policy and AppRole in the target namespace. The connector accesses one namespace and reads metadata only. ### Creating the Vault ACL Policy 1. Save the required policy rules in a file named `sail-connector.hcl`. ```text path "sys/health" { capabilities = ["read"] } path "sys/auth" { capabilities = ["read", "list"] } path "sys/mounts" { capabilities = ["read", "list"] } path "sys/wrapping/lookup" { capabilities = ["update"] } path "sys/wrapping/unwrap" { capabilities = ["update"] } path "auth/token/renew-self" { capabilities = ["update"] } ``` 2. Add the following rules for the NHI types that you want the connector to discover. ```text # Agents and machines (AppRole) and service accounts (Kubernetes) path "auth/+/role" { capabilities = ["list"] } path "auth/+/role/*" { capabilities = ["read"] } path "identity/lookup/entity" { capabilities = ["update"] } path "identity/entity/id" { capabilities = ["list"] } path "identity/entity/id/*" { capabilities = ["read"] } path "identity/group/id/*" { capabilities = ["read"] } # Tokens path "auth/token/accessors" { capabilities = ["list"] } path "auth/token/lookup-accessor" { capabilities = ["update"] } # API keys (dynamic credentials; database engine shown) path "database/roles" { capabilities = ["list"] } path "database/roles/*" { capabilities = ["read"] } path "database/static-roles" { capabilities = ["list"] } path "database/static-roles/*" { capabilities = ["read"] } path "sys/policies/acl" { capabilities = ["list"] } path "sys/policies/acl/*" { capabilities = ["read"] } # Secrets (KV v2 metadata only) path "+/metadata" { capabilities = ["list"] } path "+/metadata/*" { capabilities = ["list", "read"] } ``` > **Warning** > > Do not grant access to KV v2 `data/*` paths. The connector requires metadata access only. 3. Write the policy to the target namespace. ```text vault policy write -namespace= sail-connector.hcl ``` ### Creating the AppRole Credentials 1. Create an AppRole role that uses the policy. ```text vault write -namespace= auth/approle/role/ \ token_policies= \ token_ttl="1h" \ token_max_ttl="4h" \ secret_id_ttl="0" \ secret_id_num_uses=0 ``` 2. Read and securely store the Role ID. ```text vault read -namespace= auth/approle/role//role-id ``` 3. Generate a Secret ID. ```text vault write -namespace= -f auth/approle/role//secret-id ``` 4. Securely store the Secret ID. You enter it in **Secret ID** when you configure the source. # Troubleshooting If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support. For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information: - [SailPoint Identity Services Documentation]() - [SailPoint Support Knowledge Base]() - [SailPoint Developer Community]() ## Debug Logs For information about managing additional source settings, including debug logging and downloading connector logs, refer to [Managing Additional Settings]().