SailPoint IdentityIQ SCIM

The SailPoint IdentityIQ SCIM connector reads users from IdentityIQ's SCIM 2.0 service and creates or updates matching ICAP identities. It does not write changes back to IdentityIQ. It runs in the background for each ICAP tenant with SCIM synchronization enabled and a valid scimProvider configuration. Use it when IdentityIQ supplies ongoing cardholder data to ICAP.

The connector works with identities. It does not provision visitors, visits, credentials, access units, or their assignments. An identity created through synchronization does not by itself grant physical access. Configure credentials, access units, PACS mappings, and access assignments through their existing ICAP workflows.

Who can configure the connector

A tenant administrator can configure the connector for an existing tenant. The tenant administrator role includes the TenantGet and TenantUpdate permissions needed for the steps below. An assigned role with those permissions can also be used.

If you do not have tenant configuration access, ask your tenant administrator to set up the connector. Contact HIS support for help with service availability or network access to IdentityIQ.

Before you configure the connector

• The tenant feature setting scimSynchronizationAllowed must be set to true before you configure the connector. You can check its current value with GET /icap/v1/tenant/{tenantId}/features. If it is false or unset, contact HIS support to have SCIM synchronization enabled for your tenant. Configuring scimProvider alone does not enable this feature.

• Obtain the IdentityIQ SCIM 2.0 base URL and a technical account with read access to its Users and Schemas resources. Confirm that ICAP can reach the service from its deployment environment. The account also needs to be able to read users with the filtering, sorting, and pagination used by the configured synchronization. Use HTTPS for the SCIM connection because the connector sends the technical account's credentials to that service.

• Inspect the IdentityIQ Schemas response to find the exact names and paths of the attributes you intend to map. Custom attributes depend on what that IdentityIQ installation publishes.

• Choose an IdentityIQ attribute that has exactly one stable, unique value for every user. Map it to an ICAP externalIds value, and check for existing ICAP identities with the same value before the first synchronization. An ICAP id is a separate, ICAP-generated identifier.

• Agree which identity fields the connector will manage, including its built-in mappings. Mapping.Attributes does not list every field the connector updates. Changes to fields managed by either built-in or configured mappings may be replaced by a later synchronization.

• Define any ICAP identity custom fields before mapping values into extensionFields. The embedded ICAP service does not support automatic custom-field provisioning; leave Sync.EnsureExtensionFields at false.

• Obtain the current tenant version before an update; the tenant PATCH requires that version in If-Match.

Configure a tenant

The connection, synchronization schedule, and mappings are configured through scimProvider on the tenant resource. The prerequisite scimSynchronizationAllowed setting is a separate tenant feature returned by /features; arrange its enablement through HIS support before configuring the provider. Set scimProvider when registering a tenant, or update it with PATCH /icap/v1/tenant/{tenantId}. The provider type is SailPointIdentityIq. Its config object contains Scim, Sync, and Mapping sections for the connection, synchronization behavior, and field mapping respectively. The tenant API validates the configuration before saving it.

For an existing tenant, first read GET /icap/v1/tenant/{tenantId} and record its numeric version. The following example adds a connector that checks IdentityIQ every 60 minutes, selects one known test user, uses the SCIM user ID for correlation, and explicitly maps the two required name fields. Built-in mappings also apply, as described below. Replace the host, tenant, token, version, test username, and IdentityIQ credentials with your own values. See the configuration reference below for supported settings and defaults.

BASE_URL="https://<your-icap-host>/icap/v1/tenant/<tenantId>"
TOKEN="<access-token>"
TENANT_VERSION="<numeric-version-from-GET>"

curl --fail-with-body --silent --show-error \
  --request PATCH "$BASE_URL" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header "If-Match: $TENANT_VERSION" \
  --data-binary @- <<'JSON'
[
  {
    "op": "add",
    "path": "/scimProvider",
    "value": {
      "type": "SailPointIdentityIq",
      "config": {
        "Scim": {
          "Url": "https://<identityiq-host>/identityiq/scim/v2",
          "Username": "<identityiq-technical-user>",
          "Password": "<identityiq-password>"
        },
        "Sync": {
          "Interval": 60,
          "UserFilter": {
            "Attribute": "userName",
            "Values": ["<exact-test-username>"]
          }
        },
        "Mapping": {
          "ExternalIdPath": "$.id",
          "Attributes": [
            { "SourcePath": "$.name.givenName", "TargetPath": "$.firstName" },
            { "SourcePath": "$.name.familyName", "TargetPath": "$.lastName" }
          ]
        }
      }
    }
  }
]
JSON

The filter selects users whose source userName matches a listed value. Verify the chosen filter directly against IdentityIQ's GET /Users?filter=... before enabling the connector. Omitting UserFilter can synchronize the entire source population. In the tested dev deployment, the first synchronization began soon after the configuration was saved, so apply a narrow filter before the first update.

