Exercise 6-1: Using Single Sign-On

The Microsoft SSO service is useful for allowing web parts to access line-of-business systems without prompting for a separate log-in. In this exercise, you will create a simple web part that displays the audit log from SSO.

Prerequisites

Before beginning this exercise, be sure that you have properly configured the Microsoft SSO service on SPSPortal . This means you should have a global security group named MSSSOAdmins defined, and it should contain an account named MSSSOService. Additionally, MSSSOAdmins must be a member of the required local groups on SPSPortal . The SSO service should be running under MSSSOService. If you have not properly configured SSO, refer to the steps earlier in the chapter.

Creating the Application Definition

This exercise retrieves all necessary information from the SSO service that you need to connect to the SSO database and retrieve the audit log. You will use a group account definition to access the data store. Therefore, you must create an enterprise application definition and store the credentials for the definition.

Log on to SPSPortal as a member of MSSSOAdmins.
Select Start All Programs SharePoint Portal Server SharePoint Portal Server Single Sign-On Administration.
On the Manage Settings for Single Sign-On page, select Enterprise Application Definition Settings Manage Settings for Enterprise Application Definitions.
On the Manage Enterprise Application Definitions page, click the New Item link.
On the Create Enterprise Application Definition page, type MSSSO audit log into the Display Name box.
Type MSSSOAudit into the Application Name box.
Type < administrator@sps.local > into the Contact E-mail Address box.
Ensure the Account type is set to Group.
Type Username into the Field 1: Display Name box.
Type Password into the Field 2: Display Name box.
Choose the Yes option for Mask under Field 2 to mask the password when it is entered.
Click OK.

Entering the Credentials

Most often when you use SSO, you will not enter credentials directly. Instead, you will allow users to enter their own credentials the first time they use a web part. In this exercise, however, we will start with defined credentials to ensure that your web part is working correctly. Later you will implement a separate log-in form for first-time users.

Log on to SPSPortal as a member of MSSSOAdmins.
Select Start All Programs SharePoint Portal Server SharePoint Portal Server Single Sign-On Administration.
On the Manage Settings for Single Sign-On page, select Enterprise Application Definition Settings Manage Account Information for Enterprise Application Definitions.
In the Enterprise Application Definition list, select MSSSO Audit Log.
In the Group Account Name enter sps\MSSSOAdmins .
Click OK.
On the Account Information page, type values in that will allow access to the pubs database.
Click OK.

Creating the Web Part

At this point, you have built a couple of web parts and should understand how to start a project. Rather than repeat all the steps here again, simply open Visual Studio .NET and create a new web part library project in C#. Name the new project MSSSOAudit . After the new project is created, make appropriate modifications to the web part description file as you have done in previous exercises.

Setting References

Before you can get started writing code, you must set a reference that will allow you to use SSO and access SQL databases. Because you will be using the Credentials class and a DataSet , you must set a reference to the Microsoft.SharePoint.Portal. SingleSignon.dll assembly and the System.Data.dll assembly.

In Visual Studio, select Project Add Reference from the menu.
In the Add Reference dialog, click Microsoft.SharePoint.Portal.SingleSignon.dll and System.Data.dll .
Click Select and then OK to add the reference.
Add the following lines to MSSSOAudit.cs to reference the SSO assembly in your code along with the references necessary for database access.
```
 using Microsoft.SharePoint.Portal.SingleSignon; using System.Data; using System.Data.SqlClient; 
```

Defining the Properties

The design of your web part is going to use a DataGrid control to display the SSO_Audit table from the SSO database. In this web part, you will set up properties for the user name and password, but you will not allow them to be Browsable in the portal. Listing 6-4 shows the complete web part as it should appear after the properties are defined.

