Sample Scenario Source Files

Applies To: Windows Server 2003 with SP1

The sample in this section uses Microsoft Visual Studio .NET and refers to the Windows Server 2003 implementation of the .NET Framework runtime. The version of the .NET Framework runtime in Windows Server 2003 is different than the runtime that is included with Visual Studio .NET.

You can obtain the source code and setup programs in the sample scenario from the Microsoft Download Center Web site at https://download.microsoft.com/download/8/9/7/89734348-63AB-4F55-B11B-8C0AC50612B1/KerberosProtocolExtensions.msi. The file contains the following items:

Sample Scenarios Configuration Tasks

To set up the sample:

1. Configure the domain to run at the Windows Server 2003 functional level:

   1. Open the Active Directory Users and Computers Microsoft Management Console (MMC) Snap-in.

   2. In the console tree, right click Active Directory User and Computers server_name , point to All Tasks, and then click Raise Domain Functional Level.

   3. In the Select an available domain functional level box, click Windows Server 2003.

2. Create two domain user accounts for the IIS process pools that host the ASP.NET Web service and application:

   Note

   Although you can run the sample Web service and application in the default Network Service account that all newly-created Web applications use on the server on which IIS is installed, the Network Service account is generally used to run other services and Web applications. This means that other processes that run in this account can also exploit the extra Kerberos extensions-related privileges if you give the Network Service account the ability to use both the protocol transition and constrained delegation extensions. This is not the desired behavior, so you should isolate the ability to use Kerberos extensions to a specific domain user account on computers that are running Windows Server 2003.

   1. Open the Active Directory Users and Computers MMC Snap-in.

   2. In the console tree, double-click Active Directory Users and Computers server_name .

   3. In the details pane, right-click Users, point to New, and then click User.

   4. In the New Object User box, type the appropriate information , and then complete the procedure.

   5. Repeat step c and step d for the second user account.

3. Create a domain user account for the SQL server service. To do this, repeat the instructions in step 2.

4. Register Kerberos Service Principal Names (SPNs) for the user accounts that you created in the previous two steps.

   To use the domain account that you created as a Kerberos service account, you must use the Setspn (Setspn.exe) command-line tool to create an SPN for the account. For example, to add an SPN named ws/kerbsfuidentity for the kerbsfuidentity domain account, type the following command at a command prompt:

   setspn a ws/kerbsfuidentity kerbsfuidentity

   To create an SPN for the SQL Server service that is running on sqlcomputer.devdomain.fabrikam.com by using the sqlservice service account, type the following command at a command prompt:

   setspn a MSSQLSvc/sqlcomputer.devdomain.fabrikam.com:1433 sqlservice

   Note

   For more information about how to configure SQL Server service for Kerberos authentication, see Microsoft SQL Server 2000 Security on the MSDN Web site.

5. Create a domain user account that will be used as the user account for Web browser user authentication in scenario one and for protocol transition in scenario two. To create a domain user account, repeat the procedure that is described in step 2.

6. Configure the service accounts that will be trusted for constrained delegation to the SQL Server.

   In the sample scenario, you want to constrain the ability of the service accounts to present delegation credentials to only the specific SQL Server service account. Use the following procedure to add the specified service to the A2D2 attribute on the service accounts that you created in step 2:

   1. Right-click the user account, and then click Properties.

   2. In the Properties dialog box, click the Delegation tab,, and then click Trust this user for delegation to specified services only.

   3. Click Use any authentication protocol, and then click Add.

   4. Click the SQL Server service SPN that you registered in step 4.

   Note

   The Delegation Property tab for a user account is available only if you have created an SPN for the user account. Step 4 describes how to create an SPN.

7. Give service accounts Read access to the tokenGroupsGlobalAndUniversal user object attribute in Active Directory.

   The service accounts that is performing the protocol transition procedure must have Read access to the tokenGroupsGlobalAndUniversal user object attribute in Active Directory. To give the service accounts Read access:

   1. Open the Active Directory Users and Computers MMC Snap-in.

   2. In the console tree, click Builtin.

   3. In the results pane, right-click Windows Authorization Access Group, and then click Properties.

   4. Click the Members tab, and then click Add.

   5. In the Enter the object names to select (examples) box, type the name of the first service account that you created in step 2, and then click OK.

   6. Repeat step 7d and step 7e for the second service account that you created in step 2.

