Configuration Parameters

For the Web Services source you can configure the values of the following attributes using the SailPoint REST API. For the usage of the SailPoint REST APIs for the following attributes and keys, refer to:

API to get source details - list-sources
API to get a specific source's current schema details - list-schemas
API to add a new schema attribute to a source - create-schema
SailPoint REST API - Update Source (Partial)

createAccountWithEntReq

By default, the Web Services source creates an account for a Create Account operation and then adds the entitlements one by one. For example, if there are three entitlements (Role, Group, Profile), the source executes three requests and three API calls are sent.

Adding the createAccountWithEntReq attribute merges all the entitlement requests in a single API call. Use the createAccountWithEntReq attribute key with the value true to enable the functionality of sending entitlements with create account in a single request to the managed system.

Default value: false

throwBeforeAfterRuleException

During aggregation, if an exception is displayed from WebServiceBeforeOperationRule or WebServiceAfterOperationRule, then aggregation continues and completes successfully. Set the value of the throwBeforeAfterRuleException flag to true to terminate the aggregation by displaying an error message. This flag can be set only for Account and entitlement aggregation.

Default value: false

Note

This flag is not applicable for child endpoints.

throwProvBeforeRuleException

During provisioning, Get Object, or Test Connection operations, if an exception is thrown by the Before Operation Rule, then the operation fails. To ignore the exception in the log file and proceed with provisioning, set the value of throwProvBeforeRuleException to false. This flag can be set for all operations except Account and entitlement aggregation.

throwProvAfterRuleException

During provisioning, Get Object, or Test Connection operations, if an exception is thrown by the After Operation Rule, then the operation fails. To ignore the exception in the log file and proceed with provisioning, set the throwProvAfterRuleException attribute key with false as a value. This flag can be set for all operations except Account and entitlement aggregation.

enableHasMore

If enableHasMore is set to true, then the termination of aggregation depends on the value of the hasMore attribute. Use the enableHasMore attribute key with true as a value.

The hasMore attribute is the Boolean attribute that is set in the transientValues map in the Before or After Operation Rule. Unless the value of the hasMore attribute is false, aggregation isn't terminated.

If enableHasMore is set to false, then the aggregation terminates if the number of accounts returned is zero. Use the enableHasMore attribute key with false as a value.

lockStatus

To use the Lock/Unlock feature, add the lockStatus attribute in the application Debug page as provided in the following example:

<entry key="lockStatus" value="status=inactive"/>

In the example, status is an account schema attribute that indicates if the account is locked or not. The value (inactive) helps the Web Services connector distinguish between the locked and unlocked account.

The Web Services connector does not support provisioning of lock account.

possibleHttpErrors

If an API endpoint does not send expected error codes to flag failure conditions, you can manually configure error codes with all possible HTTP error codes and messages that the API endpoint might return, which can then result in the failure of operations.

Note

These errors don't prompt the connector to retry After Operation Rule errors or Before Operation Rule errors.

Use the possibleHttpErrors attribute with ["errorCodes","errorMessages"] as the value.

Occasionally, the Web Services connector returns the HTTP status code 200 but the response payload may contain errors. In this case, the connector must fail the request, or an OAuth token generation must try to regenerate the token.

You can also configure these possible HTTP error codes and messages to specify invalid or expired token errors. In this case, the connector regenerates and saves the token for OAuth 2.0 authentication, then retries the operation with the newly generated access token.

Note

This flag is not applicable for child endpoints.

isGetObjectRequiredForPTA

To use the Web Services source for Pass-Through Authentication, set the isGetObjectRequiredForPTA attribute key to true. For new Web Services sources, the default value for isGetObjectRequiredForPTA is true.

When set to true, it executes the Get Object operation to verify if the entered username (considered as an identity attribute) is present on the managed system or not.
When set to false, it skips the Get Object operation and the Pass-Through Authentication operation must have response mapping with account object schema attributes.

Refer to Pass-Through Authentication for more information.

objectNotFoundErrorMsg

Based on the error message list, the source decides whether to display the objectNotFoundErrorMsg error. For example, you can create an entry for objectNotFoundErrorMsg with a custom error message to identify multiple exceptions by setting the objectNotFoundErrorMsg attribute key with ["404: Not Found", "404"] as the value.

authenticationFailedErrorMsg

