integrating-with-third-party-software.md

Integrating With Third-Party Software

Building a brand new application that uses the official 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 server can be used with many of these products.

There are currently two approaches to integrating the SSO server with third-party software. Both approaches have their pros and cons.

Integrating With The OAuth2 Shim

OAuth2 is a protocol that lets users sign into many different systems. Integrating with the OAuth2 shim for SSO server is by far the easiest integration method requiring no coding and usually only takes a few minutes to get it working. Most third-party software products offer various OAuth2 integrations (Google, Facebook, Twitter, etc). You may have already noticed that API key configurations reference the OAuth2 shim that ships with SSO server.

Before getting into the setup of OAuth2, here are the downsides of the OAuth2 shim:

• No session control management from the SSO server. Sessions are controlled by the calling application whereas the official SSO clients always abide by the SSO server session lifetime.
• Very limited tags/permissions support. Mapped SSO tags are passed back with a tag: prefix, but only a custom OAuth2 provider could interpret them and do something. At that point, integrating the regular SSO client may make more sense.
• Disabled namespace support. Namespaces can still be enabled but could result in an infinite login loop since an OAuth2 provider can't detect a loop of this nature.
• No request continuation. HTML forms that were filled out will probably have to be filled out again unless the application saved them prior to initiating the login. Admittedly, this is fairly minor.

The simplest approach is to find a "generic" OAuth2 client plugin for the third-party software and install it. This is the most flexible solution as there will be freeform fields that allow for the various endpoint URLs that are needed to complete the OAuth2 flow.

If there isn't a generic OAuth2 client plugin available, a Google OAuth2 plugin for the third-party software is the next best bet. A Google OAuth2 login sequence is quite simple compared to other OAuth2 providers. Download and set up the Google OAuth2 provider. Before enabling the provider though, locate URLs with google.com and googleapis.com in the source code. There should be three: One 'auth', one 'token', and one 'userinfo'. Replace each URLs with the OAuth2 URL from a SSO server API key. Now you have created your own OAuth2 plugin for the third-party software that interfaces with the SSO server. Once the various tokens and bits are set up, it is just a matter of mapping SSO server API key fields to what Google OAuth2 emits (not all fields have to be mapped - email is probably the most important though):

• name - Full name
• given_name - First name
• family_name - Last name
• gender - Gender
• picture - Profile photo URL
• locale - Locale
• timezone - Timezone
• email - E-mail address
• email_verified - Whether or not the e-mail address is verified. Making a static field mapping here is a good idea.

Of course, the button or link that goes to the SSO server may say something like "Login with Google". To avoid confusing users, find the relevant string and/or icon and change it.

An OAuth2 provider requires the following pieces of information to function:

• A redirect/callback URI. This is usually generated by the third-party software for you and it just has to be added to the OAuth2 Redirect URIs box of the relevant API key.
• A client ID. This value is the API key.
• A client secret. This value is the OAuth secret box.
• Authorize endpoint. This value is the OAuth2 URL. This URL supports the usual extra parameters (lang, use_namespaces, etc).
• Token endpoint. This value is also the OAuth2 URL. Extra parameters are not supported.
• User info endpoint. This value is also the OAuth2 URL plus an optional access_token parameter (e.g. http://localhost/sso/server/oauth2/?access_token=). Some libraries pass a Bearer token Authorization header instead of URL parameters.

It is recommended to use an isolated API key for OAuth2. To avoid getting logged out elsewhere, using a custom namespace for OAuth2 is also recommended.

When using the Apache with Bearer tokens, the following should be added to the VirtualHost configuration:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

By default, Apache only passes properly formatted Basic Authorization headers to PHP.

Integrating With An Official SSO Client

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 more 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. The downside is that developing a plugin that uses the full power of the SSO client/server and overrides an existing login system takes time and effort.

If the software being integrated with is already in use, then the next step after creating/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.