8. Add the service accounts to the IIS worker process group on the computers that are running the ASP.NET Web service and the application:

   1. Click Start, point to Administrative Tools, and then click Computer Management.

   2. In the console tree, click Local Users and Groups, and then click Groups.

   3. In the results pane, right-click IIS_WPG, and then click Add to Group.

   4. Click Add, in the Enter the object names to select (examples) box, type the name of the service account, and then click OK.

   Note

   At the time that this document was published, you also need to manually configure the service account to have access to the %SystemRoot%/Temp folder so that you can run ASP.NET. Confirm that the service account has both List Folder\Read Data and Delete permissions to the %SystemRoot%/Temp folder.

9. Deploy the ASP.NET Web service:

   1. Create a new IIS process pool:

      Click Start, point to Administrative Tools, and then click Computer Management.

      In the console tree, double-click Services and Applications, and then double-click Internet Information Services (IIS) Manager.

      In the console tree, right-click Application Pools, point to New, and then click Application Pool.

      In the Application Pool ID box, type a name for the new application pool, and then click OK.

   2. Set the process pool identity to one of the user accounts that you created in step 2 for the process pool that hosts the ASP.NET Web service:

      In the Application Pools pane, right-click the application pool that you created in the previous step, and then click Properties.

      Click the Identity tab, click Configurable, and then type the appropriate user name and password.

10. Create a new virtual directory for the ASP.NET Web service. To do this, run the Setup.exe program in the KerbExtWebSvc folder to start the wizard that will help you set up a virtual directory for the Web Service.

11. Configure the Web service to use digest authentication:

    1. Click Start, point to Programs, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

    2. Right-click the Web service virtual directory, and then click Properties.

    3. Click the Directory Security tab, and then click Edit in the Authentication and access control box.

    4. In the Authentication Methods box, confirm that the Digest authentication for Windows domain servers check box is the only check box that is selected, click OK, and then click Apply.

12. Configure the Web service to use the process pool that you created in step 9a:

    1. In IIS Manager, right-click the Web service virtual directory, and then click Properties.

    2. Click the Virtual Directory tab, click Application Pool, and then click the application pool that you created in step 9a.

13. Configure the name of the computer that is running SQL Server in the Web services Web.config file.

    The Web service uses the application configuration section in Web.config file to find the name of the computer that is running SQL Server. Because of this, you need to modify the value of the sqlServer key (in the <appSettings> section) in the Web.config file to point to the computer that is running SQL Server. For example, if the name of the computer that is running SQL Server is computer_name, open a text editor, such as Notepad, and then open the Web.config file that is located in the folder where the Web service is installed. Search for <appSettings>, and then make the following changes to the file:

    <appSettings>

    <add key="sqlServer" value="computer_name" />

    </appSettings>

14. Deploy the ASP.NET Web application:

    1. Assign the Act as part of the operating system privilege to one of the user accounts that you created in step 2. This account should be different from the account that you used in step 9b:

       On the computer that is hosting the Web application, click Start, point to Administrative Tools, and then click Local Security Policy.

       In the console tree, double-click Local Policies, and then double-click User Rights Assignment.

       Right-click the Act as part of the operating system policy, point to Properties, and then click Add user or Group.

       Type the user account that you created in step 2 for the IIS process pool that is hosting the ASP.NET Web application, and then click OK.

    2. Create a new IIS process pool for the Web application. To do this, repeat the procedure in step 9a.

    3. Set the process pool identity to the user account that was assigned the Act as part of the operating system privilege in step 14a. To set the identity of the process pool that you created in the previous step, repeat the procedure in step 9b.

    4. Create a new virtual directory for the ASP.NET Web application. To do this, run Setup.exe in the KerbExtWebApp folder to start the wizard.

    5. Enable anonymous access to the Web application:

       Using IIS Manager, right-click the Web application virtual directory, and then click Properties.

       Click the Directory Security tab, and then, in the Authentication and access control box, click Edit.

       Confirm that the Enable anonymous access check box is the only check box that is selected in the Authentication Methods dialog box, click OK, and then click Apply.

    6. Configure the Web application to use the process pool that you created in step 14b. To do this, repeat the procedure in step 12, and then specify the process pool that you created in step 14b when you are prompted to do so.

