# 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](<https://developer.sailpoint.com/docs/api/list-sources-v-1/>)
- API to get a specific source's current schema details - [list-schemas](<https://developer.sailpoint.com/docs/api/get-source-schemas-v-1/>)
- API to add a new schema attribute to a source - [create-schema](<https://developer.sailpoint.com/docs/api/create-source-schema-v-1/>)
- [SailPoint REST API - Update Source (Partial)](<https://developer.sailpoint.com/docs/api/update-source-v-1>)

## 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:

```xml
<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](<https://documentation.sailpoint.com/connectors/web_services/va/help/configuring.html#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:

```xml
<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:

```text
{"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:

```xml
<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`:

```text
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:

```json
[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:

```xml
<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
<?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](<https://documentation.sailpoint.com/connectors/web_services/va/help/operations_reference.html>).

## 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](<https://developer.sailpoint.com/docs/api/list-sources-v-1/>), [list-source-schemas](<https://developer.sailpoint.com/docs/api/get-source-schemas-v-1/>), [create-source-schema](<https://developer.sailpoint.com/docs/api/create-source-schema-v-1/>), and [SailPoint REST API - Update Source (Partial)](<https://developer.sailpoint.com/docs/api/update-source-v-1>).

| 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. |