Aggregating SailPoint Entro NHIs & AI Agents in SailPoint ISC

The SailPoint Entro integration with SailPoint Identity Security Cloud enables comprehensive identity lifecycle management and access governance for Non-Human Identities (NHIs) and AI Agents. By exposing SailPoint Entro data via specialized API endpoints, SailPoint can aggregate these identities, map them to human identities, and apply governance policies.

Key Capabilities

Account Aggregation: Automatically pull NHI and AI Agent data from SailPoint Entro into SailPoint.
Identity Correlation: Map ownerEmail from SailPoint Entro NHIs and AI Agents to human identities in SailPoint to establish clear ownership and accountability.
Access Governance: View and manage permissions associated with machine accounts within the SailPoint ecosystem.
AI Agent Monitoring: Discover and govern agentic AI identities alongside traditional service accounts.

Architecture

This integration uses a "pull" model where SailPoint acts as the client and SailPoint Entro acts as the data provider.

+--------------------------+          REST API (HTTPS)          +--------------------------+
|                          | <--------------------------------- |                          |
| SailPoint Identity Security Cloud |      (GET /nhis /ai-agents)        |      Entro Platform      |
|     (Web Services)       |                                    |      (Control Plane)     |
|                          | ---------------------------------> |                          |
+--------------------------+        API Key Authentication      +--------------------------+

Prerequisites

