How do I remotely authenticate a user using ScreenSteps Remote Authentication?
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.
- 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
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
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)
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:
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×tamp=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.