CloudShare can set up user authentication via SAML 2.0 SSO for your account. When SSO is enabled for your account, users log into CloudShare using a dedicated SSO login page and are then authenticated by the Identity Provider (IdP) of your choice.
This guide describes how to enable SSO for your account, how to manage user authentication in SSO-enabled accounts, and how to log into CloudShare with SSO.
SAML 2.0 support includes authentication only. User authorization via SAML 2.0 is currently not supported.
Note: SSO login is for CloudShare project member users only. It does not affect end users such as students invited to classes on CloudShare or users invited to a CloudShare-hosted POC.
Enabling SSO for Your CloudShare Account
In order to enable SAML 2.0 SSO, all of the following steps must be completed. Note that the order of steps could vary depending on your IdP.
Step 1: Open a Support Request
Open a request to CloudShare Support and request SAML SSO enablement for your account.
Provide the following information:
- Entity ID - The unique string used to identify your IdP. Obtain this from your IdP.
- Public X.509 Certificate - The certificate CloudShare will use to establish trust with your IdP and validate incoming SAML assertions from your IdP. Obtain this from your IdP.
- IdP Login URL - The URL to which CloudShare should redirect users for authentication. Obtain this from your IdP.
- SAML Metadata file - A file containing your SSO configuration details. Obtain this from your IdP.
- SSO Owner - A CloudShare user of your choice who will always have password login enabled in addition to SSO login. This ensures that your organization can access CloudShare in the event of failure on the IdP side. The user must be defined in your IdP with an email address belonging to one of the specified email domains (described below).
- Email Domains - The names of the email domains and/or sub-domains that you want to enable for SSO authentication. For security reasons, these should be domains owned by your organization.
- Test User - The email address of a test user to use when testing the SSO integration. The user must be defined in your IdP with an email address belonging to one of the specified email domains (described above). This can be either the SSO owner user or a dedicated test user that you create on your IdP. Do not submit an active CloudShare project member user other than the SSO owner as the test user, since the SSO configuration disables regular login.
Based on the details you provide, CloudShare will integrate with your IdP to enable SAML 2.0 SSO on a test project in your account. At this stage, your users can continue to log into CloudShare via regular password login. We will provide you with:
- A metadata file with information about CloudShare, for your IdP.
- A dedicated login URL.
Step 2: Configure your IdP to Provide SSO for CloudShare
Follow your IdP's instructions to configure the IdP to provide SSO authentication for your CloudShare account. You will need to supply metadata from CloudShare, using the file provided to you by CloudShare Support. This will provide the IdP with information about where and how to send SAML messages.
Example instructions for configuring Okta IdP SAML settings can be found here.
Step 3: Test the SSO Integration
- Using a browser in which you are currently not logged into CloudShare or to your IdP, browse to the dedicated login URL provided to you by CloudShare Support.
- Click the Log in to CloudShare button. You will be directed to your IdP.
- Sign into the IdP using your test user.
- Verify that you are logged into CloudShare successfully as your test user.
- Report back to CloudShare Support that you have completed the integration test. Specify if you were logged into CloudShare successfully as the test user. CloudShare Support will now work with you, based on your test results, to fully establish successful integration.
Step 4: Verify Configuration of Existing Users
Once the integration with your IdP is established, CloudShare is ready to extend the integration to the active projects in your account. When this is complete, your users will no longer be able to log into CloudShare via regular password login. Therefore, the next step is to make sure that all existing users are correctly set up so that they will be authenticated successfully over SSO once the integration is fully enabled on your account.
For each user, verify that:
- On CloudShare, the user's CloudShare username is an email address that belongs to an SSO-enabled domain, as agreed with CloudShare Support in step 1. For example, if "company1.com" is a domain that CloudShare enabled for your account for SSO, then a user whose email address is "user@company1.com" is set up correctly on CloudShare for SSO authentication.
We recommend that all usernames belong to the SSO-enabled domains. In the event that a user's email address does not belong to one of your SSO-enabled domains, the user is not SSO-enabled and is authenticated using regular password login.
For example, if the domain, "company2.com" is not SSO-enabled for the account, then a user whose CloudShare user name is "user@company2.com" would not be SSO-enabled. That user would be authenticated using regular password login. AND in your IdP, EITHER - The user's IdP user name is identical to the user's CloudShare username.
In this case, during the SAML authentication process, the SAML response assertion sent by the IdP to CloudShare should include the user's email address in the NameID attribute. For example:
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameidformat:unspecified">user@company1.com</saml2:NameID>
OR - The user's email address (which is the CloudShare username) is defined in the IdP as another attribute, in such a way that the SAML response assertion from the IdP to CloudShare inserts the email address into an attribute statement with attribute name "email". For example:
<saml2:AttributeStatement>
<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrnameformat:unspecified" Name="email">
<saml2:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">user@company1.com</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
Step 5: Complete the Enablement
When you are ready for CloudShare to complete the enablement for your entire account, contact CloudShare Support and we will complete the enablement for you.
Managing User Authentication in SSO-Enabled Accounts
When your CloudShare account is SSO-enabled, SSO login is automatically enabled for all users with emails that belong to your SSO-enabled domain(s). SSO login cannot be disabled per user. In order for the users to be successfully authenticated, they must also be defined in your IdP with the same email address as their user name or email.
Normal password login is automatically disabled by default for all users whose email addresses belong to your specified SSO-enabled domains, with the exception of the SSO owner user, who can use both SSO login and password login.
If a user's email address does not belong to one of your SSO-enabled domains, the user will be enabled for normal password login and not for SSO login.
It is possible to enable password login as an additional login path for any individual SSO-enabled user. Use this option with caution. As a best security practice, we recommend restricting users to SSO login wherever possible.
Adding New Users
To add a new user, do both of the following:
- Add the user to your IdP, making sure to enter the SSO-enabled email address as the user name or as the email address, such that the IdP inserts the email address into an attribute statement with attribute name "email". For example, if the domain "company1.com" is SSO-enabled for your account, "user@company1.com" would be SSO-enabled.
- Invite the user to CloudShare (via User Management > Project Member Invitations). CloudShare checks that the email address that you enter in the Email field is SSO-enabled for your account. Provided the email domain is SSO-enabled, the user is created as an SSO-enabled user and has no CloudShare password. The user receives an invitation email directing the user to your dedicated SSO login page.
Enabling Password Login for SSO-Enabled Users (Optional)
Regular password authentication is disabled by default for SSO-enabled users.
For security best practices, we recommend that you do not normally enable password login for SSO-enabled users.
The SSO owner user, specified in your support request for SSO enablement (see step 1 above), always has the ability to log into CloudShare by regular password login. This means that in case any IdP failure should ever occur, your organization will still have a way to access CloudShare.
Note: This task requires the Project Manager user role.
To enable password login for an SSO-enabled user (not usually recommended):
- From the User Management menu, click Project Members. The Project Members page is displayed.
- Locate and click the Email of the relevant user. The User Details page for that user is displayed.
- Click Allow Non-SSO Login. The Allow Non-SSO Login button is replaced by the Allow SSO Login Only button. The user is now able to log into CloudShare via password, as well as via SSO. If the user had a CloudShare password previous to SSO enablement, that password is once again activated. In the event that the user does not have or know their password, the user should click Can't access your account? on the CloudShare login page, and follow the instructions. To disable password login, click Allow SSO Login Only.
Logging into CloudShare with SSO
Once your account is SSO-enabled, SSO-enabled users can log in via the dedicated SSO login page supplied to you by CloudShare Support.
If an SSO-enabled user visits the regular CloudShare login page, the user is redirected to the dedicated SSO login page.