Use replace instead of add when changing an existing /scimProvider. Read the tenant again to confirm the provider was saved; synchronization continues asynchronously. Keep credentials in an approved secret-management process. Tenant responses mask the SCIM password, so do not copy a masked response into a later configuration update. To change only the interval, a nested JSON Patch replace at /scimProvider/config/Sync/Interval worked in the tested dev deployment and preserved the stored credentials.

The service starts a connector runner when it detects the tenant configuration and reloads it after tenant changes. A newly started runner attempts synchronization immediately; changing an existing configuration recalculates its schedule without adding an immediate run. Removing scimProvider stops the runner for that tenant. It does not remove identities already synchronized into ICAP.

If a provider update returns SCIM synchronization is not allowed for tenant ..., check scimSynchronizationAllowed through the tenant's /features endpoint and contact HIS support to have it set to true.

Configuration reference

This reference covers the configurable properties in the supplied service and connector implementation on the develop branches, reviewed on 7 October 2026. The dev integration tests verified the basic interval, inclusion filter, mappings, and default retention behavior. Other settings below are confirmed from source code; they were not all exercised against the deployed environment. Confirm the connector version with HIS support when applying the reference to another release. The dev OpenAPI contract exposes config as a generic object rather than a detailed settings schema.

Paths are relative to scimProvider. Use the capitalization and JSON types shown. Unknown configuration sections or keys are rejected. Defaults apply when a setting is omitted; they are not instructions to send null or an empty array.

Provider and connection

Synchronization

Configure at least one synchronization trigger: a positive Interval, ScheduledTime, or Cron. When several are configured, the earliest upcoming trigger wins. Interval timing is calculated after the previous run completes. Daily reconciliation can wake the runner separately at ReconciliationTime, but it does not satisfy the runner's requirement for a synchronization trigger. Times use the deployment's local time zone; confirm that zone with HIS support.

Interval: 0 does not disable the provider or request a single run. The supplied implementation rejects starting a continuous runner when no synchronization trigger is configured, even though the tenant API accepted saving that configuration during QA. Use a positive interval in the basic setup, or configure one of the alternative triggers. Remove scimProvider to stop synchronization.

With Attribute: "userName" and Values: ["alice", "bob"], Include produces userName eq "alice" or userName eq "bob". Exclude selects other usernames and users without userName. With Values omitted, Include selects users where the attribute is present and Exclude selects users where it is absent. The connector escapes quotes and backslashes in values. Verify the resulting filter against IdentityIQ before enabling it. Omitting the filter can synchronize the entire source population.

Mapping

Supported native targets are firstName, middleName, lastName, displayName, status, emails, phoneNumbers, photo, dateOfBirth, gender, citizenship, birthCountry, and type, written as $.<attribute>. Values must also satisfy ICAP's identity validation; a syntactically valid mapping does not guarantee a successful write.

Use JSON arrays for populated lists in tenant requests. Omit optional lists when unused rather than copying the model's empty-list defaults into a request. An absent or unusable mapped value without a fallback is omitted from the outgoing identity data; it does not automatically clear the existing ICAP value. An unknown status value is omitted and logged as a warning. For a new identity, an omitted status follows ICAP's default of active, so explicitly validate your status mapping.

Example with contacts and an extension field

The following Mapping section was exercised with source changes, status changes, and contact updates. Replace the Mapping section in the earlier configuration with this example after defining an ICAP identity extension field with key employeeId and data type text. Confirm that IdentityIQ publishes the shown SailPoint schema URN and employeeId attribute. Built-in phone mapping also copied the source SailPoint extension's phone value into ICAP phoneNumbers in the validated deployment.

{
  "ExternalIdPath": "$.id",
  "Attributes": [
    { "SourcePath": "$.name.givenName", "TargetPath": "$.firstName" },
    { "SourcePath": "$.name.familyName", "TargetPath": "$.lastName" },
    { "SourcePath": "$.displayName", "TargetPath": "$.displayName" },
    { "SourcePath": "$.active", "TargetPath": "$.status" },
    { "SourcePath": "$.emails[*]", "TargetPath": "$.emails", "Type": "work" },
    {
      "SourcePath": "$['urn:ietf:params:scim:schemas:sailpoint:1.0:User'].employeeId",
      "TargetPath": "$.extensionFields.employeeId",
      "Type": "text"
    }
  ]
}

Inspect the IdentityIQ source schema and verify a representative user response before selecting a contact mapping. Confirm the contact shapes and number of values supported by your installation.

Plan the mapping and lifecycle

Map IdentityIQ's given and family names to ICAP firstName and lastName. These are required for an ICAP identity; a source user missing either value cannot become a valid identity without an agreed fallback.

