Cloud SSO Onboarding Guide

Overview

This article provides information regarding the onboarding steps for the Cloud SSO app.

Onboarding Checklist

To get your first SSO connection set up, you'll need to make sure you complete these high-level steps in order.

Prerequisites

This article assumes that you already have a  CSI Cloud ID. If you do not have a Cloud ID, please reach out to CSI and follow the steps in our Environment Setup guide first.

1. Create a Public DNS Entry

Our SSO app is 100% cloud-based, however, for security and consistent user experience, we require a public DNS CNAME Record. This is so that users see URLs consistent with your organization like sso.example.org instead of sso.cloud.csiinc.com.

You'll need to create a CNAME record for the Cloud SSO app. This entry should be the same as your organization's domain, but it is not required to be. For example, if you access iMIS at https://membership.example.org, consider creating an SSO DNS entry like sso.example.org or auth.example.org. The domain does not have to match, if you have for instance, "example.org" and "examplemembers.org" as separate base domains, you can choose either one to add the SSO subdomain onto, even if it doesn't match iMIS.

See the table below for the record that needs to be created.

ASI Test/Staging Environments

If you are working in a staging/test environment and your iMIS instance ends in *.imiscloud.com, you can still create a DNS entry like "login.example.org".

Please do not reach out to ASI and ask them to create a DNS entry. Your DNS entries are typically managed by your IT department, MSP, or web hosting company.

Corporate Network DNS Warning

If your organization is on a corporate network with separate private DNS (such as a Domain Controller or Windows Server with the DNS role, or a router/network appliance acting as a private DNS server), you will also need to add the same CNAME entry to your domain controller (or other internal DNS server), otherwise any users on the corporate LAN (or using a VPN connection to your corporate office) will not be able to use the SSO.

Consult with your IT department or MSP firm if this requirement applies to you.

CNAME records typically propagate within 1-15 minutes. You can verify that the record is active by using an online service such as https://www.nslookup.io/ – simply enter your SSO domain, and click Find DNS records. Look under the "CNAME" header, you should see the value "csicloudsso.trafficmanager.net".

If your DNS entry is live, you are ready for the next step!

2. Provision Your SSO Domain

NEW! The provisioning process is now fully automated and integrated into the product. You do not have to submit anything to CSI, and there is no more provisioning waiting period!

Navigate to the Cloud SSO app in the CSI Cloud Dashboard, and go to the Domain Setup screen. Your domain status should say Not Provisioned.

Click Provision Your Domain.

