OpenSAM Single Sign On Spec

The first step to building or joining an OpenSAM mashup is to establish Single Sign On (SSO) application launch.

Single Sign On Standards

Until one of the open Single Sign On standards gains widespread acceptance, OpenSAM recommends a relatively simple mechanism: applications delegate authentication to an OpenSAM Home Application HTTP server. This is a natural solution because the Home Application is where user's typically log in first and store their documents.

A Scenario

Although simple on the surface, a lot takes place to accomplish this SSO sign on.

Four Stages of OpenSAM SSO

Stage 1: SSO CGI Parameters

There are two SSO CGI parameter sets a Home Application can pass to a launched Productivity Application.

Parameters should be accepted by the Productivity Application as both GET and POST parameters for maximum flexibility. All OpenSAM servers should trim spaces from before and after all SSO CGI Parameter values. It is common for users and/or URL building tools to insert spaces before and after CGI parameter values. This is particularly true for the SalesForce.com custom link editor.

Table 4.1 Preferred CGI Parameters. These are used by all Home and Productivity SAM applications.
StorageServerUrl	The HTTP URL to authenticate the other CGI parameters against.
StorageADFUrl	The URL of the storage server's Application Description File.
StorageUserName	The account holder's login ID or User ID. Can contain any ASCII printable character except <, >, /, or ". This is often an email address. This is defined by the Home Application and serves only to uniquely identify the user to the Productivity Applications. Apps should assume nothing about this value.
StorageUserDisplayName	The account holder's human name. Used for UI only.
StorageUserEmailAddress	The email address of the account holder. This is used during provisioning or normal use and allows the Productivity Application to provide email send services or other capabilities for the user.
StorageSessionId	This serves as a temporary password to the HTTP server and is passed to it as a CGI parameter on all requests. This is dynamically generated by the Home Application's HTTP server.
StorageSessionData	An opaque string holding user context or task information. This is generated by the Home Application, passed to the launched Productivity Application, and then must be passed back to the Home Application as a CGI parameter on every request. This allows the Home application to further customize and refine its operation when faced with numerous request sources throughout a mashup.
StorageUserTaskDescription	This user visible string briefly describes the task they are performing when the application launch took place. This string serves two purposes: Can be displayed to the user by the productivity application in various panels or screens to remind them why the application was launched. Can be stored in user-visible logs to communicate to collaborators or managers what task was being performed with the logged action (file save, ...) took place.
StorageUserTaskId	This opaque Id value provided by the Home Application is stored in the Productivity Application's logs to help clarify what took place if a subsequent operational audit is performed.
StorageSessionTerm	The requested term, in minutes, that the login session should last.
StorageOrg	This is an organization or company name that the account is to be grouped in. The semantics of Org membership are defined by the Home Application and the Productivity Application. Being a member of an Org might imply automatic sharing of resources among accounts, org-specific provisioning details, and/or other capabilities.
StorageProvisionSkel	An ID, Key or encoding that provides additional account provisioning details. For example, it could contain quota=10GB which would direct that the account be given a storage quota of 10 GB. Home Applications should treat this as an opaque value and support the configuring of this value by administrators.
StoragePasswordNotAllowed	Indicates the Home Application will not accept a user's clear text password from the Productivity Application. The Productivity Application must never prompt the user for their password in this case.
StorageCachingNotAllowed	Indicates the Productivity Application must not cache user data or documents on their server. This achieves a higher level of security and privacy for the user.
StorageNoCGIDiagnostics	If set, requests the application not report unrecognized or invalid OpenSAM CGI parameters. Such checks can help identify misspelled parameters or parameters wth invalid syntax or values and are usually helpful. During development we may not want validity checking at all times because systems may occasionally pass additional CGI parameters an application does not expect as the OpenSAM spec grows and organizations add custom extensions for their purposes.
DEBUG	If set, requests the application lengthen the timeout for requests to the StorageServerUrl to five minutes or longer. This allows a StorageServer developer to investigate problems associated with requests made by the application. This CGI parameter may trigger other debugging support as well.
StoragePassword *DISCOURAGED*	The user's password for this account on the HTTP server. Passing this can take the place of the HTTP server generated StorageSessionId. This exists only for development and testing situations and should not be used in a production environment to avoid passing passwords in visible CGI parameters.

