Web Services Connector: A Practical Implementation Guide
The SailPoint Web Services Connector is one of the most powerful and often misunderstood integration options in SailPoint Identity Security Cloud (ISC). This practitioner guide provides a hands-on, field-tested approach to designing, configuring, and operating Web Services integrations, focusing on real-world scenarios rather than theoretical concepts.
Whether you are onboarding legacy systems, building custom integrations, or troubleshooting complex provisioning flows, this guide aims to serve as a practical reference for IAM/IGA engineers and administrators working with SailPoint ISC.
Prerequisites
Review the Integrating SailPoint and Web Services SaaS documentation and check the Prerequisites section, which states that the web services must be accessible.
Before moving forward, ensure the application can be reached via the Internet. Consult your organization’s application SME to confirm the correct connectivity requirements.
1. Creating a New Source
To create a Web Services source in Identity Security Cloud, go to Connections > Sources
From the Admin Dashboard, click Connections and select Sources.
On the Sources page, click Create New.
Search for the Web Services SaaS connector and click Configure.
On the Create source page, enter the Source Name, Description, Source Owner, and click Continue
Click the X to return to the Sources page.
On the Sources page, you see the newly created Web Services SaaS source.
2. Connection Settings
With your authentication information gathered, edit and configure your web service source. To do so, go to Connection Settings.
On the Sources page, click the web services' ellipsis icon to see its Actions' menu and click Edit.
From the Base Configuration, click Connection Settings to add the authentication information you gathered.
3. Source Setup
In the Connection Settings, enter the configuration details that you collected for the web services authentication type:
On the Connection Settings page, select your Authentication Type, complete the required fields, and enter the additional information you collected. Scroll to the bottom of the page and click Save
The Success pop-up confirms your connection settings are saved.
4. HTTP Operations
After saving the Connection Settings, click HTTP Operations and add your settings:
Click HTTP Operations to add, edit, and order HTTP operations.
To configure an HTTP operation, click Add Operation.
To add an operation, complete the required fields and the additional fields needed for the configuration.
nter a unique name for the operation to execute.
Click the Operation Type drop-down list and select the name of the operation to execute.
For a full list of the connector supported HTTP operations, go to the documentation page bellow.
HTTP Operations: https://documentation.sailpoint.com/connectors/webservices/help/integrating_webservices/http_operations.html
Click the Request Type drop-down menu and make a selection.
Click the Context URL field and enter the authentication URL specific to your operation. The connector appends the context URL to the source's Base URL. The Context URL can be empty depending on the endpoint of the Managed System.
Click HTTP Method and select from the menu the appropriate HTTP method for the endpoint you are calling. Click Save to add the HTTP Operation.
On the HTTP Operations page, add and configure the supported operations for the source.
Once the HTTP operations added, click the Additional Settings to continue configuring your source.
Use caution when renaming an HTTP operation. When you change the HTTP Operation Name, you break the configured relationships, including endpoint and parent-child relationships. After renaming an operation, reconfigure the parent-child relationships.
5. Pagination
Pagination logic can be added in aggregation. Paging allows for pagination operations to be performed multiple times when there are limits to collecting the full data. For example, you might aggregate 500 accounts and only pull 50 records at a time. Paging Steps provides space to define the operation that repeats until the full data for the 500 records is gathered. To add pagination to an aggregation process:
Click HTTP Operations and Edit icon for either aggregate or aggregateGroups.Click the Edit icon for either aggregate or aggregateGroups.
On the aggregate overlay, click Paging.
Enter the Initial Page Offset, Page Size, and Paging Steps. Click Save.
Paging Configuration Template
$sysparm_limit$=100
TERMINATE_IF $NO_RECORDS$==TRUE
$sysparm_offset$=$sysparm_limit$+$sysparm_offset$
$endpoint.fullUrl$=$application.baseUrl$+"/profiles?query[limit]="+$sysparm_limit$+"&query[offset]="+$sysparm_offset$
6. Provisioning Settings
The Web Services SaaS connector includes Additional Settings for provisioning.
The Provisioning Settings change the behavior of the settings during provisioning operations for throwing flags and creating accounts.
Throw Provisioning
Select the Throw Provisioning Rule checkboxes to set the exception flag during provisioning. Your Throw Provisioning Rule options are:
Throw Provisioning Checkboxes
When a Throw Provisioning process is checked:
If the rule is present, and an error occurs during the HTTP operation, the operation passes a flag to the rule informing it of the error.
The Create Account with Entitlement Requirement operation is triggered by giving an entitlement to the identity.
Create Account with "Ent" Request
The Create Account with "Ent" Request checkbox refers to how entitlements are added to an account when initially creating the record.
By default, the Create Account with "Ent" Request is unchecked.
Uncheck Create Account with "Ent" Request
Unchecked, the Create Account with "Ent" Request splits the process into two operations. One operation (Create Account) creates the account and the second operation (Add Entitlement) gives the entitlement to that account.
Check Create Account with "Ent" Request
If the Create Account with "Ent" Request is checked, the entitlement is included in the Create Account operation. Typically, accounts are created when entitlements are granted to identities with no pre-existing accounts.
For most sources, having an account and then adding the entitlement is not an issue. However, for some sources, having an entitlement is a requirement to having an account.
In such cases, there can be no intermediate step where an account exists without an entitlement. For these types of sources, you can combine the account creation and entitlement granting provisioning processes with Create Account With "Ent" Request checked. Always refer to your source's documentation and SMEs for guidance with the Provisioning Settings.
7. Review and Test
Once your configuration is complete, perform a test to confirm the connection to Identity Security Cloud. To do so:
Click Test Connection to initiate the test.
Account Management
Account Management enables you to maintain accurate and up-to-date account information across your connected sources within Identity Security Cloud. Sources contain two types of data that are relevant to ISC: accounts and entitlements.
8. Account Schema
Each source provides account attributes that are aggregated into Identity Security Cloud. The account schema controls that aggregation process determining which account attributes are read in and how Identity Security Cloud manages that data.
It's important to note that data must actually exist on the source, and the account schema for the connector must match the source's attributes. Since Web Services sources are generic and can apply to many applications, the schema is determined by the account aggregation endpoint.
The source's Account Schema page allows you to add, edit, and delete attributes.
Account Schema Web Services Extract
Identity Security Cloud extracts the schema information for a Web Services source from the aggregation endpoint you setup in HTTP operations. Your schema needs to be set up as a custom operation.
Aggregation Operation
The API call defined in HTTP Operations > Aggregate returns a large JSON document that is then parsed using JSONPath expressions that map to account attributes defined in the source schema.
Recommended by LinkedIn
Step 1: Run Aggregation Endpoint in Postman
To identify the data attributes in the source and how they are organized, run the source's account aggregation endpoint in Postman.
Step 2: Interpret Results
Not all information available on a source is usable in Identity Security Cloud. For this reason, you must interpret the results and decide which attributes to map in the schema.
Step 3: Manually Configure Schema
To create the schema and add new attributes, click through the steps
To create a Web Services schema, click Account Schema.
Add the attribute values. Check Add Another and Save to continue creating the schema.
The first attribute added is designated as the Account ID and Account Name. You will edit these values later. Click Continue.
Add the firstname attribute and Save.
Add the lastname attribute and Save.
Add the email attribute and Save.
Add the userId attribute and Save.
Enter the capabilities attribute as a group. Check Entitlement and Multi-Valued, and uncheck Add Another.
When the Add Attribute overlay closes, the new schema displays.
Every schema must define the Account ID and Account Name. Since username was the first attribute added, the Account ID and Account Name flags are associated to it.
Edit Account Schema
To continue, edit the schema Account ID and Account Name flags:
Click Edit Schema.
On the Edit Account Schema overlay, update the Account ID and Account Name fields.
Read the warning. If data has been aggregated, heed the warning. Since this is the initial configuration, the warning can be ignored. Click Continue.
The Success popup confirms the schema update and the Account Name and Account ID display next to their attributes.
Step 4: Configure Map of the Aggregation Operation
To configure the mapping of the aggregation operation, start at HTTP Operations:
Click HTTP Operations and For this source, click the Edit icon for the aggregate operation.The General Information fields were completed when the HTTP Operation was initially created.
The General Information fields were completed when the HTTP Operation was initially created.
If your API call uses headers, add them in the Headers overlay.
If your API call uses a Request Body, add it in the Body overlay.
For the Root Path, represents the actionable part of the JSON document returned by the API call.
Configure the expected response Success Codes for your API call.
For the Response Mapping, enter the Schema Attribute and its corresponding JSONPath expression for the Attribute Path.
The full JSONPath expression is configured by entering the Root Path and Attribute Path into the correct fields.
JSONPath Expressions
To connect a Web Services SaaS source requires technical experience with JSONPath expressions. The full JSONPath expression is obtained by referencing two different parts of the UI.
Step 5: Account Correlation, Aggregation, and Verification
To verify your Web Services SaaS source connection:
9. Account Correlation
Correlation is the process of matching and assigning source accounts to identities.
The correlation configuration is the set of criteria used to compare account attributes and identity attributes. When a match is found, the account attributed is permanently linked to the matching identity.
Application onboarding AI generates correlation configuration criteria which can be tested for efficacy before aggregation.
To correlate accounts, you pair account attributes to the identity attributes found in an identity profile.
Click Refresh Recommendations for the AI-driven correlation configuration mapping recommendations.
Correlation criteria compares the values of account and identity attributes. Whenever one correlation criteria is met, the account is correlated to the identity.
Correlation criteria executes in priority order as listed under the Recommended Criteria.
You configure account correlation before you load, or aggregate, source accounts for the first time. If you change the account correlation for a source that is already aggregated, you run another aggregation where optimization is disabled for that source.
This type of aggregation can only be done through REST API. Disabling optimization allows unchanged accounts to be reexamined for correlation.
10. Account Aggregation
Account aggregation is the process of collecting and loading account data from various sources into the system. Account aggregation gathers information about user accounts and their associated access rights from different sources.
For a Web Services source, the frequency of account aggregations can be scheduled and manually initiated ad-hoc.
Account aggregation reads data from a source into Identity Security Cloud, providing visibility to the managed source. Account aggregation is the first step toward enacting governance
Start Aggregation
To start account aggregation:
Under Source Setup, click Account Aggregation.
On the Account Aggregation page, click Start Aggregation.The popup confirms the aggregation process started.
The popup confirms the aggregation process started.
Under Latest Account Aggregation, the STATUS displays the aggregation was a Success.
Create Account
Create Account refers to the process where new user accounts are automatically generated on a connected source when access is granted. Create Account occurs when a user is assigned entitlements from a source where they do not have an account.
Application onboarding AI generates account attribute mapping recommendations. Click Refresh Recommendations for the AI-driven create account recommendations.
Attribute Sync
In the Attribute Sync configuration, you specify which account attributes on a source are kept in sync with corresponding identity attributes.
Attribute Sync can be configured for any source account attribute that Is included in the source's Create Account definition, and mapped directly from an identity attribute in that definition.
Attribute sync ensures consistency of identity information across multiple enterprise systems by automatically updating account attributes on direct sources when changes occur in the authoritative source.
Attribute Synchronization
The values of certain attributes are important and must be synchronized in an organization.
For example, several applications might be configured to use an employee's phone number for password reset operations.
What if an employee changes their phone number? With Attribute Sync, a change to the value of a synchronized attribute is then propagated to the target source.
Sources:
Good
Nice, thanks for sharing it.
TOP!!!