The Microsoft Single Sign-On Service I n the previous chapter, you created a basic Web Part that accessed a database using cre- dentials retrieved from properties of the Web Part. Although this made for a simple design, it required users to type their credentials in clear text directly into the property pane. As I stated several times, this technique is unacceptable for a production environment. In addition to security concerns, however, information workers also have difficulty simply managing credentials. Information workers are required to remember different sets of creden- tials for different line-of-business systems. Furthermore, passwords are often cryptic and hard to remember because complexity requirements prevent the use of terms that are easy to crack. All of this results in a situation where security and usability collide, often resulting in systems that are neither secure nor usable. This is where the Microsoft Single Sign-On (SSO) service comes into play. SSO acts to manage multiple credential sets by associating them with a user’s network Win- dows login credentials. Once SSO is implemented, information workers only have to remember their network credentials. When a Web Part must access a line-of-business system, it utilizes appropriate credentials that were previously associated with the user’s network credentials. You should note right at the outset that configuring SSO is complicated and getting it to work correctly is tricky. The configuration steps require several cryptic hand edits to configu- ration files that impact code access security. The overall experience can be frustrating, but the rewards are worth the effort when you finally eliminate all the annoying secondary logins required by your enterprise applications. Setting Up SSO SSO is a combination of a Windows 2003 service, a SQL Server data store, and web-based administration tools that provide credential storage and retrieval services to your Web Parts. SSO is installed by default along with SharePoint Portal Server (SPS); however, the service is stopped and set to manual start-up. In order to begin working with SSO, you must configure and start the service. Before the SSO service can be started, you must create a new global security group that will contain an account used to run the service. This same group will contain the accounts that are authorized to administer the SSO service. The account used to run the SSO service will also be a member of this group. This group must meet several requirements: 161 CHAPTER 6 ■ ■ ■ 5750_c06_final.qxd 11/3/05 9:41 PM Page 161 • Belong to the local administrators group on the job server. • Belong to the local administrators group on the server running the configuration database. • Belong to the STS_WPG and SPS_WPG groups—which run all of the pooled SharePoint components and resources—on every server in the farm where SPS is installed. • Have db_owner and public rights for the SharePoint Services configuration database. • Belong to the Server Administrators role for the SQL Server instance where the SSO database is located. Once you have defined a security group with an account, you can configure the SSO serv- ice to run under the specified account. Additionally, you can add users to the security group so that they can define credentials in the data store. Designated users may then define sets of applications and credentials for enterprise applications. To set up the SSO account, follow these steps: 1. Log in to SPSController as the domain administrator. 2. Select Start ➤ Administrative Tools ➤ Active Directory Users and Computers. 3. In the Active Directory Users and Computers dialog, right-click the Users folder and select New ➤ Group from the pop-up menu. 4. In the New Object dialog, type MSSSOAdmins in the Group Name. Any member of this group will be allowed to administer the SSO service. 5. Click OK. 6. In the Active Directory Users and Computers dialog, right-click the Users folder and select New ➤ User from the pop-up menu. 7. In the New Object dialog, type MSSSOService in the Full Name and User Logon Name boxes. 8. Click Next. 9. Type a password for the account. 10. Uncheck the “User must change password at next logon” box. 11. Check the “User cannot change password” box. 12. Check the “Password never expires” box. 13. Click Next. 14. On the next screen, uncheck the “Create an Exchange mailbox” box. 15. Click Next. 16. On the next screen, click Finish. 17. Right-click the MSSSOService object and select Properties from the pop-up menu. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE162 5750_c06_final.qxd 11/3/05 9:41 PM Page 162 18. On the Member Of tab, click Add. 19. Type in the account name sps\MSSSOAdmins and click the Check Names button. 20. Once the account name is validated, click OK. 21. Click OK again. To set up local groups, follow these steps: 1. Log in to SPSPortal as the domain administrator. 2. Select Start ➤ Administrative Tools ➤ Computer Management. 3. In the Computer Management dialog, expand the Local Users and Groups node and open the Groups folder. 4. In the Groups folder, right-click Administrators and select Add to Group from the pop-up menu. 5. In the Administrators Properties dialog, click Add. 6. Type in the account name sps\MSSSOAdmins and click the Check Names button. 7. Once the account name is validated, click OK. 8. In the Administrators Properties dialog, click OK. 9. In the Groups folder, right-click SPS_WPG and select Add to Group from the pop-up menu. 10. In the SPS_WPG Properties dialog, click Add. 11. Type in the account name sps\MSSSOAdmins and click the Check Names button. 12. Once the account name is validated, click OK. 13. In the SPS_WPG Properties dialog, click OK. 14. In the Groups folder, right-click STS_WPG and select Add to Group from the pop-up menu. 15. In the STS_WPG Properties dialog, click Add. 16. Type in the account name sps\MSSSOAdmins and click the Check Names button. 17. Once the account name is validated, click OK. 18. In the STS_WPG Properties dialog, click OK. ■ Note Because this book utilizes a single-server configuration, you do not have to add the MSSSOAdmin account to any other local groups. If you deploy a multiple-server configuration, be sure to add the account to the appropriate group for each server that meets the requirements outlined earlier. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE 163 5750_c06_final.qxd 11/3/05 9:41 PM Page 163 To set up SQL Server permissions, follow these steps: 1. Select All Programs ➤ Microsoft SQL Server ➤ Enterprise Manager. 2. In the SQL Server Enterprise Manager, expand the tree and select Console Root ➤ Microsoft SQL Servers ➤ SQL Server Group ➤ (local) (Windows NT) ➤ Security ➤ Logins. 3. Right-click the Logins node and select New Login from the pop-up menu. 4. In the Name field type sps\MSSSOAdmins. 5. On the Database Access tab, check the box associated with the configuration database (e.g., SPS01_Config_db). 6. In the list of database roles, check db_owner and public. 7. On the Server Roles tab, check the Server Administrators box. 8. Click OK. 9. Select Start ➤ Administrative Tools ➤ Services. 10. In the Services dialog, right-click the Microsoft Single Sign-On Service and select Properties from the pop-up menu. 11. On the Log On tab, select the option This Account and type in sps\MSSSOService. 12. Enter the password you set for this account. 13. Click Apply. 14. On the General tab, change the Startup Type to Automatic. 15. Click Start to start the service. Before you can access credentials using SSO, an application definition must be created for the credentials. Application definitions consist of a unique name for the application and the definition of the logon fields to accept. SSO is capable of managing a number of fields beyond user name and password. In fact, you can define any custom field for the service, such as domain or database name. Accessing the administrative pages for SSO is done by selecting Start ➤ All Programs ➤ SharePoint Portal Server ➤ SharePoint Portal Server Single Sign-On Administration. When you first access the administration pages, only one option is available. You must complete the setup of the MSSSO service by clicking the Manage Server Settings link. The server settings require you to specify the accounts that will be used to manage the SSO service and define new applications. Until these settings are complete, you cannot define new applications. Figure 6-1 shows what the page should look like the first time you access it. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE164 5750_c06_final.qxd 11/3/05 9:41 PM Page 164 To specify server settings, take these steps: 1. Log in to SPSPortal as member of MSSSOAdmins. 2. Select Start ➤ All Programs ➤ SharePoint Portal Server ➤ SharePoint Portal Server Single Sign-On Administration. 3. On the Manage Settings for Single Sign-On page, click Manage Server Settings. 4. On the Manage Server Settings page, type sps\MSSSOAdmins into the Account Name box for both the Single Sign-On Settings and Enterprise Application Definition Settings sections. 5. Click OK. Once the initial settings are entered, you may return to the Manage Settings for Single Sign-On page where the additional hyperlinks will be available. Selecting Enterprise Appli- cation Definition Settings ➤ Manage Settings for Enterprise Application Definitions opens a page where you may define new applications. This page allows you to name the applica- tion, define the fields that should be managed, and determine whether the application will use a group or individual login. Figure 6-2 shows the available configuration options. You should use a group login when you want a single set of credentials to be used by Web Parts regardless of what user is accessing the system. This design is often associated with read- only information where users do not normally need separate identification. An organization might use this, for example, to give employees access to public information regarding corpo- rate performance. In this scenario, it is not important which employee is accessing the system because the read-only information will not change. Where you are more concerned about access and permissions, you should use an individual login. Applications defined with an individual login will require that each end user have their own set of credentials. SSO is capable of prompting individuals for credentials the first time they use a Web Part; after this, the service automatically stores the credentials for future use. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE 165 Figure 6-1. The Manage Server Settings page 5750_c06_final.qxd 11/3/05 9:41 PM Page 165 To create an enterprise applications definition, follow these steps: 1. Log in to SPSPortal as a member of MSSSOAdmins. 2. Select Start ➤ All Programs ➤ SharePoint Portal Server ➤ SharePoint Portal Server Single Sign-On Administration. 3. On the Manage Settings for Single Sign-On page, select Enterprise Application Defini- tion Settings ➤ Manage Settings for Enterprise Application Definitions. 4. On the Manage Enterprise Application Definitions page, click the New Item link. 5. On the Create Enterprise Application Definition page, type My Application into the Display Name box. 6. Type MyApp into the Application Name box. 7. Type administrator@sps.local into the Contact E-mail Address box. 8. Change the Account Type to Individual. 9. Type User name into the Field 1: Display Name box. 10. Type Password into the Field 2: Display Name box. 11. Choose the Yes option for Mask under Field 2 to mask the password when it is entered. 12. Click OK. Although SSO is capable of prompting users for credentials, you can set them up ahead of time by using the administrative web pages. Because you will not know individual login infor- mation, this capability is clearly most useful when an application is defined to utilize a group CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE166 Figure 6-2. Defining an application 5750_c06_final.qxd 11/3/05 9:41 PM Page 166 login. Individual logins will generally prompt users for credentials when they first use the Web Part. We’ll see how to utilize this capability in code later on. Here is what you need to do to define login credentials: 1. Log in to SPSPortal as a member of the MSSSOAdmins group. 2. Select Start ➤ All Programs ➤ SharePoint Portal Server ➤ SharePoint Portal Server Single Sign-On Administration. 3. On the Manage Settings for Single Sign-On page, select Enterprise Application Defini- tion Settings ➤ Manage Account Information for Enterprise Application Definitions. 4. In the User Account Name box enter sps\administrator. 5. Click OK. 6. On the Account Information page, type sa into the User Name box. 7. Type the sa password into the Password box for your SPSPortal installation of SQL Server. 8. Click OK. Setting the Security Policy The Microsoft SSO service uses a SQL Server database to store application credentials, and Web Parts attempting to access this data store are subject to code access security restrictions deter- mined by the active policy. By default, WSS_Minimal and WSS_Medium do not allow access to SSO functionality. In order to grant access, you must modify the policy files or create a custom policy file. SSO uses a ticketing system for accessing credentials. Web parts can request a ticket from SSO that can subsequently be used to access credentials within the data store. Permission to access SSO is determined by the SingleSignonPermission class. This class accepts an enumer- ated value that determines the level of access the code is granted. Table 6-1 lists the possible values for the SingleSignonPermission class. Table 6-1. The SingleSignonPermission Class Permission Description Minimal The Web Part can reserve a ticket to redeem credentials later but cannot access credential information. Credentials The Web Part can redeem a ticket for credentials and access credential information. Administer The Web Part has full access to SSO for credential information and application administration. Whether you choose to modify an existing policy file or create a new one, you must make an appropriate entry in both the <SecurityClasses> and <PermissionSets> sections of the file. In the <SecurityClasses> section, you must add a reference to the SingleSignonPermission class. The following code shows the appropriate entry. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE 167 5750_c06_final.qxd 11/3/05 9:41 PM Page 167 <SecurityClass Name="SingleSignonPermission" Description= "Microsoft.SharePoint.Portal.SingleSignon.Security.SingleSignonPermission, Microsoft.SharePoint.Portal.SingleSignon.Security, Version=11.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"/> Once the entry is made to reference the SingleSignonPermission class, you must add an entry to the wss_sqltrust <PermissionSet> to grant the appropriate level of permission. As with all other permissions, you grant the access using the <IPermission> element setting Minimal, Credentials, or Administer as the value. Additionally, the specific permission grant must appear within the permission set for wss_sqltrust. As always, remember to restart Internet Information Server (IIS) once your policy changes are complete. The following code shows the entry for granting access to SSO within the wss_sqltrust permission set that you created in Chapter 5 under Listing 5-6. <PermissionSet class="NamedPermissionSet" version="1" Name="wss_sqltrust"> <IPermission class="SingleSignonPermission" version="1" Access="Credentials" /> Using SSO in a Web Part Once the service is running and the policy is established, you are ready to create a Web Part. In order to use the Microsoft SSO service in a Web Part, you must first set a reference to the SingleSignOn assembly in Visual Studio. After starting a new Web Part project, set a reference to the Microsoft.SharePoint.Portal.SingleSignon.dll assembly. Once this reference is set, you can import the library into your code by using one of the following formats for C# or VB .NET. //C# using Microsoft.SharePoint.Portal.SingleSignon; 'VB .NET Imports Microsoft.SharePoint.Portal.SingleSignon The Microsoft.SharePoint.Portal.SingleSignon namespace provides several classes that provide complete access to all of the administration functions of SSO. You can use these classes not only to access enterprise systems, but also to create your own separate adminis- tration interface. You can even go so far as to build a Web Part that allows portal users to perform self-service on their own credentials. Table 6-2 summarizes the classes available in the SingleSignon namespace. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE168 5750_c06_final.qxd 11/3/05 9:41 PM Page 168 Table 6-2. Classes in the SingleSignon Namespace Class Description Application Retrieves, adds, and deletes application definitions Credentials Retrieves, adds, and deletes application credentials SSOReturnCodes Enumerates the results of a SingleSignonException SingleSignonException Thrown when an SSO error occurs Access to the entire set of stored credentials managed by SSO is accomplished through the Credentials class. Using this class, you can store, retrieve, and delete credentials for any applica- tion stored in the configuration database. Table 6-3 lists the members of the Credentials class. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE 169 Table 6-3. The Credentials Class Member Description DeleteAllUserCredentials(String Account) Deletes all the credentials for a user or group Account for every application definition. DeleteUserCredentials(String Application, Deletes the credentials for a user or group Account for a String Account) specific Application definition. GetCredentials(UInt32 Flag, String Returns a reference to an array of Credentials given an Application, String[ ] Credentials) Application name. If the Flag is set to 0, then the cache is checked for the credentials before the database is accessed directly. If the Flag is set to 1, then the cache is not checked. GetCredentialsUsingTicket(UInt32 Flag, Returns a reference to an array of Credentials given an String Application, String Ticket, Application name and an access Ticket. If the Flag is set String[ ] Credentials) to 0, then the ADO.NET data cache is checked for the credentials before the database is accessed directly. If the Flag is set to 1, then the cache is not checked. ReserveCredentialTicket(SingleSignOn➥ Returns an access Ticket that may be used by a member TicketType.Default, String Ticket) of the SSO administrator account to access credentials. SetCredentials(UInt32 Flag, String Sets the Credentials for a specific Application for the Application, String [ ] Credentials) current user. SetGroupCredentials(String Application, Sets the Credentials for a specific Application for the String Group, String[ ] Credentials) specified Group. SetUserCredentials(String Application, Sets the Credentials for a specific Application for the String Account, String[ ] Credentials) specified Account. When a Web Part needs to access an external system, it calls the GetCredentials method. Any user is allowed to call GetCredentials; however, the active security policy determines the level of access allowed. If the credentials exist in the data store, then they are returned as an array of Strings. The order of the data returned in the array is the same as the order in which the application fields were defined by the administrator. The following code shows the basic technique using VB .NET. Dim Username As String Dim Password As String Dim strCredentials() As String Dim uintFlag As New UInt32 5750_c06_final.qxd 11/3/05 9:41 PM Page 169 Credentials.GetCredentials(UInt32.Parse("1"), "AppName", strCredentials) Username = strCredentials(0) Password = strCredentials(1) If the Web Part attempts to retrieve credentials and fails, then the GetCredentials method throws a SingleSignonException. The exact reason for the failure is subsequently determined by examining the LastErrorCode property of the SingleSignonException object. Table 6-4 lists the possible return values for the LastErrorCode property. Table 6-4. Single Sign-On Return Codes Name Description SSO_E_ACCESSDENIED Access is denied to the SSO resource. SSO_E_ALREADY_SS The computer is already set up as a secret server. SSO_E_APPLICATION_ALREADY_EXISTS The Enterprise Application Definition already exists. SSO_E_APPLICATION_CANNOT_OVERWRITE The operation is unable to overwrite the Enterprise Application Definition. SSO_E_APPLICATION_CREATION_➥ Disposition is unknown. DISPOSITION_UNKNOWN SSO_E_APPLICATION_NOT_FOUND The Enterprise Application Definition cannot be found. SSO_E_APPLICATION_TYPE_UNKNOWN The Enterprise Application Definition type is unknown. SSO_E_CREDS_NOT_FOUND The credentials could not be found. SSO_E_DB_ALREADY_EXISTS The database specified already exists. SSO_E_EXCEPTION This is a general SSO exception. SSO_E_GET_CREDS_FLAG_UNKNOWN The GetCredentials flag is unknown. SSO_E_INVALID_AUDIT_PURGE_DAYS The purge audit days specified are invalid. SSO_E_INVALID_NUMBER_OF_CRED_FIELDS The number of credential fields specified is invalid. SSO_E_INVALID_NUMBER_OF_CREDS The number of credentials is invalid. SSO_E_INVALID_TICKET_TIMEOUT The access token time-out specified is invalid. SSO_E_MASTER_SECRET_NOT_EXIST The encryption key does not exist. SSO_E_REENCRYPTING SSO is re-encrypting the SSO database. SSO_E_SECRET_ALREADY_EXISTS The base system key already exists. SSO_E_SET_CREDS_FLAG_UNKNOWN The SetCredentials flag is unknown. SSO_E_SHAREPOINT_VROOT_CANNOT_➥ The virtual root for SPS could not be found. BE_FOUND SSO_E_SSO_DB_NOT_INSTALLED The SSO database does not exist. SSO_E_SSO_NOT_CONFIGURED SSO is not configured. SSO_E_SSO_NOT_INSTALLED The SSO service is not installed. SSO_E_SSO_WRONG_VERSION The wrong SSO database version is being used. SSO_E_TICKET_TYPE_UNKNOWN The access token type is unknown. SSO_E_WRONG_SS This is the wrong secret server. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE170 5750_c06_final.qxd 11/3/05 9:41 PM Page 170 [...]... information such as the identity of the user who performed the action and the application that was accessed You can find the audit log defined under the SSO database in the SSO_Audit table Figure 6-3 shows a sample log 175 5750_c06_final.qxd 176 11/3/05 9:41 PM Page 176 CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE Figure 6-3 A sample audit log Exercise 6-1: Using Single Sign-On The Microsoft SSO service is... and store the credentials for the definition Follow these steps to create the application definition: 1 Log in to SPSPortal as a member of MSSSOAdmins 2 Select Start ➤ All Programs ➤ SharePoint Portal Server ➤ SharePoint Portal Server Single Sign-On Administration 5750_c06_final.qxd 11/3/05 9:41 PM Page 177 CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE 3 On the Manage Settings for Single Sign-On. .. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE 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... namespace Therefore, you will have to set a reference to the Microsoft. SharePoint Portal.dll assembly before you can use the class Additionally, you will want to import the namespace into your code using one of the following examples 171 5750_c06_final.qxd 172 11/3/05 9:41 PM Page 172 CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE //C# using Microsoft. SharePoint.Portal; 'VB.NET Imports Microsoft. SharePoint.Portal... method will fail if the current user has no credentials in the SSO database Talk about a catch-22! The workaround is to first define dummy credentials for each user and then delete them This will associate the user with an application definition while ensuring that the SSO_E_CREDS_NOT_FOUND exception occurs when the Web Part is first accessed The SingleSignonLocator class belongs to the Microsoft. SharePoint.Portal... web page where the user can enter their credentials if they are not found Users access the logon form provided by the SSO by clicking a hyperlink that you build in code The hyperlink is generated by the SingleSignonLocator class This class supports the GetCredentialEntryUrl method, which takes the application name as an argument The following code shows how to build a simple hyperlink in the RenderWebPart... 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 Perform these steps to set the appropriate references: 1 In Visual Studio, select Project ➤ Add Reference from the menu 2 In the Add Reference dialog, click Microsoft. SharePoint.Portal.SingleSignon.dll and System.Data.dll 3 Click Select and then... credentials." Catch x As SingleSignonException lblMessage.Text = x.Message Catch y As Exception lblMessage.Text = y.Message End Try Viewing the Audit Log Every action performed against the Microsoft SSO service is logged in the data store associated with the service Each action is logged with a member of the ServiceAction enumeration This enumeration identifies the operation that was attempted The log also captures... 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 Perform these steps to compile the Web Part: 1 Right-click the MSSSOAudit... Properties from the pop-up menu 2 In the Property Pages dialog, select Configuration Properties ➤ Build 183 5750_c06_final.qxd 184 11/3/05 9:41 PM Page 184 CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE 3 Set the Output Path property to \inetpub\wwwroot\bin 4 Click OK 5 Compile the Web Part by selecting Build ➤ Build MSSSOAudit Modifying the web.config File For the Web Part to successfully access the SQL . Tools ➤ Services. 10. In the Services dialog, right-click the Microsoft Single Sign-On Service and select Properties from the pop-up menu. 11. On the Log. self -service on their own credentials. Table 6-2 summarizes the classes available in the SingleSignon namespace. CHAPTER 6 ■ THE MICROSOFT SINGLE SIGN-ON SERVICE1 68