This article is for developers who want to allow users to sign in to their ScreenSteps site through a 3rd party application that the developer controls.
Requirements:
- You must be able to provide a URL to ScreenSteps where a user can login to a 3rd party application.
- After the user logs into the 3rd party application the 3rd party application will need to execute code which generates an MD5 signed hash (described below) and redirect the user back to ScreenSteps
Should I use this or SAML?
If you application already has support for acting as a SAML Identity Provider, then please use our SAML integration.
How it works
- When a user requests a ScreenSteps page and they are not logged into ScreenSteps they will be redirected to a page set up on your website or web application.
- Your website will handle logging the user into that page.
- Your website will redirect the user back to a ScreenSteps page with some query parameters and an MD5 hash.
- ScreenSteps will validate the MD5 hash and log the user in.
Information provided by ScreenSteps to your server
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.
The MD5 hash that your server generates
In order to information ScreenSteps that a user has permission to view content you must pass over an MD5 hash. The MD5 hash is comprised of of the following strings:
- First name of the user (required)
- Last name of the user (optional)
- Email of the user (required)
- External id (used to uniquely identify user, can be empty in which case email is used, optional)
- Organization (optional)
- ScreenSteps remote authentication token (required)
- Time (unix time, required)
The external id can be used in systems where the email address of the user might change. When a user authenticates with ScreenSteps and an external_id parameter is provided, ScreenSteps will look for a user with a matching id. If no matching external id is found then the user will be looked up using the email address that is provided. If neither the external id nor the email match a user in the system then a new user will be created.
The ScreenSteps URL that your server sends a response to
To notify ScreenSteps that a user has successfully logged in you 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
You can pass the rest of the information needed as GET parameters in the query string. You will pass the following information as GET parameters:
first_namelast_nameemailexternal_idorganizationtimestamphashreturn_to_url
DO NOT pass your ScreenSteps remote authentication token as a query parameter. It must remain secret.
Here is 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×tamp=TIMESTAMP&
hash=MD5_HASH&return_to_url=RETURN_TO_URLBy 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.
Here is some example PHP code which takes the timestamp and return_to_url GET parameters, combines them with user information, and then 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 = '[email protected]';
$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).'&last_name='.urlencode($sLastName).
'&email='.urlencode($sEmail).'&external_id='.$sExternalID.'&organization='.$sOrganization.
'&timestamp='.$sTimestamp.'&hash='.$sHash.'&return_to_url='.$sReturnToURL;
header("Location: ".$sso_url);
exit();</p>
Carlisia
Is it possible to remote authenticate a user into protected content, but instead of giving that user the url to the space in "operation mode" (I don't know how to call it), give the user the public url? The content is not public, but the public url still works if the user is logged in. In sum, I'd like to remote authenticate the user that is given a public url of a protected space. Would this work?
Blue Mango
Carlisia -
When you remotely authenticate a user we match the user up based on their email address. If you have given a user with that email address permission to view a protected space then they will be able to see the "public url".
If you a user logins using remote authentication and we don't find an email that matches for them at all in your ScreenSteps Live account then we create a new "reader" account for them. They have no access to your admin area and won't be assigned to any protected spaces. Essentially they have a reader account that only allows them to see public content.
I think the question you are asking is, can you create a new user and have them view a lesson in a protected space without first creating that user in ScreenSteps Live. Currently the answer is no. You need to create the user either via the User Provisioning API or the admin interface and assign them the appropriate space. Otherwise we have no idea what content you want them to see what content you want to hide from them.
We are looking at adding an option to pass back group information via remote authentication. That way you could just assign a group to your space on ScreenSteps Live. If the user was part of a corresponding group in your remote authentication, ScreenSteps Live would automatically log them into any protected information that group had permission to see. But that hasn't been implemented yet.
Does that all make sense?
Bill Hamaker
Is the comment that each user must be set up as a user with a Screen Steps Live account before a protected site can be integrated with a custom web site using Screen Steps Live integration still true?. Is this also true for SAML integration?
Also I see that email address is one of the parameters need to authenticate with Screen Steps Live. What if the custom web site does not track or store email addresses of the users but instead is based on user names and passwords. Is it still possible to use Screen Steps Live authentication to get single sign on?.
Greg DeVore
@Bill -
You don't have to have the user already in the system. You can set up an authentication endpoint so that a user will automatically be added to a site when they are logged in and will this have permission to view that site.
To use remote authentication you do need to send over an email address. That is what the system uses to identify the user.
Orestes
Does this mean that if someone where to copy the already formed URL, they could login and bypass security ? anytime they wanted?
Trevor DeVore
@Orestes - no because they don't have your secret token. See the last paragraph in the article.
Vincent Barrilliot
I am interested in Orestes's question (replay attack). I guess/hope there is a check of the timestamp in the MD5 hash against the current time. If so, the attack wouldn't work because if you pass that MD5 hash again, it would contain a "too old" timestamp and the Screensteps would (hopefully) detect that the request is too old and deny it. But if the only check is that the timestamp is consistent between the hash and the URL, then the attack would be successful, isn't it ?
1 Can you confirm if there is a check on the "currentness" of the timestamp ?
2 If so, what is the "tolerance" between the Screenstep's time and the timestamp that would decide whether a query is considered obsolete or not ?
Thank you
Greg DeVore
@Vincent -
The time window is 1 minute. If the timestamp is from before that then authentication will fail.