Single Sign-On in SharePoint Portal Server 2003

Archived content. No warranty is made as to technical accuracy. Content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Published: June 9, 2004

This is a sample chapter from the Microsoft SharePoint Products and Technologies Resource Kit. You can obtain the complete resource kit (ISBN 0-7356-1881-X), which includes a companion CD-ROM, from Microsoft Press.

Single sign-on is a new feature in Microsoft Office SharePoint Portal Server 2003 that provides storage and mapping of credentials such as account names and passwords so that the portal site–based applications can retrieve information from the third-party applications and back-end systems, for example, Enterprise Resource Planning (ERP) and Customer Relations Management (CRM) systems. The single sign-on functionality is implemented by the Microsoft Single Sign-On (SSOSrv) service. SSOSrv is a credential storage service that allows the saving and retrieval of credentials. The use of single sign-on functionality stops users from having to authenticate themselves more than once when the portal site–based applications need to obtain information from other business applications and systems.

In a single sign-on environment, these back-end applications and systems are referred to as enterprise applications. To enable customers to interact with an enterprise application directly from the portal site, SharePoint Portal Server 2003 stores and maps assigned credentials within an enterprise application definition. By using application definitions, you can automate, and secure the sign-on process to the corresponding enterprise applications from a portal site–based application.

The single sign-on functionality enables scenarios where multiple Web Parts access different enterprise applications, which each use a different type of authentication. Each Web Part can automatically sign on to its enterprise application without prompting the user to provide credentials each time. There are endless uses of single sign-on functionality within an enterprise environment. For example, let’s consider two different scenarios—a human resources intranet site and a business intelligence site, as follows:

  • A standard human resources (HR) portal site or page might include several Web Parts that display employee information from a back-end employee management system. This employee data is stored in a dedicated HR database system, frequently based on SAP or PeopleSoft. These HR databases do not support Microsoft Windows IDs, might not run on Windows-based operating systems and, in fact, might include proprietary logon protocols. The Web Parts on the portal site should retrieve the individual employee data without prompting for a separate logon. In this example, the individual employee does not have a separate logon to the HR system, but uses a group account that provides generic read access to the database. In other words, the employee does not know the user name and password required to log on to the system he or she is accessing.

  • An executive might use a portal site to provide a dynamic, aggregated view of relevant business information. This data is stored in two places: Siebel stores the customer relationship information, and SAP tracks accounts and payments. To see an integrated view, the portal must log on to and access both back-end systems. Prompting the user for additional passwords is an unacceptable user experience. In this example, the executive does not need to know the user names and the passwords required for logon to the back-end systems. In addition, multiple Web Parts are used to ensure this integration. By default, each Web Part separately authenticates the user to the appropriate back-end system.

As these examples show, by using single sign-on you can centralize information from multiple back-end applications through a single portal that uses application definitions. In addition, SharePoint Portal Server 2003 provides a programming interface for developers to use and extend this feature.

On This Page

Single Sign-On Architecture
Configuring Single Sign-On
Managing Single Sign-On
Creating a Web Part That Uses Single Sign-On
Summary

Single Sign-On Architecture

For each enterprise application that SharePoint Portal Server connects to, there is a corresponding enterprise application definition configured by an administrator. This application definition is used by a Web Part to integrate with the enterprise application within a portal site. The application definition controls how credentials for a particular business application are stored and mapped. The code within the Web Part uses the application definition to retrieve credentials that are then used to integrate with an enterprise application. This process is transparent to the portal site users.

There are two primary types of enterprise application definitions used with the SSOSrv service, as follows:

Individual enterprise application definitions.

  • In this scenario, individual users know and can manage their own credentials stored within the enterprise application definition.

Group enterprise application definitions.

  • In this scenario, the individual user does not know his or her credentials stored within the enterprise application definition, but is associated with a managed group account.

The single sign-on administrator, rather than the individual user, chooses the account type when configuring the enterprise application definition.

The SSOSrv service stores encrypted credentials in a Microsoft SQL Server database. When you set up the single sign-on on the job server, you specify two settings for the single sign-on database: the name of the computer running SQL Server where the credentials store will be located, and the name of the database that will become the credentials store for your Web farm. These settings are stored in the SharePoint Portal Server configuration database.

All credentials in the credentials store are encrypted using the single sign-on encryption key. When you configure single sign-on for the first time, the encryption key is created automatically. You can regenerate the key if required and re-encrypt the credentials store; for example, you might have a policy to change the key after a certain amount of time.

How Single Sign-On Works

When individual enterprise definition is used, on the first access to the Web Part that integrates with the enterprise application, if a user’s credentials have not been stored in the single sign-on database, the user is redirected to the logon form that prompts the user for appropriate credentials for the enterprise application. The number, the order, and the names of the fields in the logon form are configured by the administrator within the application definition; the logon form is generated automatically based on these configuration settings. The developer needs to write the code within the Web Part to check whether the credentials exist in the database, and to redirect the user to the logon form if necessary. The user-supplied credentials are then stored in the credentials store and mapped to the Windows account that is this user’s account for SharePoint Portal Server. Then, the user is redirected back to the original Web Part. The code in the Web Part then submits the credentials from the credentials store to the application in the way that is relevant to this application, and retrieves the necessary information that is then presented to the user within the Web Part. This process is shown in Figure 26-1. The steps are as follows:

  1. A user accesses the Web Part that integrates with the enterprise application for the first time. The Web Part code checks whether the user credentials for the required application are stored in the single sign-on database. If they are stored, the process continues from step 6 in this list.

  2. If there are no credentials stored for this user for the required application, the user’s browser is redirected to the logon form for this application.

  3. The user supplies credentials for the application.

  4. The supplied credentials are mapped to the user’s Windows account and stored in the single sign-on database.

  5. User is redirected to the original Web Part.

  6. The Web Part retrieves the credentials from the single sign-on database.

  7. The Web Part submits the credentials to the enterprise application and retrieves the necessary information.

  8. The Web Part is displayed to the user.