The connector adds the following six built-in mappings unless an explicit row targets the same field. Use the exact target spelling shown when overriding a default. Omitting a field from Mapping.Attributes keeps its built-in mapping; it does not establish that ICAP owns the field. In dev QA, locally edited display name, status, email addresses, and phone numbers were overwritten after a source change even with only the two name rows explicitly configured. Additional rows can populate other native attributes and tenant-defined extensionFields.

The table includes the built-in rows, the separate correlation setting, and one example custom-field row:

These are illustrative paths, not a ready-to-submit tenant configuration. Check your IdentityIQ /Schemas response before using a custom attribute: its schema URN and attribute names may differ. Use bracket notation for a schema URN containing colons. Keep the external-ID key and source identifier consistent for identities already in ICAP.

Check how IdentityIQ represents active and inactive users. In the validated deployment, the built-in status mapping converted SCIM active: true to ICAP active and active: false to ICAP inactive. Confirm the meaning of your source states and test an offboarding case, including any configured status mapping. An unexpected or unmapped state must not be treated as proof that physical access has been revoked. If you map a birth date, use the YYYY-MM-DD format accepted by ICAP. Map a photo only when the IdentityIQ SCIM service actually publishes a suitable value, and decide whether SailPoint or Remote Photo owns that field.

Sync.DeletedIdentities defaults to Report. A full import or reconciliation identifies ICAP identities whose paired source records are missing and reports them as deletion candidates. This mode retains those identities and does not set them to inactive. Dev QA confirmed that deleting a source user left its ICAP identity active. Use the existing ICAP offboarding workflows to deactivate an identity and review its access assignments when source removal must revoke access.

Set Sync.DeletedIdentities to Delete only when automatic removal is the agreed lifecycle policy. The connector confirms that a candidate is absent from IdentityIQ before removal. The embedded service calls ICAP's normal identity removal operation, which soft-deletes the identity; it does not purge its stored data. Deletion handling runs during full imports and reconciliation, rather than on every ordinary delta run. Reconciliation: "Off" therefore removes the daily opportunity to detect deleted source users.

Filtering out a user does not mean that the user was deleted. The connector reads excluded users to protect their matching ICAP identities from deletion. It also suspends deletion when the source returns no records while ICAP has paired identities, when source records have unusable correlation values, or when absence cannot be confirmed. An empty source is therefore not a command to remove every synchronized identity. Check logs for suspended deletion or retained candidates.

The first synchronization imports the complete selected population. Later runs normally select users by meta.lastModified or meta.created. Changing the filter, mapping rows, correlation path, status value sets, or switching from Report to Delete resets synchronization state so the next scheduled run can perform a full import. In dev QA, re-including a user synchronized a change made while that user was excluded. The default Daily reconciliation reports source users missing in ICAP but does not itself import them; DailyFullImport can import or repair the complete selected population each day.

The explicit deletion mode is confirmed by source review, but was not exercised against the dev service during the original integration QA. Test it in a non-production tenant with dependent ICAP assignments and any PACS integration before relying on it for offboarding.

Verify synchronization

Start with a non-production tenant and a small, known set of IdentityIQ people. After the configured synchronization has run, use ICAP's identity list or get endpoint to check their externalIds, names, contact details, status, and any mapped custom fields. Use the externalIds filter to locate candidates, then confirm the returned key and value because that filter matches values across external-ID keys. Check that existing identities were matched as intended and that no duplicates were created.

Test a new user, a changed user, an inactive user, and a user excluded by any source filter. If removal is enabled, test a user deleted in IdentityIQ and inspect dependent ICAP assignments before using that setting in production. Check connector logs for skipped records, duplicate correlation values, rejected ICAP writes, and failed runs.

If PACS integration is enabled, check downstream transactions after each test. A successful SCIM synchronization does not by itself prove that a PACS has applied the identity change.

Operational boundaries

• Synchronization is asynchronous. A successful tenant update means the configuration was accepted, not that a synchronization run has completed.

• The connector stores per-tenant synchronization state and uses a per-tenant lock so that work can resume and concurrent runners do not process the same tenant at once. Allow for a delay before a change appears in ICAP.

• IdentityIQ's SCIM service does not notify this connector of every user change. The connector discovers changes through its configured synchronization schedule; allow for that interval when checking a recent source change.

• Identity status can be active or inactive. Decide how your IdentityIQ source and mapping represent offboarding before relying on the resulting ICAP status. Review credential and access assignments separately as part of offboarding.

• ICAP exposes no tenant API operation in this integration to trigger a run or inspect its internal synchronization checkpoint. If expected changes do not appear, check the IdentityIQ SCIM service, the tenant configuration, and ICAP connector logs with your HIS administrator.

• Personal data copied into ICAP follows ICAP's identity lifecycle and privacy processes. Plan retention and deletion in both systems; removing the connector configuration is not a data purge.

For the tenant API, numeric If-Match handling, identity fields, and downstream PACS behavior, see Tenants and feature settings, Updates and concurrency, Identities, and PACS integration in the ICAP documentation.