iMIS Power Suite - SSO Premium

Connecting to an External Directory/Identity Provider

Learn how to connect one or more external directories to the iMIS SSO app so they can be used during sign-in.

Important! Ensure that the connection to iMIS setup step is completed first.

Managing directory connections

Do the following to manage the directory connections:

  1. Go to the Cloud Dashboard.
  2. Go to Cloud SSO > Home.
  3. Click the External Directories tab, then choose Manage Directories.

From Manage Directories, you can do the following:

  • Add an external directory (multiple with iMIS SSO Enterprise)
  • Edit or delete an existing directory connection
  • Test a directory connection and view claim information returned from that directory

Multiple directories and the External ID

iMIS EMS includes a hidden field called external_id in user security records. This field is not visible in the Staff site and is only accessible via the REST API. It stores a unique, unchangeable value from an external directory that identifies a specific user or contact record in iMIS.

Initial Directory Connection

When a directory is first connected, the external_id field is blank for all records. While it is blank, iMIS matches users based on their primary email address. Once a user logs in successfully, the field is populated with the external ID from the connected directory (for example, iMIS SSO Premium).

How the External ID Works Over Time

After being populated, the external_id is used for subsequent logins to ensure the same contact record is matched, even if the user’s email address changes. Over time, as SSO is used, more user security records in iMIS will have this field populated.

Multiple External Directories

iMIS SSO Premium supports connecting multiple external directories or identity providers. To prevent conflicts, all external IDs must be unique across all directories.

To achieve this, the external ID from the connected directory is prepended with the internal directory configuration record’s unique ID.

Example:

  • Internal directory record ID: 531b5f5e-2a2a-4b73-b109-3f17f7f34e36
  • External ID from Microsoft Entra (oid claim): 3522ec95-d540-4f11-992f-915efcd00862

The resulting iMIS External ID:

531b5f5e-2a2a-4b73-b109-3f17f7f34e36;3522ec95-d540-4f11-992f-915efcd00862

This ensures each external ID is globally unique across all connected directories.

Directory settings

When creating or editing a new directory connection, the following settings can be configured.

Directory Connection

This section specifies the Service Provider or Client App settings from the external directory.

Each directory provider (Microsoft, Amazon, Google, etc) will have specific, and often different, names for their settings and endpoints. The following documentation is generic, and we offer specific guides for the most common directory providers as well.

  • (required)  Name: A friendly name for the directory connection. Not visible except if using iMIS SSO Premium with the user-facing directory selection screen.
  • (required) Logo: A logo representing the directory. Must be a 245x36px** PNG file (transparency recommended but not required), less than 1 MB.
  • Redirect URL: This value is entered into the external directory when configuring the client application for iMIS SSO. The URL is only available after saving the form. To enter this value before obtaining the other information on this form (for example, Auth/Token URLs, or Client ID/Secret), enter dummy values on this form in the iMIS SSO, save the record in order to obtain a redirect URL, then go back and edit the dummy values with actual values from the directory provider.
  • Discovery Domain: Optional. To input this field, paste the value and selectDiscover... If successful, this will pre-populate the next 3-4 fields automatically, saving time.
    • Typically ends with /.well-known/openid-configuration, but if this part is omitted, we will attempt to add it and fetch the URL anyway.
  • (required) Authorization URL: Enter the authorization or sign-in URL from the directory.
  • (required) Token URL: Enter the token URL from the directory.
  • Userinfo URL: Not all directory providers support this. If you have this value from the directory, enter it here. If omitted, claims located in the Userinfo object cannot be mapped/utilized.
  • Issuer: If you have this value from the directory, enter it here. If specified, this value will be validated against the issuer in the token obtained from the directory during sign-in.
  • (required) Scopes: For most OpenID Connect-compliant directories, enter the following value: openid email profile (openid, email, and profile, separated by spaces). Consult the documentation for your directory as these may be different or you may be required to enter additional values here.
  • (required) Client ID: Obtained from your directory when you create a client application or service provider record.
  • (required) Client Secret: Obtained from the directory when you create a client application or service provider record. Watch out for secrets that expire. If possible, set the secret to not expire, or set a calendar reminder 3 days before the expiration date and update the Client Secret value in the external directory, and then update this directory record in iMIS SSO with the new Client Secret value.
  • (required) Enable PKCE: Enabled by default. Adds a layer of invisible security without affecting the user sign-in process at all. Works on all devices. All major directory providers support it. Only disable this feature if the external directory does not support it.
  • (required) Enable Response Mode Form Post: Disabled by default. Only enable this if the directory requires it. If disabled, uses “Query” response mode, which most directory providers support and prefer.
  • (required) Enable Token Endpoint Basic Auth: Disabled by default. Only enable this if the directory requires it. If disabled, uses the more secure “Post” body authentication.

