Developing SSO Protected Applications
Portion of Application Development with Single Sign-On presented at 2010 Developer Conference
Applications protected by SSO see three touch points with the SSO environment:
- incoming request headers injected by the SSO proxies as requests pass through them,
- calls to the SSO policy server to ascertain the current user's access to URLs (openSSO) or URNs (OES) referred to as fine-grained permissions
- Special query parameters that can force authentication or session termination are included in application resource URLs
SSO injected headers
When http requests reach a server protected by the SSO environment they include the list of headers outlined on the SSO Injected Headers page. These can be used by the applications to customize their presentation or access the correct data for the user. One has particular importance for evaluating fine grained permissions within applications.
policy-service-url indicates the policy server's URL for obtaining various services related to the SSO environment. For example, this is the location of a REST service that includes a call to learn what the name of the cookie is that houses the SSO token on incoming requests. By appending getCookieName to the policy-service-url header value and issuing an http GET to this URL an application can obtain a response body that contains the name of the cookie such as ObSSOCookie for example indicating that it should watch for a cookie by that name to obtain the SSO token on incoming requests.
As it turns out, no application needs to do this. Both a Java library and XQuery module are available for applications that handle this call, provides parsing of headers and domain objects reflecting their values, and can make calls to the policy server to answer authorization questions for the current user as will be discussed shortly. See ClientLib4J and ClientLib4X.
Calls to SSO policy server
For many resources, protecting access to them is sufficient. For others, applications with to provide resources for a broad audience but restrict some portions of that resource to specific groups. Take a navigation pane containing links to the various applications available to the user. Links should not be rendered for which the user does not have access. Since the application knows the URLs of the links it can ask the policy server if the user can access those links and render the links or not accordingly. Furthermore, applications can define URLs, URIs really, that are solely used to prevent such rendering of selective content in some of its resources and policies can be crafted accordingly even though no user agent will ever request such URIs and no resource is intended to be located at that URI anyway. These are solely for protecting application specific resources. Such calls by applications to the policy server to evaluate accessibility to internal resources are referred to Fine Grained Permissions or entitlements.
Some headers are cryptic. For example, policy-positions currently has a structure like p4/5u1234/7u444/1u8880/ indicating that the user is a Bishop of Ward 1234 in Stake 444 and Area 8880. Furthermore, a user can have multiple assignments adding to the complexity. Expecting applications to know about the SSO cookie and token value, where the policy server is located and the specifics of contacting each http service and parsing their answers is far too much overhead for applications to choose readily to participate in SSO's enabling features. Accordingly, a library conceptually known as ClientLib is available for handling such issues with versions for both Java, ClientLib4J, and XQuery, ClientLib4X.
Special Query Parameters
Of the headers injected with every request passing through a webgate two are tied to special query parameters watched for by webgate in an incoming request's URL. These are the policy-signin and policy-signout headers.
policy-signin header contains a value that is a special emtpy-value query parameter watched for by webgates on incoming requests to override an otherwise unenforced URL request forcing SSO to require the user to authenticate before proceeding. This allows for pages that have a dual-nature, ie: they serve both a public view and an authenticated user view at the same URL, to exist and provide a "Sign-in" link allowing a user of the publicly accessible view to convert to the authenticated view. Applications housing such pages can create that "Sign-In" link to be the same as the currently viewed page an add a query parameter whose name is the value of this header. That query parameter is solely a tag parameter meaning that it can be empty-valued and need not be followed by an "equals" sign and a value. Once authenticated then the user will be redirected back to the page including the special query paramter but since they have a session the request will be passed onward to the protected application.
policy-signout is effectively the mirror image of the functionality provided by the policy-signin header allowing dual-nature pages to include a "Sign-Out" link in the authenticated view allowing the user to convert from the authenticated view to the public view by terminating their SSO session.
As developers most of us love to tinker with, craft, and create new applications and technologies. And we typically want the barrier to entry into a technology to be as low and simple as possible if we are to get into and ultimately leverage the technology. SSO is no different. We need to be able to get it running in a simple manner and locally on our own box without needing to be tethered to some external system. To facilitate such an environment the SSO Environment Simulator was created.
- SSO Environment Overview: SSO Concepts and Environment
- SSO Environment Simulator: SSO Environment provided by Simulator
- SSO Simulator Getting Started: Where to get it/how to start it
- SSO Simulator Configuration Files: Config file reference
- A Working Simulator Example
- A Working Example with Conditions