Skip to main content
Skip table of contents

Connecting to an External Directory / Identity Provider

Overview

This page contains general information on how to connect one or more external directories to the Cloud SSO app, which will then be available for iMIS to use during sign-in.

Prerequisites

Ensure that you have completed the connection to iMIS setup step first.

Managing Directory Connections

In the Cloud SSO app, navigate to External Directories > Manage Directories.

On this screen, you can:

  • Add an external directory (multiple if you have Cloud 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”

In iMIS EMS, a new hidden field (not visible anywhere in the Staff site, only available via the REST API) was added to user security records: the external_id field. This field is meant to store a unique, unchangeable value from an external directory that represents a particular user/contact record in iMIS.

When first connecting a directory, this value is blank for all records. When this value is blank, iMIS falls back to matching on the primary email address for a given contact record. Additionally, upon successful login, the external_id field is populated with the value from the “connected directory” (in this case, Cloud SSO).

Once this value has been populated, it is used during subsequent logins to match to the same contact record, even if their email address changes. This means that over time, as SSO is used, the external_id field will populate for user security records in iMIS.

Because Cloud SSO Enterprise supports connecting a (theoretically) unlimited amount of external directories / identity providers that users can choose from to sign in, Cloud SSO must ensure that ALL external IDs are unique across ALL directories.

Therefore, the external ID claim that is mapped from the connected directory (say, Microsoft Entra) is prepended with the internal directory configuration record’s unique ID.

For example, if you have a directory record in Cloud SSO with internal record ID of: 531b5f5e-2a2a-4b73-b109-3f17f7f34e36 and you have configured Microsoft Entra to map the External ID claim to Microsoft’s oidclaim with a value like this: 3522ec95-d540-4f11-992f-915efcd00862 Then your iMIS External ID for this individual would be:

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

Directory Settings

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

(red star) denotes a required field.

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.

  • (red star) Name: A friendly name for the directory connection. Not visible unless you have Cloud SSO Enterprise and are using the user-facing directory selection screen.

  • (red star) Logo: A logo representing the directory. Must be a 245×36px** 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 Cloud SSO. The URL is only available after saving the form. If you require this value before obtaining the other information on this form (e.g. Auth/Token URLs, Client ID/Secret), you can enter dummy values on this form in the Cloud SSO, save the record in order to obtain a redirect URL, then go back and edit the dummy values with actual values from your directory provider.

  • Discovery Domain: Not required, but if you have it, paste it in and press (tick) Discover… If successful, this will pre-populate the next 3-4 fields automatically, saving you time.

    • Typically ends with: /.well-known/openid-configuration but if you omit this part, we will attempt to add it and fetch the URL anyway.

  • (red star) Authorization URL: Enter the authorization or sign-in URL from your directory.

  • (red star) Token URL: Enter the token URL from your directory.

  • Userinfo URL: Optional. Not all directory providers support this. If you have this value from your directory, enter it here. If omitted, claims located in the Userinfo object cannot be mapped/utilized.

  • Issuer: Optional. If you have this value from your directory, enter it here. If specified, this value will be validated against the issuer in the token obtained from the directory during sign-in.

  • (red star) 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.

  • (red star) Client ID: Obtained from your directory when you create a client application or service provider record.

  • (red star) Client Secret: Obtained from your 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 Cloud SSO with the new Client Secret value.

  • (red star) 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 you are positive that your external directory does not support it.

  • (red star) Enable Response Mode Form Post: Disabled by default. Only enable this if your directory requires it. If disabled, uses “Query” response mode, which most directory providers support and prefer.

  • (red star) Enable Token Endpoint Basic Auth: Disabled by default. Only enable this if your directory requires it. If disabled, uses the more secure “Post” body authentication.

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

User and Claim Settings

A Note About “Claims”

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.

You can view the claims coming back from a directory by going to the directory listing screen and pressing the purple “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, you 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.

  • Just-in-Time User Creation (iMIS 2017 Only): Specifies whether or not to create a new contact record if the user cannot be found/matched. (Commonly referred to as “JIT”.) Not applicable to iMIS EMS and has no effect in these environments.

  • 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 (iMIS EMS Only): Specify the claim name and location that represents this user’s “unique ID” or “object ID”.

    • (warning) 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 your 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).

  • Custom Field 1 Table and Column (iMIS 2017 Only): Optionally, you can specify the name of a contact-type single instance panel in iMIS. If the configured claim below has a value, it will be written into the panel at time of sign-in.

  • Custom Field 1 (iMIS 2017 Only): Optional. Specify the claim name and location that represents the custom value you want to synchronize into the specified panel/field above.

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

For iMIS EMS, the External ID, Username, Email, First Name, and Last Name claims are always required. This is due to the requirements of the OpenID Connect module inside of iMIS.

For iMIS 2017 only: The ✏️ next to each claim controls if that field is synchronized only when the user is created (unchecked), or every time the user signs in successfully (checked).

Role Mapping

(red star) Staff User Identification

If you have set iMIS to use OIDC for Staff & Public Users, AND the directory you are connecting contains a mixture of staff and non-staff users, you must instruct the Cloud 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/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/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.

iMIS Licensing Warning: If you allow more staff users to sign in than you have 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

Fallback to E-mail Matching (iMIS 2017 only): If specified, if the username claim does not match a username in iMIS, an additional lookup will be performed on the primary email address field in iMIS to see if a match can be found. For this setting to work properly, there cannot be any duplicate primary email addresses in iMIS.

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 e-mail 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 (e.g. Entra), while all other users are automatically routed to the other directory.

To configure this scenario:

Staff Directory Settings

  • Staff User Identification = Always

  • Is Hidden = True

  • Domain Suffix List = Your Org’s Email Domain (e.g. 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 Cloud 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, you can 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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close