On subsequent access, when the user requests the Web Part, to get the necessary data from the enterprise application the credentials are retrieved from the single sign-on database. The process is transparent to the user. (See Figure 26-1.)

Cc750137.f26xr01(en-us,TechNet.10).gif

Figure 26-1. Accessing an enterprise application using single sign-on

When group enterprise definition is used, the account mapping is configured by the administrator. The administrator specifies the credentials for accessing the enterprise applications that are valid for all members of a Windows group. If the user who accesses the Web Part belongs to the mapped Windows group, the access credentials are already stored in the single sign-on credentials store. The code in the Web Part retrieves the credentials, submits them to the enterprise application, and retrieves the necessary information. The Web Part is then displayed to the requesting user. In this scenario, the whole process is transparent to the user. The user is not aware of any authentication information required for the enterprise application; it is only known to the administrator.

Security Recommendations Regarding the Topology of the Server Farm

When using the single sign-on service, you can help enhance security by distributing your resources in the server farm. Specifically, the configuration of the front-end Web server, the job server, and the computer storing the single sign-on database can affect security.

Less secure configuration.

  • Everything is deployed on one server. This configuration is less secure because the front-end Web server, the single sign-on database stored in SQL Server, and the encryption key are on the same computer. This configuration is not recommended.

More secure configuration.

  • Two-computer configuration where one computer is the front-end Web server. The second computer is the job server containing the single sign-on database stored in SQL Server and the encryption key.

Recommended configuration for better security.

  • Configuration of three or more computers in which the front-end Web server, the job server containing the encryption key, and the server containing the single sign-on database stored in SQL Server are different computers.

If you are using single sign-on in a shared services scenario, the user credentials stored in the parent server farm are available to the administrators of all child server farms. It is recommended that you run applications using single sign-on on the parent portal site only and use an iFrame in the application for child portal sites. You should disable the single sign-on service on child server farms. We will discuss how to disable the SSOSrv service later in this chapter.

Configuring Single Sign-On

To configure single sign-on for the first time, you must complete the following tasks:

  1. Determine and set up necessary Windows accounts.

  2. Enable the single sign-on service on the job server.

  3. Configure the single sign-on settings.

  4. Create a new application definition.

  5. Provide account information for the application definition.

  6. Enable the single sign-on service on the front-end servers.

Step 1: Set Up Single Sign-On Accounts

The SSOSrv service uses the following four types of accounts:

  • Configuration account for single sign-on

  • Single sign-on administrator account

  • Single sign-on service account

  • Enterprise application manager account

Before configuring single sign-on, you must determine and, where necessary, create and set up these accounts.

Configuration Account for Single Sign-On

Configuration Account for single sign-on is the Windows account that will be used to configure the SSO. When setting up single sign-on, you use this account to log on to the job server. This account must meet the following requirements:

  • Be a member of the local Administrators group on the job server.

  • Be a member of the local Administrators group on the computer running SQL Server that stores the single sign-on database.

  • Be either the same as the single sign-on administrator account, or be a member of the group account that is the single sign-on administrator account. (The single sign-on administrator account is discussed in the next section.)

Single Sign-On Administrator Account

The single sign-on administrator account can be either the Windows Global group or the individual user account, and it will be used to set up and manage the single sign-on service. This account cannot be a local domain group account or a distribution list.

Make sure that the following requirements are met for the single sign-on administrator account:

  • The single sign-on service account must be this user or a member of this group.

  • The configuration account for single sign-on must be this user or a member of this group.

We will specify this account as the single sign-on administrator account in step 3, “Configure the Single Sign-On Settings on the Job Server.” After it has been configured, this user account or members of this group account will have full access to the single sign-on administration pages and will be able to make configuration and application definition changes.

Single Sign-On Service Account

The single sign-on service account is the user account that will run as the single sign-on service. Make sure the following requirements are met:

  • The single sign-on service account must be the same as the single sign-on administrator account or a member of the group account that is the single sign-on administrator account.

  • The single sign-on service account must be a member of the local group STS_WPG on all servers running SharePoint Portal Server 2003 in the server farm.

To make the user a member of STS_WPG, do the following:

  1. On the taskbar, click Start, point to Administrative Tools, and then click Computer Management.

  2. In the console tree, under the System Tools node, expand the Local Users and Groups node.

  3. Click Groups.

  4. Double-click STS_WPG.

  5. In the STS_WPG Properties dialog box, click Add.

  6. Add the user.

The single sign-on service account must be a member of the local group SPS_WPG on all servers running SharePoint Portal Server in the server farm.

To make the user a member of SPS_WPG, do the following:

  1. On the taskbar, click Start, point to Administrative Tools, and then click Computer Management.

  2. In the console tree, under the System Tools node, expand the Local Users and Groups node.

  3. Click Groups.

  4. Double-click SPS_WPG.

  5. In the SPS_WPG Properties dialog box, click Add.

  6. Add the user.

The single sign-on service account must be a member of the public database role on the SharePoint Portal Server configuration database.

Cc750137.note(en-us,TechNet.10).gif  On a single server deployment, if the single sign-on service runs under an account that is a member of the local Administrators group, you do not need to ensure that the user has the public right on the configuration database. However, for security reasons it is recommended that you do not run the service under an account that is a member of the local Administrators group.

