Integrating 3rd Party Single Sign On in Sharepoint Portal Server

Introduction :

Microsoft SharePoint Portal Server 2003 enables enterprises to develop an intelligent portal that seamlessly connects users, teams, and knowledge so that people can take advantage of relevant information across business processes to help them work more efficiently. Microsoft Windows SharePoint Services and SharePoint Portal Server 2003 have become very popular in recent years and have helped many businesses create an infrastructure for sharing and collaborating internal information.

Intranet users are commonly required to use a separate password to authenticate themselves to each server they need to access in the course of their work. Multiple passwords are an ongoing headache for both users and system administrators. Users have difficulty keeping track of different passwords, tend to choose poor ones, and then write them down in obvious places. Administrators must keep track of a separate password database on each server and deal with potential security problems related to the fact that passwords are sent over the network routinely and frequently.

Single sign-on (SSO) is mechanism whereby a single action of user authentication and authorization can permit a user to access all computers and systems that he or she has access permissions for, without the need to enter multiple passwords.

In large enterprises, It is a very challenging task to authenticate users against SharePoint Portal with the existing single sign on solutions. For example one company might use Netegrity single sign-on solution to authenticate its different applications like HR, Intranet, Employee self service, etc. That same user base wants to use SharePoint Portal solutions also.

This article examines how to integrate 3rd party single sign on solutions such as Netegrity Site Minder with Windows SharePoint Portal 2003 using web page authentication. It explains how to protect SharePoint sites with 3rd party SSO and use the same credentials to login into SharePoint Portal Server.

IIS 6.0 Authentication Model:

An important part of many distributed applications is the ability to identify someone, known as a principal or client, and to control the client's access to resources. Authentication is the act of validating a client's identity. Generally, clients must present some form of evidence, known as credentials, proving who they are for authentication. Typically, credentials include a username/password pair.

SharePoint Portal 2003 is built upon IIS 6.0. Lets first take a look at the authentication model of IIS.

IIS provides a variety of authentication schemes:

Anonymous (enabled by default):
Anonymous authentication allows a user to access web and FTP sites without having to provide a username and password. When a client user accesses a web or FTP site, IIS uses the Internet Guest Account to authenticate that user.

The Internet Guest Account is created when IIS is installed, and it is named IUSR_<Computername>, where <Computername> is the name of the host machine. Having an account to use for anonymous access allows you to configure which resources all anonymous users can access on your server. The anonymous account is also added to the Guests group when IIS is installed, so any restrictions or permissions applied to that group also apply to the account.

Basic Authentication:
When a server uses Basic Authentication, the Web browser (or the FrontPage client) prompts the user for a name and password. The user name and password are then transmitted across HTTP, in clear text. Using this user name and password, IIS authenticates the corresponding Windows NT user.
To use Basic authentication, a user account must be defined on either the local machine or on a trusted domain controller. The account-based access control is all done through the NT File System (NTFS) permissions on the file system.

Integrated Windows authentication:
Integrated Windows authentication is the most secure method of authentication, but it is available only with Internet Explorer. In Integrated Windows authentication, the user's browser proves itself to the server using a cryptographic exchange during the authentication process.

Integrated Windows authentication supports both the Kerberos v5 and the NTLM (NT LAN Manager) protocols for authentication through the Negotiate package.

Digest Authentication:
Like Basic Authentication, Digest Access Authentication is based on a simple challenge-response method. The Digest scheme challenges using a nonce value (a server-specified data string which may be uniquely generated each time a 401 error is made.). A valid response contains a checksum of the user name, the password, the given nonce value, the HTTP method, and the requested URL. In this way, the password is never sent as easily decoded text, which is Basic Authentication's biggest weakness.

.NET Passport Authentication:
IIS 6 can use Microsoft's .NET Passport to authenticate users requesting resources from a web site or a web site virtual directory. The benefit that this solution offers is that the credentials are stored and managed on another server that you are not responsible for building or maintaining. Users can authenticate using the .NET Passport service and then be allowed access to the web site hosted on your WS03 server.

SharePoint Authentication Model:

IIS handles base HTTP requests, but Windows SharePoint Services implements an Internet Server API (ISAPI) filter (STSFLTR.DLL) that modifies IIS behavior to handle managed paths, or inclusions and exclusions.

The ISAPI filter either redirects requests to the Windows SharePoint Services ISAPI extension, or it allows ASPX pages (.aspx) and Web service URLs (.asmx) to fall through the filter to the SharePoint ASP.NET handler.

SharePoint ISAPI filter sits on IIS and checks all the incoming requests and modifies IIS behavior to handle http requests. So whenever a user requests a SharePoint managed URL, it challenges the users for credentials based on defined authentication scheme on IIS.