Enter your domain (do not include https://) into the SSO Domain field.

Click Start Provisioning.

Do not close your browser or navigate away from the page while provisioning is processing.

If your DNS record is set up correctly, you should see a success message, and your domain should report as "Online".

Domain Reporting as Offline

If your domain is reporting as "Offline" but it has a valid SSL certificate and there were no errors during provisioning, and you are on a corporate or organizational network that may have internal DNS (such as Windows DNS), then you will also need to add an internal CNAME DNS entry that matches the public one. Your IT department or MSP can assist with this process. It usually involves adding an entry into the Windows Server Domain Controller DNS, or sometimes a firewall or network appliance.

Once this is added, the domain should report as Online.

You can test to see if this is the cause of the error by signing in to the Cloud Dashboard and viewing this page outside of your corporate network, such as on an LTE hotspot or personal/home internet connection.

3. Configure Cloud SSO System Settings

Refer to the System Settings article for information on the settings fields.

One of the iMIS Identity mode settings is required to be configured. The branding and other settings are optional.

Show Identity Mode Comparison Chart

Comparing iMIS Identity Modes

iMIS 2017 and EMS (RiSE Client Application Mode)	iMIS 2017 Legacy On-Premises (Forms Auth Mode)
iMIS Cloud Compatible Traditional Hosting / On-Premise Compatible Uses your existing styled RiSE sign-in form  Uses a dedicated brandable sign-in form OAuth2 consent screen support Single Sign-On Single Sign-Out (Current iMIS platform limitations prevent single sign-out at this time.)	iMIS Cloud Compatible Traditional Hosting / On-Premise Compatible Uses your existing styled RiSE sign-in form Uses a dedicated brandable sign-in form OAuth2 consent screen support Single Sign-On Single Sign-Out This mode is deprecated and will not be supported in a future version of the product. Customers migrating to iMIS EMS should use the RiSE Client Application identity mode.

iMIS EMS 0r 2017

1. Create the RiSE Client Application

You will need to create a registered Client Application in RiSE. Navigate to Settings > Contacts > Client Applications and click "Add Client Application".

Fill out the form:

2. Create the Public RiSE SSO Page

Next, you will need to create a RiSE page with the SSO iPart on it. Follow these instructons:

• Create a RiSE page that is accessible via a public URL in a "shared" or "common" area/site.

• Name the RiSE page and URL something like "SSO", or "SSO Redirect".

• Add only the Contact > Single Sign-On iPart onto the page. (Do not add any other iParts or layouts.)

  • Select the correct RiSE Client applicaton that you created in Step 1 above.

• Set the security of the page to Authenticated Users Only. 

• Do not add any custom redirect rules to the page.

Publish the page, and make a note of the Publish Location / Full URL (including https://).

3. Add/Update SSO System Settings

Once you have your RiSE Client Application saved, and public RiSE page published in iMIS, back in the Cloud SSO app, go to (or refresh) the Settings page, choose the "iMIS Cloud" or "iMIS EMS" tab, and:

• Select the iMIS Client Application's name that you just created from the dropdown

• Enter in the iMIS Client Secret that you configured in RiSE in Step 1 above

• Enter the Public RiSE Page full URL that you copied from Step 2 above

Finally, press Save at the bottom to save the System Settings page.

iMIS 2017 (Legacy Forms Auth)

Deprecation Warning

Legacy Forms Authentication mode is considered deprecated and is not recommended for new installations.

Customers currently using this mode may continue to do so, however, when migrating from iMIS 2017 to iMIS EMS, this setup process will need to be reconfigured using the standard iMIS EMS / RiSE client application mode.

Shared Forms Auth Setup

If you chose On-Premise / Legacy (Forms Auth) mode above, and iMIS is not configured for shared forms authentication (or you are unsure), please follow this guide to ensure that iMIS is configured correctly:

→ iMIS Shared Forms Auth Setup and Configuration

CSI recommends using the RiSE Client Application configuration (switch to the iMIS 2017 or EMS tab).

For iMIS 2017 On-Premise

Shared Forms Auth Setup

If you chose On-Premise / Legacy (Forms Auth) mode above, and iMIS is not configured for shared forms authentication (or you are unsure), please follow this guide to ensure that iMIS is configured correctly:

→ iMIS Shared Forms Auth Setup and Configuration

CSI recommends using the RiSE Client Application configuration (switch to the iMIS 2017 or EMS tab).

You will need the following items from your iMIS web.config file:

• Forms Auth Cookie Name (typically "Login" or similar)

• Forms Auth Domain (which must be configured to use a base domain value for cookie sharing, typically ".example.org")

• Forms Auth Cookie Path (most of the time, this value is the default, a forward slash "/")

• Machine Validation Key

• Machine Decryption Key

Additionally, your primary iMIS login that members use (including iMIS desktop, if still in use) must be on the same domain as the SSO was set up on, above.

You may also proceed to configure any additional OAuth or Branding settings on this page, as well.

4. Set Up Your Connected Apps

The last step is to set up at least one connected app registration. This step depends highly upon the third party website that you are integrating with the SSO.

For certain off-the-shelf solutions (like WordPress or Drupal integrations, for instance), these can be configured easily using a web interface. These integrations typically expect you to provide the Client ID, Client Secret, (sometimes) JWT Signing Key, and user profile mapping information.

For custom third-party services, such as event or LMS vendors, integrating the Cloud SSO app with these vendors typically requires a conversation with that company to determine if they support this form of SSO. You can provide the third party vendor the link to this page, so that they can learn more about our solution and determine if they can integrate with the Cloud SSO product: SSO Information for Third Party Vendors

Setup and Configuration Assistance

If you need any assistance with configuring your Cloud SSO app settings, or integrating the Cloud SSO with a third party website or vendor, CSI can provide paid consulting services to help you get up and running.

Support@csiinc.com