This guide details the management of the Microsoft Entra ID SSO App to enable secure single sign-on with Incident IQ (iiQ).
Warning: Adjusting synchronization settings may adversely affect device data, user data, and/or user mapping settings in Incident IQ. Only qualified personnel should make these adjustments.
If the entire text isn't visible when mapping, just hover over it to view it fully.
App Management Navigation
To access the management page for the Microsoft Entra ID SSO App:
On the left navigation bar, click Incident IQ Apps.
Click Manage.
To the right of Microsoft Entra ID SSO, click Manage.
The management page provides access to the following tabs:
Overview: View basic user and group data, reset authentication status, or run a manual sync with your SSO.
User Mappings: Update user filter settings and email translations.
Location Mappings: Change the default location users map to if no existing mapping is found.
Role Mappings: Set the default role to use if no existing mapping is found.
Sync History: Access to view synchronization history between SSO and Incident IQ.
User History: Search for a user’s information with your SSO integration.
Overview Tab
This tab provides a summary of your current users, groups, and changes made to users in iiQ during the last sync with Microsoft Entra ID SSO.
Reset Authentication: Click Reset to reset your authentication status with Microsoft Entra ID.
Manual Sync: Click Start New Sync to force a manual synchronization with your Entra ID directory.
User Mappings Tab
This tab manages user filtering, information translation, and account handling (creation, updates, and deactivation).
Filter
You can select to include or exclude users from being imported based on their email address, Username, or group(s).
Note: You can only filter by one email address.
Example Email Filter: If you exclude an email address and set a filter for “@iiq.k12.ga.us”, iiQ will automatically exclude email addresses containing this string during a sync.
It is recommended to run a sync without the “create user” option enabled first. The filter options are not counteractive.
Mapping (Controls how fields are populated in Incident IQ)
Translate Username: Enables iiQ to translate usernames pulled from Entra ID into a uniform format when storing in iiQ.
Email Translation: Enables iiQ to translate emails pulled from Entra ID into a uniform format when storing in iiQ. This is often necessary when using iiQ with programs such as Infinite Campus.
Example: Setting a translation to find “@azure.com” and replace it with “@iiq.k12.ga.us” will update and store the address as “@iiq.k12.ga.us” in iiQ only, without changing the address in Entra ID itself.
Phone Number Mapping: Select whether to import phone numbers and define the mapping process.
Import Handling (Controls how users are populated in iiQ)
Create User: When enabled, a new user is created in iiQ for any new users found during the initial import or subsequent syncs.
Update User: When enabled, a user in iiQ is updated whenever changes are detected during a sync, including custom fields.
Update Custom Fields: When enabled, only user custom fields are updated when changes are detected during a sync.
Set to ‘No Access’: When enabled, if a user is removed or disabled in Entra ID, their role in iiQ is changed to 'No Access'. This field overrides any locked user fields, prioritizing the disabling of the user in iiQ
Map Custom Values
This section allows you to select additional values to be imported and map them to default or custom fields in iiQ.
Please note that there may be pre-configured mappings that cannot be changed.
Field Mapping Options:
Select the custom value.
Select the iiQ field (default or custom) that the custom value should map to.
If mapping to a Custom Field, you must set a field name, select a field type (text, number, or date), and specify whether the field is searchable via filters.
Additional Options
Login Button Text: Customize the login button text (default is Microsoft Entra ID).
Grace period for re-linking to existing iiQ account: This setting prevents the continuous creation of duplicate user accounts.
The default is 365 days.
This setting is read-only for customers and editable by iiQ Admin Employees.
The last section, Field Mappings, controls which fields this app should update.
Team Mappings Tab
This feature maps groups of users from SSO to Teams in iiQ for assigning permission policies.
Groups can only be mapped to one Team per product. If needed, the same group can be mapped to a team for different products/modules.
When mapping groups to a team, a team is automatically created within Incident IQ. It is not possible to manually map groups to pre-existing teams.
Navigate the Teams Mappings tab. Instructions for creating new groups and mapping them to teams are in steps 1-4, along with rules for syncing.
An initial sync must be run to import Groups before Group-to-Team mappings can be assigned.
Mapping and Synchronization Steps
Group Selection: In the Search field, select groups (excluding nested groups). Wildcard search is supported, with the first 25 matching groups populated.
Team Name: The Team Name defaults to the SSO Group name, but you can modify it.
The name must be unique; a duplicate name will trigger an error.
Product Selection: Next (if you have multiple iiQ products), select which product this team should be created for.
Example: Group Admin can be mapped to one team in the Ticketing module and mapped to one team in the Facilities module.
Groups can only be mapped to one Team per product. If needed, the same group can be mapped to a team for different products/modules.
Sync Execution: After creating the mapping and clicking Save, go to the Overview tab and select either:
Download Data from SSO (recommended if your district is going through frequent group membership changes, e.g., at the beginning of the year).
Re-Run Last Sync (if there have been no changes in group membership since the last sync).
Verification and Renaming: After the sync, the new team is created, members are added, and the Status column shows ‘Team Created’.
You can change the team’s name later by clicking Save and then Re-Run Last Sync.
Deletion and Permissions
A mapped group can be deleted by selecting the Trash Can icon on the left and confirming the deletion in the pop-up window.
Team Deletion: An iiQ Team is automatically deleted if the mapped group is removed from the SSO solution or is no longer detected during syncs. Admins must review and update any affected Rules.
User Removal: Users who are no longer members of a mapped group will be automatically removed from the corresponding iiQ Team at the next sync.
Product Deactivation: If an iiQ product is deactivated, teams mapped to that product will no longer appear.
Permissions: Changes to distribution group membership in SSO automatically update Team membership and permissions during the subsequent sync.
Location Mappings Tab
Function: Select or modify current location mappings and adjust the default location for users without a mapped location.
Mapping Methods: Map by groups, location name, or both.
When mapping, if the full name is not visible, hover over the name to view it.
Role Mappings Tab
Function: Select or modify how users are mapped to iiQ roles and select the default role for unassigned users.
Mapping Methods: Use groups, role names, or both. You can add one or multiple user groups or role names to each role using the Custom Mapping section.
SSO integration can only elevate user roles, not downgrade them (e.g., an Agent role cannot be downgraded to a requestor role).
Department Mappings Tab
Function: Select or modify how users are mapped to iiQ Departments.
Mapping Methods: Use groups, Department Name, or both. Custom mappings can use one or multiple user groups or department names.
Employment Mappings Tab
Function: Select or modify how users are mapped to iiQ Employments.
Mapping Methods: Use groups, Employment Name, or both. Custom mappings can use one or multiple user groups or Employment Names.
Sync History Tab
Function: Provides logs for every synchronization attempt (successful or not) between Microsoft Azure SSO and Incident IQ.
Details: Clicking View Details displays the number of users who were added, updated, not changed, or set to no access during that sync.
Actions and Filtering: You can Download SSO Data. Sync data can be filtered under the Details Status section by selecting a status and entering a user’s name or email address.
User History Tab
Function: Allows you to search for any user’s Entra ID SSO information.
Information Displayed: Entra ID, email addresses, Group Membership, and sync history.
Utility: This information helps quickly determine whether the user is affected by any email translations, establish their group mappings, and identify whether syncing between the systems is being suppressed.