To assign rights on the configuration database, do the following:

  1. On the SQL Server computer, open SQL Server Enterprise Manager.

  2. Expand the Microsoft SQL Servers node.

  3. Expand the SQL Server Group node.

  4. Expand the (local) (Windows NT) node.

  5. Expand the Security node.

  6. Click Logins, and then do one of the following:

    • If the logon name does not exist, right-click Logins, click New Login, and then in the Name box, type the account for the user in the format DOMAIN\user_name.

    • If the logon name already exists, right-click the logon name, and then click Properties.

  7. Click the Database Access tab.

  8. In the Specify which databases can be accessed by this login section, select the check box for the configuration database.

  9. In the Database roles for database_name section, select the public check box.

  10. Click OK.

  11. Close SQL Server Enterprise Manager.

The single sign-on service account must be a member of the Server Administrators server role on the SQL Server instance where the single sign-on database is located.

Cc750137.note(en-us,TechNet.10).gif  On a single server deployment, if the single sign-on service runs under an account that is a member of the local Administrators group, you do not need to ensure that the user is a member of Server Administrators server role on the SQL Server instance where the single sign-on database is located. However, for security reasons, it is recommended that you do not run the service under an account that is a member of the local Administrators group.

To make the user a member of the Server Administrator role

  1. On the SQL Server computer, open SQL Server Enterprise Manager.

  2. Expand the Microsoft SQL Servers node.

  3. Expand the SQL Server Group node.

  4. Expand the (local) (Windows NT) node.

  5. Expand the Security node.

  6. Click Logins, and then do one of the following:

    • If the logon name does not exist, right-click Logins, click New Login, and then in the Name box, type the account for the user in the format DOMAIN\user_name.

    • If the logon name already exists, right-click the logon name, and then click Properties.

  7. Click the Server Roles tab.

  8. Select the Server Administrators check box.

  9. Click OK.

  10. Close SQL Server Enterprise Manager.

Enterprise Application Manager Account

The enterprise application manager account can be the Windows Global group account, or individual user account, that will be used to set up and manage application definitions. This account cannot be a local domain group or a distribution list.

You do not need to perform any configuration steps now; we will configure this account to become the enterprise application manager account in step 3, “Configure the Single Sign-On Settings on the Job Server.” However, it is useful to notice the rights that this account will have after it has been specified as the enterprise application manager account, as follows:

  • This account or members of this group have rights to create, modify, or delete application definitions from the single sign-on administration pages.

  • This account or members of this group do not have rights to configure single sign-on. Only members of the single sign-on administrator account can configure single sign-on.

  • Rights that this user or members of this group have are automatically contained in the single sign-on administrator account.

Step 2: Enable the Single Sign-On Service on the Job Server

To enable the SSOSrv service, do the following on the job server:

  1. On the taskbar, click Start, point to Administrative Tools, and then click Services.

  2. On the Services management console, double-click Microsoft Single Sign-on Service.

  3. Click the Logon tab.

  4. Under Log on as, click This account.

  5. In the This account box, type an account name that you determined as a single sign-on service account in the previous step.

  6. In the Password and Confirm password boxes, type the password.

  7. Click Apply.

  8. Click the General tab.

  9. In the Startup type list, click Automatic.

  10. In the Service status section, if the service status does not display Started, click Start.

  11. Click OK.

Step 3: Configure the Single Sign-On Settings on the Job Server

To configure the single sign-on settings, you must be logged on as the configuration account on the job server. As we discussed earlier in step 1, “Set Up Single Sign-On Accounts,” this account must be a member of the local Administrators group on the job server, and must also be a member of the group account that you specify as the single sign-on administrator account.

You cannot configure single sign-on remotely. To configure single sign-on, go to the computer running as the job server, log on as the configuration account, and then do the following:

  1. On the SharePoint Portal Server Central Administration for server_name page, in the Component Configuration section, click Manage settings for single sign-on.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for server_name page, in the Server Settings section, click Manage server settings.

  3. On the Manage Server Settings for Single Sign-On page, in the Single Sign-On Settings section, in the Account name box, type the name of the single sign-on administrator account that you determined in step 1, “Set Up Single Sign-On Accounts.” The format of the account is DOMAIN\group_name or DOMAIN\user_name.

  4. In the Enterprise Application Definition Settings section, in the Account name box, type the name of the enterprise application manager account that you determined in step 1, “Set Up Single Sign-On Accounts.” The format of the account is DOMAIN\group_name or DOMAIN\user_name.

  5. In the Database Settings section, do the following:

    1. In the Server name box, type the name of the database server on which you want to store the settings and account information for single sign-on.

    2. In the Database name box, type the name of the single sign-on database.

      If the database does not exist, it is created.

  6. In the Time Out Settings section, do the following:

    1. In the Ticket time out (in minutes) box, type the number of minutes to wait before allowing a ticket, or access token, to time out.

    2. In the Delete audit log records older than (in days) box, type the number of days to hold records in the audit log before deleting.

  7. Click OK.

  8. If a message box appears stating that you have reconfigured single sign-on, click OK.

    Cc750137.note(en-us,TechNet.10).gif  The audit log is overwritten after the number of days you specify. Because the log contains a record of any illicit operations or logon attempts, it is recommended that you maintain backup copies of the logs. The logs reside in the single sign-on database in the SSO_Audit table. This table is automatically backed up when you back up the database.

Step 4: Create an Application Definition