Single Sign On in an Enterprise & Problem Definition:

Many Organizations maintain its employee’s, users’ information in LDAP or Active Directory. They use 3rd party applications like Netegrity Site Minder policy servers as a mechanism for Single Sign On. The SiteMinder application is used to authenticate users for different applications like HR, Payroll, Employee Self services and many more.

But for SharePoint applications, users must be registered as system users in ordered to use full and secured functionality. If you set basic authentication on, then whenever user requests a SharePoint site URL, the browser pops up a dialog box to get user name and password. This is truly annoying. As of now, SharePoint doesn’t provide forms based authentication so that users can enter their credentials in a web page and access SharePoint services easily.

Integrating 3rd Party SSO with SharePoint Portal:

To solve this problem, we need to write our own ISAPI Extension on top of SharePoint ISAPI filter. Our ISAPI extension gets the credentials from a web page and allows the user to login into SharePoint services.

Before explaining the solution to this problem, It's assumed that you already have a setup of 3rd party single sign on solution, SiteMinder for this example, and you are using SiteMinder as a mechanism to authenticate your web applications.

Let’s discuss step by step approach to solve this problem.

1. Installing SiteMinder Agent on the box where SharePoint Services exists.
2. Protect your websites using SiteMinder administration tool.
3. Install Custom Authentication ISAPI filter on IIS 6.0
4. Configure Custom Authentication Filter.
5. Develop ad-hoc application to allow the user to login into the system with out challenging him again for credentials.

Creating a web site in SharePoint Portal:

As a first step, create a site called “empweb” in the SharePoint portal.

Installing SiteMinder Agent:

Install SiteMinder Web Agent on the box where you installed SharePoint 2003 Services. This web agent is normally used to protect your web sites based on configuration. When ever user hits your web server and requests a page from a web site that is protected by this agent, SiteMinder redirects the user to a login web page for authentication. Installing SiteMinder agent is pretty straight forward. Refer to your documentation for step by step installation instructions.

Protect “empweb” using SiteMinder:

Once you install your web agent, then go to your SiteMinder administration tool to protect your web site.

Install Custom Authorization ISAPI filter on IIS:

Custom Authorization on IIS can be done using an ISAPI extension that intercepts all incoming requests in the same way that an ISAPI filter intercepts all incoming requests.

Beginning with IIS 6.0, ISAPI extensions can intercept all incoming requests to the IIS server using the HSE_REQ_EXEC_URL function. This functionality is called wildcard application mapping. ISAPI extensions that implement this functionality are called global interceptors. Global interceptors can replace ISAPI filters that read raw data while including the added benefits of ISAPI extensions. A chain of global interceptors can be set up to redirect to one another or redirect to another resource.

In IIS 5.1 and earlier HSE_REQ_EXEC_URL is not available.

The CustomAuth ISAPI extension (version 1.0 from IIS 6.0 Resources Tool kit. or download from here) reads the user name and password from a web page and authenticates that user against NT Authentication principles. This extension provides an alternative to Basic, NTLM, and other Internet Information Services (IIS) authentication methods. With CustomAuth, you can create a custom logon form for collecting user credentials, or you can use or modify the logon form included with the tool. When you use CustomAuth for authentication, client credentials are retained in a cookie for the duration of the session.

1. In addition to allowing you to create a customized logon form, CustomAuth provides three authorization benefits:

1. After the user submits the initial logon form, credentials are never sent across the network in plaintext. Although credentials are sent in plaintext the first time that they are submitted, by default, CustomAuth requires Secure Sockets Layer (SSL) for this transaction.
2. You can specify a logon time limit, after which the user is no longer logged on to the site.
3. Users can log off the site manually.

To install CustomAuth as an ISAPI filter

1. In IIS Manager, right-click the Web site for which you want to use the custom authorization form, and select Properties.
2. Click the ISAPI Filters tab, and then click Add.
3. In the Filter name text box, type CustomAuth.
4. In the Executable text box, type the full path to customauth.dll or click Browse to navigate to it, and then click OK.

To install CustomAuth as a wildcard script map, allow CustomAuth.dll in the Web Service Extensions folder, and save CustomAuth.ini in the same directory as CustomAuth.dll

