SSO Client: Setting Up a Remote Sign-In

Welcome! More than likely you have arrived at this page because you are the developer responsible for integrating your existing sign in system with a SSO Server based application. Or you are the person responsible for a running SSO Server instance. In either case, what follows are simple instructions and example code to get up and running quickly and the responsibilities of both parties. If you've done this sort of integration work before, it should only take about 30 minutes of your time to complete the entire process. If not, this will take a while to complete but won't be too painful because the end result is pretty cool (in a nerdtastic way).

The Remote Login provider of the SSO Server allows for relatively quick and painless setup of a SSO Client when it is located behind a firewall. This is accomplished with web browser redirects. Trust is established through revokable API keys, hard to guess secrets, and layers of cryptographic communications.

The rest of this documentation assumes that a "Manager" manages the SSO Server and that a "Deployer" manages deployment of the SSO Client. The instructions are step-by-step. You need only read the steps that apply to you.

Manager and Deployer: Resolving Issues

Obviously, nothing is perfect and Remote Login is a complex provider to set up with lots of room for error. As the author of the SSO server/client, my hope is that following this documentation will resolve most problems. Both parties should work with each other on technical issues first and, if it is determined to be a problem with the software itself that can't be fixed without changing it, then agree to use the forums on this site to discuss the problems being encountered.

It is also a good idea to document the source code with contact information. You never know when the Manager or Deployer will need to be reached about the setup.

Manager: Application Support for Remote Login

Your application has to support the Remote Login provider. The most common method is to accept an additional request parameter in the URL called "sso_remote_id", which will be passed onto the SSO Server as-is. You might have code that looks like this:

	if (!$sso_client->LoggedIn())  $sso_client->Login("", "You must login to use this system.");

SSO_Login() supports a third parameter that contains an array of information that will be passed onto the SSO Server. Modify the code to look like:

	$extra = array();
	if (isset($_REQUEST["sso_remote_id"]) && is_string($_REQUEST["sso_remote_id"]))
		$extra["sso_provider"] = "sso_remote";
		$extra["sso_remote_id"] = $_REQUEST["sso_remote_id"];
	if (!$sso_client->LoggedIn())  $sso_client->Login("", "You must login to use this system.", $extra);

