Set up Single Sign-on

Updated Aug 06, 2019

By default, ScreenSteps allows you to manage viewing privileges to your content by creating users and viewing groups in your ScreenSteps account.

Single Sign-on allows you to incorporate a 3rd party user management system with your ScreenSteps account so that you do not have to manage users in two separate places (or inconvenience your end users by making them remember another login and password).

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://na3.salesforce.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.

Where do you want to create the endpoint?

In ScreenSteps, you can create a Single Sign-on connection at the site level or the account level. Which one would you like to do?

Confirm your site is marked private

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Select the site you want to create an SSO Endpoint for.
  2. Click Settings
  3. Click Settings (a different Settings)
Check Private > update

Create a new Endpoint

Configure Single Sign-on

Just below your site settings is Single Sign-on.

  1. Click Single Sign-on
  2. Click Configure SSO
Create the Endpoint
  1. Include a title (like "Salesforce")
  2. Confirm ScreenSteps Remote Authentication is selected
  3. Click Create

Create endpoint in ScreenSteps Account

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Click Account
  2. Click Single Sign-on
Create the Endpoint
  1. Include a title (like "Salesforce")
  2. Confirm ScreenSteps Remote Authentication is selected
  3. Click Create

Add Viewer Group to your ScreenSteps site

You will need to add this viewer group to the ScreenSteps site that the users will be viewing.

Click Back to Sites
Confirm site > click Viewers
  1. Confirm you are in the correct site
  2. Click Viewers
Click Add Group
Add your Salesforce Group

Now your users will be authenticated to your ScreenSteps site.

Confirm your site is marked private

Check Private > update

Navigate back to Account Single Sign-on

Configure Endpoint and Copy Token

  1. Enter the new URL you created in the previous step into the Remote Login URL.
  2. Copy the remote authentication token to the clipboard (you'll use it later)
  3. Click Update (3).
Enter URL Into ScreenSteps Admin Area

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 previous lesson.
  2. After pasting in the code and inserting your token, click the Save button.
<p>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);
    }
}</p>
It's saying I need to have a Test Class

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

<p>@isTest
private class ScreenStepsLiveRemoteLoginControllerTest {
  static testmethod void testSSLiveRemoteAuthToken() {
    ScreenStepsLiveRemoteLoginController test = new ScreenStepsLiveRemoteLoginController();
    System.assert(test.md5String != '');
  }
}</p>

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 Pages Page

Expand the Develop folder and click on Visualforce Pages.

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 text that appears below.

*Replace {{ScreenSteps Remote Consumer URL}} with the Remote Consumer URL located in ScreenSteps.

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

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

Copy the Remote Test URL from ScreenSteps.

Get your remote authentication test URL from ScreenSteps
Open a different browser

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

Open up 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.

Paste URL Test URL into your browser and hit return
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...".

The Login Page
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 the Single Sign-On area in ScreenSteps and update the Remote Login URL.

Enter URL Into ScreenSteps Admin Area

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

Generate a self-signed certificate on Salesforce.com

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

Select Security Controls > Certificate and Key Management
Select Security Controls &gt; Certificate and Key Management
Create Certificate

Enter a label and unique name and select Save.

Enable Salesforce as an Identity Provider

Select Setup
Select Setup
Select Security Controls > Identity Provider
Select Security Controls &gt; 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.

Where do you want to create the endpoint?

In ScreenSteps, you can create a Single Sign-on connection at the site level or the account level. Which one would you like to do?

Confirm your site is marked private

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Select the site you want to create an SSO Endpoint for.
  2. Click Settings
  3. Click Settings (a different Settings)
Check Private > update

Create a new Endpoint

Configure Single Sign-on

Just below your site settings is Single Sign-on.

  1. Click Single Sign-on
  2. Click Configure SSO
Create the Endpoint
  1. Include a title (like "Salesforce")
  2. Confirm SAML is selected
  3. Click Create

