Before employees can report a case via your internal portal, they must log in with your organization's Single Sign On (SSO) integration. This means employees will be able to access your internal portal using the same log in information from another application, such as your human resources information system (HRIS).

You can configure two separate SSO integrations with Case IQ for the:

1. Internal portal, where employees can submit cases to your organization.
2. Main Case IQ application, where investigators and managers work through cases and administrators manage the application's settings.

This article covers how to configure an SSO integration for your application's internal employee portal, including:

• Setting up an SSO integration by uploading metadata or manually configuring all settings.
• Generating Case IQ metadata.
• Mapping fields from your identity provider to the fields of internal portal user accounts.

To manage your SSO settings for the main application, refer to the Set up Single Sign On (SSO) article instead.

We use several technical terms in these instructions to explain how an SSO integration works. See a glossary of important SSO terms below:

Upload Metadata Method

You can quickly configure an SSO integration by uploading a metadata file into Case IQ. Metadata contains the provider certificate and URL in XML format to help set up a SAML communication between the identity provider and service provider. 

1. Navigate to Settings > Access > Internal Portal Single Sign-On (SSO). 

2. You can either upload metadata as an .xml file or enter your identity provider’s URL. 

3. Click Confirm on the “Upload Metadata?” pop-up. The “Identity Provider Certificate”, “Identity Provider Endpoint”, and “Identifier Format” fields will be populated in the form, but your configuration settings will not be saved yet.

4. Complete the following fields: 

• Identifier Mapping: indicate the required data field for creating Case IQ accounts, such as email or first name. The field you choose will tell Case IQ how to connect identity provider information with Case IQ user profiles and look for existing user profiles.
• Identifier Data Mapping: choose the identity provider attribute to map to the data field you select in “Identifier Mapping”. For example, if you select “Email” in “Identifier Mapping”, enter the attribute value of the email field in your identity provider. The following sample identity data mapping attribute was used in the screenshots video below for email: “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
• Enabled: set to “Yes” to activate your SSO integration. 

5. Click the Save button to enable the SSO integration for your internal portal. To map additional data from your identity provider to Case IQ fields, refer to the User Mapping section of this article.

Manual Configuration Method

Rather than uploading metadata, you can manually fill in all fields on the "Internal Portal Single Sign On (SSO)" page. Alternatively, you can complete the same settings in Settings > System > System > Options (see details in Options).

1. Navigate to Settings > Access > Internal Portal Single Sign-On (SSO). Click the Edit button.

2. Set the "Enabled" field to "Yes". You will not be able to change the Protocol, Auto User Provisioning, or User Role Fallback settings.

3. Fill in the following fields in the Identity Provider (IdP) section. You can find this information from your identity provider application’s settings.

• Identity Provider Endpoint: paste or type your identity provider’s URL in the text box, which will tell Case IQ from what source to accept the authentication information. 
  • Your identity provider URL will look something like this sample URL: "https://report04.caseiqlab.com/simplesaml/saml2/idp/metadata.php".
• Identity Provider Certificate: copy your identity provider certificate from your identity provider application’s settings and paste it in the “Identity Provider Certificate” field. The identity provider certificate will appear as numerous lines of random alphanumeric characters.
  • The certificate is exchanged between the identity provider and Case IQ. Case IQ must have the certificate to confirm that information sent from your identity provider is coming from a trusted source.

4. Fill in the following fields in the Service Provider (SP) section to tell Case IQ how to use data from your identity provider.

• Identifier Mapping: choose the required data field for creating Case IQ accounts, such as email or first name. The field you choose will tell the system how:
  • Case IQ should connect information from the identity provider to a Case IQ user profile.
  • Case IQ should look for existing user profiles.
• Identifier Data Mapping: enter the identity provider attribute to map to the data field you selected in “Identifier Mapping”. For example, if you select “Email” in “Identifier Mapping”, enter the attribute value of the email field in your identity provider. 
  • Your identity provider's data mapping attribute will look similar to the following sample attribute: “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”.
