ScreenSteps

How to Set up Single Sign-on

Updated on

Workflows are not supported in your browser.
Please use a recent version of Chrome, Edge, Firefox or Safari to display this page.

Background

Single Sign-on makes it easier for users to authenticate to ScreenSteps and improve adoption of ScreenSteps. Refer to What is Single Sign-on? if you are not familiar with what Single Sign-on is.

Procedure

Configure the Identity Provider in ScreenSteps

You must first configure your site's Identity Provider.

Refer to Configuring Identity Providers for your Account or Sites if you are not familiar with where to configure Single Sign-on settings in ScreenSteps.

Update the settings for the User Properties tab

When you configure an Identity Provider (IDP) in ScreenSteps, you specify how user roles and groups in ScreenSteps will be handled when logging in through the Identity Provider.

Before you activate your IDP in ScreenSteps you should  configure the following behavior on the User Properties tab:

  1. The Default Role
    • This role will be assigned to users who log into ScreenSteps through the IDP for the first time and who do not yet have a ScreenSteps user account.
  2. A User Group
    • This is the group that all users will be assigned to when they log into ScreenSteps through the IDP. Note that if you remove the user from this group later on they will be added back into the group the next time they log in.
User Properties

Will you be connecting to your IDP using SAML?

An Additional Option

You do NOT need to select the checkbox. This is just an available option if you would like it.

If you are connecting to your Identity Provider using SAML then you have the option to use the Manage each user's groups through IDP checkbox.

This allows you to manage user groups outside of ScreenSteps by sending over the groups a user should belong to in the SAML assertion.

This is an advanced option which requires additional configuration by your IT team. Refer to our Managing user groups through your Identity Provider using the SAML Assertion help article for more information.

User Properties

Do you want to configure Single Sign-on at the account or site level?

In ScreenSteps, you can configure Single Sign-on for a Site or the Account (Content Management and Admin Centers). Please refer to the following help article to help you decide:

Should I create a Single Sign-on Endpoint at the Site or Account level?

Confirm your site is marked private

Before configuring Single Sign-on make sure that the Site is Private. Refer to the following help article if you need directions:

How do I make a site private?

Content Management and Admin Centers

When you configure Single Sign-on at the account level it will control access to the Content Management and Admin Centers. It will also automatically control access to the Primary Site on your account unless you set up a vanity domain for the Primary Site.

A note about activating your IDP configuration

Your Identity Provider will not be used to log users into ScreenSteps until you explicitly activate it after completing a testing step. If, however, you are unable to log in after activating the IDP then refer to our help article How do I get back into my account if I have accidentally locked myself out?

Select how you will set up SSO

If you are going to be using ScreenSteps with another service such as Salesforce, Google Apps, Azure AD, or PhenixID, then choose one of those options below to set up Single Sign-on.

If you are NOT using any of those services, then you will want to select either SAML (if you have SAML) or Remote Authentication (for all other situations).

What do you want to set up Single Sign-on with?

Does your Salesforce instance use My Domain?

If you are using Salesforce My Domain, then setting up Single Sign-on is pretty straight forward. If you're not using My Domain, you can still set up Single Sign-on, but it requires different steps.

Confirm you meet pre-requisites

Before you can deploy a custom Apex class in your production application you will need to create it first in your Salesforce sandbox organization. Before you continue these steps you should already have a sandbox org created.

Create a Salesforce.com login URL

In just a moment you will create a new page in Salesforce.com.

You need to enter the url to that new Salesforce.com page in ScreenSteps; however, since that page doesn't exist yet, we will show you what that page will be called.

Copy your URL
Copy Your Salesforce.com URL

From your Salesforce.com Setup area copy your Salesforce.com domain from the address bar and paste it into a text editor.

Add a login to the URL

Add the following to the end of the copied URL:

apex/sslive_login

If your Salesforce.com url were https://na3.salesforce.com/ then your new URL would look like this:

https://na84.lightning.force.com/apex/sslive_login
Sandbox URL or Production URL?

The URL you created is the URL that ScreenSteps will redirect to when a Salesforce user needs to log in to view ScreenSteps.  