Create endpoint in ScreenSteps Account

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Click Account
  2. Click Single Sign-on
Create the Endpoint
  1. Include a title (like "Salesforce")
  2. Confirm SAML is selected
  3. Click Create

Add Viewer Group to your ScreenSteps site

You will need to add this viewer group to the ScreenSteps site that the users will be viewing.

Click Back to Sites
Confirm site > click Viewers
  1. Confirm you are in the correct site
  2. Click Viewers
Click Add Group
Add your Salesforce Group

Now your users will be authenticated to your ScreenSteps site.

Confirm your site is marked private

Check Private > update

Navigate back to Account Single Sign-on

Upload Metadata

Click on the Upload new Salesforce Configuration file button and select the metadata file you downloaded previously. This file will populate the SAML certificate and the remote login url.

Copy the SAML Consumer URL and Note Entity ID

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

Copy the SAML Consumer URL to the clipboard.
Note the Entity ID

Create a Connected App

Select Setup
Select Setup
Open App Manager
Open App Manager
Create New Connected App

Click the New Connected App button.

Select Connected Apps &gt; 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

Enter Web App Settings and Save

Scroll down to Web App Settings and do the following:

  1. Check Enable SAML
  2. Enter the Entity Id for your ScreenSteps SSO endpoint.
  3. Enter the ACS URL from ScreenSteps here. This is the SAML Consumer URL from the Single Sign-on Endpoint you created in ScreenSteps.
  4. Set Subject Type to Username
  5. Set Name ID Format to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  6. Select Save.
What you should see

You should now see this screen.

What you should see

Assign User Profiles to your Connected App in Salesforce

Select Setup
Select Setup
Select Manage Connected Apps
Open App Manager
Select your ScreenSteps Connected App
Select your ScreenSteps Connected App
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

Test the connection

Switch back to the ScreenSteps window and copy the SAML Test URL. Paste the URL into a new browser window to test your Salesforce SAML integration.

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 Salesforce 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 into ScreenSteps and into Salesforce.

If that doesn't work, contact ScreenSteps support at support@screensteps.com

Activate the Endpoint in ScreenSteps

Activate endpoint

Navigate to the Single Sign-on area in ScreenSteps:

  1. Click the Activate checkbox.
  2. Click Update

Share ScreenSteps URL with users

Click Go To Site button

Navigate to the site that is connected to the Single Sign-on you just set up. Click on the Go To Site button.

Share this URL

This is the end-user URL of your knowledge base. Share this URL with viewers.

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.

Where do you want to create the endpoint?

In ScreenSteps, you can create a Single Sign-on connection at the site level or the account level. Which one would you like to do?

Confirm your site is marked private

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Select the site you want to create an SSO Endpoint for.
  2. Click Settings
  3. Click Settings (a different Settings)
Check Private > update

Create a new Endpoint

Configure Single Sign-on

Just below your site settings is Single Sign-on.

  1. Click Single Sign-on
  2. Click Configure SSO
Create the Endpoint
  1. Include a title (like "Google")
  2. Confirm SAML is selected
  3. Click Create

Create endpoint in ScreenSteps Account

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Click Account
  2. Click Single Sign-on
Create the Endpoint
  1. Include a title (like "Google")
  2. Confirm SAML is selected
  3. Click Create

Add Viewer Group to your ScreenSteps site

You will need to add this viewer group to the ScreenSteps site that the users will be viewing.

Click Back to Sites
Confirm site > click Viewers
  1. Confirm you are in the correct site
  2. Click Viewers
Click Add Group
Add your Google Group

Now your users will be authenticated to your ScreenSteps site.

Confirm your site is marked private

Check Private > update

Navigate back to Account Single Sign-on

Include Configuration Settings from Google

Configure the Remote Login URL
  1. Paste the URL that you copied from the Google IdP Information browser window.
  2. Click Update.
Upload the SAML Certificate

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

  1. Click the Upload new SAML 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 this URL and the Entity ID later on as you finish configuring the Google App.