To create an application definition, you need to be logged on as a member of single sign-on administrator account or as an enterprise application definition manager account. To create an application definition, do the following:

  1. On the SharePoint Portal Server Central Administration for server_name page, in the Component Configuration section, click Manage settings for single sign-on.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for server_name page, in the Enterprise Application Definition Settings section, click Manage settings for enterprise application definitions.

  3. On the Manage Enterprise Application Definitions page, click New Item.

  4. On the Create Enterprise Application Definition page, in the Application and Contact Information section, do the following:

    1. In the Display name box, type a display name for this application definition.

      When administrator changes the settings for the application definition at a later stage, the application definition is listed using its display name.

      The display name is what the user sees on the logon form when entering credentials on the first access.

      Cc750137.tip(en-us,TechNet.10).gif  If you enter a long name with no spaces in it for the display name, the entire name might not be displayed.

    2. In the Application name box, type an application name for the application definition. The application name is used by developers.

      Cc750137.tip(en-us,TechNet.10).gif  If you enter a long name with no spaces in it for the application definition name, the entire name might not be displayed.

    3. In the Contact e-mail address box, type an e-mail address for users to contact for this application.

  5. In the Account Type section, do one of the following:

    • If you want all users to log on by using a single account, select Group.

      Users do not need to enter any credentials with this option.

    • If you want users to log on by using their own account information, select Individual.

      Each user will have to provide credentials when accessing the Web Part for the first time.

      Cc750137.tip(en-us,TechNet.10).gif  If you specify a group account as the account type, so that all users log on by using a single account, ensure that you have the appropriate number of client licenses for the application that you are accessing.

  6. In the Logon Account Information section, select one or more fields to map to the required logon information in the necessary order for this enterprise application. The number and the order of the fields are defined by the enterprise application logon requirements. For each field, do the following:

    1. Type a display name for each field as a reminder of the required information. For an individual user application definition, the display name is what the users see on the logon form when entering their credentials for the enterprise application. For a group application definition, the display name of the field is what the administrator sees when entering the mapped group account credentials for the enterprise application.

    2. If the field contains sensitive information, such as a password, click Yes for Mask so that the information is not displayed within this field when it is being filled in or viewed.

      For example, for access to Oracle, you might enter the following:

      Field 1 = Oracle user name

      Field 2 = Oracle user password (select Yes for the Mask option)

      Field 3 = Oracle database name

      If you need to access the SAP application, for SAP credentials you might enter the following:

      Field 1 = SAP user name

      Field 2 = SAP password (select Yes for the Mask option)

      Field 3 = SAP system number

      Field 4 = SAP client number

      Field 5 = language

  7. Click OK.

Step 5: Provide Account Information for an Application Definition

After you have created the application definition, for group application definition you have to specify the logon account credentials. For individual application definitions, you can specify credentials for the users or, alternatively, the users may enter their credentials in the logon form on the first access.

To specify the logon account information for the application definition, do the following:

  1. On the SharePoint Portal Server Central Administration for server_name page, in the Component Configuration section, click Manage settings for single sign-on.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for server_name page, in the Enterprise Application Definition Settings section, click Manage account information for enterprise application definitions.

  3. On the Manage Account Information for an Enterprise Application Definition page, in the Account Information section, do the following:

    1. In the Enterprise Application Definition list, select the name of the application definition. If you created the application definition to use an individual account, the user account name box is displayed on the page. If you created the application definition to use a group account, the group account name box is displayed.

    2. In the User account name or Group account name box, type the account name that will be mapped to the application credentials.

    3. Click OK.

  4. On the Provide application_definition_display_name Account Information page, in the Logon Information section, enter the credentials to be used for the logon to the enterprise application. The number, the order and the names of the fields displayed follow configuration in the Logon Account Information section of the application definition.

Step 6: Enable the Single Sign-On Service on the Front-End Web Servers

After you have configured the single sign-on settings on the job server, you need to enable the single sign-on service of the front-end Web servers. To enable the single sign-on service on each front-end Web server, follow the instructions given earlier in step 2, “Enable the Single Sign-On Service on the Job Server.”

Managing Single Sign-On

After you have configured the single sign-on for the first time, you are likely to need to perform administration tasks at a later stage, including the following:

  • Creating and deleting the application definitions

  • Managing account credentials mapped within the application definitions

  • Regenerating, backing up, and restoring the encryption key

  • Enabling auditing of the encryption key

  • Disabling the SSOSrv service

In this section, we will discuss the single sign-on administration tasks. If you need to change your single sign-on configuration, make sure you consider the following:

  • The single sign-on configuration and encryption key management tasks cannot be done remotely. To configure single sign-on or manage the encryption key, go to the computer running as the job server and specify the settings locally.

  • If you change the job server to another server, you must reconfigure single sign-on. After changing the job server, you must delete the entire registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ssosrv\Config on the old job server.

  • If you reconfigure single sign-on and you want to change the account that you specified for managing the single sign-on service (the single sign-on administrator account), the user who reconfigures the single sign-on and the single sign-on service account must be a member of both the current single sign-on administrator account that manages the service and the new account that you want to specify.

Editing an Application Definition

You can edit the display name, the e-mail contact, and the logon fields for an enterprise application definition. You cannot edit the application definition name or change the account type.

To edit an application definition, do the following:

  1. On the SharePoint Portal Server Central Administration for server_name page, in the Component Configuration section, click Configure the Single Sign-on component and manage enterprise application definitions for portals.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for server_name page, in the Application Settings section, click Manage settings for enterprise application definitions.

  3. On the Manage Enterprise Application Definitions page, rest the pointer on the display name for the application definition, and then click the arrow that appears.

  4. On the menu that appears, click Edit.

  5. On the Edit Enterprise Application Definition page, in the Application and Contact Information section, you can edit the display name and the e-mail contact.

  6. In the Display Name box, type a display name for this application definition. The display name is what the user sees.

  7. In the E-mail Contact box, type an e-mail address for users to contact for this application.

  8. In the Account Information section, select one or more fields to map to the required logon information for this application definition.

  9. Type a display name for each field as a reminder of the required information. The display names for the fields will appear on the logon page for the application.

  10. To ensure that sensitive information, such as a password, is not displayed when viewing account information, click Yes for Mask?

  11. Click OK.

