Using Microsoft Single Sign-On Service
Microsoft Single Sign-On (SSOSrv) service provides storage and mapping of credentials such as account names and passwords so that portal-based applications can retrieve information from third-party Enterprise Resource Planning (ERP) and Customer Relations Management (CRM) systems. These back-end systems are known as enterprise applications. Microsoft Office SharePoint Portal Server 2003 helps to secure these enterprise applications by storing and mapping assigned credentials using an enterprise application definition. An enterprise application definition allows customers to interact with enterprise applications directly from the portal.
Scenarios
HRWeb
A standard human resources (HR) portal site or page may include several Web Parts that display employee information from a back-end employee management system. This employee data is stored in a dedicated HR database system, frequently based on SAP or PeopleSoft. These HR databases may not support Microsoft Windows authentication, may not run on Windows-based operating systems and, in fact, may include proprietary logon protocols. The Web Parts on the portal site should retrieve the individual employee data without prompting for a separate logon. In this example, the individual employee does not have a separate logon to the HR system, but uses a group account that provides generic read access to the database.
Business Intelligence
An executive may use a portal to provide a dynamic, aggregated view of relevant business information. This data is stored in two places: the Siebel back-end system stores the customer relationship information while the SAP back-end system tracks accounts and payments. To see an integrated view, the portal site must log on to and access both back-end systems. Prompting the user for additional passwords is an unacceptable user experience. In this example, the executive does not know the user name and password required for logon, and does not need to. Multiple Web Parts are used to ensure this integration of both back-end systems, and by default, each Web Part separately authenticates the user to the appropriate back-end system.
Notes Database
An organization may use legacy Lotus Notes databases for issue tracking and is not prepared to change databases before deploying a portal site. Each corporate user has a dedicated Notes account. Corporate developers build Web Parts that display the database and provide users with logon access and appropriate read/write permission. In addition, the portal securely stores the user name and password to minimize repeated logon requests.
Types of Application Definitions
There are two primary types of enterprise application definitions used with Microsoft Single Sign-On service:
- Individual enterprise application definitions. Individual users know and manage their own credentials on the enterprise application definition.
- Group enterprise application definitions. The individual user does not know his or her credentials on the enterprise application definition, but is associated with a managed group account.
Note The administrator, rather than the individual user, chooses the account type when configuring access to the enterprise application definition.
Logon Form
A Web Part retrieves the credentials from SSOSrv to access the enterprise application definition. For individual enterprise application defintions, if a user has not stored their credentials in the single sign-on credential database, then the user must be directed to the single sign-on logon form to enter their credentials.
To get a logon form
- Call the GetCredentials method of the Credentials class. Specify the application name for which you want to retrieve credentials.
- If SSOSrv cannot find credentials for the user for the enterprise application definition, the GetCredentials method throws a SingleSignonException. If the LastErrorCode property of the SingleSignonException is SSO_E_CREDS_NOT_FOUND, call the GetCredentialEntryUrl(String) method or the GetCredentialEntryUrl(String, Int) method of the SingleSignonLocator class to build the URL to the Single sign-on logon form. Use the GetCredentialEntryUrl(String,Int) method when the URL returned is to be formatted for Secure Sockets Layer (SSL) on a particular port. You would pass the specified port when the system cannot detect which SSL port to use, such as when multiple SSL port mappings exist or a nonstandard SSL port is used. Specify the name of the enterprise application definition and the SSL port number when calling the GetCredentialEntryUrl(String,Int) method.
- When you retrieve the URL for the logon form, redirect the browser to the URL. The logon form is displayed and prompts the user for the account name and password to use with the enterprise application definition. After SSOSrv saves the credentials, the form redirects control back to the original Web Part.
Assigning the SingleSignonPermission
If your Single SignOn Web Part is partially trusted (installed in the \bin directory of a virtual server), you must assign a custom Code Access Security Permission (SingleSignonPermission) to it. The following instructions grant a specific level of SingleSignonPermission to all assemblies in the \bin directory of a virtual server. For more information about how to restrict the permission grant to just a single assembly and not all assemblies in the \bin directory, see Microsoft Windows SharePoint Services and Code Access Security.
To add the SingleSignonPermission, make the following changes to the Windows SharePoint Services policy files: WSS_MediumTrust.config or WSS_MinimalTrust.config, depending on which one is in use
- To the <SecurityClasses> section, add: <SecurityClass Name="SingleSignonPermission" Description="Microsoft.SharePoint.Portal.SingleSignon.Security.SingleSignonPermission, Microsoft.SharePoint.Portal.SingleSignon.Security, Version=11.0.0.0, Culture=neutral, PublicKeyToken= 71e9bce111e9429c"/> .
- To the <Permission Set> section, and specifically to the PermissionSet whose Name is 'ASP.Net', add: <IPermission class="SingleSignonPermission" version="1" Access="Minimal" />
The Access modifier in the preceding permission may be set to Minimal, Credentials, or Administer. For more information, see the SingleSignonAccess enumeration documentation.
The following Web Part code example shows how to redirect the user to the logon form to save credentials for an enterprise application:
using System;
using System.Web.UI;
using System.Xml.Serialization;
using System.Runtime.InteropServices;
using Microsoft.SharePoint.WebPartPages;
using Microsoft.SharePoint.Portal.SingleSignon;
namespace Microsoft.SharePoint.Portal.SSOSample
{
[ToolboxData("<{0}:SSOSampleWebPart runat=server></{0}:SSOSampleWebPart>")]
[XmlRootAttribute (Namespace = "urn:schemas-microsoft-com:SSOSampleWebPart")]
[GuidAttribute("24452DC9-2710-4288-99A7-245560DCD6E5")]
public class SSOSampleWebPart: WebPart
{
public SSOSampleWebPart()
{
}
protected override void RenderWebPart(HtmlTextWriter writer) //RenderWebPart
{
string[] rgGetCredentialData = null;
try
{
//Try to get the credentials for this application.
//Before running this code, make sure that an individual application
//called "MyIndividualApplicationID" has been added.
Credentials.GetCredentials(1,"MyIndividualApplicationID", ref rgGetCredentialData);
}
catch (SingleSignonException ssoe)
{
//This exception is thrown if this user does not have credentials for the
//"MyIndividualApplicationID" application.
if(SSOReturnCodes.SSO_E_CREDS_NOT_FOUND == ssoe.LastErrorCode)
{
//Send the user to the SSO logon form. The logon form will:
//- Prompt the user for credentials for this application.
//- Save credentials for this user for this application.
//- Redirect the user back to this Web Part.
string strSSOLogonFormUrl = SingleSignonLocator.GetCredentialEntryUrl("MyIndividualApplicationID");
writer.Write("<a href=" + strSSOLogonFormUrl +">Click here to save your credentials for the Enterprise Application.</a>");
writer.WriteLine();
}
}
}
}
}
For more information on single sign-on and its implementation, see the Single Sign-On in SharePoint Portal Server 2003 chapter from the Microsoft SharePoint Products and Technologies Resource Kit.