This article covers the steps to set up single sign-on (SSO) with Cloud Academy or QA. This feature is available to enterprise accounts. You must be an admin to access the screen in the application where you perform this procedure. You also need access to configuration information from your identity provider (IdP).
Note: This article contains different URLs to use in your configuration depending on whether you are using Cloud Academy or QA. When you see both options, choose the URL that corresponds to the kind of account you use.
This article contains the following sections:
Single Sign-on
When you set up SSO, users at your company can use their regular network credentials to sign in to the web platform and mobile app. You configure SSO with whatever identity provider your company uses, such as Okta, Centrify, or Azure Active Directory.
Single sign-on uses SAML 2 and currently supports only SP-initiated workflows.
Logging in to the Web Platform
Once you have set up SSO, your users have two options for logging in to the web platform: using the SSO link on the login page or using your company's custom URL.
If your users go to the login page at cloudacademy.com/login, they click the Login with SSO link at the bottom of the form, as you see in the following image.
A screen appears for the users to enter their email address. The system uses the domain of the email address to redirect the user to your company's custom login screen.
Alternately, your users can go directly to your company's custom URL to log in to the application on the web platform. The URL looks something like:
https://{company}.sso.cloudacademy.com/
Or
https://{company}.sso.app.qa.com/
Where the token {company} is a value that you choose. For example, the URL might look like the following if the value you choose for {company} is acme:
https://acme.sso.cloudacademy.com/
The {company} value you choose must be unique across all accounts to ensure you have a unique custom URL. See the Checking the Subdomain and Testing the Integration procedure later in this document for step-by-step instructions.
Tip: Choose a simple value for your unique identifier to make your login URL easier to remember and type.
Logging in to the Mobile App
When users log in to the mobile app, instead of entering their username and password on the initial splash screen, they tap the Company SSO link at the bottom of the screen, as you see in the following image.
From there, a screen appears where users enter their email address. The app uses the domain of the email address to determine which Company SSO custom login to direct the user to. From there, the user logs in to the app with their IdP network credentials.
How to Set Up Single Sign-on
The process to set up SSO has three parts:
- Import the application production settings into your identity provider
- Use the metadata.xml file from your identity provider to complete the fields on the Integrations page in the application
- Test the integration
The following sections walk through each of these three parts.
Import Production Settings to Identity Provider
The first step to setting up SSO is to import the production settings below into your identity provider.
Entity ID
urn:federation:cloudacademy
Metadata File
For Cloud Academy accounts:
https://cloudacademy.com/saml/metadata.xml
For QA accounts:
https://app.qa.com/saml/metadata.xml
Signed Auth Requests
true
Signed Assertions
false
Assertion URL
For Cloud Academy accounts:
https://cloudacademy.com/labs/social/complete/saml/
For QA accounts:
https://app.qa.com/labs/social/complete/saml/
NameID Format
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Hash Algorithm(s)
SHA-1, SHA-256
Public Certificate
The public certificate is too long to print in this article. Click this link to GitHub to find and copy the public certificate.
Once that is complete, you need to retrieve your metadata.xml file to complete the steps in the next part of the procedure.
Complete the Integrations Page
Use the following steps to navigate to the Integrations page from the dashboard:
- Pause your mouse over your company's name in the upper-right corner of the screen and choose Settings & Integrations from the menu that appears.
The Settings & Integrations screen appears. - Click the Integrations tab at the top of the screen. The Integrations tab appears with a list of available integrations.
- Click the SSO card. The SSO screen appears.
Tip: If you use Okta as your identity provider, you can click the Okta card instead to go the Okta marketplace where you can configure your SSO. - Complete the fields as described below.
The following fields appear on the screen:
General Settings
- Entity ID URL: A unique identifier for the IdP. Look for the value of the entityID property on the md:EntityDescriptor element in the metadata.xml file.
- SSO URL (Location): The endpoint for handling SAML transactions. Look for the value of the Location property on the md:SingleSignOnService element in the metadata.xml file.
- Certificate: An X.509 certificate helps identify secure connections. Look for the ds:X509Certificate element in the metadata.xml file.
- Email Domains: Enter all the domains your company uses for user emails, such as example.com or us.example.com. The mobile app matches the domain of a user's email address to direct the user to the correct company SSO login page.
- Permanent User ID: Enter the name of the field that holds the ID your identity provider uses to uniquely identify your users. Tip: If possible, avoid using email address as this ID so that users can still log in to their account even if their email address with your company changes.
- First Name: Enter the IdP field that holds the user's first name. If you are integrating with Microsoft Active Directory, this value is a URI.
- Last Name: Enter the IdP field that holds the user's last name. If you are integrating with Microsoft Active Directory, this value is a URI.
- Username: Enter the IdP field that holds the user's username. If you are integrating with Microsoft Active Directory, this value is a URI.
- Email: Enter the IdP field that holds the user's email address. If you are integrating with Microsoft Active Directory, this value is a URI.
Security Settings
- Authentication Requests Signed? Indicates whether your configuration requires authentication requests to be signed for security. Usually set to True. Look for the WantAuthnRequestsSigned property of the md:IDPSSODescriptor element in the metadata.xml file.
- Requested Authentication Context? Indicates whether your configuration requires that additional information be added to the SAML assertion to help decide the user's entitlement.
Important: If your users log in with a Windows-integrated method (authentication that uses the identity on the PC to log the user in), you should set this value to False. Otherwise, this is usually set to True.
Extra Settings
- Name ID Format: The default value, urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, is usually correct. Look for the value in the md:NameIDFormat element in the metadata.xml file to verify.
- Logout URL: The URL of the landing page where users go after logging out. This is an optional field.
When the fields are complete, click Save.
Checking the Subdomain and Testing the Integration
When you click Save, a window appears with a link where you can test your integration.
You can look at the link in this window to see what {company} value the application chose for your custom login URL. If you want to change this value, you can click the X in the upper-right corner of this window to close it. A new field has appeared on the screen called Subdomain.
You can update this field and click Save again to continue the configuration test. If the subdomain you chose is already taken, you receive an error. Choose a different value and try again.
When the subdomain is ready, test the URL in a different browser window and click Confirm. Important: The company SSO links from the standard login page and the mobile app do not work until you click Confirm. You must perform your test from the custom URL.
Tip: Paste the URL into an incognito tab on your browser so you can be sure you are not already logged in as you test the login experience.
How to Migrate Users to SSO
Some or all of your users may have begun using the application before you set up SSO. These users are accustomed to signing in to the web platform from https://cloudacademy.com/login/ or https://myqa.qa.com/account/login and the mobile app from the initial splash screen.
When you set up SSO, these users can continue using their standard login procedure until they are ready to change to the custom process. Once a user logs in to the platform using your custom URL or to the mobile app using the company SSO login screen for the first time, the application migrates the account to require using the SSO going forward.