Listing 6-4: Defining the Properties

 using System; using System.ComponentModel; using System.Web.UI; using System.Web.UI.WebControls; using System.Xml.Serialization; using Microsoft.SharePoint; using Microsoft.SharePoint.Utilities; using Microsoft.SharePoint.WebPartPages; using Microsoft.SharePoint.Portal.SingleSignon; using System.Data; using System.Data.SqlClient; namespace MSSSOAudit {     [DefaultProperty(""),         ToolboxData("<{0}:Log runat=server></{0}:Log>"),         XmlRoot(Namespace="MSSSOAudit")]     public class Log : Microsoft.SharePoint.WebPartPages.WebPart     {C          //PROPERTIES          private string m_userName="";          private string m_password="";          [Browsable(false),Category("Miscellaneous"),          DefaultValue(""),          WebPartStorage(Storage.Shared),          FriendlyName("UserName"),          Description("The account name to access the SSO database")]          public string userName          {              get              {                  return m_userName;              }              set              {                  m_userName = value;              }          }          [Browsable(false),Category("Miscellaneous"),          DefaultValue(""),          WebPartStorage(Storage.Shared),          FriendlyName("Password"),Description("The password to access the SSO database")]          public string password          {              get              {                   return m_password;              }              set              {                   m_password = value;              }          }     } }

Defining the Child Controls

Your web part will show the audit table in a grid; therefore, you must override the CreateChildControls method to add the new DataGrid control. In this method, you programmatically create a new instance of the grid, adjust its properties, and add it to the Controls collection for the web part. Listing 6-5 shows how to create the child controls for the web part.

Listing 6-5: Creating Child Controls

 //CHILD CONTROLS protected DataGrid grdAudit; protected Label lblMessage; protected override void CreateChildControls() {     //DataGrid     grdAudit = new DataGrid();     grdAudit.Width = Unit.Percentage(100);     grdAudit.HeaderStyle.Font.Name = "arial";     grdAudit.HeaderStyle.ForeColor = System.Drawing.Color.Wheat;     grdAudit.HeaderStyle.BackColor = System.Drawing.Color.DarkBlue;     grdAudit.AlternatingItemStyle.BackColor = System.Drawing.Color.LightCyan;     Controls.Add(grdAudit);     //Label     lblMessage=new Label();     lblMessage.Width = Unit.Percentage(100);     lblMessage.Font.Name = "arial";     lblMessage.Text = "";     Controls.Add(lblMessage); }

Rendering the Web Part

Because your web part is displaying just the rows from the audit table, you can place your single sign-on code directly in the RenderWebPart method without concern for the state of any of the child controls. If you were relying on user interaction, you would have to consider the web part life cycle and event firing order to determine the best place to retrieve credentials. Listing 6-6 shows how to render the web part output.

Listing 6-6: Rendering the Web Part

 //RENDERING protected override void RenderWebPart(HtmlTextWriter output) {     string[] strCredentials=null;     string strConnection=null;     SqlDataAdapter objAdapter;     SqlCommand objCommand;     SqlConnection objConnection;     DataSet objDataSet;     //Try to get credentials     try     {     // Call MSSSO     Credentials.GetCredentials(Convert.ToUInt32(1),         "MSSSOAudit",ref strCredentials);     //save credentials     userName=strCredentials[0];     password=strCredentials[1];     //Create connection string     strConnection += "Password=" + password;     strConnection += ";Persist Security Info=True;";     strConnection += "User ID=" + userName + ";Initial Catalog=SSO;";     strConnection += "Data Source=(local)";     }     catch (SingleSignonException x)     {     if (x.LastErrorCode==SSOReturnCodes.SSO_E_CREDS_NOT_FOUND)         {lblMessage.Text="Credentials not found!";}     else         {lblMessage.Text=x.Message;}     }     //Try to show the grid     try     {         //query the SSO database         objAdapter=new SqlDataAdapter();         objDataSet=new DataSet("root");         objConnection=new SqlConnection(strConnection);         objCommand=new SqlCommand("Select * from SSO_Audit",objConnection);         objAdapter.SelectCommand=objCommand;         objAdapter.Fill(objDataSet,"audit");         //bind to the grid         grdAudit.DataSource=objDataSet;         grdAudit.DataMember="audit";         grdAudit.DataBind();     }     catch (Exception x)     {         lblMessage.Text+=x.Message;     }     finally     {         //draw grid         grdAudit.RenderControl(output);         output.Write("<BR>");         lblMessage.RenderControl(output);     } }

Deploying the Web Part

Just like all of the web parts you have created previously, this one requires a strong name and must be marked as safe in the web.config file. Additionally, you must grant this web part permission to access both SQL Server databases and the Microsoft SSO service. You will grant these permissions by modifying the web.config and wss_mediumtrust.config files.

Creating a Strong Name

At this point, it should be clear that accessing the Strong Name tool is a common operation when creating web parts. Therefore, you may want to make it more easily available in Visual Studio. Follow these steps to add the Strong Name tool to the Visual Studio environment:

In Visual Studio select Tools External Tools from the menu.
In the External Tools dialog, click Add.
Change the Title for the new tool to Strong Name Tool .
Near the Command box, click the ellipsis ( ) button.
Navigate to \Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\bin and select sn.exe .
In the Open file dialog, click Open.
Check the "Use output window" box.
Check the "Prompt for arguments" box. Figure 6-4 shows the completed tool definition.

Figure 6-4: Adding the Strong Name tool to Visual Studio
After you complete the definition, click OK.
To use the Strong Name tool, select Tools Strong Name Tool from the Visual Studio menu.

In the Strong Name Tool window, type -k c:\keypair.snk into the Arguments box.

Note	This operation overwrites any previously defined key pair at the same location. To avoid this problem, you can either continue with the existing key pair, or define a new key in another location.

Click OK.
In Visual Studio .NET, open the AssemblyInfo.cs file.
In AssemblyInfo.cs modify the AssemblyKeyFile attribute as follows :
```
 [assembly: AssemblyKeyFile(c:\keypair.snk)] 
```
Save and close AssemblyInfo.cs .

Compiling the Web Part

Once the strong name is defined and referenced in the key file, you are ready to compile the code. Because web parts must run in the \bin directory underneath the root of the web site, it is easier if you simply compile your assembly into the required directory. This will make it easier to get the web part working.

Right-click the MSSSOAudit project in Visual Studio .NET and select Properties from the pop-up menu.
In the Property Pages dialog, select Configuration Properties Build.
Set the Output Path property to \inetpub\ wwwroot \bin .
Click OK.
Compile the web part by selecting Build Build MSSSOAudit.

Modifying the web.config File

For the web part to successfully access the SQL database, you must make an entry in the web.config file under the <SafeControls> section. You will also have to change the trust level for the site because web parts cannot access databases under the default trust level of WSS_Minimal.

In Visual Studio, select Tools Strong Name Tool from the menu.
In the Strong Name Tool window, type the following into the Arguments box:
```
 -T c:\inetpub\wwwroot\bin\MSSSOAudit.dll 
```
Click the OK button to display the PublicKeyToken .
Open the web.config file in Visual Studio.
Locate the <SafeControls> section of the file. In this section, you must add a new <SafeControl> entry for your web part. The following example shows the form, but you must substitute your particular PublicKeyToken :
```
 <SafeControl Assembly="MSSSOAudit, Version=1.0.0.0, Culture=neutral, PublicKeyToken=ba635e9bfab94eac" Namespace="MSSSOAudit" TypeName="*" /> 
```
Locate the <System.web> section of the file. In this section, change the <trust> element so that the security policy is set to WSS_Medium as shown here:
```
 <trust level="WSS_Medium" originUrl="" /> 
```
Save the file and close it.

Assigning Permissions

Before SPS will authorize the web part to interact with SSO, you must grant permission by modifying the policy file. You could create your own custom file as I described in the previous chapter, or simply modify the current policy. For this exercise, you will modify the wss_mediumtrust.config file.

Open wss_mediumtrust.config in Visual Studio for editing.

In the <SecurityClasses> section, add the following entry to reference the permission class:

 <SecurityClass Name="SingleSignonPermission" Description= "Microsoft.SharePoint.Portal.SingleSignon.Security.SingleSignonPermission, Microsoft.SharePoint.Portal.SingleSignon.Security, Version=11.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"/>

Caution

The code above should appear on a single line within the configuration file. If it is not written on a single line, SharePoint Services may throw errors.

In the policy file, locate the <PermissionSet> element with the Name attribute of ASP.NET. Add the following <IPermission> element directly beneath the <PermissionSet> element to grant access to the SSO service.
```
 <IPermission     class="SingleSignonPermission"     version="1"     Access="Administer" /> 
```
Save the file and close it.
Restart IIS to have the new policy take effect.

Using the Web Part

Once the web part is properly compiled, placed in the \bin directory, marked as safe, and given permission to access SSO, it can be used in a portal page. To use the web part, you will import it into a gallery. Once it's imported, you can drag it onto a page and set its properties.

Log in to SPS as a member of the MSSSOAdmins security group.
Navigate to any site that you have previously created.
On the site home page, select Modify Shared Page Add Web Parts Import.
In the Import pane, click Browse.
Locate the file MSSSOAudit.dwp and click Open.
In the Import pane, click Upload.
Drag the MSSSOAudit web part from the pane to any zone on the page. The audit records should immediately appear in the grid.