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.
Onboarding Checklist
A Cloud ID (with a valid Background Account set up)
An SSO subdomain with correctly configured DNS entry (like login.example.org or sso.example.org)
Configuration of the Domain Setup page to provision and activate your custom SSO domain
Configuration of the SSO System Settings page to connect it to iMIS
Configuration of a SAML Client App or OIDC Client App to create an SSO connection to a third-party system
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.
DNS Type | Name / Prefix | Alias |
|---|---|---|
CNAME |
|
|
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.
iMIS EMS / 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:
Field | Value |
|---|---|
Client ID | Enter a unique but recognizable value. We recommend CSI-Cloud-SSO. |
Client Secret | Enter a secret passphrase. This passphrase will be visible in plaintext, so do not use a password you use elsewhere for this value. Remember this value for later. If you need to generate a random string, click here to generate a random string from Random.org. |
Refresh Token Lifetime | Enter "1". (Refresh tokens are only used once within a few seconds of being created.) |
Login Redirect URL | OpenID ConnectEnter: https://<Your-SSO-Domain>/imis/callback SAMLEnter: https://<Your-SSO-Domain>/saml/imis/callback |
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.
The iMIS Client ID and iMIS Client Secret are not the same as your OpenID Connect Client ID and Client Secret. The values above are only used to connect the Cloud SSO app to iMIS.
Use the OpenID Client ID and Client Secret found in the OIDC Client Apps page when setting up integrations with third parties.
If you are only using SAML or OpenID Connect (not both), then you only need to follow these instructions once.
If you plan to use both SAML and OpenID Connect at the same time, then please repeat these instructions above a second time. Running SAML and OIDC together requires two RiSE Client Applications and two public RiSE pages. There are separate fields in the Cloud SSO System Settings page for both OpenID and SAML configuration values.
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
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).
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.