Copy the SAML Consumer URL to the clipboard.
Note the 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 Single Sign-on window into the ACS URL field.
  2. Enter the Entity ID for your ScreenSteps SSO endpoint.
  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.

Test the connection

Switch back to the ScreenSteps window and copy the SAML Test URL. Paste the URL into a new browser window to test your Google SAML integration.

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 Google 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 into ScreenSteps and into Google.

If that doesn't work, contact ScreenSteps support at support@screensteps.com

Activate the Endpoint in ScreenSteps

Activate endpoint

Navigate to the Single Sign-on area in ScreenSteps:

  1. Click the Activate checkbox.
  2. Click Update

Share ScreenSteps URL with users

Click Go To Site button

Navigate to the site that is connected to the Single Sign-on you just set up. Click on the Go To Site button.

Share this URL

This is the end-user URL of your knowledge base. Share this URL with viewers.

Instructions were pulled from this Microsoft Azure tutorial. They have been reproduced below for your convenience.

Where do you want to create the endpoint?

In ScreenSteps, you can create a Single Sign-on connection at the site level or the account level. Which one would you like to do?

Confirm your site is marked private

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Select the site you want to create an SSO Endpoint for.
  2. Click Settings
  3. Click Settings (a different Settings)
Check Private > update

Create a new Endpoint

Configure Single Sign-on

Just below your site settings is Single Sign-on.

  1. Click Single Sign-on
  2. Click Configure SSO
Create the Endpoint
  1. Include a title (like "Google")
  2. Confirm SAML is selected
  3. Click Create

Create endpoint in ScreenSteps Account

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Click Account
  2. Click Single Sign-on
Create the Endpoint
  1. Include a title (like "Google")
  2. Confirm SAML is selected
  3. Click Create

Add Viewer Group to your ScreenSteps site

You will need to add this viewer group to the ScreenSteps site that the users will be viewing.

Click Back to Sites
Confirm site > click Viewers
  1. Confirm you are in the correct site
  2. Click Viewers
Click Add Group
Add your Google Group

Now your users will be authenticated to your ScreenSteps site.

Confirm your site is marked private

Check Private > update

Navigate back to Account Single Sign-on

Determine role for new users

When users login to ScreenSteps for the first time using Single Sign-on, ScreenSteps will assign them to one of two roles: Reader or Learner.

  1. Select the role you want viewers to be assigned
  2. Click Update

Copy the SAML Consumer URL

You will use this URL when you set up Azure AD.

Confirm you meet prerequisites

These prerequisites were included in the Microsoft tutorial.

In the Azure Active Directory (Azure AD) tutorial, you learn how to integrate ScreenSteps with Azure AD. Integrating ScreenSteps with Azure AD provides you with the following benefits:

  • You can control in Azure AD who has access to ScreenSteps.
  • You can enable your users to be automatically signed-in to ScreenSteps (Single Sign-On) with their Azure AD accounts.
  • You can manage your accounts in one central location - the Azure portal.

If you want to know more details about SaaS app integration with Azure AD, see What is application access and single sign-on with Azure Active Directory. If you don't have an Azure subscription, create a free account before you begin.

Prerequisites

To configure Azure AD integration with ScreenSteps, you need the following items:

  • An Azure AD subscription. If you don't have an Azure AD environment, you can get one-month trial here
  • ScreenSteps single sign-on enabled subscription
Scenario description

In this tutorial, you configure and test Azure AD single sign-on in a test environment.

  • ScreenSteps supportsSPinitiated SSO

Add ScreenSteps from the gallery

To configure the integration of ScreenSteps into Azure AD, you need to add ScreenSteps from the gallery to your list of managed SaaS apps.