15. In the Web applications Web.config file, configure the name of the computer that is running SQL Server.

16. Configure the computer that is running SQL Server:

    1. Configure SQL Server to use Integrated Windows Authentication:

       Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

       Right-click the instance of the SQL Server that you want to manage, and then click Properties.

       Click the Security tab, and then click Windows only.

       Click This account, type the domain user name and password to configure the startup service account to use the user account that you created in step 3, and then click OK.

    2. Set up the sample database and stored procedure by running the Kerbs4u.sql script file:

       To run the Kerbs4u.sql script file, click Start, point to Programs point to Microsoft SQL Server, and then click Query Analyzer.

       To connect to the target SQL Server computer, in the Connect to SQL Server box, click the SQL Server to which you want to connect, and then click OK.

       On the File menu, click Open. Navigate to the sample folder that contains the Kerbs4u.sql file, click the Kerbs4u.sql file, and then click Open.

       Press F5 to run the SQL Server script.

       When you run the script, both a KerbS4uDB database and a GetUserInfo stored procedure are created. SQL Query Analyzer returns output that is similar to the output that is in Figure 4 when you successfully run the script.

       Grant rights to the user account that you created in step 5.

    Figure 4: Setting up the Sample Database and Stored Procedure

In the following configuration steps, you will grant the user account login rights to KerbS4uDB, and then you will add permissions so that the user has permissions to run the GetUserInfo stored procedure:

1. Open the SQL Server Enterprise Manager MMC Snap-in.

2. Right-click Logins, and then click New Login.

3. In the SQL Server Login Properties New Login dialog box, click Windows Authentication, in the Domain box, click the user login domain, in the Name box, type the user account that you created in step 5, click Grant access, and then, in the Database box, click KerbS4uDB in the Database box.

4. Click the Database Access tab, select the KerbS4uDB check box, in the Database roles for KerbS4uDB box, click the public row , and then click Properties.

5. In the Database Role Properties public dialog box, click Permissions.

6. In the Exec column, select the GetUserInfo check box, and then click OK.

Running the Samples

The following sections describe how to test the sample scenarios.

Running Sample Scenario One

To run sample scenario one:

1. Start Internet Explorer, and then type the URL for the Web service method in the Address box. For example, type https://www.fabrikam.com/kerbextwebsvc/authxws.asmx?op=testkerbsfu.

2. In the Enter Network Password dialog box for digest authentication, type the domain user name and password, and then click OK.

3. Click Invoke to send a test call to the TestKerbSfu Web method. When the call successfully runs, you receive a return string that is similar to the following return string:

   <?xml version="1.0" encoding="utf-8" ?> 
   <string xmlns=https://fabrikam.com/>web method user context: 
   FABRIKAM\jeffpike; AuthenticationType: Digest; Sql server user 
   context: FABRIKAM\jeffpike</string> 
   

The return string indicates that the fabrikam\jeffpike domain user has been authenticated by the Digest authentication protocol. The user account that is used to authenticate the SQL Server connection is returned by the GetUserInfo stored procedure. To confirm that you successfully used constrained delegation to connect to the SQL Server, view the Security event log on the computer that is running SQL Server to verify that the user account successfully logged on to the network by using the Kerberos authentication package. To view the Security event log, right-click My Computer, click Manage, click to expand Event Viewer, and then click Security. Figure 5 shows an example of this logon event. At the bottom of the Event Properties dialog box, Transitted Services information is displayed. The Transitted Services information displays the identity of the service that uses constrained delegation. Note that the computer must be configured to audit successful logons to capture this event. You can enable this configuration through the Audit Policy option in the Local Security Policy MMC Snap-in.

Figure 5: Kerberos User Logon Event Log

Sample Scenario One Code Walkthrough

In sample scenario one, the user is authenticated through HTTP Digest authentication. The ASP.NET Framework runtime automatically instantiates a WindowsIdentity object for the authenticated user. Subsequently, the Web service method impersonates the user before authenticating to the SQL server. The following code sample provides an example for how you can perform protocol transition with programming code for sample scenario one:

