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:
- 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.
- 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.
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.
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:
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, Microsoft Entra ID, 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
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_loginIf your Salesforce.com url were https://na3.salesforce.com/ then your new URL would look like this:
https://na84.lightning.force.com/apex/sslive_loginSandbox 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
- Enter the new URL you created in the Create a Salesforce.com login URL step into the Remote Login URL.
- Copy the remote authentication token to the clipboard (you'll use it later)
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.
Navigate to your Salesforce.com Setup Area
Remember that this must be in your sandbox organization.
Navigate to Apex Classes Page
From the menu, expand Develop and click on Apex Classes.
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
- In the code field, paste the code that appears below the screenshot.
*Make sure to replace the stringINSERT_REMOTE_AUTH_TOKEN_HEREin the code with the remote authentication token you copied in the Configure Remote Login URL and Copy Remote Authentication Token step. - After pasting in the code and inserting your token, click the Save button.
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);
}
}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 != '');
}
}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
From the Visualforce Pages page, click on New to create a new page.
Paste in Page Markup
- You can assign the Label to whatever you like but the Name field must be sslive_login
- In the markup field, paste the code snippet that appears below.
- Replace
{{ScreenSteps Remote Consumer URL}}with the Remote Consumer URL (see screenshot below) located in ScreenSteps. - 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 += '×tamp={!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>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
From the list of pages, click on the Security link next to the sslive_login page.
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.
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.
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_loginThe URL you include in the Remote Login URL field would then look like this:
https://na3.salesforce.com/apex/sslive_login
Generate a self-signed certificate on Salesforce.com
Select Setup
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
Create Certificate
Enter a label and unique name and select Save.
Enable Salesforce as an Identity Provider
Select Identity Provider
Enable Identity Provider
You may be presented with this screen. If you are, click the Enable Identity Provider button.
Select your self-signed certificate
Then select your self-signed certificate (1) and click Save (2).
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.
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.
After uploading the metadata file the Remote Login URL and X.509 SAML Certificate will be filled in.
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.
Create a Connected App in Salesforce
Open App Manager
Create New Connected App
Click the New Connected App button.
Enter Basic Information
Enter Basic Information
Just enter the required information. It doesn't really matter what you enter here.
Enter Web App Settings and Save
Scroll down to Web App Settings and do the following:
- Check Enable SAML
- Paste the Entity ID that you copied to the clipboard in the previous step.
- Copy and paste the SAML Consumer URL from ScreenSteps into the ACS URL field.
- Set Subject Type to Username
- Set Name ID Format to
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent - Change the Signing Algorithm for SAML Messages to SHA256
- Select Save.
What you should see
You should now see this screen.
Assign User Profiles to your Connected App in Salesforce
Click Manage
Manage the connected app that you just created.
Select Manage Profiles
Scroll down ot the Profiles section and 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.
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:
- Copy the SSO URL to the clipboard.
- 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.
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-.
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.
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"
- Confirm Application Name says ScreenSteps
- Click Next
Enter Service Provider Details
In the Service Provider Details screen do the following:
- Paste the SAML Consumer URL you copied from the ScreenSteps IDP configuration screen into the ACS URL field.
- Copy and paste the Entity ID from the ScreenSteps IDP configuration screen into the Entity ID field.
- Set the Name ID to Basic information and Primary Email.
- Set the Name ID Format to EMAIL.
- 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 Microsoft Entra ID.
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.
Follow Microsoft's Configuration Instructions
Microsoft has created a ScreenSteps Microsoft Entra ID integration. Click the link below to continue configuring Microsoft Entra ID.
Tutorial: Microsoft Entra SSO integration with ScreenSteps
Make sure you complete the above tutorial before continuing on to the next step.
Upload the public key certificate
Follow the Entra ID instructions in the Assigning a new X.509 SAML Certificate to an Identity Provider configuration in ScreenSteps help article. They will show you how to download the certificate from Entra ID and then upload it to ScreenSteps.
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
- 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)
- Fetch the mail attribute for the user.
- Use mail as Name ID attribute.
- Go to Scenarios->Federation-> <newly_added_scenario> -> Identity Provider. Deselect Require signed requests. Save.
- Then export your SAML IdP metadata by going to the URL:
- https://<YourServerDomainName>/saml/authenticate/<authenticator_alias>?getIDPMeta
- and download the metadata to a xml file.
- Save the IDP Signing Certificate as a file (follow this instruction)
- Fetch the SingleSignOnService -> Location value.
- Fetch the SingleLogoutService -> Location value. [Optional]
Include Configuration Settings from PhenixID
- Paste the Remote Login URL from PhenixID (SingleSignOnService -> Location value)
- Paste the Logout URL from PhenixID (SingleLogoutService -> Location value) - this is optional.
Upload the SAML Certificate file
- From the Certificate tab, upload the IDP Signing Certificate that you downloaded from PhenixID.
Add trust to ScreenSteps on PhenixID Authentication Services
- Login to configuration manager
- Open Scenarios->Federation->SAML Metadata upload
- Click the plus sign
- 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>- Copy the SAML Consumer URL from ScreenSteps and replace the
{{SCREENSTEPS_CONSUMER_URL}}string in the screensteps-metadata.xml file with it. - Copy the Entity ID from ScreenSteps and replace the
{{SCREENSTEPS_ENTITY_ID}}string in the screensteps-metadata.xml file with it.
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, Microsoft Entra ID, 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
- 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.
- SAML Consumer URL and Entity ID: You will need to enter both of these values into your Identity Provider.
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.
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>- Copy the SAML Consumer URL from ScreenSteps and replace the
{{SCREENSTEPS_CONSUMER_URL}}string in the screensteps-metadata.xml file with it. - Copy the Entity ID from ScreenSteps and replace the
{{SCREENSTEPS_ENTITY_ID}}string in the screensteps-metadata.xml file with it.
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:X509CertificateScreenSteps 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:
- If a user with that email already exists in the system, ScreenSteps will match the email in the SAML response to that user.
- 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
- Make sure you have set the Login through option to Remote Authentication.
- 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.
- The Log out url is optional. This a url that users will be taken to once they log out of the ScreenSteps account.
- Once you are done, select Update.
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.
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.
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.
The ScreenSteps Identity Provider column will now show that Single Sign-on is active.