http://www.coolapp.com/?StorageServerUrl=https%3A%2F%2Fwebdav.homeapplication.com/handlr
&StorageUserName=JohnSmith
&StorageSessionId=FKD39053DLS
&StorageOrg=ABC%20Company

https://webdav.homeapplication.com/handlr?
&StorageUserName=JohnSmith
&StorageSessionId=FKD39053DLS
&StorageOrg=ABC%20Company

Host: webdav.homeapplication.com
User-Agent: Server-to-Server HTTP_Request
Connection: close
Depth: 1
Content-Type: text/xml
Authorization: Basic c2ZkZW1vQGluZXRvZmZpY2UuY29tOkZBRjk4QjE2NEE5QzQzMEI3Rjk5QzUwN0QwRDNBNTRG^M
Content-Length: 171

The StorageUserName and StorageSessionId is contained in both the HTTP request CGI parameters and in the Authorization: Basic header.

Prior to 4/3/2008, this document recommended the WebDAV PROPFIND request be used to access the Home application server. We now recommend the perhaps faster HEAD request which is an HTTP request and therefore does not require the Home Application support any WebDAV extensions.

These are the Custom Link contents entered into the Edit Custom Link page at the SalesForce.com setup::Edit Custom Button or Link page:

https://www.coolapp.com?StorageUserName={!User.Username}
&StorageSForceSessionId={!User.Session_ID}
&StorageSForceOrg={!Organization.Name}
&StorageSForceUrl={!API.Enterprise_Server_URL_60}
&StorageServerUrl=https%3A%2F%2Fwww.sharemethods.net%2Fnepal%2Fwebdav%2F

This is the URL SalesForce.com generates and launches when the user clicks on that custom link:

https://www.coolapp.com/?StorageUserName=johnsmith%40inetoffice.com%20
&StorageSForceSessionId=rp84dT_kitNx6kkbY0tT5bueKM80EAWjgfHolU.Q6NrXxT8ZQ8Znh6nXYWU4_aGzo%3D%20
&StorageSForceOrg=AcmeCompany%20
&StorageSForceUrl=https%3A%2F%2Fna1.salesforce.com%2Fservices%2FSoap%2Fc%2F6.0%20
&StorageServerUrl=https%3A%2F%2Fwww.sharemethods.net%2Fnepal%2Fwebdav%2F%20

https://www.sharemethods.net/nepal/webdav/?
&StorageUserName=johnsmith%40inetoffice.com
&StorageSForceSessionId=rp84dT_kitNx6kkbY0tT5bueKM80EAWjgfHolU.Q6NrXxT8ZQ8Znh6nXYWU4_aGzo%3D%20
&StorageSForceOrg=AcmeCompany%20
&StorageSForceUrl=https%3A%2F%2Fna1.salesforce.com%2Fservices%2FSoap%2Fc%2F6.0%20

The StorageSForce* parameters are originally generated by SalesForce.com within a custom link and passed to the productivity application. The Productivity Application passes those SForce parameters to the other Home Application for authentication. The other Home Application then re-submits the StorageSForceSessionId back to the StorageSForceUrl SOAP API server for validation. Thus the parameters have made a full round trip among three applications within the SAM mashup and all applications are SSO signed on based on a SalesForce.com user account.

The user then edits a document within the Productivity Application (www.coolapp.com). When they click the save button coolapp.com saves the document to sharemethods.net's WebDAV storage utilizing the same StorageSForce* parameters.

Stage 2: Confirm CGI Parameter Validity

If your Productivity Application caches user documents, data, or preferences, then it must make sure every login attempt is authenticated by the same organization that originally provisioned the account. This is to ensure no one can gain access to any remnants of user's data by passing in a StorageServerUrl to authenticate against that they, rather than the genuine user, controls.

To accomodate the broadest array of server and clustering architectures, the Productivity Application should check only the domain name + path portion of the StorageServerUrl and allow the host name portion to vary. For example, if the first time an account is provisioned the StorageServerUrl=http://www2.rocknservers.com/datahere, then the Productivity Application should record rocknservers.com/datahere as the valid Storage Server domain + path. If a subsequent attempt to authenticate is made using StorageServerUrl=http://www8.rocknservers.com/datahere, then the Productivity Application should allow the log in since www8.rocknservers.com is always controlled by the same organization that www2.rocknservers.com is.

