Warning: This document contains instructions for adjusting 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.
This guide details the management of the ClassLink SSO App to enable secure single sign-on with Incident IQ (iiQ).
If the entire text isn't visible when mapping, just hover over it to view it fully.
Accessing App Management
To access the management page for the SSO App:
Go to the Apps Management page by selecting Incident IQ Apps > Manage on the left navigation bar.
Locate your desired SSO application and select Manage to the right.
Overview Tab
Function: Provides a summary of your current users, groups, and user changes in iiQ since the last SSO sync.
You can enable the following settings:
Enable User Login: Allows SSO authentication into iiQ.
Enable User Sync: Required for nightly/manual syncs using the iiQconnectors app.
Sync
Forces a manual sync. Note: Run the connectors app first to ensure fresh data is sent.
General
Download the Service Provider Metadata that is used when installing or updating the iiQ vendor account in ClassLink.
Identity Provider Settings Tab
Function: Configure metadata, SAML attribute mappings, and login logic.
Identity Provider Setup
Select algorithm (SHA-1 or SHA-256). Metadata URLs are found in your ClassLink console under the Incident IQ vendor account.
SAML Attribute Mapping
Define which fields iiQ uses to look up users against ClassLink data.
Identity Provider Options
Miscellaneous configuration (Contact iiQ support for adjustments).
Login History Tab
Function: Review successful and unsuccessful login attempts.
Use Filter Assertions or Login Results to narrow search criteria. Results display at the bottom of the tab.
User Mappings Tab
Function: Define import filters, field translations, and import handling.
Filter
You can select to include or exclude users from being imported based on their email address, Username, OU fragments, or groups (these options depend on your SSO). You can only filter by one email address.
Important: iiQ does not recommend the need to "include" emails upon a first sync.
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.
Example OU Fragment Filter: Setting a wildcard OU Filter to “Guests” ensures that all users who belong to an OU containing the word “Guests” will not import during a sync. When using the OU Fragment filter, you must include a backslash at the beginning.
Example: /serviceaccounts
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 ClassLink into a uniform format when storing in iiQ.
Email Translation: Enables iiQ to translate emails pulled from ClassLink into a uniform format when they are stored in iiQ. This is often necessary when using iiQ with programs such as Infinite Campus.
Example: Setting a translation to find “@google.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 SSO.
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 ‘Create User’ is enabled, this option appears; if a user is removed or disabled in Google, their role in iiQ is set to 'No Access'.
The Set to No Access 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 Google SSO).
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
Function: Map SSO Groups to iiQ Teams.
Groups can only be mapped to one Team per product. 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.
An initial sync must be run to import Groups before Group-to-Team mappings can be assigned.
Mapping and Synchronization
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 after the sync if needed. To save it, you will go through the sync process again 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, OU fragments, location name, or all three.
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, OU fragments, role names, or all three. You can add one or multiple user groups or role names to each role using the Custom Mapping section.
When mapping by OU, you must include a backslash at the beginning of the OU. Example: /serviceaccounts
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
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, OU fragments, or all three. 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, OU fragments, or all three. 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 the 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 SSO information.
Information Displayed: SSO 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.
Sync Executable Tab
Function: Configure the file used to send data to Incident IQ.
Note: If changes are made, you must re-download and replace the executable file.
AD Profile: At least one profile must be created that includes the following information:
AD Username, Password, Domain, and Server IP.
OU filters: You may also set up specific OUs to search for during syncs, so the system pulls user data only from those OUs. However, leaving OU filters blank is recommended.
Additional Attributes: You can include additional attributes through the executable during syncs if needed. Any custom fields mapped in the User Mappings tab must be properly set up here.