To add ScreenSteps from the gallery, perform the following steps:

  1. In the Azure portal, on the left navigation panel, click Azure Active Directory icon.
  1. Navigate to Enterprise Applications and then select the All Applications option.
  1. To add new application, clickNew applicationbutton on the top of dialog.
  1. In the search box, type ScreenSteps, select ScreenSteps from result panel then click Add button to add the application.

Configure Azure AD Single Sign-on

In this section, you enable Azure AD single sign-on in the Azure portal.

To configure Azure AD single sign-on with ScreenSteps, perform the following steps:

  1. In the Azure portal, on the ScreenSteps application integration page, select Single sign-on.
  1. On the Select a Single sign-on method dialog, select SAML/WS-Fed mode to enable single sign-on.
  1. On the Set up Single Sign-On with SAML page, click Edit icon to open Basic SAML Configuration dialog.
  1. On the Basic SAML Configuration section:
    • Enter ScreenStepsLive as the Identifier
    • paste in your ScreenSteps SAML Consumer URL

Your ScreenSteps SAML Consumer URL is what you copied from the ScreenSteps Single Sign-on area.

What is the SAML Consumer URL?

You can find your SAML Consumer URL where you set up your Single Sign-on in ScreenSteps.

  1. Some of our customers need to manually configure the Reply URL url in order to get SSO working with Azure. This can be done by checking the Show advanced URL settings checkbox while configuring Azure as shown below. For the Reply URL you will enter the SAML Consumer URL.
  1. On the Set up Single Sign-On with SAML page, in the SAML Signing Certificate section, click Download to download the Certificate (Base64) from the given options as per your requirement and save it on your computer.

You will upload this file to ScreenSteps in the next section of this tutorial.

  1. On the Set up ScreenSteps section, copy the appropriate URL(s) as per your requirement.

You will paste the Login URL and the Logout URL in the next section of this tutorial.

Confirm Attribute Mappings

If needed, the following attribute mappings will be used when provisioning users from an Azure SAML response:

Azure Attribute |  ScreenSteps User Attribute

emailAddress     |  email

givenname          |  first_name

surname              |  last_name

name                   |  login

Include Configuration Settings from Azure AD

  1. Paste the Login URL that you copied in Azure AD
  2. Paste the Logout URL that you copied in Azure AD
  3. Click Update
Upload the SAML Certificate file
  1. Upload the SAML file that you downloaded previously in the Azure portal.

Create an Azure AD test user

The objective of this section is to create a test user in the Azure portal called Britta Simon.

  1. In the Azure portal, in the left pane, selectAzure Active Directory, selectUsers, and then selectAll users.
  1. Select New user at the top of the screen.
  1. In the User properties, perform the following steps.
  • In the Name field enter BrittaSimon.
  • In the User name field type **brittasimon@yourcompanydomain.extension**

    For example, BrittaSimon@contoso.com
  • Select Show password check box, and then write down the value that's displayed in the Password box.
  • ClickCreate.

Assign the Azure AD test user

In this section, you enable Britta Simon to use Azure single sign-on by granting access to ScreenSteps.

  1. In the Azure portal, select Enterprise Applications, select All applications, then select ScreenSteps.
  1. In the applications list, select ScreenSteps.
  1. In the menu on the left, select Users and groups.
  1. Click the Add user button, then select Users and groups in the Add Assignment dialog.
  1. In the Users and groups dialog select Britta Simon in the Users list, then click the Select button at the bottom of the screen.
  2. If you are expecting any role value in the SAML assertion then in the Select Role dialog select the appropriate role for the user from the list, then click the Select button at the bottom of the screen.
  3. In the Add Assignment dialog click the Assign button.

Test the connection

Copy the SAML Test URL. Paste the URL into a new browser window to test your Azure AD integration.

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 Azure AD 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 into ScreenSteps and into the Azure portal.

If that doesn't work, contact ScreenSteps support at support@screensteps.com

Activate the Endpoint in ScreenSteps

Activate endpoint

Navigate to the Single Sign-on area in ScreenSteps:

  1. Click the Activate checkbox.
  2. Click Update

