All Collections
Integrations Hub
Integrations Hub - SSO with iMIS EMS (OAuth)
Integrations Hub - SSO with iMIS EMS (OAuth)

Creating an SSO in IH using iMIS EMS (OAuth) | Average Task Time: 40-60 minutes

Julia Delk avatar
Written by Julia Delk
Updated over a week ago

Index:

In this article, we'll go over the steps for setting up an Integrations Hub SSO with iMIS EMS.

*** Not sure if you have EMS or iMIS Web Service? Here's an easy way to check:

Within your iMIS account, navigate to:

Settings > About iMIS > iMIS version

Version 20.3 or later = EMS
Version 20.2 or earlier = Web Service

Here is a screenshot of what this settings area will look like or similar to:

Turns out you have iMIS Web Service? See this article.

Basic Setup within Integrations Hub

1. Get Started with Integrations Hub.

2. Add a new SSO connector from the Integrations Hub dashboard.

3. You will be brought to a page with different SSO options. Select iMIS EMS (iMIS OAuth).

4. You will now be shown the below screen. You'll need the Process URL from this page in one of our next steps so copy/paste this link into a notepad for easy access.

5. Keep this screen open in your browser. We'll be jumping over to your iMIS account to adjust some settings but we'll need to return to this page once we're done.

iMIS Side Settings

6. In a new browser tab, go to your iMIS organization account URL: https://{instanceurl}/staff

Example:

My organization is called King of The Hill and my website is KingoftheHill.com. This means my iMIS account login link should be: https://KingoftheHill.com/staff

7. Request admin login credentials from your staff if you don't have them already (it's important that these credentials are admin, other account types will not have access to what we need). Once you have the proper credentials, login to iMIS with these credentials on the above page.

8. Now we're going to begin adjusting some settings and gathering a few items from within your organization's iMIS account. We'll be copy/pasting these items into your Integration Hub so be sure to add these to a notepad as we go, for easy reference after (just like your Integration Hub Process URL) .

9. First, let's create a new Client Application in iMIS by navigating to Settings > Contacts > Client Applications located on the dashboard list on the left side of your screen.

10. You should now see a Client Applications table. Select "Add Client Application" on the right side of the table:

11. You'll be taken to the below page. Go ahead and fill in these items then click "Save":

  • Client ID: OpenWater

  • Client Secret: Generate and copy/paste a random guid

  • Refresh Toke: 60

  • Login Redirect URL: (the link you saved in a notepad in step 4)

IMPORTANT NOTE: Save the Secret Key in your notepad- you'll need this again later but you won't be able to see it again after generating and using it.

12. Next, we're going to grab your Login URL from inside iMIS. Once logged in, you'll see settings/ dashboard items located on the left side of your screen. You need to scroll down to Rise > Page Builder > Manage Content:

13. You'll be brought to a new page. On this page, go to the top, and select New > Website Content Folder. Name the folder OpenWater.

14. Now repeat steps 12 and 13 but instead of New > Website Content Folder, select your OpenWater folder from the left side list and go to the New > Website Content page.

15. Then, under the Definition tab, add the Publish Title. We usually suggest: OpenWaterSSO, then click "Add Content".

16. Now you'll be shown new directory options, select Content Types > Contact > Single Sign-On.

17. You should now be prompted to select a client application. Choose the client application we just made called OpenWater.

18. You can now go back to the website content page from step 15. Now click into the "Properties" tab and check off "Content requires user to log in". Save and Publish this page.

19. We'll now repeat steps 14-18 to create a second content page. To do this, go back to that same folder we named OpenWater, and then click New > Website Content. Set these on Definition page then click Add Content:

  • Title: OpenWater Login

  • Layout: Single Column

20. Now you'll be shown new directory options, select ContentTypes > Contact > Contact Sign In.

21. After this, select the Redirect Rules tab on the content page and:

  • Conditions for Redirect: User is Authenticated

  • Redirect to: OpenWaterSSO

22. With this complete, you can now get your Login URL and save it in your notepad. After clicking "Save and Publish", go back to the Definition tab. You will now see a Login URL on this page, labeled as "Publish Location". It should follow this structure: https://{imisInstanceUrl}/OpenWaterSSO/OpenWater-Login.aspx

23. Let's grab your User Info IQA Path. Looking back to your iMIS dashboard items located on the far left of your screen, click Rise > Intelligent Query Architect. Once this page loads, click "New" (located at the top), and select "Folder".