Deleting an Application Definition

When you delete an application definition, it is removed from the single sign-on database. In addition, all credentials associated with the application definition are removed. To delete an application definition, do the following:

  1. On the SharePoint Portal Server Central Administration for server_name page, in the Component Configuration section, click Configure the Single Sign-on component and manage enterprise application definitions for portals.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for server_name page, in the Application Settings section, click Manage settings for enterprise application definitions.

  3. On the Manage Enterprise Application Definitions page, rest the pointer on the display name for the application definition, and then click the arrow that appears.

  4. On the menu that appears, click Delete.

  5. On the confirmation message box, click OK.

Managing Account Information for an Application Definition

You can update or delete individual account information for a single application definition, or you can remove an account from all application definitions.

For group application definitions, you can update the account information, but you cannot remove the Windows account from a group application definition because there is a one-to-one correspondence between a group application definition and the account. If necessary, you can delete the group application definition.

To manage account information for an application definition, do the following:

  1. On the SharePoint Portal Server Central Administration for server_name page, in the Component Configuration section, click Manage settings for single sign-on.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for server_name page, in the Enterprise Application Definition Settings section, click Manage account information for enterprise application definitions.

  3. On the Manage Account Information for an Enterprise Application Definition page, in the Account Information section, do the following:

    1. In the Enterprise Application Definition list, select the name of the application definition.

    2. If you created the application definition to use an individual account, the User account name box appears. If you created the application definition to use a group account, the Group account name box appears. In the User account name or Group account name box, type the account name to modify.

  4. In the Enterprise Application Definition section, you can perform one of the three operations: update the account information for the application corresponding to this application definition, delete the stored credentials for this account for this application, and delete the stored credentials for this account from all application definitions.

    Cc750137.note(en-us,TechNet.10).gif  For individual application definitions, all three options are available. For group application definitions only the update option is available; both delete options are grayed out.

To update the account information for this application, do the following:

  1. Click Update account information.

  2. Click OK.

  3. On the Provide application_definition_display_name Account Information page, in the Logon Information section, enter the credentials to be used for the logon to the enterprise application. The number, the order, and the names of the fields displayed follow configuration in the Logon Account Information section of the application definition.

  4. Click OK.

To delete the stored credentials for this user account from this application definition, do the following:

  1. Click Delete stored credentials for this account from this enterprise application definition.

  2. Click OK.

  3. To delete the user credentials, click OK on the confirmation message box.

To remove this user account credentials from all application definitions, do the following:

  1. Click Delete stored credentials for this account from all enterprise application definitions.

  2. Click OK.

  3. To delete the user credentials from all application definitions, click OK on the confirmation message box.

Creating the Encryption Key

The encryption key is used as part of the encryption process for credentials used with single sign-on. The key helps to decrypt encrypted credentials stored in the single sign-on database. The first time you configure single sign-on and enterprise application definitions on the Manage Server Settings for Single Sign-On page, the encryption key is created automatically. You can regenerate the key if the previous credentials are compromised or if you have a policy to change the key after a certain number of days.

When you create an encryption key, you can choose to re-encrypt the existing credentials with the new key. When you re-encrypt the SSOSrv service credential store, events are logged in the Microsoft Windows Server 2003 application event log. Once re-encryption is initiated, you can monitor the application event log to verify that the credential store has been re-encrypted. Event ID 1032 is recorded in the application event log when re-encryption is started. Event ID 1033 is recorded in the application event log when re-encryption has ended. If there are any failures during re-encryption, an event is recorded in the log.

If the job server is restarted or SSOSrv is stopped on the job server during the re-encryption process, you should look in the event log for errors. If the event log reports an error, you must restart the re-encryption process from the Manage Encryption Key page.

Cc750137.note(en-us,TechNet.10).gif  If the re-encryption process is preempted in any way, it will have to be re-run. If the re-encryption process is preempted, it reverts back to its original state

The re-encryption process is a long-running operation. It is recommended that you change or restore the encryption key during non-peak periods.

During the re-encryption process, Write operations such as updating credentials and changing application definitions are not allowed. Read operations such as retrieving credentials continue to work as normal.

Cc750137.note(en-us,TechNet.10).gif  To re-encrypt the existing credentials, the single sign-on service account must be a member of the Server Administrators server role on the SQL Server instance where the single sign-on database is located. For other requirements for single sign-on service account, refer to the section “Single Sign-On Service Account” earlier in this chapter.

You cannot create the encryption key remotely. To re-generate the encryption key, go to the computer running as the job server, log on as the single sign-on administrator account, and do the following:

  1. On the SharePoint Portal Server Central Administration for server_name page, in the Component Configuration section, click Manage settings for single sign-on.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for server_name page, in the Server Settings section, click Manage encryption key.

  3. On the Manage Encryption Key page, in the Encryption Key Creation section, click Create Encryption Key.

  4. On the Create Encryption Key page, to re-encrypt the credentials for the single sign-on database, select the Re-encrypt all credentials by using the new encryption key check box, and then click OK.

    Cc750137.note(en-us,TechNet.10).gif  If you do not re-encrypt the existing credentials with the new encryption key, users must retype their credentials for individual application definitions, and administrators for group application definitions must retype group credentials.