Share ScreenSteps URL with users

Click Go To Site button

Navigate to the site that is connected to the Single Sign-on you just set up. Click on the Go To Site button.

Share this URL

This is the end-user URL of your knowledge base. Share this URL with viewers.

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]

Where do you want to create the endpoint?

In ScreenSteps, you can create a Single Sign-on connection at the site level or the account level. Which one would you like to do?

Confirm your site is marked private

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Select the site you want to create an SSO Endpoint for.
  2. Click Settings
  3. Click Settings (a different Settings)
Check Private > update

Create a new Endpoint

Configure Single Sign-on

Just below your site settings is Single Sign-on.

  1. Click Single Sign-on
  2. Click Configure SSO
Create the Endpoint
  1. Include a title (like "PhenixID")
  2. Confirm SAML is selected
  3. Click Create

Create endpoint in ScreenSteps Account

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Click Account
  2. Click Single Sign-on
Create the Endpoint
  1. Include a title (like "Google")
  2. Confirm SAML is selected
  3. Click Create

Add Viewer Group to your ScreenSteps site

You will need to add this viewer group to the ScreenSteps site that the users will be viewing.

Click Back to Sites
Confirm site > click Viewers
  1. Confirm you are in the correct site
  2. Click Viewers
Click Add Group
Add your Google Group

Now your users will be authenticated to your ScreenSteps site.

Confirm your site is marked private

Check Private > update

Navigate back to Account Single Sign-on

Include Configuration Settings from PhenixID

  1. Paste the Login URL from PhenixID (SingleSignOnService -> Location value)
  2. Paste the Logout URL from PhenixID (SingleLogoutService -> Location value) - this is optional.
  3. Click Update
Upload the SAML Certificate file
  1. Upload the IDP Signing Certificate that you downloaded from PhenixID.

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

Test the connection

Navigate back to your ScreenSteps Single Sign-on area.

Copy the SAML Test URL. Paste the URL into a new browser window to test your PhenixID integration.

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 PhenixID login page.

Did the test work?

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

Double check your work

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

If that doesn't work, contact ScreenSteps support at support@screensteps.com

Activate the Endpoint in ScreenSteps

Activate endpoint

Navigate to the Single Sign-on area in ScreenSteps:

  1. Click the Activate checkbox.
  2. Click Update

Share ScreenSteps URL with users

Click Go To Site button

Navigate to the site that is connected to the Single Sign-on you just set up. Click on the Go To Site button.

Share this URL

This is the end-user URL of your knowledge base. Share this URL with viewers.

Summary of what these instructions include

You will now go through general instructions for creating a Single Sign-on (SSO) endpoint that uses SAML. 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.

Where do you want to create the endpoint?

In ScreenSteps, you can create a Single Sign-on connection at the site level or the account level. Which one would you like to do?

Confirm your site is marked private

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Select the site you want to create an SSO Endpoint for.
  2. Click Settings
  3. Click Settings (a different Settings)
Check Private > update

Create a new Endpoint

Configure Single Sign-on

Just below your site settings is Single Sign-on.

  1. Click Single Sign-on
  2. Click Configure SSO
Create the Endpoint
  1. Include a title (like "SAML SSO")
  2. Confirm SAML is selected
  3. Click Create

Create endpoint in ScreenSteps Account

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Click Account
  2. Click Single Sign-on
Create the Endpoint
  1. Include a title (like "SAML SSO")
  2. Confirm SAML is selected
  3. Click Create

Add Viewer Group to your ScreenSteps site

You will need to add this viewer group to the ScreenSteps site that the users will be viewing.

Click Back to Sites
Confirm site > click Viewers
  1. Confirm you are in the correct site
  2. Click Viewers
Click Add Group
Add your Salesforce Group

Now your users will be authenticated to your ScreenSteps site.

Confirm your site is marked private

Check Private > update

Navigate back to Account Single Sign-on

Configure the endpoint