Administrative access to SailPoint Identity Security Cloud.
A SailPoint Entro API Token (generated in the SailPoint Entro Console) generated by SailPoint Entro Admin user.
Your SailPoint Entro Environment URL (e.g. https://api.entro.security).

Configuration Steps

Create the Source in SailPoint
1. Navigate to Admin > Connections > Sources.
2. Click Create New (top left).
3. Select Web Services SaaS as the source type.
Connection Settings
1. Go to Connection Settings and configure:
  - Authentication Type: API Token.
  - Base URL: Your SailPoint Entro environment URL (e.g. https://api.entro.security).
  - API Token: Paste your SailPoint Entro API Key.
  - Connection Timeout (in seconds): 120.
2. Click Save.

Configure HTTP Operations

You must add three operations under the HTTP Operations tab:

Operation A: Test Connection

Operation Name: Test Connection.
Operation Type: Test Connection.
Request Type: API.
Context URL: /api/entroApi/identity-now/nhi?take=1.
HTTP Method: GET.
Header: Key: Authorization, Value: <Your_Entro_API_Token>.
Response Information: Root Path: items, Success Codes: 2**.

Response Mapping:

Schema Attribute	Attribute Path
displayName	displayName
accountType	accountType
name	name

Operation B: Get NHIs

Operation Name: get NHIs.
Operation Type: Account Aggregation.
Request Type: API.
Context URL: /v2/identity-now/nhi?take=1000.
Method: GET.
Header: Key: Authorization, Value: <Your_Entro_API_Token>.
Response Information: Root Path: items, Success Codes: 2**.
Paging: Page Size: 200, Page Steps: TERMINATE_IF $response.hasNext$ == FALSE $endpoint.fullUrl$ = $application.baseUrl$ + "/v2/identity-now/nhi?take=1000&skip=" + $response.nextSkipOffset$.

Response Mapping:

You can either enter the attributes below manually or paste this script in the Dev Tools > Console.

/**
* Ensure the "Add" button is visible on the screen before running the script.
*/
(async () => {
const mappings = [
{ schema: "suspiciousActivity", path: "suspiciousActivity" },
{ schema: "secondary Email", path: "secondary Email" },
{ schema: "NHIType", path: "NHIType" },
{ schema: "displayName", path: "displayName" },
{ schema: "complianceBreach", path: "compliance Breach" },
{ schema: "entroGuid", path: "entroGuid" },
{ schema: "secondaryPhoneNumber", path: "secondary Phone Number" },
{ schema: "isActive", path: "isActive" },
{ schema: "accountNamelnEntro", path: "accountNamelnEntro" },
{ schema: "employee Number", path: "employeeNumber" },
{ schema: "accountID", path: "accountID" },
{ schema: "ownerName", path: "ownerName" },
{ schema: "riskSeverity", path: "riskSeverity" },
{ schema: "permissions", path: "permissions" },
{ schema: "familyName", path: "family Name" },
{ schema: "exposed", path: "exposed" },
{ schema: "id", path: "id" },
{ schema: "email", path: "email" },
{ schema: "expiration Date", path: "expiration Date" },
{ schema: "isProduction", path: "isProduction" },
{ schema: "manager", path: "manager" },
{ schema: "accountType", path: "accountType" },
{ schema: "givenName", path: "givenName" },
{ schema: "LastRotated", path: "LastRotated" },
{ schema: "creationDate", path: "creation Date" },
{ schema: "ownerEmail", path: "ownerEmail" },
{ schema: "tags", path: "tags" },
{ schema: "phoneNumber", path: "phoneNumber" },
{ schema: "name", path: "name" },
{ schema: "isldle", path: "isidle" },
{ schema: "status", path: "status" }
];

console.log(`🚀 Starting automation for ${mappings.length} attributes...`);

for (const item of mappings) {
// 1. Find and click the 'Add' button
// Note: Selector may need adjustment based on the specific SailPoint UI version
const addBtn = Array.from(document.querySelectorAll('button')).find(b => b.textContent.includes('Add'));

if (addBtn) {
addBtn.click();
// Wait for the new row to render
await new Promise(resolve => setTimeout(resolve, 300));

// 2. Find the last empty input fields for Schema Attribute and Attribute Path
const inputs = document.querySelectorAll('input[type="text"]');
if (inputs.length >= 2) {
const pathInput = inputs[inputs.length - 1]; // Usually the second column
const schemaInput = inputs[inputs.length - 2]; // Usually the first column

// 3. Set values and trigger events so the UI (React/Angular) picks up the change
const setNativeValue = (element, value) => {
const valueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value").set;
valueSetter.call(element, value);
element.dispatchEvent(new Event('input', { bubbles: true }));
element.dispatchEvent(new Event('change', { bubbles: true }));
};

setNativeValue(schemaInput, item.schema);
setNativeValue(pathInput, item.path);

console.log(`✅ Added: ${item.schema} -> ${item.path}`);
}
} else {
console.error("❌ Could not find the 'Add' button. Please ensure you are on the Response Mapping section.");
break;
}
}

console.log("🏁 Automation complete! Please review the mappings and click 'Save'.");
})();

Schema Attribute	Attribute Path
suspiciousActivity	suspiciousActivity
secondaryEmail	secondaryEmail
NHIType	NHIType
displayName	displayName
complianceBreach	complianceBreach
entroGuid	entroGuid
secondaryPhoneNumber	secondaryPhoneNumber
isActive	isActive
accountNameInEntro	accountNameInEntro
employeeNumber	employeeNumber
accountID	accountID
ownerName	ownerName
riskSeverity	riskSeverity
permissions	permissions
familyName	familyName
exposed	exposed
id	id
email	email
expirationDate	expirationDate
isProduction	isProduction
manager	manager
accountType	accountType
givenName	givenName
LastRotated	LastRotated
creationDate	creationDate
ownerEmail	ownerEmail
tags	tags
phoneNumber	phoneNumber
name	name
isIdle	isIdle
status	status

Operation C: Get Permissions

Operation Name: get permissions.
Operation Type: Group Aggregation-Permission.
Request Type: API.
Context URL: /v1/identity-now/nhi-permissions.
HTTP Method: GET.
Header: Key: Authorization, Value: <Your_Entro_API_Token>.
Response Information: Root Path: items, Success Codes: 2**.
Paging: Page Size: 200, Page Steps: TERMINATE_IF $response.hasNext$ == FALSE $endpoint.fullUrl$ = $response.nextRequestURL$.

Response Mapping:

Schema Attribute	Attribute Path
displayName	displayName
accountType	accountType
name	name

Test Connection
1. Go to Review and Test.
2. Validate the connection configuration are set as defined above.
3. Click on Test Connection.
Schema and Correlation Mapping
1. Entitlement Types:
  - Click on Create Entitlement Type:
    - Name: Permission.
    - Check the box for Include permissions in aggregations.
    - Add the below three attributes:
      - Name: name, Description: name, Type: string, check Entitlement and Multi-Valued.
      - Name: displayName, Description: displayName, Type: string.
      - Name: accountType, Description: accountType, Type: string.
    - Click on Edit Type and set Entitlement ID: name and Entitlement Name: name.
2. Entitlement Aggregation:
  1. Click on Start Aggregation and verify the run is in progress without errors.
  2. Set scheduled task for automatic aggregation.
3. Account Schema:
  - Manually add or upload the schema (below). Ensure:
    - isActive, isIdle, isProduction, exposed, suspiciousActivity are set to Boolean.
    - permissions are set to type Permission with Entitlement and Multi-Valued set as well.
    - tags are set to Multi-Valued.
  - Click on Edit Schema then:
    - Check the box for Include permissions in aggregations.
    - Set the Account ID and Account Name to id.
  355B
  
  SailPoint Entro NHIs-schema.csv
  
  csv
  
  Download Open
4. Account Correlation:
  
  Navigate to Account Correlation and map the following:
  
  Identity Attribute Account Attribute
  
  Name id
  
  Work Email email
  
  Name name
5. Account Aggregation:
  - Click on Start Aggregation and verify the run is in progress without errors.
  - Set scheduled task for automatic aggregation.
6. Machine Accounts:
  - Enable Classification and click Save.
    - Click on Process Classification verify the run is in progress without errors.
  - In Mappings Set Machine Account Owner attribute to Account to Identity then map Account Attribute: ownerEmail, Transform: ToLower, Human Identity Attribute: email. Click Save.

Validation & Troubleshooting

Manual Trigger: Navigate to Admin > Connections > Sources, select the SailPoint Entro source, and click Start Aggregation.
Verify Identity Mapping: Search for a known human identity in SailPoint Identity Security Cloud and verify they are listed as the owner of their respective SailPoint Entro machine accounts.
Check Aggregation History: Ensure the "Account Aggregation" task completes with a "Success" status.

Common Issues

Correlation Failures

Symptom: NHIs are aggregated but show "Uncorrelated" or no owner.
Fix: Verify that the ownerEmail field in SailPoint Entro matches the email attribute on the Human Identity in SailPoint exactly.

401 Unauthorized

Symptom: Aggregation fails with authentication errors.
Fix: Regenerate the SailPoint Entro API Token and update the Authorization header in all HTTP Operations. Ensure the token is prefixed with Bearer if required by your SailPoint tenant configuration.

Paging Issues (Partial Data)

Symptom: Only a subset of NHIs (e.g., exactly 200 or 1000) are appearing.
Fix: Review the Paging Steps in the HTTP Operation. Ensure the $response.nextSkipOffset$ variable is correctly configured in the full URL string.

Missing Permissions

Symptom: Accounts are aggregated, but the "Permissions" tab is empty.
Fix: Ensure "Include permissions in aggregations" is checked in both the Entitlement Management and the Account Schema settings.

Identity Attribute	Account Attribute
Name	id
Work Email	email
Name	name