The Microsoft Single Sign-On Service

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 Settingssections.. Selecting

The Microsoft Single

Sign-On Service

In 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 simplymanaging 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 dows login credentials Once SSO is implemented, information workers only have to remember

Win-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 towork 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 thatwill 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

C H A P T E R 6

■ ■ ■

• Belong to the local administrators group on the job server.

• Belong to the local administrators group on the server running the configurationdatabase

• Belong to the STS_WPG and SPS_WPG groups—which run all of the pooled SharePointcomponents 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 SSOdatabase is located

Once you have defined a security group with an account, you can configure the SSO ice to run under the specified account Additionally, you can add users to the security group

serv-so that they can define credentials in the data store Designated users may then define sets ofapplications 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 andselect 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

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

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 andopen the Groups folder

4. In the Groups folder, right-click Administrators and select Add to Group from thepop-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-upmenu

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

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

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 selectProperties 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 forthe credentials Application definitions consist of a unique name for the application and thedefinition of the logon fields to accept SSO is capable of managing a number of fields beyonduser 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 Whenyou first access the administration pages, only one option is available You must complete thesetup of the MSSSO service by clicking the Manage Server Settings link The server settingsrequire you to specify the accounts that will be used to manage the SSO service and definenew 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

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

5. Click OK

Once the initial settings are entered, you may return to the Manage Settings for SingleSign-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 WebParts 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 individuallogin 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

Figure 6-1.The Manage Server Settings page

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 ServerSingle Sign-On Administration

3. On the Manage Settings for Single Sign-On page, select Enterprise Application tion Settings ➤Manage Settings for Enterprise Application Definitions

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

Figure 6-2.Defining an application

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 ServerSingle Sign-On Administration

3. On the Manage Settings for Single Sign-On page, select Enterprise Application tion Settings ➤Manage Account Information for Enterprise Application Definitions

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

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

in the SingleSignon namespace

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

Table 6-3.The Credentials Class

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

GetCredentials(UInt32 Flag, String Returns a reference to an array of Credentials given an Application, String[ ] Credentials) Applicationname If the Flag is set to 0, then the cache is

checked for the credentials before the database is accesseddirectly 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, Applicationname 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 theFlagis 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

Credentials.GetCredentials(UInt32.Parse("1"), "AppName", strCredentials)

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

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

Your Web Part should treat the SSO resource exactly as it would any protected resourcelimited by code access security policies This means that you should always implement error

handling when attempting to access the data store In most cases, you will be attempting to

retrieve credentials and should be concerned that the credentials do not exist This situation

can happen frequently with application definitions that contain an individual login In fact,

it is almost guaranteed to happen the first time a user invokes a Web Part that accesses a new

application definition

Because an administrator will not know individual credentials, your Web Part should expect

to handle SSO_E_CREDS_NOT_FOUND the first time any user accesses your Web Part In response, you

must help the user enter the correct credentials into the data store for future use SSO supports

the user by providing a 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

GetCredentialEntryUrlmethod, which takes the application name as an argument The

fol-lowing code shows how to build a simple hyperlink in the RenderWebPart method to redirect

users to the logon form

Try

Catch x As SingleSignonException

'If we cannot get the credentials, then show a link to log in

If x.LastErrorCode = SSOReturnCodes.SSO_E_CREDS_NOT_FOUND Then'Get the URL to save SSO credentials

Dim strURL As StringstrURL = SingleSignonLocator.GetCredentialEntryUrl("MyApp")'Display a link

output.Write("<a href=""" + strURL + """>Please log in</a>")End If

End Try

■ Caution The GetCredentialEntryUrlmethod 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_FOUNDexception occurs when the Web Part is first accessed

The SingleSignonLocator class belongs to the Microsoft.SharePoint.Portal 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

cre-to manage all of their credentials directly from the portal.

The Application class is the primary class used to administer SSO This class has a ber of subclasses that form collections of information contained in the data store Table 6-5lists the subclasses of the Application class

num-Table 6-5.Subclasses of the Application Class

Class Description

ApplicationCollection A collection of all Enterprise Application Definitions

ApplicationInfo A single application definition from a collection of definitionsApplicationFieldCollection A collection of all fields defined in an application

ApplicationField A single field from a collection of fields

When creating any administrative tool for credentials, you will most likely want to begin

by listing the available application definitions Using the ApplicationCollection class, you cangain access to the entire collection of application definitions and display them You canaccess the collection by simply creating the ApplicationCollection object You can thenenumerate the collection to retrieve the definitions Listing 6-1 shows how to access thecollection and display the results in a list box

Listing 6-1.Listing Application Definitions

Try

'Get collection of all application definitionsDim objCollection As New Application.ApplicationCollectionDim objApp As Application.ApplicationInfo

For Each objApp In objCollection'List only the individual applications, not group apps

If objApp.Type = Application.ApplicationType.Individual Then

'Create the new listingDim objItem As New ListItemWith objItem

.Text = objApp.ApplicationFriendlyName.Value = objApp.ApplicationNameEnd With

'Add the new listinglstApps.Items.Add(objItem)End If

NextCatch x As SingleSignonException

lblMessage.Text = x.MessageCatch y As Exception

lblMessage.Text = y.MessageEnd Try

After the available applications are listed, users will want to select an application andenter their credentials The ApplicationFieldCollection class provides access to all of the

fields that are defined for an application Using this class, you can label a set of text boxes with

the required fields for entry Because each application definition is limited to a maximum of

five fields, creating a display where users can enter information is relatively easy to handle

Listing 6-2 shows an example of configuring five TextBox and Label controls to display the

field names and a place for the user to type the credentials

Listing 6-2.Displaying Field Information

Try

'Get the collection of fieldsDim objFields As New _Application.ApplicationFieldCollection(lstApps.SelectedValue)

Dim objField As Application.ApplicationFieldDim i As Integer = 0

'Show fieldsFor Each objField In objFields

i += 1Select Case iCase 1Text1.Visible = True

If objField.Mask = True ThenText1.TextMode = TextBoxMode.PasswordElse

Text1.TextMode = TextBoxMode.SingleLineEnd If