1. In IIS Manager, right-click the Web site for which you want to use the custom authorization form, and select Properties.
2. Click the Home Directory tab.
3. In the Application settings area, click Configuration, and then click the Mappings tab.
4. On the Mappings tab, click Insert.
5. Type the full path to Customauth.dll in the Executable text box, or click Browse to navigate to it.
6. Click the Verify File Exists check box to clear it, and click OK. Click OK in the Application Configuration dialog box, and then click OK in the Properties dialog box.
   
   
   
   
7. Click the Web Service Extensions folder.
8. In the details pane, click Add a new Web service extension.
9. In the Extension name text box, type CustomAuth and click Add.
10. Type the full path to CustomAuth.dll in the Path to file text box or click Browse to navigate to it, and click OK.
11. Ensure that CustomAuth.dll is highlighted, and then click Set extension status to allowed.
12. Click OK.

View Larger Image

For CustomAuth to function properly, you must configure the following three security settings:

1. Allow only Anonymous authentication for the virtual directory in which the protected Web site exists. Otherwise, the other authentication method or methods will take precedence over CustomAuth, and users will not see the CustomAuth logon page.
To allow Anonymous authentication

1. Right-click the Web site, and then click Properties.
2. Click the Directory Security tab.
3. Under Authentication and access control, click Edit.
4. Ensure that the Enable anonymous access option is selected and that no other options are selected.
5. Click OK.

2. If you are not using the default CustomAuth logon and logoff pages, ensure that your custom pages allow only Anonymous authentication and access to the IUSR_ComputerName account, which is the account used by anonymous users. (You can set logon and logoff page in the config file.)
For the logon success page (the protected Web page), you must deny access to IUSR_ComputerName.
Important
3. Do not deny access to IUSR_ComputerName for the logon page (the page that collects user credentials). If you do, the user will be prompted to provide credentials over and over and will never be able to log on.

To deny access to IUSR_ComputerName

1. Right-click the protected site, and click Permissions.
2. Click Internet Guest Account.
3. Under Permissions for Internet Guest Account, select the Deny option for Full Control, (all other Deny options also are selected), and then click OK.

CustomAuth Configuration: Using CustomAuth configuration file, we can set LogonURL,LogoffURL,LogonSuccessURL,
LogonTimeout,LogonType for the SharePoint Portal Server 2003. Download this configuration file from here.

Develop an ASP.NET application to use CustomAuth ISAPI Extension:

Note: The Default installation of WSS takes over the entire IIS Server by means of ISAPI Filter (STSFLTR.DLL) and intercepts every single request - response which ultimately prevents us from running IIS virtual directories as ASP.NET web applications. So to run our ad-hoc application to integrate custom authentication, we should exclude this path from the managed SharePoint Server.)

View Larger Image

Application Flow:

1. SSO Login Page is used to get the credentials from the user. Whenever the user types a SharePoint web site (Final Target) URL in the browser which is protected by SiteMinder, SiteMinder throws him to a SSO Login Page.
2. Once authenticated, the user should be redirected to the ssologinsuccess.aspx page. In this page store the user name and final target URL in a cookie or pass it in Query String to access it later point of time. Then redirect to the SharePoint Logon Page.
3. The SharePoint Logon Page should look something like this: (Here I passed Userid and final target URL in query string from SSO Login success page to SharePoint Logon Page.)
   

   <form name="LogonForm" action="/Logon" method="post" ID="Form1">
               <table border="0" cellspacing="2" cellpadding="0" ID="Table1">
               <tr>
                    <td><input type="hidden" size="30" name="UserName"
   				 			value = <%=userName%>></td>
               </tr>
               <tr>
                   <td><input type="hidden" size="30" name="targetURL"
   							value ="<%=Request.Params["targeturl"]%>">
                          <input type="hidden" size="30" name="Password"
   					   		value = <%=password%>>
                   </td>
               </tr>
               </table>
   </form>
   

4. CustomAuth DLL intercepts this SharePoint Logon Page and authenticates the user with the credentials provided in this page. Once it succeeds, it will return to SharePoint Logon Success page. We configured these pages in CustomAuth Configuration file. But here, this user USERID should be a system account on the SharePoint Server box. So whenever a user requests access to any SharePoint web application, we should create a user id in the system and will have to give required privileges according to the user role. This can be automated using a web page by implementing WIN 32 APIs.
5. In the SharePoint Logon Success Page URL, just redirect it to final target.

   private void Page_Load(object sender, System.EventArgs e)
   {
   string targetURL = Request.Cookies["finalurl"].Value;
   Response.Redirect(targetURL);
   
   }
   

In this way we can integrate third party Single Sign On applications like SiteMinder with SharePoint Portal with the help of ISAPI Extensions. Also developers can modify CustomAuth.cpp file according to their custom needs and implement the SharePoint authentication to meet their goals. Download complete source code from here.

Authors

Sharat Nellutla is an Architect at Verizon Communications. He designs and develops telecommunication applications using .NET and Java. His current work includes voice over ip protocol applications and intranet web applications.