Backing Up the Encryption Key

After creating the encryption key, you should back it up. You must back up the key to a 3.5-inch floppy disk. You should lock up the backup disk for the encryption key in a safe place.

Cc750137.note(en-us,TechNet.10).gif  Because the encryption key is the key that decrypts the encrypted credentials stored in the single sign-on database, the backup copy of the key should not be stored with the backup copy of the database. If a user obtains a copy of both the database and the key, the credentials stored in the database could be compromised.

You cannot back up the encryption key remotely. To back up the encryption key, go to the computer running as the job server, log on as the single sign-on administrator account, and do the following:

  1. On the SharePoint Portal Server Central Administration for server_name page, in the Component Configuration section, click Manage settings for single sign-on.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for server_name page, in the Server Settings section, click Manage encryption key.

  3. Insert a 3.5-inch disk into a disk drive on the computer running as the job server.

  4. On the Manage Encryption Key page, in the Encryption Key Backup section, in the Drive list, click the letter of the disk drive, and then click Back Up to back up the encryption key.

  5. In the completion message box that appears, click OK.

  6. Remove the 3.5-inch disk from the disk drive.

Restoring the Encryption Key

You cannot restore the encryption key remotely. To restore the encryption key, go to the computer running as the job server, log on as the single sign-on administrator account, and do the following:

  1. On the SharePoint Portal Server Central Administration for Server server_name page, in the Component Configuration section, click Manage settings for single sign-on.

    Alternatively, click Start, point to All Programs, point to SharePoint Portal Server, and then click SharePoint Portal Server Single Sign-On Administration.

  2. On the Manage Settings for Single Sign-On for Server server_name page, in the Server Settings section, click Manage encryption key.

  3. Insert a 3.5-inch disk into a disk drive on the computer running as the job server.

  4. On the Manage Encryption Key page, in the Encryption Key Restore section, in the Drive list, click the letter of the disk drive, and then click Restore to restore the encryption key.

  5. Click OK.

    When the restore completes, the Manage Settings for Single Sign-On for Server server_name page appears.

  6. Remove the 3.5-inch disk from the disk drive.

    Cc750137.note(en-us,TechNet.10).gif  Restoring the encryption key and re-encrypting the single sign-on credentials store with the restored key is a long-running process. It is recommended that you restore the encryption key during non-peak periods.

Enabling Auditing for the Encryption Key

You should enable auditing for the encryption key. Then, if the key is read or written to, there will be an audit trail in the security log in Microsoft Windows Server 2003 Event Viewer.

To enable auditing for the encryption key, you need to modify the registry using regedit and then enable auditing using Group Policy Object Editor.

  1. To modify the registry, do the following:

    1. On the taskbar, click Start, and then click Run.

    2. Type regedit and then click OK.

    3. In Registry Editor, navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ssosrv\Config.

    4. Right-click Config, and then click Permissions.

    5. In the Permissions for Config dialog box, click Advanced.

    6. In the Advanced Security Settings for Config dialog box, click the Auditing tab, and then click Add.

    7. In the Select User, Computer, or Group dialog box, in the Enter the object name to select box, type everyone.

    8. Click OK.

    9. In the Auditing Entry for Config dialog box, in the Failed column, select the Full Control check box, and then click OK.

    10. Click OK, and then click OK again to close all dialog boxes.

    11. Close Registry Editor.

To enable auditing, do the following:

  1. On the taskbar, click Start, and then click Run.

  2. Type mmc and then click OK.

  3. In the console, on the File menu, click Add/Remove Snap-in.

  4. In the Add/Remove Snap-in dialog box, on the Standalone tab, click Add.

  5. In the Add Standalone Snap-in dialog box, in the Available Standalone Snap-ins list, click Group Policy Object Editor, and then click Add.

  6. In the Select Group Policy Object dialog box, ensure that Local Computer appears in the Group Policy Object box, and then click Finish.

  7. In the Add Standalone Snap-in dialog box, click Close.

  8. In the Add/Remove Snap-in dialog box, click OK.

  9. Expand the following nodes:

    • Local Computer Policy

    • Computer Configuration

    • Windows Settings

    • Security Settings

    • Local Policies

    • Audit Policy

  10. In the details pane, double-click Audit object access.

  11. In the Audit object access Properties dialog box, select the Failure check box, and then click OK.

    You can verify that auditing is working by doing the following:

    1. Log off.

    2. Log on as a user who should not have access to the registry key.

    3. Try to read the registry key.

    4. Look in the security log in Windows Server 2003 Event Viewer for audit entries.

Disabling the Single Sign-On Service

To disable the single sign-on service on the server farm, you must disable it on each front-end Web server, on the job server, and on any server running the single sign-on service.

If you want to delete all credentials associated with application definitions, you must delete each enterprise application definition.

To disable the single sign-on service, do the following on each front-end Web server, job server, and any server running the single sign-on service:

  1. On the taskbar, click Start, point to Administrative Tools, and then click Services.

  2. On the Services management console, double-click Microsoft Single Sign-on Service.

  3. On the General tab, in the Startup type list, click Manual.

  4. In the Service status section, click Stop.

  5. Click OK.

Creating a Web Part That Uses Single Sign-On

After you have configured the single sign-on and created the application definitions, you need to develop a Web Part that implements the single sign-on functionality and retrieves information from the corresponding back-end application programmatically.