Note that a request from www2.rocknservers.net should be denied since that domain could have been obtained by someone other than those who own www.rocknservers.com.

Note also that these details preclude the use of different hostnames to differentiate between different organizations. For example, you cannot host the company RAIDERS at raiders.football.net and the company SEAHAWKS at seahawks.football.net. Such an arrangement might allow the RAIDERS to log into the SEAHAWKS' OpenSAM accounts. If you wish to host this way, you'll have to set up another domain name to do all the OpenSAM SSO authentication or be sure that the path portions to their WebDAV accounts vary also: StorageServerUrl=raiders.football.net/raiders and StorageServerUrl=seahawks.football.net/seahawks.

Other validation checks can be made as needed. For example, the StorageOrg might be verified to be the same as that submitted
when the account was originally provisioned.

Stage 3: Authenticate Via HTTP

Once the StorageServerUrl is validated as being genuine for the account, the other login credentials must be submitted to that server
to establish if this login is valid.

The check is performed simply by doing a HTTP HEAD request on the StorageServerUrl URL. The StorageUserName and StorageSessionId are submitted as CGI parameters within the URL used to make the HTTP request.

All the other Storage SSO CGI parameters are also submitted to the HTTP server as CGI parameters within the HTTP HEAD request URL. This is required because some OpenSAM HTTP servers may want the StorageOrg, StorageSForceOrg, etc. to fully authenticate, and HTTP Authorization does not accomodate addtional params besides the UserName and Password.

If a StorageServerPassword is provided by CGI rather than the StorageSessionId, then the StorageUserName and StorageUserPassword are submitted to the HTTP server in an HTTP Authenticate header just as they would if the user typed their username and password into a browser's prompt. In this scenario the 'realm' supplied by the WebDAV server has no bearing.

If the HTTP HEAD request succeeds with any HTTP status 2NN code, then the login attempt is successful. If the HTTP HEAD request fails, then any reason that the HTTP server wishes to give is given as HTML within the request response body. The Productivity Application displays that HTML as the reason for failure.

For example, if the account is temporarily unavailable for maintenance, the HTTP server would place such a message in the response body and the Productivity application will relay it to the user. This way the user knows to try again later and does not call product support for assistance.

As an additional security measure, we recommend you make two requests to the HTTP server. The first will be made with no HTTP Authorization headers and no HTTP URL CGI parameters. This first request must fail with error 401. If it does not fail then the server is misconfigured to allow public access to that portion of the URL namespace and cannot be relied upon to authenticate. This is especially useful during developement. This first check is referred to as the "Misconfigured server precheck."

Stage 4: Just-in-time Provision Account

Some Productivity Applications operate in OpenSAM with no persistent data or meta data whatsoever. They store all user data on the
Home Application's HTTP server. Such applications do not need to provision an account.

Other Productivity Applications may cache documents, portions of documents, meta data, or user preferences within their system. These applications must at this point check to see if the account identified by the StorageUserName has been provisioned yet, and if not, provistion it using the provisioning CGI params supplied.

Note that because some Application Servers may not provision accounts, and other Application Servers might just-in-time provision
(or even re-provision after a hardware failure or upgrade) at any time, the full set of OpenSAM Standard SSO CGI Parameters must be
provided by the Home Application to the Productivity Application on every launch.

Manual Sign Ons

Depending on how stringent your security requirements are, you may or may not want to allow users to enter their password into a third-party application. If security requirements are low, then you may want to support this manual re-sign-on mechanism.

A user may work in a single Productivity Application session for several hours or even days. Because the StorageSessionId is has a limited life (usually a few hours, but perhaps a few days), it can expire before the user saves the document they are working on.

The Productivity Application will, of course, have autosaved the document and it will be available for recovery whether or not this re-sign-on mechanism is available.

In this case, the Productivity Application puts up a box requesting: "Your session has expired. Please log in to <storage domain name>. ID: [------], Password: [------]. The Productivity Application submits the entered ID and Password pair to re-connect to the Home Application HTTP server.