[WebMethod]
public string TestKerbSfu()
{

    //
    // impersonate the user before connecting to the SQL database
    //
    
    WindowsIdentity userIdentity = Context.User.Identity as WindowsIdentity;
    WindowsImpersonationContext impContext = userIdentity.Impersonate();
    
    string userName = ConnectToSql( sqlServer );
    
    if( impContext != null )
    {
        impContext.Undo();
    }
    
}

private string ConnectToSql( string sqlServer )
{
    ...
    try
    {
        string connString = "integrated security=SSPI;initial
catalog=KerbS4uDB;data source=" + sqlServer + ";Connect Timeout=30";
        connection = new SqlConnection( connString );
        connection.Open();
        ...
     }
}

Multiple processing steps occur when the SqlConnection.Open function is called:

1. The Kerberos SSP is invoked when the Web service connects to the SQL server. The Kerberos SSP finds an impersonation-level user token for the impersonated user; however, the Kerberos SSP does not find a Kerberos ticket that is available for the user.

2. The Kerberos SSP initiates protocol transition, and then obtains a service ticket to the Web service on behalf of the impersonated user.

3. The Kerberos SSP obtains a service ticket to SQL Server through constrained delegation.

Running Sample Scenario Two

To run sample scenario two, start Internet Explorer, type the URL for the Web application in the Address box (for example, type https://www.fabrikam.com/KerbExtWebApp), and then press ENTER.

The Web application redirects the browser to the user logon page. Note that the sample code does not validate the user and password information that is typed in at the logon page. Typically, your Web application that uses ASP.NET form-based authentication verifies that the user name and password are valid before allowing the user to use the Web application. After the user logs on, the browser is redirected to the Web applications default page. The default page is where you type the user account that you want the Web application to use for protocol transition. When protocol transition is successful, the next Web page allows you to connect to the SQL server through constrained delegation. When the SQL stored procedure returns, the browser displays both the impersonated and delegated user identities. Similar to sample scenario one, you can examine the Security event log on the computer that is running SQL server to look at the Kerberos-related events that were logged during the SQL connection authentication.

Sample Scenario Two Code Walkthrough

There are two code samples that you should examine for scenario two. The first code sample is used to initiate protocol transition into Kerberos and the second code sample demonstrates how to use constrained delegation to connect to the SQL server.

The following code sample shows how you can initiate protocol transition by creating a new instance of the WindowsIdentity class object:

private void DoProtocolTransition_Click(
object sender, System.EventArgs e)
{
    ...
    WindowsIdentity newIdentity = new WindowsIdentity( UserAccount.Value );
    
    if( null == newIdentity )
    {
        Msg.Text = "Cannot do protocol transition, please try again";
        return;
    }
    
    //
    // Store this user as part of the HTTP session state
    //
    
    HttpContext.Current.Session.Add( "KerberosIdentity", ( object )newIdentity );
    ...
}

Note that the Web browser user can specify the Kerberos security principal for protocol transitioning in this Web application. Typically, a Web application may use a user mapping table to determine the Kerberos security principal that will be used as the user identity for Kerberos protocol transition. The previous code shows that a new WindowsIdentity class object is created for the user that you specify in the UserAccount.Value variable. After the class object is created, the WindowsIdentity object is stored in the ASP.NET HTTP session state. The Web application can retrieve this WindowsIdentity object from the HTTP session state when it needs to impersonate the user and use constrained delegation to authenticate the connection to the SQL server. The following code sample shows how the Web application performs protocol transition and constrained delegation:

...
//
// Get the user's Kerberos identity from the HTTP session state
//
WindowsIdentity user = ( WindowsIdentity )HttpContext.Current.Session[
                       "KerberosIdentity" ];
...
//
// impersonate the user before connecting to the SQL database
//

WindowsImpersonationContext impContext = user.Impersonate();
string userName = ConnectToSql( sqlServer );

Identity.Text = "Impersonated user identity = " + user.Name + "; SQL
Server user identity = " + userName;
if( impContext != null )
{
    impContext.Undo();
}
...