SharePoint Portal Server 2003 provides a programming interface for developers to use and extend the single sign-on feature. There are two namespaces provided solely for interaction with the single sign-on functionality, as well as one class in a more generic Microsoft.SharePoint.Portal namespace, as follows:

  • The Microsoft.SharePoint.Portal.SingleSignOn namespace contains core classes that allow you to work with account credentials and application definitions in the single sign-on credentials store. These core classes and their functionality are listed in Table 26-1. The required assembly is Microsoft.SharePoint.Portal.SingleSignon, located in Microsoft.SharePoint.Portal.SingleSignon.dll.

  • The Microsoft.SharePoint.Portal.SingleSignOn.Security namespace contains two classes that control the ability to access Single Sign-On resources programmatically from the code. These two classes and their functionality are listed in Table 26-2. The required assembly is Microsoft.SharePoint.Portal.SingleSignOn.Security, located in Microsoft.SharePoint.Portal.SingleSignOn.Security.dll.

  • The SingleSignonLocator class in the Microsoft.SharePoint.Portal namespace allows you to locate a URL for the logon form for the SSOSrv service. It has the GetCredentialEntryUrl(strAppName, [port]) method that returns the URL for the logon form for a given application definition. The method takes two parameters: strAppName, which is a name of an application that is configured in the corresponding application definition, and the optional port number for SSL. If you do not specify the port number, and SSL is not enabled on the server, the port number will default to port 80 (that is, the port value will be omitted from the URL). If the second parameter is absent and SSL is enabled on the server, the port number is assumed to be the standard SSL port 443. However, if you require the URL returned to be formatted for SSL on a particular port, you need to specify it. For example, you would pass the specified port when the system cannot detect which SSL port to use, such as when multiple SSL port mappings exist. The required assembly for this class is Microsoft.SharePoint.Portal, located in Microsoft.SharePoint.Portal.dll.

    Table 26-1. Microsoft.SharePoint.Portal.SingleSignOn Namespace Core Classes

    Class

    Description

    Application

    Exposes functionality to add, get, and delete enterprise application definitions

    Credentials

    Exposes functionality to manage user and group credentials and access tokens

    SSOReturnCodes

    Contains all the return codes for SSOSrv service that the SingleSignonException class will throw

    SingleSignonException

    Instantiates an exception from the SSOSrv ser vice with a specific error code

    Table 26-2. Microsoft.SharePoint.Portal.SingleSignOn Security Namespace Classes

    Class

    Description

    SingleSignOnPermission

    Allows security actions for SingleSignOnPer mission to be applied to code using declarative security.

    SingleSignOnPermissionAt tribute

    Represents a custom permission that controls the ability to access Microsoft SharePoint Products and Technologies resources to manage user and group credentials and access tokens.

For example, let’s look into a code in the Web Part that retrieves the account credentials for a back-end enterprise application from the single sign-on credentials database. The corresponding application definition is configured to use individual accounts. The code checks whether a requesting user’s credentials have already been stored in the single sign-on credential database. If not, the user is redirected to the Single Sign-On logon form to enter the required credentials for accessing the back-end application.

The code should implement the following sequence:

  1. Call the GetCredentials method of the Credentials class. Specify the application name for which the credentials need to be retrieved from the single sign-on database.

  2. If the SSOSrv service cannot find credentials for the user for the enterprise application specified, the GetCredentials method throws a SingleSignonException. If the LastErrorCode property of the SingleSignonException is SSO_E_CREDS_NOT_FOUND, call the GetCredentialEntryUrl(String) method—or the GetCredentialEntryUrl(String, Int) method—of the SingleSignonLocator class to build the URL to the single sign-on logon form.

  3. After the URL for the logon form has been retrieved, redirect the browser to this URL. The logon form is created by the SSOSrv service. It prompts the user to enter credentials for the enterprise application in a number of fields. The order, the number and the display names for these fields are configured within the application definition under Logon Account Information. For example, if the enterprise application uses user name and password for authentication, two fields will be present in the logon form. For SAP, you may need five fields. After the SSOSrv service saves the credentials, the form redirects control back to the original Web Part.

The code in your Web Part will be similar to the following example that shows how to redirect the user to the logon form to save credentials for an enterprise application called SampleApp:

