The Microsoft Single Sign-On Service

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