upload saml certificate
  1. X.509 certificate - You need to get this certificate file from your SAML provider and upload it to ScreenSteps. It must be in PEM format.
  2. SAML Consumer URL - Use this URL with your SSO provider.
  3. SAML Test URL - Use this URL to test that your SAML settings work (after you save them and configure your identity provider).
  4. Once you have entered all of your settings, select Update.

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

Metadata for your identity provider

If your identity provider needs you to enter metadata for ScreenSteps, use the SAML Consumer URL.

upload saml certificate

For the Entity ID use the Entity ID assigned to your ScreenSteps SSO endpoint.

Here is the XML Metadata for ScreenSteps. Be sure to replace the {{}} with your SAML Consumer URL:

<entitydescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityid="ScreenSteps-Live">
   <spssodescriptor protocolsupportenumeration="urn:oasis:names:tc:SAML:2.0:protocol" authnrequestssigned="false" wantassertionssigned="false">
      <nameidformat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</nameidformat>
      <assertionconsumerservice binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" location="{{replace with your ScreenSteps SAML Consumer URL }}" isdefault="true" index="0"></assertionconsumerservice>
   </spssodescriptor>
</entitydescriptor>

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, the user will be created as a "reader" or "learner" user in ScreenSteps depending on the "Assign the following role to new user" SSO endpoint setting. You can go back later and adjust the role of SAML users after they have logged in.

How we find the email address

ScreenSteps will check three values for the user email address:

  • We will check the AttributeStatement for an 'email' value.
  • We will check the AttributeStatement for a 'mail' value.
  • We will change the Subject/NameID

Below is an example SAML response with the NameID set to mail@example.com:

<samlp:Response xmlns:saml='urn:oasis:names:tc:SAML:2.0:assertion' Version='2.0' xmlns:samlp='urn:oasis:names:tc:SAML:2.0:protocol' ID='GOSAMLR12901174571794' Destination='{recipient}' IssueInstant='2010-11-18T21:57:37Z'>
  <samlp:Status>
    <samlp:StatusCode Value='urn:oasis:names:tc:SAML:2.0:status:Success'/></samlp:Status>
  <saml:Assertion Version='2.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' ID='pfxa46574df-b3b0-a06a-23c8-636413198772' xmlns:xs='http://www.w3.org/2001/XMLSchema' IssueInstant='2010-11-18T21:57:37Z'>
    <saml:Issuer>https://app.onelogin.com/saml/metadata/13590</saml:Issuer>
    <ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#'/>
        <ds:SignatureMethod Algorithm='http://www.w3.org/2000/09/xmldsig#rsa-sha1'/>
        <ds:Reference URI='#pfxa46574df-b3b0-a06a-23c8-636413198772'>
          <ds:Transforms>
            <ds:Transform Algorithm='http://www.w3.org/2000/09/xmldsig#enveloped-signature'/>
            <ds:Transform Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#'/>
          </ds:Transforms>
          <ds:DigestMethod Algorithm='http://www.w3.org/2000/09/xmldsig#sha1'/>
          <ds:DigestValue>pJQ7MS/ek4KRRWGmv/H43ReHYMs=</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>yiveKcPdDpuDNj6shrQ3ABwr/cA3CryD2phG/xLZszKWxU5/mlaKt8ewbZOdKKvtOs2pHBy5Dua3k94AF+zxGyel5gOowmoyXJr+AOr+kPO0vli1V8o3hPPUZwRgSX6Q9pS1CqQghKiEasRyylqqJUaPYzmOzOE8/XlMkwiWmO0=</ds:SignatureValue>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MIIBrTCCAaGgAwIBAgIBATADBgEAMGcxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRUwEwYDVQQHDAxTYW50YSBNb25pY2ExETAPBgNVBAoMCE9uZUxvZ2luMRkwFwYDVQQDDBBhcHAub25lbG9naW4uY29tMB4XDTEwMDMwOTA5NTg0NVoXDTE1MDMwOTA5NTg0NVowZzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFTATBgNVBAcMDFNhbnRhIE1vbmljYTERMA8GA1UECgwIT25lTG9naW4xGTAXBgNVBAMMEGFwcC5vbmVsb2dpbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAOjSu1fjPy8d5w4QyL1+zd4hIw1Mkkff4WY/TLG8OZkU5YTSWmmHPD5kvYH5uoXS/6qQ81qXpR2wV8CTowZJULg09ddRdRn8Qsqj1FyOC5slE3y2bZ2oFua72of/49fpujnFT6KnQ61CBMqlDoTQqOT62vGJ8nP6MZWvA6sxqud5AgMBAAEwAwYBAAMBAA==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </ds:Signature>
    <saml:Subject>
      <saml:NameID Format='urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress'>example@mail.com</saml:NameID>
      <saml:SubjectConfirmation Method='urn:oasis:names:tc:SAML:2.0:cm:bearer'>
        <saml:SubjectConfirmationData NotOnOrAfter='2010-11-18T22:02:37Z' Recipient='{recipient}'/></saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions NotOnOrAfter='2010-11-18T22:02:37Z' NotBefore='2010-11-18T21:52:37Z'>
      <saml:AudienceRestriction>
        <saml:Audience>{audience}</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement SessionIndex='_531c32d283bdff7e04e487bcdbc4dd8d' AuthnInstant='2010-11-18T21:57:37Z' SessionNotOnOrAfter='2010-11-19T21:57:37Z'>
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
      <saml:Attribute Name='uid'>
        <saml:AttributeValue xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xs='http://www.w3.org/2001/XMLSchema' xsi:type='xs:string'>demo</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name='another_value'>
        <saml:AttributeValue xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xs='http://www.w3.org/2001/XMLSchema' xsi:type='xs:string'>value</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Activate endpoint

