- Introduction
- Architectural overview
- Diagram and typical sequence of events
- Encryption and management of payload
- Outages, maintenance windows, and queuing of interception events
- Frequently asked questions
Introduction
IdentityIQ provides an agent that can be deployed to Active Directory domains that can be used to intercept password changes made to user accounts in Active Directory. The AD PWI agent is used to synchronize those password changes to other applications, using IdentityIQ as an intermediary and provisioning engine to push that password change out to other management systems.
Architectural overview
The AD PWI agent is installed on all Domain Controller hosts in an Active Directory domain or forest. The PWI agent is, at its core, a ".DLL" file installed on the Active Directory server that is registered to receive password notification events. The intercept agent communicates password change events back to IdentityIQ by making a REST API call to the same hosts/URLs that service end-user browser requests for IdentityIQ. Due to the nature of Active Directory, and the fact that any domain controller can process a password change event, the agent must be installed on every domain controller host in a forest or directory. Care must be taken to ensure that every installed copy of the AD PWI agent uses the same configuration.
To avoid confusion: other provisioning agents used with Windows, like IQService, are not part of the AD password intercept architecture.
Diagram and typical sequence of events
A password intercept begins when an end-user changes their Active Directory password using ctl-alt-del or any of a number of alternative methods to change an Active Directory account password. The password change is processed by the domain controller host to which the user's session is bound. The AD PWI agent, installed on the domain controller host, receives an event from Active Directory informing it of the sAMAccountName and new password that was assigned. The AD PWI agent receives the clear-text password for the new password in this transaction.
The password intercept agent then looks at the configuration stored in the ServiceConnectionPoint object on Active Directory (in Organizational Unit PWDINT_SERVER_OU) and reads the URL for the IdentityIQ system it should communicate with. The agent then establishes an HTTP/HTTPS connection with the IdentityIQ server, calling the IdentityIQ REST API function to launch a workflow, launching specifically the workflow named as the Password Intercept workflow in the IdentityIQ system configuration (the default workflow is called Password Intercept). The sAMAccountName and clear text new password for the account that had a password change are passed as parameters to the workflow.
Once inside IdentityIQ, the Password Intercept workflow handles the processing and synchronization of the password to downstream applications. The Password Intercept workflow is often modified for site-specific needs. The default behavior of the workflow is to synchronize the new password down to all accounts correlated with the identity for applications which have a direct provisioning connector configured which supports password resets. The default behavior will not create work items with the users clear text password or send those to administrators of non-directly connected systems.
The following diagram illustrates a typical AD PWI installation, and a detailed description is provided below. (Click the picture for a zoomed in view.)
The diagram illustrates an AD domain with 3 domain controller hosts: X, Y and Z. The IdentityIQ PWI agent is installed on every domain controller host. This is illustrated by the gears icons in the drawing.
The arrows indicate the flow of data when an end user resets their password via Active Directory, like when they use ctrl-alt-del from their workstation. The gray arrow shows their workstation binding to the AD network for the password reset. Their password reset is transacted with one of the 3 AD servers, either X, Y or Z as illustrated by the green arrows.
When the password change is logged by the domain controller the, AD PWI agent receives the transaction, including sAMAccountName and new clear text password. The PWI agent establishes a secure HTTPS connection to the IdentityIQ platform through a load-balancer as illustrated by the blue arrows. Most installations use some form of load-balancer between the PWI agents and the IdentityIQ application servers, as shown in the diagram. Finally, the IdentityIQ application servers process the password intercept by invoking the “Password Intercept” workflow for the end user.
Encryption and management of payload
The AD PWI agent communicates with IdentityIQ via a REST API call which is made over an HTTP/HTTPS connection. For encrypted communications, ensure that the URL provided to the AD PWI agent includes the "https://" prefix appropriate for your installation. The specific encryption mechanism used between the AD PWI agent and the IdentityIQ Application servers are configured in a site-specific fashion and are configured when the keystore and HTTPS encryption certificates of the IdentityIQ servlet container (Tomcat, JBoss, WebLogic, WebSpehere) are configured. It is possible, but not recommended, to configure the agent to use clear text HTTP to communicate with IdentityIQ.
Inside of IdentityIQ, the user's new password is encrypted with SailPoint's "context.encrypt()" API before the password reaches the Workflow engine for processing and synchronization out to other applications. This prevents workflow debugging and log messages from exposing the user's new password in clear text in a log file. The "context.encrypt()" API uses the site-specific encryption keys configured in IdentityIQ's KeyStore to perform the encryption.
The following log snippet illustrates an example password intercept event being processed by an IdentityIQ application server. On lines 05, 08, 11 you can see the notification of which application's user account had a password change, and on line 12, you can see the ciphertext representing the user's new password.
2015-08-21 14:19:31,247 TRACE http-8080-4 sailpoint.api.IdentityLifecycler:118 - Entering launchWorkflow(app = sailpoint.object.Application@3381ca63[id=2c906e8b432fe43501432ff9b96b0254,name=Active Directory], link = sailpoint.object.Link@34903a17[id=2c906e8b432fe43501432ffa890f026b,application=Active Directory,identity=CN=Chris C. Clay,CN=Users,DC=example,DC=com], ident = sailpoint.object.Identity@43714a3e[id=2c906e8b432fe43501432ffa890f026a,name=chris.clay], password = *****, interceptionTime = 8/21/2015 7:19:29 PM, retryCount = 0, sentTime = 8/21/2015 7:19:29 PM, server = TESTLABDC.example.com)
2015-08-21 14:19:31,247 INFO http-8080-4 sailpoint.api.IdentityLifecycler:359 - Launching password intercept workflow
2015-08-21 14:19:31,247 INFO http-8080-4 sailpoint.api.IdentityLifecycler:360 - <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE WorkflowLaunch PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<WorkflowLaunch caseName="Password Intercept - chris.clay" launcher="PasswordIntercept" targetClass="Identity" targetId="2c906e8b432fe43501432ffa890f026a" targetName="chris.clay" workflowRef="workflowPasswordIntercept">
<Variables>
<Map>
<entry key="applicationName" value="Active Directory"/>
<entry key="identityName" value="chris.clay"/>
<entry key="interceptionTime" value="8/21/2015 7:19:29 PM"/>
<entry key="nativeIdentity" value="CN=Chris C. Clay,CN=Users,DC=example,DC=com"/>
<entry key="password" value="1:Wkte/IDM5aTvNInniczrWg=="/>
<entry key="retryCount" value="0"/>
<entry key="sentTime" value="8/21/2015 7:19:29 PM"/>
<entry key="server" value="TESTLABDC.example.com"/>
</Map>
</Variables>
</WorkflowLaunch>
As of the time of writing (IdentityIQ 6.4p4), the AD PWI agent will negotiate an encryption channel for its HTTPS transaction with IdentityIQ using TLS v1.0. SailPoint plans to support newer encryption options, e.g. TLS v1.2, in a later version of the AD PWI agent. If your installation has specific encryption needs here, please discuss this with your Account Manager, Engagement Manager, or contact SailPoint Support.
Outages, maintenance windows, and queuing of interception events
In the event that the HTTPS load balancer front-ending IdentityIQ's REST API (UI) servers is offline, or IdentityIQ itself is offline, the individual PWI agents will retry connecting after a configured interval. The PWI maintains the password in an in-RAM memory till the password change events are successfully processed. The number of retries and maximum amount of time a PWI agent will re-attempt to submit the transaction to IdentityIQ is configurable in the ServiceConnectionPoint object in Active Directory organizational unit PWDINT_SERVER_OU. The password change events are not spooled to a cache file or recorded on disk. This prevents exposing of users' clear-text passwords in a log, transaction, or journal file.
In the event that the PWI client itself is offline, or is taken offline after IdentityIQ has been offline for an extended period, then password changes that are enqueued in-RAM will be lost and will not be communicated to IdentityIQ. Users need to re-submit new passwords to re-apply the synchronization through IdentityIQ to the downstream systems in this event.
Frequently asked questions
Q: Are the passwords encrypted by PWI before sending them to IdentityIQ? How do we ensure confidentiality?
A: To ensure confidentiality the communication channel between the AD PWI agent and IdentityIQ must be encrypted with HTTPS. This is configured inside the application server. In transit, the message payload (including the password itself) is not double-encrypted in the HTTPS channel, exclusively relying on the HTTPS wrapper to provide security. Once the payload reaches the IdentityIQ application server, the password payload is re-encrypted using IdenittyIQ's encryption before being passed off to other modules of the application software. See the example log above for details. For the TCP/HTTP transit portion of the communication there are some specifics that must be correctly administered for this to be configured in a secure fashion:
- The PWI must be configured to use HTTPS to communicate with IdentityIQ if you want the password payload encrypted.
- If the PWI is configured to use HTTP and not HTTPS then the password will be sent in clear text over the network to the IdentityIQ application server.
- The PWI will send the credentials via clear text HTTP when configured to do so, without issuing a warning or other cautionary message. Please triple-check the configuration of every installed PWI agent in your enterprise.
- An extra security step to take here is to disable clear-text HTTP (ports 80 or 8080) on the application server instances to which the PWI will be connecting.
Q: How does IdentityIQ use DirSync in relation to password intercepts or changes?
A: IdentityIQ uses DirSync to only detect delta changes in the account attributes. This process happens during the account aggregation process and not during the password interception process. The password field values of Active Directory accounts are not aggregated into IdentityIQ. Active Directory stores the passwords as one way cryptographic hash that are not recoverable by external tools after the password has been assigned to the user's account.
Q. How does the password trickle from the filter to IdentityIQ? (i.e. What is the process from the Local Security Authority (LSA) to the IdentityIQ client?)
A. Whenever password change is attempted on one of the Domain Controllers (DCs), the LSA process on that DC gets the request. The LSA checks if the new password adheres to password policies set by the registered password filters on the DC. For validating new password, Windows has some built in password filters. The PWI client registers its own custom password filter under LSA process during installation process. The password intercepted by the filter is sent to the AD PWI client. The client stores it in an in-memory queue and then sends the queued items to IdentityIQ one by one through REST calls.
As illustrated in the link above, each password filter is called twice: first to validate the new password and then, after all filters have validated the new password, to notify the filters that the change has been made. Only when the custom password filter DLL is called the second time to notify of the change, does it send the password change to IdentityIQ.
Q. How is the filter installed and registered on the DC?
A. The filter DLL is installed in the appropriate System folder for 32 or 64 bit machines. It is registered by inserting the The password filter DLL name in the registry entry for HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Notification Packages. The value is - "SAILPOINTPWDINT" for version 6.3p3 and onward
and "IIQPWDINT" for version upto 6.3p2
Installing and Registering a Password Filter DLL (Windows)
Q. Does the Password Interceptor validate the certificate presented to it for validity? Does it accept self-signed certificates only or can it use certificates issued by an enterprise CA ?
A. Yes, password interceptor does validates the certificate, but it will not tell what exactly is wrong with certificate. For example, if the certificate is expired then it will not tell that the certificate is expired but will instead throw an error message like "WebException raised!The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel. Status:TrustFailure". Password interceptor uses self-signed certificates issued on the IdentityIQ server. That client certificate should be exported from the IdentityIQ server and kept under Trusted root CA on the DC where the PWI client is installed. It supports both self signed and enterprise CA certificates.
Q. Is there any way to monitor the service to see if it’s actually doing work or hung up (not just checking to see that it reports as running)?
A. It is Windows service, so you can open the service console and check if it is started. You can also turn on logging. To check if the filter dll is loaded or not, open the Run window and type msinfo32. This will open system information console; select Software environment - > Loaded modules and check the filter dll name in right side pane. (For IdentityIQ versions 6.3p2 and earlier, the name to look for should be IIQPWDINT.dll. For 6.3p3+, look for SAILPOINTPWDINT.dll.)
Q. In the event a DC is out of touch for more than the interception_timeout parameter or the service has to be restarted, is there a way to see what the interceptor on that DC has pending to send to IIQ before it’s discarded?
A. If interception_timeout happens then that interception will be discarded. This is why it is important to consider that configuration value carefully and set it appropriately. In case of service restart, we can see user names for which the interception data has not yet been sent in the service log files.
Q. What permissions are needed for an AD account to be able to install the client service on a DC? And what permissions are required to run the service ?
A. Creating configuration object in the directory (PWDINT_SERVER_OU + SCP object) requires Read and Write permissions on the Directory. Creating registry keys for storing part of configuration requires read, write permissions on the Registry. Creating a Windows service requires Administrator privileges.
