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
  • Logging in to the Web Platform
  • Logging in to the Mobile App
• How to Set Up Single Sign-on
  • Import Production Settings to Identity Provider
  • Complete the Integrations Page
  • Checking the Subdomain and Testing the Integration
• How to Migrate Users to SSO

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 AD.

Single sign-on uses SAML 2 and currently supports only SP-initiated workflows.

Logging in to the Web Platform

When any users access the login screen, they have options:

• Create an account
• Log in with their Google, Facebook, or Apple account
• Log in with an email address and password

Before you set up SSO, your early users probably use the email address and password to log in. After you set up SSO, your users should still enter their corporate email address in the Email field. The system will detect that the email domain belongs to an account with SSO enabled and change the Login button to a Login with SSO button. 

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:

1. Import the application production settings into your identity provider
2. Use the metadata.xml file from your identity provider to complete the fields on the Integrations page in the application
3. Test the integration

The following sections walk through each of these three parts.

Part 1: 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. 

Part 2: Complete the Integrations Page 

Use the following steps to navigate to the Integrations page from the dashboard:

1. 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.
   
2. Click the Integrations tab at the top of the screen. The Integrations tab appears with a list of available integrations.
   
3. 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.
   
   
4. Complete the fields as described below.

The following fields appear on the screen:

General Settings

• Entity ID: 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.

SAML Attributes Mapping

• 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.
• 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.

Part 3: 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 General Settings section called Subdomain. 

The Subdomain URL field is a read-only field that contains a the URL generated from the Subdomain value.

You can update the Subdomain value 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: You cannot use the application login page or mobile app to test because these do not use the SSO configuration 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. After they enter their email address in the field and see the button change to Login with SSO, they can click Login with Email to display the usual Password and CAPTCHA fields.

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.