The first step to building or joining a SAM mashup is to establish Single Sign On (SSO).

Single Sign On Standards

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

Because WebDAV is built on HTTP and uses HTTP authentication (http://www.ietf.org/rfc/rfc2617.txt), virtually every server and client toolset supports it.

We plan to eventually recommend one of the more powerful: Liberty Alliance SSO, or OpenID

A Scenario

The following scenario illustrates SAM SSO.

1. Aaron arrives at work and logs into his SaaS Document Management System.
   This is his SAM Home Application.
2. From within his Home Application Aaron browses to a document and clicks the Edit button.
3. A Web 2.0 Productivity Application is launched with the document loaded and ready for editing.
   This Productivity Application is provided by a company other than the Home Application provider.
4. After a few edits, Aaron clicks on the Save button within the Productivity Application.
5. The changed document is saved back to Aaron's Home Application.

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

Four Stages of SAM SSO

SAM SSO is accomplished in four stages:

1. SSO CGI Parameters
   When the Web 2.0 Productivity Application is launched in step c., it is passed the SAM standard SSO CGI parameters. These parameters specify what user to authenticate and where to authenticate them.
2. Confirm CGI Parameter Validity
   Upon launch, the Web 2.0 Productivity Application first confirms the SAM SSO CGI parameters are valid for the account according to its records. This preliminary check does not include checking the password or Session ID.
3. Authenticate Via WebDAV
   The SSO CGI parameter values are used to access the user's Home WebDAV server. If the server access succeeds, then the sign on is successful. If the access fails (usually failure 404), then the sign on has failed.
4. Just-in-time Provision Account
   The final step is to provision the account within the Web 2.0 Productivity Application's system, if needed. This is called just-in-time provisioning.

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 SAM 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.

Use this handy tool to build an encoded URL containing the SSO parameters: http://new.inetword.com/s/buildurl.php

Parameters marked with a * are mandatory.

Examples

URL within a Home Application to launch a Productivity Application:

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

WebDAV request URL to authenticate the SSO via WebDAV:

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

WebDAV HTTP request including headers:

PROPFIND /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

Notes:

The WebDAV request is over HTTPS (ssl), so Authorization: Basic is allowed.

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

Examples

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

WebDAV request URL to authenticate the SForce based SSO via WebDAV:

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

Explanation:

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 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, then the Productivity Application should record rocknservers.com as the valid Storage Server domain. If a subsequent attempt to authenticate is made using StorageServerUrl=http://www8.rocknservers.com, 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.

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 WebDAV

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 WebDAV PROPFIND request on the StorageServerUrl URL. The StorageUserName is submitted as the HTTP Authorization: user name. The StorageSessionId is submitted as the HTTP Authorization: password.

All the other Storage SSO CGI parameters are submitted to the WebDAV server as CGI parameters within the WebDAV PROPFIND request URL. This is required because some SAM WebDAV 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 that is submitted as the HTTP Authorization password.

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

For example, if the account is temporarily unavailable for maintenance, the WebDAV 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 assistence.

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 WebDAV 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 SAM Standard SSO CGI Parameters must be
provided by the Home Application to the Productivity Application on every launch

Manual Sign Ons

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.

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 WebDAV server.

A Productivity Application may solicit manual sign ons using that same UI in other scenarios. For example, if a Productivity Application is launched with a StorageServerUrl and a StorageUserName, but no StorageSessionId, then it could prompt the user for their password before attempting the sign-on.

Copyright © 2006-2007, the authors.