• Identifier Format: indicate how identity provider information will be mapped to Case IQ user accounts via the SSO integration. You can select one of the default options available in the “Identifier Format” picklist. Alternatively, you can type in a custom format and hit Enter on your keyboard.
• Require Identity Provider to Sign Assertions: choose if the identity provider should sign each assertion. Assertions are messages from the identity provider containing the user's authentication details. By default, “Require Identity Provider to Sign Assertions” is turned on, as this is the default signature option for most identity providers. You can turn this option off if your identity provider does not require assertions to be signed.
• Require Identity Provider to Sign Entire Authentication Response: indicate if the identity provider will sign the SAML response at the top level, meaning the signature will appear outside the assertion block. By default, “Require Identity Provider to Sign Entire Authentication Response” is turned off. Turn this option on if your identity provider will sign the SAML response at the top level.
• Request Authentication Context: choose if you want to provide authentication context to indicate what information the identity provider will send to Case IQ in the SAML assertion to make an informed entitlement decision.
  • If you select “Yes”, the “Authentication Context” field will be displayed. The system default context will already be populated but you can either select or type in another context. 

5. Click the Save button to enable the SSO integration for your internal portal. To map additional data from your identity provider to Case IQ fields, refer to the User Mapping section of this article.

Service Provider Metadata

If your identity provider needs additional information from Case IQ to the SAML communication, you can check the following fields on the Internal Portal Single Sign-On (SSO) page, which are automatically generated:

• Service Provider Entity ID: a unique name for Case IQ as the service provider, which by default is the metadata URL.
• Internal Portal Service Provider Consumer URL: Case IQ will use the following format: “[your application’s URL]/authd/internal-portal-saml”.

After setting up and enabling the SSO integration in Case IQ, you can preview and download service provider metadata from Case IQ as well. Click the Options () button to see the “Download” and “Preview XML” options, so you can save the metadata XML file or view it in a pop-up.

User Mapping

After you have configured your SSO integration, you can use the User Mapping section to set exactly how the information sent from the identity provider will be used in Case IQ.

All User Mapping elements are numbered in the screenshot below and descriptions are provided following the image.

1. The column of dropdown menus, labelled (1) in the screenshot above, are Case IQ user profile fields. The following user profile fields will be displayed in the dropdown menus by default: “Email”, “User ID”, “First Name”, "Last Name", “Language”, “User Role”, and “Theme”. 
2. The text boxes, labelled (2) in the screenshot above, are data fields sent from your identity provider. For the “Email”, “User ID”, “First Name”, and “Last Name” Case IQ fields, the attribute values used by Microsoft Azure Active Directory will be populated in the identity provider data fields by default, as these attribute values are commonly used in user mapping. To change the attribute value, type in your identity provider's attribute value for the equivalent data field.
3. When you click the plus button beside a field, (3), you can add default values for the user profile field or set up a custom value mapping scheme if there are multiple identity provider values to map to one Case IQ user profile field. See more in the next sections, Default User Profile Values and Custom Values.
4. Click the Delete button, (4), to remove the user profile field row if your identity provider does not contain a corresponding field. Alternatively, you can leave the identity provider attribute field blank.
5. Add more fields from the user profile form by clicking the “+ User Mapping” button, (5). The “Search Fields” dropdown that will be displayed will contain all fields on the user profile form, including dynamic fields added via the Form Builder (see Edit a Standard Form Layout). 

Default User Profile Values

You can set a default field value by clicking the Plus button for the row. This means that all user accounts created by this SSO integration will have the default value you selected for the field.

1. Click the Edit button on the Internal Portal Single Sign-On (SSO) page. 

2. Scroll down to the User Mapping section. Click the Plus button for the User Mapping row.

3. In the "Add Values" pop-up, select an option in the “Default Value" dropdown. This dropdown includes all options available in the corresponding Case IQ user profile field picklist. 

4. Click Save in the "Add Values" pop-up to save the default value for that field. Then, save your internal portal SSO settings. 

Custom Values

If the corresponding field in your identity provider has more values than the Case IQ user profile field, you can create a custom mapping scheme using the following steps.

1. Click the Edit button on the Internal Portal Single Sign-On (SSO) page. 

2. Scroll down to the User Mapping section. Click the Plus button for the User Mapping row.

3. In the Custom Values section of the Add Values pop-up, click the “+ Value” button. 

4. Choose a value of the user profile field in the “Select” dropdown. 

5. Enter the value in your identity provider to map to the user profile value.

6. You can add more custom values by clicking the “+ Value” button again. 

7. Click Save to submit your custom value mapping scheme, which will now be displayed under the identity provider field in the User Mapping section. Then, save your internal portal SSO settings.