The IIQ Backbone: Architecture, Clusters, and the Heartbeat
👋 Hi, I’m Kranthi Kumar Puttapaka, a Certified SailPoint IAM Engineer with experience in building secure and scalable identity solutions. I help organizations streamline their Identity & Access Management (IAM) processes and strengthen their security posture. I specialize in designing and implementing enterprise-grade IAM systems using technologies like SailPoint IdentityIQ, Identity Security Cloud (ISC), Okta, Azure AD (Entra ID), and CyberArk. My focus areas include identity governance, access lifecycle automation, role-based access control, and Zero Trust security architectures. Over the years, I’ve led multiple SailPoint IIQ to ISC migration projects with zero downtime, developed custom connectors for seamless integrations, and implemented compliance frameworks like SOX, GDPR, HIPAA, and NIST. I also have hands-on experience with cloud platforms such as AWS and Azure, enabling organizations to adopt cloud-native identity governance. On the technical side, I work with Java, JavaScript, Python, and BeanShell for customization and automation. My toolkit includes Spring Boot, Spring Security, Docker, Terraform, and databases like MySQL, Oracle, MongoDB, and LDAP. Here on Hashnode, I write about IAM architecture patterns, SailPoint implementation deep dives, cloud identity strategies, Zero Trust security models, and real-world challenges I’ve solved in Identity Governance. Always excited to connect with fellow IAM professionals and share knowledge about building secure, scalable identity solutions. Let’s make the digital world more secure, one identity at a time!
1. The Web Tier (The User Interface & API)
The Web Tier is the presentation and entry layer. It is technically the identityiq.war file deployed into a web container (like Apache Tomcat).
Primary Function: To serve the UI (the "Dashboard") and the entry points for external integrations (the SCIM, REST, and SOAP APIs).
Internal Mechanic: This tier handles short-lived threads. When you click a button, the Web Tier handles that specific request.
Engineer’s Logic: In a clustered environment, you typically place a Load Balancer in front of multiple Web Tier nodes. If one node fails, the user session can be failed over.
Scaling: To scale the Web Tier, you increase the number of HTTP threads in Tomcat’s
server.xmlor add more nodes to the Load Balancer.
2. The Task Tier (The Engine Room)
This is where the real "work" of Identity Management happens. While the code is the same as the Web Tier, the purpose is different.
Primary Function: Executing long-running background processes. This includes Aggregations, Identity Refreshes, Email Notifications, and Workflow executions.
The "Worker" JVM: In high-scale environments, architects designate specific servers as "Task Only." These nodes don't accept traffic from the Load Balancer; their CPUs are 100% dedicated to processing data.
Threading: This tier uses the Task Definition and Task Result objects to track progress. If a Task node crashes, the
spt_task_resultremains "pending" until another node in the cluster picks it up.
3. The Database Tier (The Persistent Store)
The Database (IdentityDB) is the single source of truth. IIQ uses Hibernate (an ORM) to translate Java objects into SQL rows.
The Schema: Almost all tables start with
spt_.spt_identity: All your users.spt_application: Your system connections.spt_link: The accounts on those systems.
The XML CLOB: As we discussed, IIQ stores complex object data in a column called
attributes. This is a CLOB (Character Large Object) containing XML.Engineering Impact: Database latency is the #1 killer of IIQ performance. Because IIQ must "marshal" (convert XML to Java) and "unmarshal" (Java to XML) constantly, your DB I/O must be lightning-fast.
4. The Cluster Heartbeat: spt_server
In a distributed system, nodes need "Self-Awareness."
The Check-In: Every 60 seconds (configurable), each node running the IIQ code writes its status to the
spt_servertable.Split Brain Prevention: If Node A hasn't checked in for 5 minutes, Node B assumes Node A is dead. Node B will then attempt to take over any tasks Node A was running.
Service Definition Pinning: This is the most important configuration for an Engineer. You can go into the System Setup > Servers menu and tell Node A: "You are only allowed to run UI services," and tell Node B: "You are only allowed to be a TaskExecutor." ---
5. The Security Anchor: iiq.properties & secret.key
The iiq.properties file is the first thing IIQ reads when it wakes up. It tells the app how to find the Database.
The
secret.key: This is a physical file or a string in the properties that serves as the AES encryption key for the entire installation.The Trap: IIQ encrypts sensitive data (like your Active Directory Service Account password) before saving it to the
spt_applicationtable.The Disaster Scenario: If you add a new Task Node but it has a different
secret.keythan the Web Node, the Task Node will try to run an aggregation, pull the encrypted password from the DB, and fail to decrypt it. The task will fail with an "Invalid Key" error, even though the password is correct.
Technical Validation Challenge
Scenario: Your company just added a 4th server to the cluster to handle a massive influx of new employees. You've copied the identityiq.war and the iiq.properties file correctly. However, when you start the server, it appears in the spt_server table, but it refuses to pick up any background tasks.
What is the most likely Service Definition that is missing from this new server's configuration in the UI?
If you look at the
spt_servertable in the database, what column would you check to see if the server is actually "talking" to the rest of the cluster in real-time?
What's your assessment of this configuration failure?