The Incident IQ ADFS App allows administrators to integrate Incident IQ with Active Directory Federation Services (ADFS). It comes with the Incident IQ LocalAd user sync service, which automatically populates user data in iiQ from the active directory server. This allows users to log in to Incident IQ using ADFS single sign-on seamlessly.
The following guide is designed to provide step-by-step instructions on how to install the Microsoft Onsite Active Directory Federated Services App.
Installation
Before beginning the installation process, you will need to ensure you have the following:
Ability to create and edit user permission in your active directory.
A machine that runs .NET Framework v.4.5.1 or higher and has network access to your district’s AD server.
Begin by selecting Incident IQ Apps > Browse on the left navigation bar.
Click on the Microsoft ADFS app and then select Install to begin.
Step one of the installation process provides an overview of how installing the Microsoft ADFS app will affect your Incident IQ installation. Select Continue once you are ready to proceed to step two.
Step two of the installation process provides an overview of how installing the Microsoft ADFS app will affect your Incident IQ installation. Once you have completed your review, select Install App to begin the integration process.
Once the installation has been completed, you can begin creating an active directory user.
Creating an Active Directory User
Once you’ve installed the Microsoft ADFS app in Incident IQ, you will need to create a new user in your Active Directory. This user will need the following roles assigned to it:
Replicating directory changes.
Read.
Important Note: You will need to complete this step before proceeding. If you are unfamiliar with granting these specific permissions to a user, please refer to the following Microsoft help guide on Giving Users Replicating Directory Changes Permissions.
Downloading the Service Provider Metadata
For the next phase of the ADFS installation, you will need to click on Download Service Provider Metadata under the General section of the Overview tab.
In the new tab, copy the URL in the window that opens with your site’s metadata. This link will be used in the next section of your ADFS installation.
Establishing the ADFS Party Trust
On your AD server, begin by running the application ADFS (Active Directory Federated Services). Right-click the Relying Party Trusts node in the tree and click Add Relying Party Trust.
This will open the Add Relying Party Trust Wizard. From here, keep the Claims Aware option checked before clicking on Start.
Ensure the “Import data about the relying party published online or on a local network” option remains checked. In the “Federation metadata address” field, you must paste the URL copied in during the previous section. Once you have the metadata link filled out, click Next.
In this step, you can keep the default name for the relying party or rename it to whatever you want. Once you are satisfied with the name, click Next.
Leave “Permit everyone” checked on the “Choose an access control policy” section, then click Next.
You will not need to do anything in the next step. Click Next.
Make sure “Leave Configure claims issuance policy for this application” is checked, then click Close.
In the Edit Claim Issuance Policy dialog that is now displayed, click Add Rule.
In the next step, leave Send LDAP Attributes as Claims selected and click Next.
Give the claim rule a name of your choosing (i.e., IncidentIQ). In the Attribute store dropdown, select Active Directory.
Finally, you will need to map one or more LDAP attributes to send to iiQ that will be used to lookup the user. You must pick attributes with the same value in both systems while being unique and available for all users logging in. For most districts, mapping the username and email address will be sufficient. Once mapped, click Finish.
When you’re happy with your mapping, click View Rule Language. That will bring up a dialog similar to the one below. Take note of the URLs that start with the following:
These SAML attributes will be passed to IncidentIQ and need to be mapped inside the Incident IQ ADFS app. This will be covered in the next section. Click OK on all three open dialogs to return to the main ADFS window. This part of the setup is now complete.
Configuring Identity Provider Settings
At this point, you will need to provide your ADFS metadata URL and SAML attributes identified at the end of the previous section. Begin by navigating the Microsoft ADFS app in Incident IQ and selecting the Identity Provider Settings tab.
From here, you will need to enter your ADFS metadata URL. You can find your ADFS Federation Metadata file URL on the ADFS server through AD FS Management. Click on ADFS > Service > Endpoints and go to the Metadata section. The link will look similar to the link below:
Once you have the link, enter it into the Url field in the Identity Provider Settings page.
Once you enter the ADFS metadata URL, you should see the Metadata Document section automatically populate with your metadata information.
Next, in the SAML Attribute Mapping section, click on the Add New Map button.
Next, you will need to enter your SAML data URL into the SAML Attribute Name field, then select which user data field this should correspond to in Incident IQ. You will want to map SAML attributes to Incident IQ’s username and email fields. These attributes should begin with the following as noted at the end of the previous section:
Additionally, you will need to identify the SAML attribute and repeat this process for each additional data field you want to pull from ADFS beyond the username and email fields.
Once you have entered your metadata URL and completed mapping your SAML data URLs, click Save at the bottom of the page.
Downloading SYNC and Configuration Files
Now you will need to download the application for the AD-iiQ sync. This application will need to be downloaded on a machine with network access to reach an AD server (you can run it on the AD server itself, but that’s not a requirement). The app’s machine must also have the .NET Framework v4.5.1 or higher.
If your ADFS installation meets the system requirements, begin by clicking on the Executable tab in the ADFS app.
From here, you will need to fill in the following information:
AD Username
AD Password
AD Domain
AD Server IP
If you do not have an account created in ADFS for this purpose, you will need to do so before proceeding further.
You may also add specific OUs to search for groups and users and select additional AD attributes to copy over into Incident IQ if needed. Please note that these fields are optional, and we recommend leaving the Group and User OU fields blank.
Once you have filled in the Active Directory Connection information, click Download Executable.
Configuring the Active Directory Integration
After you have created your AD user and downloaded the executable, you will need to extract the Microsoft AD Connectors file. Once extracted, run the application titled IncidentIQ.Connectors.MicrosoftAd.exe as an administrator. This will open up a new application window. At this point, click Run now to begin your first manual sync.
Running the application can take a while, depending on the number of users in your AD (syncing about 10,000 users takes roughly 10-15 minutes). Upon completion, you will see a message stating, “Completed sending data to IncidentIQ.”
Creating a Scheduled Sync Task
To schedule the sync to occur automatically, you’ll need to create a task in Windows Task Manager. You can do so by searching for Administrative Tools and selecting Task Scheduler. This will open the Task Scheduler window.
In the Task Scheduler window, start by clicking on Action > Create Basic Task...
This will open the Create Basic Task Wizard. At the very least, you will need to provide a name for the new task. You can also add a task if desired. Once complete, click Next.
In the next step, you will be asked to select when this task should Trigger. We recommend running it daily (overnight) for the most accurate user data. Please ensure you set the task to run regardless of whether a user is logged in or not on the server. Once complete, click Next.
For the next step, you will need to specify what action the task will take when running. Select Start a Program and then click on Next.
When specifying the action to perform, locate the file IncidentIQ.Connectors.MicrosoftAd.exe in the Program/script file browser. Supply the argument -usersync in the Add arguments field. And finally, you will need to indicate the path you unzipped the files to in the Start in field. Once complete, click Next.
In the final step, you may review your task’s settings. Once you have completed your review, check the Open the Properties dialog for this task when I click Finish option and then click Finish.
In the properties pop-up window, begin by selecting Run whether user is logged on or not. Additionally, you will also need to check Run with highest privileges. Failure to check both options can prevent the connector from processing requests.
---
Hannah Bailey - Director, Customer Engagement