Integrating SSO Clients With Third-Party Software
Building a brand new application that uses the SSO client is one thing. The earlier 'test_oo.php' and 'test_flat.php' examples are great starting points for managing signed in users in a brand new application. However, there are quite a few popular software applications out there that implement their own login systems. With a bit of work, the SSO client can be used with many of these products.
Integrating the SSO client with a third-party software product requires detailed knowledge of how that product's internals work as well as a healthy knowledge of the scripting/programming language that the software is written in. There is usually a "users" database table, which contains information about users and permissions that those users have. Trying to replace all of the code that references that database table would be a huge undertaking and would result in massive modifications, making upgrades to the product an impossible task later on. The inability to upgrade a product will eventually result in the system getting taken over through some security vulnerability in the product.
A better solution is to fake it. The goal of "faking it" is to override the target login system and keep the third-party software mostly oblivious to that fact. What is meant by this is to locate the earliest common point in the software product that results in the fewest modifications (if any) to the software to override the login system transparently with the SSO client. Essentially this involves writing some software "glue" between two distinct sign in systems. Many third-party software products support what are known as "plugins" (also known as "hooks" or "extensions"). Plugins introduce additional features into a product in such a way that the core of that software product is not modified. The end result is the ability to easily upgrade the core product whenever there are new releases of that software.
An example plugin is the MyBB plugin. It is fairly fancy in that it includes a nice admin interface to support the installation of the SSO client and make installation happen as smoothly as possible. However, it does several other things that are generally useful and common concepts among plugins that implement the SSO client:
- The plugin loads the SSO client software very early in the process. This allows it to restore most POST data/requests when returning from the SSO server. However, since MyBB doesn't offer a hook early enough in the process, it had to be written in a slightly different way from most MyBB plugins to get past that problem. The worst case scenario if this doesn't happen is that POST data is lost and the user loses some work when they come back from the SSO server.
- The plugin uses a secondary database table to map SSO server IDs to local user IDs. Whenever someone signs in and returns from the SSO server, the secondary table is checked to see if that SSO user ID has been seen before. If so, it looks up the target user and signs the person into the forums as the user they signed in as before. The extra table helps with system performance and avoids modifying the main MyBB users table structure. If the user doesn't exist, it is created in the MyBB users table just like it would be created via MyBB itself. The plugin actually relies on e-mail address as a key, so that it is possible for two users with different SSO server user IDs with the same e-mail address to end up mapping to the same MyBB account - this can happen if two different providers are used.
- The plugin emulates session cookies. The same functions that MyBB uses to set up a user session are also called by the plugin. The plugin actually manages the session based on what the SSO client says. MyBB, however, is completely unaware that the login system has been replaced. It sees the user in the users table and the session cookies and thinks that all is well.
- The plugin uses SSO server fields and tags to implement permissions. This allows permissions for the application to be managed at the SSO server level rather than the application level. The plugin has a bit of extra work to do to keep permissions in sync, but it is worth the effort for a seamless experience - at least from the perspective of the SSO server admin.
- The plugin completely overrides both the 'login' and 'register' paths. The plugin sees any request to login or register and uses the SSO client to redirect the request to the SSO server.
- The plugin ignores the 'upgrade' path. When upgrading the software, the MyBB plugin gets out of the way and the original login system is restored. This happens because upgrades are more delicate than the normal MyBB software execution path. The upgrade system also doesn't always load plugins in the first place.
Other plugins for third-party software products will have a similar sort of approach.
If the software being integrated with is already in use, then the next step after installing a plugin might be to import those user accounts into the SSO server. See the documentation on importing existing user accounts. If the existing login system relies, for example, on e-mail address as a unique key in the users table, the plugin could be authored to take advantage of that fact and skip most of difficult bits of account migration for most users with the main exception being admin users.
If you don't know how to write a plugin to integrate with a specific third-party software product, you can try asking about it on the forums.