Based on the error message list, the source decides whether to display the authenticationFailedErrorMsg error. For example, you can create an entry for authenticationFailedErrorMsg with custom error messages to identify exceptions (there can be multiple):

Key - connector_authenticationFailedErrorMsg
Value - ["Authentication Failed"]

expiredPasswordErrorMsg

Based on the error message list, the source decides whether to throw the expiredPasswordErrorMsg error. For example, you can create an entry for expiredPasswordErrorMsg with a custom error message to identify exceptions (there can be multiple) by setting the expiredPasswordErrorMsg attribute key with ["Password Expired"] as a value.

If the response contains a string that matches expiredPasswordErrorMsg, then the connector redirects the user from the login page to the Change Password page.

Note

If you use OAuth 2.0 authentication and you have the error messages for expired password correctly set, the connector tries to refresh the access token after the first failed connection attempt if the authentication endpoint supports it.

updateAttrWithChangePassword

To enable single requests for change password and update operations, use the updateAttrWithChangePassword attribute key with true as a value.

If the value of the updateAttrWithChangePassword attribute is true in the source and the plan contains no attribute request named "password" (change password), then the specific Update operation type endpoint is invoked.

Setting the value of the updateAttrWithChangePassword attribute to true does not include requests for add or remove entitlements. These requests are executed independently.

disableCookies

By default, the Web Services source supports cookies. Disable cookies by adding the disableCookies attribute key with true as a value. This attribute is not applicable for the authentication API call operation.

addRemoveEntInSingleReq

Add or remove multiple entitlements such as Role, Permissions, or Profile. To send multiple entitlement requests in a single request to the managed system, set the value of the addRemoveEntInSingleReq parameter to true as shown in the following example:

<entry key="addRemoveEntInSingleReq">
    <value>
        <Boolean>true</Boolean>
    </value>
</entry>

If addRemoveEntInSingleReq is set to true, then the payload for entitlements must also be set as shown in the following example:

{"group_id" : $plan.groups$,
"permission":$plan.permission$,
"roles": $plan.roles$
}

skipGetObjectInCreate

The Web Services connector supports the skipGetObjectInCreate attribute (Boolean) to skip the getObject call if it is present during the Create provisioning operation.

deleteStatus

This attribute marks whether an object is deleted during delta aggregation. To set the value of deleteStatus, set the value as shown in the following example:

<entry key="deleteStatus" value="deleted=true"/>

Note

Additional configurable attributes are available beyond those documented here. Refer to the SailPoint REST API links above to list a source's current configuration and confirm available attribute keys before setting a new one.

Configuration for Response

When configuring the Web Services source, map the schema attribute as follows for JSON and XML.

JSON Response Configuration

Single endpoint - In a JSON response, all the attributes can be mapped as follows, considering the Root Path as $.list:

Id = id
displayName = displayName
username = jive.username
enabled = jive.enabled
emails = emails[*].value

Multiple endpoints - Refer to the following response example for the first and second endpoints:

Type	Response Example	Response Mapping
First endpoint	`{"meta": {...}, "resources": ["01dcc3dd-5b72-4fb2-a43b-424e092bd6af", "032b704e-1467-48b3-ad70-29a04f1a20ab", "042ab092-918f-4ed3-97eb-196fbe917e77"], "errors": []}`	Response Attribute Mapping: `uid = $`. Root Path: `$.resources.*`
Second endpoint	Context URL - `/users/entities/users/v1?ids=$response.uid$`. Example: `{"meta": {...}, "resources": [{"uid": "john.doe@santander.us", "firstName": "John", "lastName": "Doe", "uuid": "01dcc3dd-5b72-4fb2-a43b-424e092bd6af", "customer": "81971f9d094d494bae5a5fd97052509f"}], "errors": []}`	Response Attribute Mapping: `firstName = $.resources[0].firstName`, `lastName = $.resources[0].lastName`. Root Path: not required

Parsing JSON array - The following is an example for parsing a JSON array:

[1,10,21,31,46,89,90,67,88,98,101]

The response mapping for the above example is:

Response Attribute Mapping (id is an attribute in the schema): id = $
Root Path: $.*

XML Response Configuration