Note: Requirements taken from Microsoft’s sign-in branding requirements for consistency.

User and Claim Settings

Note: A claim is simply a value in one of three possible sources from the external directory’s response: the Access Token, the ID Token, and the Userinfo Endpoint.

View the claims coming back from a directory by going to the directory listing screen and pressing the Test Directory button. After a successful login, the claim display window will open, showing all of the claim values that were sent back, grouped under each header (Access Token, ID Token, etc).

When mapping claims, specify the variable name or key name of the claim that you want to map, as well as the location of that claim.

This format is used below to map the contact’s information over to iMIS, as well as (optionally) determine if they are a staff user or not.

  • New Contact Member Type: Specifies the member type for new contacts created via JIT. Not applicable to iMIS EMS and has no effect in these environments.
  • New Contact Status: Specifies the member status for new contacts created via JIT. Not applicable to iMIS EMS and has no effect in these environments.
  • External ID Mapping: Specify the claim name and location that represents this user’s unique ID or object ID.

      Important! This value must be a unique value from the directory that represents the user, that stays the same even if they change their email address in the directory. For example, in Microsoft Entra, this is referred to as the Object ID or oid claim, and in Amazon Cognito, this is the Subject or sub claim. Consult the directory’s documentation to find the correct claim to use for a user’s unique, immutable value.

  • Username Mapping: Specify the claim name and location that represents this user’s iMIS username. For iMIS EMS: Set this value to the same value as the Email Mapping field below.
  • Email Mapping: Specify the claim name and location that represents the user’s primary email address (typically, this is labeled as email).
  • First Name Mapping: Specify the claim name and location that represents the user’s first name (typically, this is labeled as given_name).
  • Last Name Mapping: Specify the claim name and location that represents the user’s last name (typically, this is labeled as family_name).

The * next to each claim controls if that claim is required. If the claim is missing or empty, the sign-in will fail.

Note: The External ID, Username, Email, First Name, and Last Name claims are always required. This is due to the requirements of OpenID Connect.

Staff User Identification (Required)

If iMIS is set to use OIDC for Staff & Public Users, and the connecting directory contains a mixture of staff and non-staff users, you must instruct the iMIS SSO on how to determine if a user is a staff user or not:

  • None: This directory only contains public users/members, not any staff users.
  • Always: This directory only contains staff users, not any public or non-staff users.
  • If Claim Type Exists: If set, will look at the entered Staff Claim Name in all of the claim areas (Access Token, ID Token, Userinfo Endpoint) and if there is a claim key or name matching this value (even if the value is blank), then the user is signed in as a staff user.
  • If Claim Type Matches Exactly: If set, will look at the entered Staff Claim Name in all of the claim areas, and if there is a claim key or name matching the specified name, and the claim’s value matches the value entered in the Staff Claim Value, then the user is signed in as a staff user.

Warning! If more staff users are allowed to sign in than there are available staff licenses, unexpected behavior or errors may occur. Always ensure that the staff users that are allowed to sign in via this directory are covered by an available staff license. To block access to certain organizational staff from accidentally signing in to iMIS and creating a license issue, restrict those users' permissions to be able to sign into the iMIS client application in the directory configuration itself.

Advanced Settings

  • Is Hidden: If set, this directory will be hidden from the public directory selection screen, but still available for sign-in (see below).
  • Domain Suffix List: If set, and if the user who is signing in’s email address domain matches one of the domains in this list, then the directory selection screen will be bypassed, and this directory will be automatically selected for that user. The user will be taken directly to the sign-in page for this directory and will not be allowed to select a different directory. This also applies to hidden directories. Specify a single domain, or a comma-separated list of domains, e.g.: example.com -or- example.org, members.example.com

Staff and Public Users in Different Directories

A common pattern is to have staff in one directory (typically Microsoft Entra), and public users or members in a different directory. In this case, it is possible to automatically route staff to use their directory (such as Entra), while all other users are automatically routed to the other directory.

To configure this scenario, use the following settings:

Staff Directory Settings

  • Staff User Identification = Always
  • Is Hidden = True
  • Domain Suffix List = The Org’s Email Domain (for example, example.org)

Public Directory Settings

  • Staff User Identification = Never
  • Is Hidden = False
  • Domain Suffix List = blank

Staff users will be routed to sign into their directory because their email domain matches the one entered. Then, because there is only one non-hidden directory configured, public users will automatically be directed to sign into the configured public directory.

Single Logout (SLO)

Since iMIS SSO is a passthrough application, and no session information is stored within it, single logout is not supported within the application itself. However, within iMIS, it is possible to configure a Single Logout page that logs the user out of iMIS, as well as a connected external directory.

More information and instructions for setting this up can be found on the Enabling Single Logout (SLO) page.