Now the application accepts a URL like:[Deployer's Remote Key]

You will need to figure out the correct URL for your application. You can get the correct value for the Deployer's Remote Key from the remote configuration in the SSO Server admin under Remote Login -> Manage Remotes -> Edit -> Remote Key. From here on, the URL will be referred to as the "Entry Point URL" since it is how end-users will access the system to sign into your application.

Manager: Send Setup Information

If you haven't done so already, follow the directions in the "SSO Server Provider: Remote Login" section of the SSO server/client documentation up to the point of visiting this page. Send the following information to the Deployer:

As part of the information, it is also a good idea to include a reminder on what the next step is for the Deployer ("Install the SSO Client", "Connecting the SSO Client", and "Send Response"). Things like requesting a URL to an icon and mentioning the sign in icon size (default is 48x48 pixels), allowed IP address ranges of the Deployer's users, allowed IP address ranges of the server(s) that will be using the API key, and verification of what is already entered into the system are commonly requested. The response for such information, as described in the next section, is known as the "Common Setup Information."

Deployer: Installing the SSO Client

You don't have to know how the SSO server works to do the integration. The SSO server/client documentation is quite extensive. You are welcome to read it, but don't feel like it is necessary to do so other than knowing it is available and to see what the Manager has had to suffer through.

At any rate, you should have received five pieces of information from the Manager:

You may also be asked for a URL to use that contains an icon of a specific size, the range of allowed IP addresses for your users (from an outside-your-firewall perspective), the range of allowed IP addresses of the server(s) that will use the API key (i.e. the server(s) on which you install the SSO client - again, from an outside-your-firewall perspective), and to verify any information already gathered. You will include your response as part of the "Send Response" step. From here on, your response for this information will be referred to as "Common Setup Information."

You are now ready to install the SSO client. Installing the SSO client is similar to, but a reduced version of, installing Barebones CMS. The installation procedure is as follows:

At this point, the SSO client is installed but not connected to your sign in infrastructure.

Deployer: Connecting the SSO Client

Each sign in system is different, but a lot of enterprise environments rely on Active Directory, LDAP, or another account management interface. Users, while they understand the need, hate signing into systems, especially with different passwords and even dislike signing in multiple times with the same username and password. So, if you want to get fancy, look up something called SSPI or GSSPI/GSSAPI. All major web servers have support for this protocol (e.g. mod_auth_sspi for Apache), which allows for transparent sign in using an existing set of sign in tokens from the user's OS. For example, if a user signs in to the OS via Active Directory, which uses an authorized domain controller, the OS gets sign in tokens. SSPI relies on NTLM, which all major web browsers support, to talk to the OS to get the signed in user's sign in tokens, which the browser passes securely to the server. The server then passes the tokens on to Active Directory, which confirms that the tokens are valid for the particular user. The resulting user information gets passed onto scripting languages on the server, which can act on the information.

There are two different ways to use the SSO client: Fully automated using SSPI or a similar protocol as described above (ideal) or displaying username and password fields and having the user enter them in (not as ideal). How you want to integrate with the SSO client is up to you.

What follows is a short code sample that demonstrates basic integration with the SSO client:

	require_once "client/config.php";
	require_once SSO_CLIENT_ROOT_PATH . "/index.php";

	$sso_client = new SSO_Client;

	// Check the input to make sure signing in is even possible.
	if (!$sso_client->CanRemoteLogin())
		echo "Access denied.";

	// Check login here (LDAP, SSPI, etc).
	// ...

	// Get a unique user ID and fill out protected fields.
	$userid = "42";
	$fieldmap = array(
		"first_name" => "John",
		"last_name" => "Smith",
		"email" => ""

	// Finalize the sign in.
	$sso_client->RemoteLogin($userid, $fieldmap);

That should be fairly simple to follow along with but it might help to understand where the above code fits into the big picture:

The "Entry Point URL" is the front end of the application with a special token that gets passed onto the SSO server. The SSO client running on the application front end talks to the SSO server and sets up a new temporary session and gets a URL that represents the SSO server front end. The web browser is redirected to the SSO server front end and the Remote Login provider (the SSO server can have multiple sign in "providers") sees the special token that was passed, verifies that it is a token it recognizes, and then enables the temporary session for remote access. The Remote Login provider then redirects the web browser to the URL where your sign in code resides (how the server knows about your internal URL is discussed a bit later). You sign in the user and then push information to the SSO server via the SSO_RemoteLogin() function, which requires knowing the SSO server endpoint URL and having an API key and secret, which are stored in 'config.php'. The SSO_RemoteLogin() function redirects the browser back to the SSO server front end upon successful completion of the information push. The Remote Login provider confirms that the information sent is valid and then completes the activation step of signing in.

Depending on the information you send to the SSO server, it may also be possible to completely bypass the validation phase and have a fully transparent sign in process all done with browser redirects and cookies. That is, the user goes to the Entry Point URL while on your network and, the next thing they know, they are signed into the Manager's application. Some users might find it slightly magical and/or creepy despite being securely signed in.

The code you write should try to fill in the field list as best as possible. If you use SSPI or similar, you may only get a username. From there you'll have to connect to LDAP to obtain additional information about that user to send onto the SSO server. Under no circumstances should you send a user's password to the SSO server.

From here on, the entry URL of the code that does the sign in will be referred to as the "Internal Sign In URL."

Deployer: Send Response

The integration on your end is now done. You are now ready to send the response to the Manager. Send the following information:

This information actually doesn't have to be sent all at once, but the Manager will likely appreciate having everything in one nice, neat package to finalize the setup. More than likely, you will want to test things as they are being developed. So, as soon as each piece of information becomes available, letting the Manager know is a good strategy to being able to test the setup sooner than later. In particular, the "Internal Sign In URL" makes it possible to test the entire sign in process. Where there are multiple parties involved, keeping the lines of communication open is a great strategy for a successful and rapid deployment.

The Manager may indicate their preference on how and when they want to receive information based on previous deployments.

Manager: Final Setup

Once you receive the "Internal Sign In URL" and "Common Setup Information" as described above, you can plug the information into the correct locations within the SSO server admin. The remote will be fully operational as soon as the "Internal Sign In URL" is copied into the Remote API key's "Live URL" field.

Once all the information is plugged in, the Deployer can begin testing. It is important to be lenient toward changes, especially during the setup phase. Be sure to remind the Deployer of the Entry Point URL, which users must use to sign in using the remote.

Once the Deployer is happy, you can celebrate.

Deployer: Testing and Final Deployment

Use the Entry Point URL to test the system. This URL is what you will send to your users so they can sign into the system. If there are changes that need to be made, contact the Manager.

How you let users know about the Entry Point URL is up to you. It could be done via e-mail, a nightly push that adds a Bookmark to their web browser, etc.

Now that all of this mess is done, go celebrate! If you actually enjoyed the deployment, hop on the forums and share your joy.

© CubicleSoft