Example 1 - XML response for mapping:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns="urn:partner.soap.sforce.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sf="urn:sobject.partner.soap.sforce.com">
 <soapenv:Header>
      .....
 </soapenv:Header>
 <soapenv:Body>
    <queryResponse>
       <result xsi:type="QueryResult">
         <done>true</done>
         <queryLocator xsi:nil="true"/>
         <records xsi:type="sf:sObject">
           <sf:type>User</sf:type>
           <sf:Id>123456</sf:Id>
           <sf:Alias>Alias</sf:Alias>
           <sf:City xsi:nil="true"/>
           <sf:CommunityNickname>CName1</sf:CommunityNickname>
           <sf:Email>test@test.com</sf:Email>
           <sf:IsActive>false</sf:IsActive>
           <sf:Username>test@test.com</sf:Username>
           <sf:FirstName>Test</sf:FirstName>
           <sf:LastName>Test</sf:LastName>
         </records>
        <size>1</size>
         </result>
     </queryResponse>
   </soapenv:Body>
</soapenv:Envelope>

Example 2 - XML response for mapping:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><userList id="5457373">
<name>DillardsEveryone</name>
  <memberList>
    <listMember>example@example.com</listMember>
    <listMember>gage5.test5@test5.dillards.com</listMember>
  </memberList>
</userList>

For more specific examples of the JSON and XML format responses or inputs for the supported fields or operations on the Web Services source, refer to Operations Reference.

Additional Configuration Attributes for OAuth2

The following attributes are applicable only if Authentication Type is selected as OAuth2. For the Web Services source you can configure the values of these attributes using the SailPoint REST API. For the usage of the SailPoint REST APIs for these attributes and keys, refer to list-sources, list-source-schemas, create-source-schema, and SailPoint REST API - Update Source (Partial).

Attribute	Description
`oauth_headers`	To have customized headers as a part of the access token generation request, use the `oauth_headers` attribute key with the value as `{"Content-Type":"application/x-www-form-urlencoded"}`. Web Services uses the access token configured in the application as the authorization header for each endpoint; users no longer need to specify the authorization header for each endpoint. If authorization is provided at the endpoint level, it takes precedence over the access token. SailPoint recommends providing the authorization header suffix in the access token provided (for example, `Bearer <Access Token>`). If no prefix is provided, Web Services uses `Bearer` as the default Authorization header prefix. To send additional headers for token generation, use the `saml_headers` attribute key with the value as `{"<customHeaderKey>":"<customHeaderValue>"}`.
`oauth_headers_to_exclude`	By default, an Authorization BASIC header with a Base64-encoded Client ID and Client Secret is part of the access token generation request. Some managed systems do not support this header. If there is no Authorization BASIC header required for such managed systems, it can be excluded from the request. Use the `oauth_headers_to_exclude` attribute key with the value as `"Authorization, Xrftoken"`.
`oauth_request_parameters`	For some managed systems, custom request parameters may be required to be part of the access token generation request. Use the `oauth_request_parameters` attribute key with the value as `{"<parameter_name>":"<parameter_value>"}`. Example body: `[{"op": "add", "path": "/connectorAttributes/oauth_request_parameters", "value": { "<parameter_name>": "<parameter_value>" }}]`
`oauth_body_attrs_to_exclude`	To delete any of the standard request attributes which are not supported by managed systems' access token generation requests, use the `oauth_body_attrs_to_exclude` attribute key with the value as `"customParamKey,customParamValue"`.
`saml_headers`	(Optional) Used for SAML assertion generation; if additional header information is required, use the `saml_headers` attribute key with the value as `{"<customHeaderKey>":"<customHeaderValue>"}`.
`saml_headers_to_exclude`	(Optional) Used for SAML assertion generation; the key provided here is excluded from the header while executing the SAML Assertion generation request. Use the `saml_headers_to_exclude` attribute key with the value as `"Authorization,CUSTOM_HEADER"`.
`oAuthJwtHeader`	Contains the `alg` (algorithm used for signing the JWT assertion). Use the `oAuthJwtHeader` attribute key with the value as `["alg":"RS256"]`. If required, additional header attributes can be provided in this map.
`oAuthJwtPayload`	Contains `aud` (Audience), `exp` (Expiry of the JWT assertion), `iss` (Issuer), and `sub` (Subject). Use the `oAuthJwtPayload` attribute key with the value as `["aud", "exp", "iss", "sub"]`. If required, additional payload attributes can be provided in this map. For additional attributes like `jti`, `iat`, `nbf`, if only the key (not the value) is available in the map, the connector uses the default values for those attributes.

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.