At this stage, you can either use the Sandbox URL or the Production URL.

Use the Sandbox URL if you want to first test single sign-on in your sandbox org.

Use the Production URL if you DON'T think you need to first test single sign-on in your sandbox org.

Configure Remote Login URL and Copy Remote Authentication Token

  1. Enter the new URL you created in the Create a Salesforce.com login URL step into the Remote Login URL.
  2. Copy the remote authentication token to the clipboard (you'll use it later)
Enter Remote Login URL

Create a New Class in Salesforce

IMPORTANT: This must be done in a sandbox organization and then deployed to production.

Even if you copied the Production URL in the previous step, you must first create a new Apex Class in a sandbox organization.

Remember that this must be in your sandbox organization.

Navigate to your Salesforce.com Setup Area
Navigate to Apex Classes Page

From the menu, expand Develop and click on Apex Classes.

Create a New Class
Create a New Class

Click on the New button to create a new class.

If you don't see the New button it is because you are in your production organization, not a sandbox organization.

Paste in the Controller Code

  1. In the code field, paste the code that appears below the screenshot.

    *Make sure to replace the string INSERT_REMOTE_AUTH_TOKEN_HERE in the code with the remote authentication token you copied in the Configure Remote Login URL and Copy Remote Authentication Token step.
  2. After pasting in the code and inserting your token, click the Save button.
Code example
public class ScreenStepsLiveRemoteLoginController {
  public string md5String {get;set;}
  private string ssliveToken = 'INSERT_REMOTE_AUTH_TOKEN_HERE';

    public ScreenStepsLiveRemoteLoginController () {
        String theUserName = UserInfo.getUserName();
        String theEmail = UserInfo.getUserEmail();
        String theOrgName = ''; //UserInfo.getOrganizationName(); (not available in apex page)
        String theReturnToURL = ApexPages.CurrentPage().getParameters().get('return_to_url');
        String theTimeStamp = ApexPages.CurrentPage().getParameters().get('timestamp');
        
        String theStringToHash = UserInfo.getFirstName() + UserInfo.getLastName() + 
        theEmail + UserInfo.getUserId() + theOrgName + this.ssliveToken + theTimeStamp;
        
        Blob keyblob = Blob.valueof(theStringToHash);
        Blob key = Crypto.generateDigest('MD5',keyblob);
        md5String = encodingUtil.convertToHex(key);
    }
}
Click to copy
It's saying I need to have a Test Class

If you need to include an accompanying test class, use the following APEX code.

@isTest
private class ScreenStepsLiveRemoteLoginControllerTest {
  static testmethod void testSSLiveRemoteAuthToken() {
    ScreenStepsLiveRemoteLoginController test = new ScreenStepsLiveRemoteLoginController();
    System.assert(test.md5String != '');
  }
}
Click to copy

Create a Visualforce Page

IMPORTANT: This does NOT need to be done in the sandbox org.

If you want to test single sign-on with Salesforce, then you will need to create it in both the sandbox and the production organization.

Navigate to Visualforce Pages Page
Create New Page
Create New Page

From the Visualforce Pages page, click on New to create a new page.

Paste in Page Markup

Paste in Page Markup
  1. You can assign the Label to whatever you like but the Name field must be sslive_login
  2. In the markup field, paste the code snippet that appears below.
  3. Replace {{ScreenSteps Remote Consumer URL}} with the Remote Consumer URL (see screenshot below) located in ScreenSteps.
  4. Click the Save button to save your changes.
<page controller="ScreenStepsLiveRemoteLoginController">
  <h1>Redirecting to ScreenSteps...</h1>
  
  <script>   
    var theSSLiveURL = '{{ScreenSteps Remote Consumer URL}}';
    var theOrganization = encodeURIComponent('');

    theSSLiveURL += '?first_name=' + '{!JSENCODE(URLENCODE($User.FirstName))}';
    theSSLiveURL += '&last_name=' + '{!JSENCODE(URLENCODE($User.LastName))}' + '&email=' + '{!JSENCODE(URLENCODE($User.Email))}';
    theSSLiveURL += '&external_id=' + '{!JSENCODE(URLENCODE($User.Id))}' + '&organization=' + theOrganization;
    theSSLiveURL += '&timestamp={!JSENCODE(URLENCODE($CurrentPage.parameters.timestamp))}' + '&hash={!JSENCODE(URLENCODE(md5String))}';
    theSSLiveURL += '&return_to_url=' + '{!JSENCODE(URLENCODE($CurrentPage.parameters.return_to_url))}';
    theSSLiveURL += '&redirect_uri=' + '{!JSENCODE(URLENCODE($CurrentPage.parameters.redirect_uri))}';
    theSSLiveURL += '&response_type=' + '{!JSENCODE(URLENCODE($CurrentPage.parameters.response_type))}';
    theSSLiveURL += '&client_id=' + '{!JSENCODE(URLENCODE($CurrentPage.parameters.client_id))}';
    
    window.location = theSSLiveURL;
  </script>
</page>
Click to copy
Remote Consumer URL
Remote Consumer URL

Set permissions for the Visualforce Page

Now that you have created the Visualforce page you need to make sure that your Salesforce users have permission to access it.

Edit Page Permissions
Edit Page Permissions

From the list of pages, click on the Security link next to the sslive_login page.

Add Profiles
Add Profiles

Add any necessary profiles to the list of Enabled Profiles. Any user with a matching profile will be able to access the login page. If the user does not belong to a profile listed under Enabled Profiles then they will be presented with an error stating that they don't have permission to view the page.

Remember that if you are doing this in a sandbox org you will also need to update permissions in your production org.

Test the connection

Get your remote authentication test URL from ScreenSteps

From the Testing and Activation tab copy the Remote Test URL from ScreenSteps.

Get your remote authentication test URL from ScreenSteps
Open an Incognito Window or a different browser

You need to make sure you test this when you are NOT logged into ScreenSteps.

Open an Incognito Window or a new browser (e.g. Edge, Firefox, Safari, Chrome) that isn't logged into ScreenSteps.

Paste the Test URL into your browser and hit return

You should be directed to the Salesforce.com login screen.

Login page
The Login Page

After successfully logging in to Salesforce.com you will see the page you created earlier for a brief moment. It will say "Redirecting to ScreenSteps Live...".

Success!

You should now be logged into ScreenSteps.

Deploy code to production and update URL in ScreenSteps

Deploy your code to production

Refer to your Salesforce documentation for how to deploy your Apex class to production.

Enter URL Into ScreenSteps Admin Area

You need to use the domain for your production organization in Salesforce. Go back to ScreenSteps and update the Remote Login URL.

If your production Salesforce.com url were https://na3.salesforce.com/ then you would add this to the end:

apex/sslive_login

The URL you include in the Remote Login URL field would then look like this:

https://na3.salesforce.com/apex/sslive_login
Enter URL Into ScreenSteps Admin Area

Generate a self-signed certificate on Salesforce.com

Select Setup
Navigate to your Salesforce.com Setup Area

If you already have a self-signed certificate for your Salesforce organization then you can skip this part of the setup.

Navigate to the Certificate and Key Management
Certificate & Key Management
Create Certificate

Enter a label and unique name and select Save.

Create Certificate

Enable Salesforce as an Identity Provider

Select Identity Provider
Select Security Controls & Identity Provider
Enable Identity Provider

You may be presented with this screen. If you are, click the Enable Identity Provider button.

Enable Identity Provider
Select your self-signed certificate

Then select your self-signed certificate (1) and click Save (2).

Select your self-signed certificate

Download Metadata

You should now see this screen. Click on Download Metadata. You will use this file later on you download to configure your settings in ScreenSteps.

Download Metadata

Upload Metadata

In ScreenSteps, click on the Upload metadata file button and select the metadata file you downloaded previously. This file will populate the X.509 SAML Certificate and the remote login url.

Update metadata file

After uploading the metadata file the Remote Login URL and X.509 SAML Certificate will be filled in.

Remote Login URL
X.509 SAML Certificate

Copy the SAML Consumer URL and Note Entity ID

You will need to use the SAML Consumer URL and the Entity ID later on as you finish configuring the Salesforce App.

Note the SAML Consumer URL and Entity ID

You will need both the SAML Consumer URL and the Entity ID in the steps that follow. Copy the Entity ID to the clipboard now by clicking the Entity ID Copy button.

SAML Consumer URL and Entity ID

Create a Connected App in Salesforce

Open App Manager
Open App Manager
Create New Connected App

Click the New Connected App button.

Select Connected Apps & New

Enter Basic Information

Enter Basic Information

Just enter the required information. It doesn't really matter what you enter here.

Enter Basic Information

Enter Web App Settings and Save

Scroll down to Web App Settings and do the following:

  1. Check Enable SAML
  2. Paste the Entity ID that you copied to the clipboard in the previous step.
  3. Copy and paste the SAML Consumer URL from ScreenSteps into the ACS URL field.
  4. Set Subject Type to Username
  5. Set Name ID Format to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  6. Change the Signing Algorithm for SAML Messages to SHA256
  7. Select Save.
Enter Web App Settings and Save
What you should see

You should now see this screen.

What you should see

Assign User Profiles to your Connected App in Salesforce

Click Manage

Manage the connected app that you just created.

What you should see
Select Manage Profiles

Scroll down ot the Profiles section and select Manage Profiles.

Select Manage Profiles
Select Profiles and Save

Select all of the profiles that you want to allow to login to ScreenSteps via single sign-on.

You should have single sign-on configured now.

Select Profiles and Save

Add a service/App to your domain

Navigate to your Google Apps Admin console.

1. Click Apps in your Google Admin console
2. Click SAML apps
3. Click "Add a service/App to your domain"

Set up your own custom app

1. Click "Setup My Own Custom App"
2. Copy URL and Download Certificate

From the Google IdP Information screen do the following:

  1. Copy the SSO URL to the clipboard.
  2. Click the Download button next to Certificate to download a PEM file. You will upload this file to ScreenSteps in just moment.

Make sure to keep the Google Apps window open. You will come back to this after you do some tasks in ScreenSteps.

Include Configuration Settings from Google

Configure the Remote Login URL

Paste the URL that you copied from the Google IdP Information browser window.

Remote Login URL
Upload the SAML Certificate

Upload the SAML file that you downloaded previously in Google Apps.

Click on the Certificate tab and then click on the the Upload Certificate file button. You will be prompted to select a file. Select the .pem file you downloaded from Google. The file should start with GoogleIDPCertificate-.

Upload PEM file

Copy the SAML Consumer URL and Note Entity ID

You will need to use the SAML Consumer URL and the Entity ID later on as you finish configuring the Google App.

Note the SAML Consumer URL and Entity ID

You will need both the SAML Consumer URL and the Entity ID in the steps that follow. Copy the SAML Consumer URL to the clipboard now by clicking the SAML Consumer URL Copy button.

SAML Consumer URL and Entity ID

Enter Application Name

Navigate back to Google and click Next

Return to the Google browser window and click the Next button.

Enter ScreenSteps as the Application Name then click "Next"
  1. Confirm Application Name says ScreenSteps
  2. Click Next

Enter Service Provider Details

In the Service Provider Details screen do the following:

  1. Paste the SAML Consumer URL you copied from the ScreenSteps IDP configuration screen into the ACS URL field.
  2. Copy and paste the Entity ID from the ScreenSteps IDP configuration screen into the Entity ID field.
  3. Set the Name ID to Basic information and Primary Email.
  4. Set the Name ID Format to EMAIL.
  5. Click Next.

Finish Setting up SSO in Google

Click Finish

You do not need to add any mappings. Click Finish.

Click OK

Turn SAML app on in Google

Turn ScreenSteps SAML app on

Before you can test the SAML integration you will need to turn it on in Google Apps. From the settings page click on the menu to turn it on.

Copy the SAML Consumer URL and Note Entity ID

You will need to use the SAML Consumer URL and the Entity ID later on as you finish configuring Azure Active Directory.

Note the SAML Consumer URL and Entity ID

You will need both the SAML Consumer URL and the Entity ID in the steps that follow. Copy the SAML Consumer URL to the clipboard now by clicking the SAML Consumer URL Copy button.

SAML Consumer URL and Entity ID

Follow Microsoft's Configuration Instructions

Microsoft has created a ScreenSteps Azure Active Directory integration. Click the link below to continue configuring Azure.

Microsoft Tutorial: Azure Active Directory integration with ScreenSteps

Make sure you complete the above tutorial before continuing on to the next step.

Confirm System Requirements

*These instructions were reproduced from this Phenix support page: https://support.phenixid.se/sbs/screensteps/

Make sure you have the following
  • PhenixID Authentication Server 2.0 or higher
  • ScreenSteps installed
  • ScreenSteps administration rights

Setup PhenixID Authentication Services

  1. Setup PhenixID Authentication Services as a SAML IdP using one of the Federation scenarios described here. (If the desired authentication method is not provided by a scenario, use the documentation for the SAML authenticatorhere)
  2. Fetch the mail attribute for the user.
  3. Use mail as Name ID attribute.
  4. Go to Scenarios->Federation-> <newly_added_scenario> -> Identity Provider. Deselect Require signed requests. Save.
  5. Then export your SAML IdP metadata by going to the URL:
  6. https://<YourServerDomainName>/saml/authenticate/<authenticator_alias>?getIDPMeta
  7. and download the metadata to a xml file.
  8. Save the IDP Signing Certificate as a file (follow this instruction)
  9. Fetch the SingleSignOnService -> Location value.
  10. Fetch the SingleLogoutService -> Location value. [Optional]

Include Configuration Settings from PhenixID

  1. Paste the Remote Login URL from PhenixID (SingleSignOnService -> Location value)
  2. Paste the Logout URL from PhenixID (SingleLogoutService -> Location value) - this is optional.
Paste in urls
Upload the SAML Certificate file
  1. From the Certificate tab, upload the IDP Signing Certificate that you downloaded from PhenixID.
Upload certificate

Add trust to ScreenSteps on PhenixID Authentication Services

  1. Login to configuration manager
  2. Open Scenarios->Federation->SAML Metadata upload
  3. Click the plus sign
  4. Add ScreenSteps SAML SP Metadata by uploading the ScreenSteps SAML SP Metadata (see instructions that follow for creating a screensteps-metadata.xml file to upload).
Generating the Metadata file

Copy the following text and paste it into a new file named screensteps-metadata.xml.

<md:EntityDescriptor entityID="{{SCREENSTEPS_ENTITY_ID}}" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="{{SCREENSTEPS_CONSUMER_URL}}" index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>
Click to copy
  1. Copy the SAML Consumer URL from ScreenSteps and replace the {{SCREENSTEPS_CONSUMER_URL}} string in the screensteps-metadata.xml file with it.
  2. Copy the Entity ID from ScreenSteps and replace the {{SCREENSTEPS_ENTITY_ID}} string in the screensteps-metadata.xml file with it.
SAML Consumer URL and Entity ID

Summary of what these instructions include

You will now go through generalized instructions for configuring an Identity Provider that uses SAML for Single Sign-on. If you intend on using SSO with other services (such as Salesforce, Google Apps, Azure Active Directory, or PhenixID) and plan on using SAML with those services, then select the instructions above for that specific service.

Otherwise, continue going through these instructions.

Configure the Identity Provider

Configuration URLs
  1. Remote Login URL and Logout URL: The Remote Login URL is the URL that ScreenSteps should redirect users to when they try to log into ScreenSteps. You will get this URL from your Identity Provider. The Logout URL is optional and may be provided by your provider.
  2. SAML Consumer URL and Entity ID: You will need to enter both of these values into your Identity Provider.
Configuration URLs
Upload the SAML Certificate

You will need to upload an X.509 SAML Certificate file in PEM format from your SAML IDP file.

Click on the Certificate tab and then click on the the Upload Certificate file button. You will be prompted to select a file. Select the .pem file from your IDP.

Upload PEM file

Does your identity provider need you to enter metadata for ScreenSteps?

Generating the Metadata file

Copy the following text and paste it into a new file named screensteps-metadata.xml. After you replace the variables in the text as described below, will upload this file to your Identity Provider.

<md:EntityDescriptor entityID="{{SCREENSTEPS_ENTITY_ID}}" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="{{SCREENSTEPS_CONSUMER_URL}}" index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>
Click to copy
  1. Copy the SAML Consumer URL from ScreenSteps and replace the {{SCREENSTEPS_CONSUMER_URL}} string in the screensteps-metadata.xml file with it.
  2. Copy the Entity ID from ScreenSteps and replace the {{SCREENSTEPS_ENTITY_ID}} string in the screensteps-metadata.xml file with it.
SAML Consumer URL and Entity ID

SAML Response Requirements

Security Certificate

The response must have a certificate that matches the certificate that you upload to ScreenSteps. The path should be:

ds:X509Certificate

ScreenSteps will compute a fingerprint from this certificate and compare it to the fingerprint of the certificate you have uploaded to ScreenSteps.

Identifying users

You need to pass in the email address of the user you want to authenticate. When you do this, ScreenSteps will do one of two things:

  1. If a user with that email already exists in the system, ScreenSteps will match the email in the SAML response to that user.
  2. If a user with that email does not exist, they will be assigned the role and group specified in the User Properties tab in the Identity Provider configuration screen in ScreenSteps.
How we find the email address

Refer to the article SAML attributes that ScreenSteps accepts for identifying users for a description of which attributes and subject values ScreenSteps checks for the user's email address.

Confirm you meet requirements

In order to set up Remote Authentication you will need someone who is familiar with writing code on a web server. They must be able to complete the steps in our Setting Up Your Application to Use ScreenSteps Remote Authentication (Not SAML) article.

Once you have someone who is capable of implementing the necessary code you can proceed with setting up Remote Authentication.

Enter Configuration Settings for your Remote Authentication server

  1. Make sure you have set the Login through option to Remote Authentication.
  2. You must at least enter a Remote login URL. This is the url that users will be redirected to login to your account. You will need to work with a software developer in order to figure out which URL to use.
  3. The Log out url is optional. This a url that users will be taken to once they log out of the ScreenSteps account.
  4. Once you are done, select Update.
Enter Settings

Provide Remote Authentication Token and Remote Consumer URL to the developer

Now that you have configured the Identity Provider in ScreenSteps you have the Remote Authentication Token and Remote Consumer URL that the developer will need in order to implement Remote Authentication on the 3rd party server. Provide this information to the developer so that they can finish setting up the Remote Login URL. The developer will follow the instructions in the Setting Up Your Application to Use ScreenSteps Remote Authentication (Not SAML) article.

The token and URL

Test the connection

Now that you have configured ScreenSteps and your service you are ready to test.

From the Testing and Activation tab in ScreenSteps copy the SAML Test URL (or the Remote Test URL if you configured Remote Authentication). Paste the URL into an Incognito browser window to test your Identity Provider configuration. The Identity Provider login page should appear.

This is NOT the URL that you will share with end users. This is just a test to make sure that you are directed to the correct login page.

SAML Test URL

Did the test work?

When you pasted that URL into a new browser window, did it direct you to a Google login page?

Double check your work

Go through the process again and double check that you entered all of the correct information.

If it still doesn't work, contact ScreenSteps support at [email protected].

Activate the Identity Provider in ScreenSteps

From the Testing and Activation tab click the Active checkbox and then click Done. You will now log in using the Identity Provider you just configured.

Activate Identity Provider

The ScreenSteps Identity Provider column will now show that Single Sign-on is active.

SSO is active
Congratulations, you are done!
Previous Article Should I create a Single Sign-on Endpoint at the Site or Account level?
Next Article Setting Up Your Application to Use ScreenSteps Remote Authentication (Not SAML)
Still Need Help? Contact Us