24. Write "OpenWater" as the folder name and then click "Save".

25. Save this gist then import it into the OpenWater folder. Do this by selecting the folder OpenWater, and click Import at the top of your screen. A new popup will appear with a file importer. Select the gist we had you save, and click "Upload".

26. Ensure you update the destination with the new folder, and click "Import".

27. Open the IQA you just imported, copy the path and save it in your notepad.

28. At this stage, add additional fields that you'd like to be pulled into your OpenWater Instance upon user sign-in. To do this, go to the Display Tab and select "View all Columns".

29. This should show you all available properties. Select what fields you want to get for the user profile which will be used to map to OpenWater's user profile fields. Once you're done, click "Save" in the top right.

30. Last, let's make a quick note of your Base URL. Your Base URL is your iMIS account URL minus "/staff" at the end: https://{instanceurl}/

Back to Integrations Hub

31. Jumping back to Integrations Hub in the browser tab you left open earlier, we're going to now add all of these data pieces from iMIS to your Integrations Hub settings. At this stage you should now have:

  • Admin Username and Password

  • Login URL: https://{imisInstanceUrl}/OpenWaterSSO/OpenWater-Login.aspx

  • Base URL: https://{imisInstanceUrl}

  • Client Secret: Generated in step 11 and saved in your notepad

  • User Info IQA Path: $/OpenWater/GetDataByUserId

32. Let's begin by giving your connector a name. This name can be whatever you'd like but we normally suggest this format: {Name of Organization} SSO {Year}

33. You now copy/paste the Login URL you saved earlier in the field located under the Name. This should be the URL for the page you created on iMIS, and it should be: https://{imisInstanceUrl}/OpenWaterSSO/OpenWater-Login.aspx

34. Under the Login URL field, add the Query Path: $/OpenWater/GetDataByUserId

35. Under "Query Path" click "Select Credentials" then click "Add New Credentials" from the drop-down menu:

36. You should now have a half-window open up on the right side of your screen labeled "Create New Credentials". You'll need to input the following from those previous pieces of data we saved:

  • Credentials Name could be anything, but we normally suggest repeating the same name you added to the Config section a few minutes ago: {Name of Organization} SSO {Year}

  • Your Base URL should be: https://{imisInstanceUrl}

  • Your Client Secret: Generated in step 11 and saved in your notepad

  • Admin Username

  • Admin Password

  • Now click "Add"

37. The "Create New Credentials" half-window will now close. Click "save" at the top of left the connector settings.

38. Located under "Save" on the top left of your screen, click the "Field Mapping" tab. You'll now see an assortment of drop-down menus, allowing you to set what user profile fields your SSO will pull from your iMIS database into OpenWater. You can add to or delete any of the fields that auto-populate for you.

Additional Tip:

The OpenWater fields should auto-populate but if you're not sure what fields are set in your OpenWater instance, you can find those here:

https://{YourOpenWaterInstanceName}.secure-platform.com/admin/organizations/main/userprofileformtemplate/preview

Your iMIS object is going to be the Query Path we set earlier: $/OpenWater/GetDataByUserId

iMIS Fields are the fields we selected within iMIS in Step 29. You can now use a dropdown to select any field you'll like.

39. Once you're done, click "Save" and then "Publish" in the top left of your screen.

40. Now go back to your "Settings" tab, copy the Begin URL, and place it into your handy notepad.

Finalize Your SSO within OpenWater Instance

33. Login to your OpenWater instance as an admin: https://{YourOpenWaterInstanceName}.secure-platform.com/admin/

34. From the dashboard settings located on the left side of your screen, scroll down to System Settings > Login Configuration

35. On this Login Configuration page, add the below settings:

  • Check "Allow 3rd Party Corporate Handshake Authentication"

  • Choose "Json Web Token" from the list

  • The Login URL is the Begin URL we just copied from Integrations Hub

  • Secret Key will be the same JWT Secret Key located in your integrations hub settings page

  • For your Login Button Text, we suggest: Login with {CompanyName}

  • Click Save

Secret Key in Integrations Hub Settings:

36. Your SSO is now complete- high-five yourself, you did it!

Testing Your New SSO

37. As with any new integration or workflow, testing is super important! Follow these steps here: https://help.getopenwater.com/en/articles/6991126-testing-a-new-sso-single-sign-on-integration

Did this answer your question?