protected override void RenderWebPart(HtmlTextWriter writer) //RenderWebPart
{
  string[] rgGetCredentialData = null;
  try
  {
  //Try to get the credentials for this application.
  //Before running this code, make sure that an individual
  //application definition for application called "SampleApp"
  //has been added.
    Credentials.GetCredentials(1,"SampleAPP", ref rgGetCredentialData);
  }
  catch (SingleSignonException ssoe)
  {
  //This exception will be thrown if this user does not have
  //credentials for the "SampleApp" application.
    if(SSOReturnCodes.SSO_E_CREDS_NOT_FOUND == ssoe.LastErrorCode)
      {
      //Send the user to the single sign-on logon form.  
      //The logon form will:
      //- Prompt the user for credentials for this application
      //- Save credentials for this user for this application
      //- Then redirect the user back to this Web Part
        string strSSOLogonFormUrl = SingleSignonLocator.GetCredentialEntryUrl
          ("MyIndividualApplicationID");
        writer.Write("<a href=" + strSSOLogonFormUrl +">Click here to save your 
         credentials for the Enterprise Application.</a>");
        writer.WriteLine();
      }
  }
}

After the user credentials for the enterprise application have been stored in the single sign-on database, the custom code in the Web Part should retrieve the credentials using GetCredentials method, then submit them to the enterprise application in a manner that is relevant to this application, then retrieve the necessary data from this application, and then finally render the data in the Web Part. Referring back to Figure 26-1 that shows eight steps described in the section “How Single Sign-On Works,” the preceding code corresponds to steps 1 through 5. In addition to this code, you have to implement steps 6 through 8.

Your code for interacting with the enterprise application such as submitting credentials and retrieving information will be different depending on the type of application you are accessing. You need to consider that in an enterprise environment, where a user interacts with many systems and applications, it is likely that the environment does not maintain the user context through multiple processes, products, and computers. This user context is crucial to provide single sign-on capabilities because it is necessary to verify who initiated the original request. To overcome this problem, SharePoint Portal Server provides ability to use a Single Sign-On (SSO) ticket (not a Kerberos ticket). An SSO ticket is an encrypted access token that can be used to get the credentials that correspond to the user who made the original request. Also, in the enterprise environment you might consider using Microsoft BizTalk Server as a transformation engine for the authentication requests, as well as requests for data, between your Web Part and a format that is understood by the enterprise application.

An example of such enterprise application integration (EAI) infrastructure is shown in Figure 26-2. In this scenario, a Web Part gets the information from a line of business (LOB) back-end application using BizTalk Server 2004. The LOB application requires authentication. In this example, we will assume that the enterprise application definition for the LOB application has already been created, and the user credentials have been stored in the SSO database.

The authentication process shown in Figure 26-2 consists of several steps, as follows:

  1. The Web Part calls Microsoft.SharePoint.Portal.SingleSignon.Credentials.ReserveCredentialTicket() with the user. This method reserves a credential ticket for the user and then returns an encrypted access token (SSO ticket) to the calling Web Part.

  2. The Web Part passes the SSO ticket to the BizTalk Server 2004 native SOAP adapter by calling a Web service that runs on BizTalk Server. The SSO ticket is passed within the header of the SOAP request. When the SOAP adapter receives a request containing an SSO ticket, the ticket is stored as the SSO Ticket property in the context property of the BizTalk message. For details on configuring BizTalk 2004 SOAP adapter for integration with SharePoint Portal Server single sign-on, refer to https://msdn.microsoft.com/ library/default.asp?url=/library/en-us/operations/htm/ebiz_ops_adapt_file_eixk.asp.

  3. BizTalk passes the SSO ticket to the adapter for the LOB application that has the ability to call into SSO to redeem user’s credentials using an SSO ticket. The LOB adapter calls Microsoft.SharePoint.Portal.SingleSignon.Credentials.GetCredentialsUsingTicket().method with the encrypted SSO ticket along with the enterprise application definition name to retrieve the security credentials for the given application from the SSO credentials database. Alternatively, to redeem the ticket and obtain the user credentials from the SSO credentials database, you can use BizTalk Enterprise SSO object model and call Microsoft.BizTalk.SSOClient.Interop.ISSOTicket.RedeemTicket() method with the encrypted SSO ticket and with the enterprise application definition name.

  4. The LOB adapter performs the necessary authentication and accesses the LOB application.

    Cc750137.note(en-us,TechNet.10).gif  Only members of the SSO administrators group can call the Microsoft.SharePoint.Portal.SingleSignon.Credentials.GetCredentialsUsingTicket() method to get credentials for another user using an SSO ticket.
    For details on necessary permissions to call Microsoft.BizTalk.SSOClient.Interop.ISSOTicket.RedeemTicket() method, refer to https://msdn.microsoft.com/library/default.asp?url=/library/en-us/sdk/htm/frlrfmicrosoftbiztalkssolookupinteropissoticketclassredeemtickettopic.asp.

    Cc750137.f26xr02(en-us,TechNet.10).gif

    Figure 26-2. Enterprise application integration using SharePoint Portal Server single sign-on

If the Web Part that uses single sign-on is partially trusted (installed in the \bin directory of a virtual server), you must assign a custom Code Access Security Permission (SingleSignOnPermission) to it. To add the SingleSignOnPermission, make the following changes to one of the WSS policy files—either WSS_MediumTrust.config or WSS_MinimalTrust.config, depending on which one is in use:

  1. To the <SecurityClasses> section, add:

    <SecurityClass Name="SingleSignonPermission"   
    

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

  1. To the <Permission Set> section, and specifically to the PermissionSet where Name is “ASP.Net”, add:

    <IPermission class="SingleSignonPermission" version="1" Access="Minimal" />

The Access modifier in the above permission may be set to Minimal, Credentials, or Administer, as follows:

Minimal.

  • Allows a user to reserve a ticket

Credentials.

  • Allows a user to redeem credential tickets

Administer.

  • Allows a user to configure the SSOSrv service and maintain applications and credentials

    Cc750137.note(en-us,TechNet.10).gif  These instructions grant a specific level of SingleSignonPermission to all assemblies in the \bin directory of a virtual server. For more information about how to restrict the permission grant to just a single assembly and not all the assemblies in the \bin directory, see the “Code Access Security For Developers” section in the Microsoft SharePoint Products and Technologies SDK at https://msdn.microsoft.com/library/default.asp?url=/library/en-us/spptsdk/html/smpscCodeAccessSecurityDevs.asp.

Summary

SharePoint Portal Server 2003 provides single sign-on functionality implemented by Microsoft Single Sign-On service. The SSOSrv service provides storage and mapping of credentials such as account names and passwords so that portal site–based applications can retrieve information from third-party enterprise applications such as ERP and CRM systems. The credentials are encrypted and stored in the SQL Server database. For each enterprise application, you need to configure the corresponding single sign-on application definition. SharePoint Portal Server 2003 provides a programming interface to use the single sign-on feature. After you have configured the application definition, you need to create a Web Part that programmatically implements the single sign-on functionality using classes provided by SharePoint Portal Server, and then retrieves the data from the corresponding back-end application. There are numerous uses for single sign-on functionality in the enterprise environment.