Warning: This document contains instructions for adjusting app synchronization settings that can adversely affect your device data, user data, and/or user mapping settings in Incident IQ. As such, only qualified personnel should proceed with making adjustments to the settings outlined in this document.
Guide Overview
The Microsoft ADFS Integration App allows administrators to facilitate logins through Microsoft ADFS single-sign on in Incident IQ. This also allows districts the ability to automatically populate and update user data in iiQ based on information from your local active directory server. The following guide is designed to provide an in-depth overview on how to manage the Microsoft ADFS App in iiQ.
Not what you were looking for? Perhaps one of these other guides will help:
- Installing the Microsoft ADFS App – A guide designed to provide step-by-step instructions on how to install the Microsoft ADFS App in Incident IQ.
- Managing Incident IQ Apps – A guide designed to provide a brief overview of Incident IQ Apps and how to access app management.
Guide Index
You can use the following links below to quickly navigate to a specific section in this document. To quickly return to this index simply use the Return to Index link located at the end of any section.
Accessing the Microsoft ADFS App Management
Navigate to the Apps Management page and select the Manage button on the Microsoft ADFS App.
This will take you to the Microsoft ADFS App management page where you will be able to select the following tabs:
- Overview tab where you can view basic user and group data, reset your authentication status or run a manual sync with your active directory.
- Identity Provider Settings tab allows you to configure your Microsoft ADFS metadata, SAML attribute mappings, miscellaneous logic used during login attempts, as well as your login button.
- Login History tab where you can review both successful and unsuccessful login attempts made by your district users.
- User Mappings tab where you can update your filter settings and email translations.
- Location Mappings tab where you can change the default location users will automatically map to if they do not have an existing mapping in the system.
- Role Mappings tab where you can change the role users will automatically map to if they do not have an existing mapping in the system.
- User History tab where you can look up individual users data coming in from Microsoft ADFS.
- Sync Executable tab allows you to setup, update, and download your sync executable file.
Overview Tab
This tab provides you with a brief summary of your current users, groups, and changes made to users in Incident IQ during the last sync with Microsoft ADFS.
In the General Settings tab you may enable the following settings:
- Enable User Login: This allows users to log into Incident IQ through the Microsoft ADFS SSO. If this option is disabled, then all accounts authenticated through Microsoft ADFS will be unable to log in.
- Enable User Sync: This option allows Incident IQ to update user accounts with data provided by the iiQconnectors app. Without this option, the ability to run nightly or manual user syncs will become disabled.
Also, you have the option of forcing a manual sync with your active directory by selecting Re-Import. Please note that this import will only update user data based on the last data sent to Incident IQ through the connectors app. If you are running a manual sync during the day you will first want to manually run the connectors app to send over a new batch of user data.
And finally, you can use the Download Service Provider Metadata link to access the Incident IQ metadata url. This is only needed during the installation process or when making changes to the Incident IQ vendor account in Microsoft ADFS.
Identity Provider Settings
This tab allows you to setup and configure your Microsoft ADFS metadata, SAML attribute mappings, miscellaneous logic used during login attempts, as well as your login button.
Underneath the Identity Provider Setup, you may select whether your algorithm uses SHA-1 or SHA-256. Additionally, the metadata url used in this tab can be found in your instance of Microsoft ADFS. You do not have to populate or edit the metadata document as this is filled in automatically when you save your metadata url.
The SAML Attribute Mapping section allows you to determine what field Incident IQ should use when looking up users, and what field in Microsoft ADFS iiQ should be checking against.
The Identity Provider Options allows you to configure miscellaneous options used during user logins. They are as follows:
- Allow Identity Provider Initiated SSO: This option should be toggled on if your login requests originate, or can originate, from outside of Incident IQ.
- Allow Replay Attacks: This option should only be used if your users are experiencing “InResponseTo” errors when attempting to log in.
- Omit Assertion Signature Check: This will allow you assertions to omit the assertion signature check.
- Quirks Mode: This allows backwards compatibility for users accessing the site through webpages designed for older browsers.
- Don’t Request Signed Assertion: This will allow your assertions to return unsigned.
- Ignore NameID length requirement: When this option is checked, the minimum length of the NameID will not be validated.
The final option on the page allows you to customize what label you want to use for the Microsoft ADFS login button. By default it will say “Microsoft ADFS,” but you can change it to say something like “District Login” instead.
Login History
This tab allows you to search for all attempted logins to Incident IQ through Microsoft ADFS. This includes the ability to see both successful and unsuccessful logins.
If needed, you can use the Filter Assertions or Login Results options to narrow the login results displayed on this page.
All login attempts that match your current search settings will appear at the bottom of the tab.
User Mappings Tab
From here, you can change your email filter and translation information, as well as your user creation, updating, and deletion settings. The filters section allows you to sort out users being imported based on their email or OU group.
The filters section allows you to sort out users being imported based on their email or OU group.
- Example Email Filter: If you set a filter for “@iiq.k12.ga.us” in the email section, Incident IQ will automatically ignore these email addresses containing this string during a sync.
- Example OU Filter: Setting a OU Filter of “OU=Guests” will ensure that all users that belong to this particular OU will not import during a sync.
- Email Translation: This enables Incident IQ to translate email addresses pulled from Microsoft ADFS into a uniform format when storing in iiQ. This is useful, and often necessary when using Incident IQ in conjunction with programs such as Infinite Campus.
- Example: Setting a translation to find “@k12.us.com” and replace it with “@iiq.k12.ga.us” will ensure that all “@k12.us.com” addresses are updated and stored as “@iiq.k12.ga.us” in iiQ only. This will not make any changes to the addresses stored within Microsoft ADFS itself.
- Create User: When this box is checked, a new user will be created in Incident IQ for any new users found during the initial import from Microsoft ADFS, as well as any new users found when a sync is run.
- Update User: When this box is checked, a user will be updated in Incident IQ when any changes are found during a sync.
- Delete User: When this box is checked, a user will be deleted in Incident IQ when a user is found to have been removed in Microsoft ADFS during a sync.
At the bottom of this tab, you can map fields of data pulling in from Microsoft ADFS to default or custom user fields in Incident IQ using the Map custom values from microsoftADFSSso section.
Please note, any custom field added here will need to also be setup in the sync executable as well in order for Incident IQ to pull this data field during a sync. Please refer to the Sync Executable tab for additional information on making changes to connectors executable.
Location Mappings Tab
This tab allows you to select or modify your current location mappings between Incident IQ and Microsoft ADFS. The default location acts as a fallback for user accounts that do not match any of your other custom location mappings. Please note that if no custom role mappings are set, then all users brought into the system will default to this location
When mapping to locations, you may use groups, OU fragments, location name, or any combination of the three.
The custom mappings section allows you to specify your user groups or OUs you wish to utilize for mapping users to their respective locations. Please note, when using OUs you will want to structure them in the same format as the examples below:
- OU=Cold Harbor
- OU=Class of 2024
- OU=CHMS
Role Mappings Tab
This tab allows you to select or modify which user groups are assigned to which role in Incident IQ. The default location acts as a fallback for user accounts that do not match any of your other custom role mappings. Please note that if no custom role mappings are set, then all users brought into the system will default to this role.
When mapping to roles, you may use groups, OU fragments, location name, or any combination of the three.
The custom mappings section allows you to specify your user groups or OUs you wish to utilize for mapping users to their respective roles. Please note, when using OUs you will want to structure them in the same format as the examples below:
- OU=Staff and Faculty
- OU=Students
- OU=IT Staff
Sync History Tab
This tab allows you to view your sync history between Microsoft ADFS and Incident IQ. Every sync, whether it completed successfully or not, is logged for reference purposes.
Clicking on particular sync will bring up the sync details which include the total number of users, groups, as well as the number of users added, updated and skipped. Clicking on the Created, Updated, or Skipped options below the overview will pull up all users affected by this change during the sync.
User History Tab
This tab allows you to search for any user’s Microsoft ADFS information. This includes their Microsoft ADFS ID, email addresses, Group Membership, and their sync history. This information is useful in quickly determining if the user is affected by any email translations, establishing their group mappings, and identifying if syncing between the systems is being suppressed.
Sync Executable Tab
This tab allows you to configure your sync executable file used to access and send data to Incident IQ. Please note that if you make any changes to this page after initial setup, you will need to redownload a new executable file and replace your old one in order for these changes to take effect during syncs.
At least one profile should be setup on this page with the following data provided:
- AD Username
- AD Password
- AD Domain
- AD Server IP
You may also setup specific OUs to search for during syncs so the system only pulls user data from those. However, we recommend leaving the filters blank.
Also, you may also pull in additional attributes through the executable during syncs if needed. Please note, if you have any custom fields mapped in the Users Mapping tab, you will need to ensure they are properly setup here as well.