Once you have finished testing your endpoint click the Activate checkbox.

Confirm you meet requirements

Remote authentication is pretty simple to implement. Basically you authenticate a user on your server and then send a special string to the ScreenSteps server telling it that the user is valid. This article will explain how the string is generated.

Requirements:

  • You must be able to provide a URL to ScreenSteps where a user can login to your application
  • After the user logs into this page on your application, you will need to generate a signed hash (described below) and redirect the user back to ScreenSteps

Information provided by ScreenSteps

For Your Information: When the ScreenSteps server redirects a user to your remote authentication url it sends along a couple of pieces of information in the query parameters:

  • return_to_url: This is the url that the user requested on ScreenSteps. You will pass this back to ScreenSteps after the user authenticates so that ScreenSteps can display the requested resource to the user.
  • timestamp: This is the time value that you can use when generating the MD5 hash.

Where do you want to create the endpoint in ScreenSteps?

In ScreenSteps, you can create a Single Sign-on connection at the site level or the account level. Which one would you like to do?

Confirm your site is marked private

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Select the site you want to create an SSO Endpoint for.
  2. Click Settings
  3. Click Settings (a different Settings)
Check Private > update

Create a new Endpoint

Configure Single Sign-on

Just below your site settings is Single Sign-on.

  1. Click Single Sign-on
  2. Click Configure SSO
Create the Endpoint
  1. Include a title (like "Remote Auth")
  2. Confirm ScreenSteps Remote Authentication is selected
  3. Click Create

Create endpoint in ScreenSteps Account

Open a new browser window and navigate to your ScreenSteps Admin area. You will need to refer to both the ScreenSteps and Google windows.

  1. Click Account
  2. Click Single Sign-on
Create the Endpoint
  1. Include a title (like "Remote Auth")
  2. Confirm ScreenSteps Remote Authentication is selected
  3. Click Create

Add Viewer Group to your ScreenSteps site

You will need to add this viewer group to the ScreenSteps site that the users will be viewing.

