OAuth Proxy to SSO Integration Guide
This document is intended for SSO implementers. We hope to share some of our experience with common integration patterns between the gadget server's OAuth-enabled HTTP fetching service and third party SSO systems.
Background on Gadget Server HTTP Fetching
A developer using the Shindig gadgets server has the ability to make outbound HTTP(S) requests via the makeRequest API. The gadget server conforms to the OAuth standard as used in OpenSocial for signing outbound HTTP requests and managing tokens. This feature has sometimes been referred to as the OAuth Proxy, since it allows a developer to ask for the client-side OAuth protocol to be handled on his behalf, without having to fully implement all the logic to bring his applications up to OAuth spec. It also allows untrusted gadgets operate in the trust realm of the gadgets server for a limited set of functions.
Common SSO patterns
There are generally two forms of SSO:
Browser-based, and user interactive
Server to server (web services)
Most SSO systems on the market support some form of browser web SSO, fewer support web services. Services that use the OAuth Proxy's HTTP fetching system have some limitations when used with browser-based SSO systems that make server to server the preferred mode of interop. The following scenarios will focus on SSO-specific changes that should be done to support a server-to-server auth model where no user interaction is required. This is sometimes referred to as "two-legged OAuth".
From our experience, the amount of centralized control in an IT environment, and variability of the web-serving environment can greatly affect how easily changes to the SSO system can be deployed. We've divided SSO interop into two main categories, based on the amount of control an IT group has over the SSO agents installed on each application / web service. And, whether the SSO agents can support web services in addition to web browsers. In general, an SSO system from a top-tier vendor should have agents that work in both browser and web services mode.
SSO Agent Auth Forwarding
The suggestion for IT environments where the SSO agents can support web services and can either be upgraded, or already support arbitrary web auth, is to have SSO agents forward the relevant parts of a request that are needed for validation on to a central SSO server.
In the case of a signed fetch, where the singed request parameters include identity attributes, there need not be any authorization, or permissions checks by the SSO server in this flow, as this can be left up to the web app behind the SSO agent. In that case, the forwarding is only for validating the authenticity of the attributes passed in the request to the service provider. The service provider, or endpoint, does not need to know about the keys used to sign the request, but should care what the OAuth consumer id of the calling app is for the purpose of checking a whitelist of allowed client apps. The request carries no inherent authorization information, but it does have set of attributes that can be trusted if the signature validates.
See Introduction To Signed Requests and Validating Signed Requests on the OpenSocial Wiki for more information.
When the request includes an OAuth Access Token, there are inherit permissions delegated to the calling application and these can be returned to the service provider via the permissions model built into the SSO system. One example might be a simple authorization scope, such as the set of URLs on the service provider that the consumer is allowed to access. This authorization scheme is outside the scope of OAuth and could be proprietary to the SSO system.
The deployment model here is update the central SSO server to support OAuth request validation, then, if necessary, update each agent as needed for each web service needs to support Signed Fetch. Some SSO servers already support this forwarding model and it can be extended to include support for forwarding the relevant parts of an OAuth request. (The common elements, that may already be supported in this mode are the Authorization header, the url, method and the post body). A central SSO server simplifies the task of key management between the company running the SSO and the OAuth Proxy.
In this model, each hosted application, or OAuth client, need only be aware of the endpoint that has the necessary data. It doesn't need to know the location or setup of the central SSO server because all interaction happens through a back channel request. This is similar to the SAML artifact profile. In addition, the hosted application need not support redirecting or server-side persistence of proprietary SSO tokens. This is a stateless system where each request has unique authentication information.
Client Redirect Auth
In some IT environments, the deployed SSO agents are not homogeneous, or for whatever reason, it's easier to modify only the central SSO server. In this scenario, the client is redirected from the service provider to the central SSO server, and it does a token swap, changing the OAuth request into a local SSO token. In this browser-like model, an SSO agent on a web service only accepts proprietary SSO tokens, and when it sees OAuth, it ignores it and redirects to the SSO server. The OAuth Proxy's fetch system needs to be redirected to the SSO server to swap the OAuth Access token or Signed Fetch credentials for a SSO token. It is then redirected back to the web service and this time sends the SSO token. This approach does not require SSO agents to be updated and all web services within the organization can immediately support OAuth. The OAuth proxy manages OAuth tokens and OAuth redirects for the gadget, but in the case of SSO tokens, it is up to the gadget to save the SSO token returned from the SSO server after the swap and create a subsequet makeRequest call with the appropriate SSO token to the desired endpoint.
However, this approach has some drawbacks in the gadgets environment. It requires redirects, and since we recommend you DO NOT use User Prefs for storing tokens, nor the AppData store of OpenSocial, there is no easy, reliable user-centric persistence for these sensitive SSO tokens in the gadgets system. Tokens obtained will be lost after a container page refresh and when the token is lost for whatever reason, the OAuth for SSO swap needs to happen again. In addition, there is more client-side logic required to support this SSO token management in the gadget.
In the end, either system, the redirect-based, or web services, will work with the OAuth Proxy, but you may find that the Agent Forwarding scheme is more transparent to gadget developers.