Click Back to Sites
Confirm site > click Viewers
  1. Confirm you are in the correct site
  2. Click Viewers
Click Add Group
Add your Google Group

Now your users will be authenticated to your ScreenSteps site.

Confirm your site is marked private

Check Private > update

Navigate back to Account Single Sign-on

Enter Single Sign-on Settings

Enter Settings
  1. Make sure you have set your mode to ScreenSteps Remote Auth.
  2. You must at least enter a Remote login url. This is the url that users will be redirected to login to your account.
  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.

Providing information to ScreenSteps

The MD5 hash

In order to provide information to ScreenSteps that a user has permission to view content, you must pass over an MD5 hash.  

The MD5 hash

The MD5 hash is comprised of of the following strings:

  1. First name of the user (required)
  2. Last name of the user (optional)
  3. Email of the user (required)
  4. External id (used to uniquely identify user, can be empty in which case email is used, optional)
  5. Organization (optional)
  6. ScreenSteps remote authentication token (required)
  7. Time (unix time, required)

You can pass the rest of the information needed as GET parameters in the query string. You must pass all of the information used to make the MD5 hash EXCEPT for your ScreenSteps remote authentication token (this must remain secret). An example:

https://example.screenstepslive.com/login/remote/44?first_name=FIRST_NAME&last_name=LAST_NAME&email=you%40domain.com&
external_id=EXTERNAL_ID&organization=ORGANIZATION&timestamp=TIMESTAMP&
hash=MD5_HASH&return_to_url=RETURN_TO_URL

By passing over the information used to create the hash ScreenSteps can combine the secret remote authentication token with the information you passed over in order to confirm that the hash is valid. This keeps others from being able to log users in.

Using PHP to log a user into ScreenSteps

Here is some example PHP code which takes the 'timestamp' and 'return_to_url' GET parameters, combines them with user information and redirects back to the ScreenSteps server.

Remember to replace {{ScreenSteps Remote Authentication Token}} and {{ScreenSteps Remote Consumer URL}} with the correct values for your ScreenSteps SSO setup.

<p>$sToken = '{{ScreenSteps Remote Authentication Token}}';
$sRemoteAuthenticationURL = '{{ScreenSteps Remote Consumer URL}}';
$sFirstName= 'John';
$sLastName= 'Doe';
$sEmail = 'john.doe@email.com';
$sExternalID = ""; 
$sOrganization = ""; 
$sReturnToURL = urlencode($_GET['return_to_url']);
$sTimestamp = $_GET['timestamp'];

/* Build the message */
$sMessage = $sFirstName.$sLastName.$sEmail.$sExternalID.$sOrganization.$sToken.$sTimestamp; 
$sHash = MD5($sMessage);
$sso_url = $sRemoteAuthenticationURL .'?'.
      'first_name='.urlencode($sFirstName).'&amp;last_name='.urlencode($sLastName).
      '&amp;email='.urlencode($sEmail).'&amp;external_id='.$sExternalID.'&amp;organization='.$sOrganization.
      '&amp;timestamp='.$sTimestamp.'&amp;hash='.$sHash.'&amp;return_to_url='.$sReturnToURL;
header("Location: ".$sso_url);
exit();</p>

Copy the Remote Consumer URL

To notify ScreenSteps that a user has successfully logged in, you will need to redirect to a url and pass a number of parameters. The URL you redirect to will be the Remote Consumer URL that you can find in your remote authentication settings.

An example might look like this:

https://example.screenstepslive.com/login/remote/44

 

The URL

Copy Authentication Token

Copy Authentication Token

Copy the Remote Authentication Token. You will need to add this to the script you are using generate your remote authentication token.

Test Remote Authentication

Copy Remote Auth Test URL
Copy remote auth test url

If you want to test your remote authentication settings you can copy and paste this Remote Test URL  into your browser.

Activate Endpoint

Once you have finished testing your endpoint click the Activate checkbox.

Still Need Help?

Contact Us