Protocol Transition with Constrained Delegation Technical Supplement

 

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Protocol Transition with Constrained Delegation Technical Supplement

Web Service Security: Scenarios, Patterns, and Implementation Guidance for Web Services Enhancements (WSE) 3.0

Microsoft Corporation

patterns & practices Developer Center
Web Service Security: Home
December 2005

Download	Download this guide in PDF format
Community	Web Service Security Community Workspace [Content link no longer available, original URL:https://go.microsoft.com/fwlink/?LinkId=57044]

Contents

New Kerberos Extensions
Implementation
Implementation Context
More Information

Consider the following scenario:

You are deploying a Web service that does not use Windows integrated authentication. After a client is authenticated; the client needs to be transitioned to a Windows account so that role-based authorization can be performed. The Web service also needs to interact with Web services or other downstream resources that can only be accessed with valid Windows credentials.

The common approach to this problem is to have the client application send a user ID and password that can be used for authentication within the Web service. However, this requires the client application to store a password for use when it accesses the Web service. In addition, the password needs to be protected while it is in transit between the application and the Web service. Both of these requirements represent a security risk that should be avoided.

The solution to this problem is to use the new Kerberos protocol extensions in Windows Server 2003. The new extensions require the user ID but not the password. You still need to establish trust between the client application and the Web service; however, the application is not required to store or send passwords. One of these extensions, referred to as Protocol Transition, can initialize a valid WindowsIdentity object with only the user ID. The other extension uses the new WindowsIdentity object with constrained delegation to access remote resources.

The new extensions are:

• The Kerberos protocol transition extension, S4U2Self.
• The Kerberos constrained delegation extension, S4U2Proxy.

The following list identifies three distinct operations that you can implement with the new extensions:

• Use protocol transition to initialize a WindowsIdentity object for authorization checks.
• Use protocol transition to initialize a WindowsIdentity object for impersonation.
• Use constrained delegation to access remote resources.

The first two operations can be implemented independently of each other, but the third operation requires that you use protocol transition when you are not using Kerberos authentication. In other words, constrained delegation has two configurations; one that requires Kerberos authentication and another that works with any authentication protocol. When you use the configuration that supports any authentication protocol, you must first implement protocol transition with impersonation before you implement constrained delegation.

The next section provides details on the extensions themselves. After you have an understanding of these extensions, see the "Implementation" section to learn how to implement the operations described earlier.

New Kerberos Extensions

As previously mentioned, Windows Server 2003 provides two new Service-for-User (S4U) Kerberos extensions that support protocol transition and constrained delegation. Protocol transition and constrained delegation can be used independently of each other, but they are often used together to implement the scenario described in the introduction.

Protocol Transition

The S4U2Self Kerberos extension can be used to initialize a WindowsIdentity object with the user ID with a valid Windows account in Active Directory. The password associated with the user ID is not required. This feature allows you to transition from any authentication protocol into the Kerberos authentication protocol.

This operation is accomplished by using the ticket-granting ticket (TGT) of a service account to request a service ticket for itself. The service account in this case is the one associated with the Web service that performs the protocol transition. The service ticket that is returned from the ticket-granting service (TGS) contains identity and principal information for the user whose ID was sent with the request.

The new WindowsIdentity that is initialized with this service ticket can then be used to perform role-based authorization checks. In addition, when used with constrained delegation, this new identity can be used to access downstream resources. There are limitations to what this new identity is allowed to do that are based on the privileges of the service account. These limitations are discussed in the "Implementation" section later in this technical supplement.

Constrained Delegation

The S4U2Proxy Kerberos extension provides an implementation of constrained delegation that allows you to use a Kerberos service ticket—instead of a TGT—to request another service ticket. Delegation is considered to be constrained because the identity (service account) that is used to request the service ticket must be configured to access a specific service.

**Note   **For more information about the use of TGTs, see Kerberos Technical Supplement for Windows in Chapter 7, "Technical Supplements."

Constrained delegation works with or without protocol transition. The primary restriction is that the service account used to request a Kerberos service ticket must be configured to access the requested service. In addition, the service account must be able to impersonate the client prior to calling the service. For example, when you use Windows integrated authentication with impersonation, the default Web server's computer account can be configured for constrained delegation without making any changes to the Internet Information Services (IIS) process account.

A restriction of protocol transition is that the Web server's computer account cannot be used for constrained delegation without modifying the IIS process account. The reason for this is that the default IIS process account (which is the NT AUTHORITY\NETWORK SERVICE account on Windows 2003 Server) does not have necessary privileges to implement impersonation using the WindowsIdentity object that was created during protocol transition. Instead of modifying the default IIS process account, you can also use a different service account for the IIS process.

**Note   **The S4U2Self and S4U2Proxy extensions are only supported on Windows Server 2003. As a result, protocol transition with constrained delegation does not work on Windows Server 2000 or on Windows XP. It is possible, however, to call services on these platforms by using the service ticket that is retrieved from the delegated request.

For more information about the Kerberos protocol and related patterns, see the following:

• Brokered Authentication: Kerberos in Chapter 1, "Authentication Patterns"
• Implementing Message Layer Security with Kerberos in WSE 3.0 in Chapter 3, "Implementing Transport and Message Layer Security"
• Kerberos Technical Supplement for Windows in Chapter 7, "Technical Supplements"

Scenarios

.NET Framework applications can implement protocol transition by creating an instance of the WindowsIdentity object with a User Principal Name (UPN), which is similar to an e-mail address. For example, if the user ID is steve and the corresponding Active Directory domain is globalbank.net, the UPN is steve@globalbank.net.

It is also possible to use protocol transition to initialize a WindowsIdentity object using a common Active Directory account for trusted subsystem implementations. This type of approach is normally used when you want to improve scalability with resources that use object or connection pooling based on the credentials that were used to access them. For example, connection pooling with SQL Server will work only if a common identity is used.

As a result, the following two primary scenarios are associated with protocol transition in Windows:

• Transitioning from a different authentication protocol, such as X.509 client certificates, into the Kerberos protocol.
• Transitioning from custom authentication by using a common identity for trusted subsystem implementations.

Implementation

This section describes how to implement each of the following three distinct operations that you were introduced to earlier in this technical supplement:

• Use protocol transition to initialize a WindowsIdentity object for authorization checks.
• Use protocol transition to initialize a WindowsIdentity object for impersonation.
• Use constrained delegation to access remote resources.

These operations are performed with a sample application that starts with authorization and finishes with the use of impersonation and constrained delegation to access a remote resource.

Instead of focusing on client authentication, the discussion focuses on protocol transition with constrained delegation by using an identity that is retrieved from an X.509 client certificate. For more information about using client certificates for authentication with Web services, see How to Call a Web Service Using Client Certificates from ASP.NET.

**Note   **This guidance assumes that the reader is familiar with Active Directory, Internet Information Services (IIS), and the .NET Framework.

Use Protocol Transition to Initialize a WindowsIdentity Object for Authorization Checks

Starting with .NET Framework 1.1, a new constructor was added to WindowsIdentity that uses the S4U2Self Kerberos extension to request a service ticket. The ticket-granting ticket (TGT) of the service account is used to request a service ticket for itself by using identity information from the client who is accessing the service. As a result, the privileges of the service account also affect the type of WindowsIdentity object that is created. For example, if the service account has Trusted Computing Base (TCB) privileges, the WindowsIdentity object can be used for impersonation, which is required to implement constrained delegation.

Even if the service account does not have TCB privileges (which is often the case), you can use the new WindowsIdentity constructor to initialize an identity object and then use that to initialize a WindowsPrincipal object for role-based authorization checks, using the client's security roles. A service account without TCB privileges can also be used to access resources directly. However, that account's identity is used to access the resource instead of the client's identity.

The following code example shows how to initialize a WindowsIdentity object with the user ID and domain information that is associated with the client. It then uses that information to perform role-based authorization checks.

WindowsIdentity identity = new WindowsIdentity( <logon name>@<domain> );
if( identity != null )
{
    WindowsPrincipal userPrincipal = new WindowsPrincipal( identity );
    if( userPrincipal.IsInRole( @"GLOBALBANK\ServiceUsers" ))
    {
        ...
    }
    else
    {
        lblMessage.Text = "Not In Role: Service access denied";    
    }
}

Example: Using protocol transition to initialize a WindowsIdentity object for role-based authorization checks

It is useful to have access to a client's identity and roles, but the default IIS service account does not have the necessary permissions to impersonate the client when it accesses a resource. To provide this functionality, the next section describes how to configure a new service account that will be used as the identity of an application pool in IIS 6.0.

Note   The previous code example from a Web application shows what was used to implement protocol transition with constrained delegation. GLOBALBANK\ServiceUsers represents an Active Directory group that is used to provide role-based authorization checks. The field named lblMessage is a Web application Label control that is used to display messages. This example is extended throughout the remainder of this technical supplement.

Use Protocol Transition to Initialize a WindowsIdentity Object for Impersonation

If you want to use the client's security context to access resources, impersonation must be implemented prior to accessing the resource. To implement this with protocol transition, you should create a new service account and configure that account to perform the protocol transition.

By default, IIS applications and services run under the NETWORK SERVICE account on Windows Server 2003. The easiest way to support protocol transition is to give this account Trusted Computing Base (TCB) privileges on the service host. An account with TCB privileges can act as part of the operating system when it performs operations. However, the problem with this approach is that the NETWORK SERVICE account is used by many Web applications and services. Giving this account operating system privileges represents a significant security risk.

With the use of application pools in IIS 6.0, you can mitigate this risk by creating a new pool that uses an identity with TCB privileges. To accomplish this task, you must first create a domain user account and configure it to have proper privileges on the Web server. After the account is configured, it can be used as the identity of a new application pool. Any Web applications or services that need to implement protocol transition with impersonation can then use this new application pool.

**Note   **The following steps require that you have administrative privileges on appropriate servers to perform the operations.

Step One: Create a Domain Account

On the domain controller, use the following steps to create a new user account.

To create a domain user account

1. On the Administrators menu, click Active Directory Users and Computers.

2. Create a new user and configure it with the following settings:

   First Name: Domain
   Last Name: Pool
   User Name: DPool
   Clear: User must change password at next login
   Select: User cannot change password
   Select: Password never expires

The new account is automatically added to the Users group on the domain. You do not need to add it to any other groups. At this point, there is nothing else you need to configure for the account on the domain, but this account does need additional privileges on the host Web server.

Step Two: Configure the Domain Account on the Web Server

Several permissions are required on the Web server to use the new domain account for protocol transition with IIS 6.0. You must configure the account for TCB privileges and add it to a group that has permissions for application pools. To work correctly, the account also needs special permissions on a temporary folder for protocol transition.

Assign TCB privileges

1. On the Administrators menu, click Local Security Policy.
2. Expand Local Policies, and then click User Rights Assignments.
3. Open the Act as part of the operating system policy, and add the DPool account that you created in the previous step.

Add account to IIS_WPG

1. On the Administrators menu, click Computer Management.
2. Expand Local Users and Groups, and then click Groups.
3. Open the IIS_WPG group, and then add the DPool account.

Give IIS_WPG special folder permissions

1. Open Windows Explorer, and then click the %SYSTEM%\Temp folder.

2. Right-click the Temp folder, and then click Sharing and Security.

3. On the Security tab, click the Advanced button.

4. In the Advanced Security Settings for Temp dialog box, click the Add button and add the IIS_WPG group. This opens the Permission Entry for Temp dialog box.

5. In the Permission Entry for Temp dialog box, select the following check boxes:

   List Folder / Read Data
   Delete

This last configuration is required to support protocol transition, but it makes sense to assign these rights to the IIS_WPG group instead of the individual domain accounts. In addition, because the NETWORK SERVICE account already has this privilege, you are not assigning any privileges to IIS_WPG that a typical Web application does not have.

Step Three: Create a New Application Pool

This step uses the Internet Information Services (IIS) Manager, which is located on the Administrative Tools menu.

To add a new application pool

1. Expand the server (local computer), and then click Application Pools.
2. Right-click Application Pools, point to New, and then click Application Pool.
3. Name the pool DomainPool. Make sure the Use default settings for new application pool option is selected, and then click OK to create the new pool.
4. In IIS Manager, expand Application Pools, and then click the new pool that you created.
5. Right-click DomainPool, and then click Properties.
6. On the Identity tab, click Configurable, and then type the new DPool domain account you created in Step One: Create a Domain Account.
7. Click OK to close the dialog box.

Step Four: Configure the Web Application to Use the New Application Pool

This step assumes that you have an ASP.NET Web application or service that uses protocol transition to access a Web service that requires message-based Kerberos authentication. The creation of the Web applications and implementation of message-based security with the Kerberos protocol are beyond the scope of this chapter. Instead, the focus is on tasks that are required to implement protocol transition.

To configure the Web application to use the new application pool

1. In the Internet Information Services (IIS) Manager dialog box, expand the server (local computer), expand Web Applications, expand the Web site folder, and then click your Web application.
2. Right-click the Web application, and then click Properties.
3. On the Virtual Directory tab, click the application pool (DomainPool) that was created in the previous step.
4. Click OK to close the dialog box.

With the Web application configured to use the new application pool, you can use the following code example to test the configuration and make sure that impersonation is supported by the WindowsIdentity object created using protocol transition.

...
    WindowsIdentity identity = new WindowsIdentity( <logon name>@<domain> );
    if( identity != null )
    {
        WindowsImpersonationContext context = null;
        try
        {
            context = identity.Impersonate();
            // Perform operations that require impersonation...
        }
        catch( Exception ex )
        {
            lblMessage.Text = "Impersonation Failed: " + ex.Message;    
        }
        finally
        {
            context.Undo();
        }
    }
...

Example: Using protocol transition to initialize a WindowsIdentity object for impersonation

Notice that the Impersonate operation is performed within a try/catch block. This is because the WindowsIdentity object does not provide information about the service ticket that is associated with the service account. In other words, the identity cannot be checked to determine whether it supports impersonation before attempting the Impersonate operation. This means that if the service account does not have TCB privileges, this operation will throw an exception.

**Note   **The code sample performs a context.Undo() statement in the finally block to revert the security context back to the original identity. If this operation fails, which is rare, the recommendation is to exit the application with a system error and shut down the process. In other words, the application process should be stopped immediately.

Even though you now have IIS configured for protocol transition with impersonation, you still cannot access downstream resources with the transitioned identity. Your final task is to configure Active Directory to support constrained delegation.

Use Constrained Delegation to Access Remote Resources

Two types of constrained delegation are available: one that requires the Kerberos protocol and another that supports any protocol. To support protocol transition, you must use the configuration that supports any authentication protocol. However, before configuring delegation, you need to create a Service Principal Name (SPN) for the DPool domain account, which is the account you created in the previous task.

Step One: Create SPN for Domain Account

A Service Principal Name (SPN) represents a unique name that is used by the Kerberos protocol to access a service's long term key when it creates a service ticket. To request a service ticket, the service must have an associated SPN registered in Active Directory. By default, all of the standard services use a HOST-based SPN, which is configured when the operating system is installed. By using a different account as the identity for the application pool, this host SPN can not be used. Instead you need to create a new host-based SPN for the domain account.

The tool you use to create a new SPN is named setspn.exe, which is found in Windows Support Tools for Windows Server 2003. To create a new SPN, open the command prompt in the Support Tools menu and type the following command.

setspn –a http/<host>.<domain> DPool

The following list explains the command elements:

• –a tells SetSPN to create and then add a new SPN.
• http is the built-in service class used by IIS and Internet Explorer when Windows integrated security is used.
• <host> is the name of the host computer; you need to change this to match the Web server you are configuring.
• <domain> is the domain; you need to change this to match your domain.
• DPool is the host user account configured for protocol transition.

For more information about SPNs, setspn.exe, and the Kerberos security protocol, see the Kerberos Technical Supplement for Windows in Chapter 7, "Technical Supplements."

After the SPN is created, it is possible to configure constrained delegation so that the Web application or service can use a transitioned identity to access downstream resources.

**Note   **The example in this chapter uses the built-in HTTP service class as the SPN that maps to a domain account. This is not necessary in message layer security where you can specify the SPN. However, when you use Windows Integrated Security, you must map the service account to the HTTP SPN because both Internet Explorer and IIS use the HTTP SPN when they interact with a Web-based service.

Step Two: Configure Delegation

When the SPN is created, a new Delegation tab is added to the associated domain account, which provides the ability to configure constrained delegation. Figure 1 shows the new Delegation tab for the DPool account.

Figure 1. The Domain Pool Properties dialog box

As you can see in Figure 1, the Domain Pool (DPool) properties are configured to Trust this user for delegation to specified services only and for Use with any authentication protocol. In the Services to which this account can present delegated credentials list, there is a single entry with a service type of HTTP, which means that DPool can only access the HTTP service class that is associated with the user or computer shown in the next column.

Remember that DPool is configured as the identity of an application pool in IIS. This application pool is used to host Web applications that implement protocol transition. In other words, this is the identity that is used to request a Kerberos service ticket on behalf of a user that was transitioned into the Kerberos protocol. To request a ticket on behalf of the transitioned user, you must configure DPool to support constrained delegation with any authentication protocol as shown in Figure 1.

**Note   **You can use constrained delegation to access any service that supports the Kerberos protocol. This means that a Web application that is running on Windows Server 2003 can access a Web service that is running on Windows XP by using protocol transition with constrained delegation.

Sample Code

After you complete all of the tasks, you can implement protocol transition from any Web application or service that is hosted in the new application pool. However, the main restriction is that you can only access services that are configured in the Delegation tab of the host identity that is associated with the application pool. This identity is a domain account that has been configured to support protocol transition and constrained delegation on the Web server.

The following code sample demonstrates how to implement protocol transition with constrained delegation using a client's logon name.

WindowsIdentity identity = new WindowsIdentity( <logon name>@<domain> );
if( identity != null )
{
    WindowsPrincipal userPrincipal = new WindowsPrincipal( identity );
    if( userPrincipal.IsInRole( @"GLOBALBANK\ServiceUsers" ))
    {
        WindowsImpersonationContext context = null;
        try
        {
            context = identity.Impersonate();
            try
            {
                Service.KerberosService service = 
                    new Service.KerberosService();
                service.PreAuthenticate = true;service.Credentials = CredentialCache.DefaultCredentials;
                lblMessage.Text = service.HelloWorld();
            }
            catch( Exception ex )
            {
              lblMessage.Text = "Service Call Failed: " + ex.Message;    
            }
        }
        catch( Exception ex )
        {
            lblMessage.Text = "Impersonation Failed: " + ex.Message;    
        }
        finally
        {
            context.Undo();
        }
    }
    else
    {
        lblMessage.Text = "Invalid Role: Service access denied";    
    }
}

Example: Using protocol transition with constrained delegation to access a service with the client's logon name.

The Web service in this example was deployed on Windows XP and has been configured to support Windows integrated authentication with impersonation enabled. When a Web service request is sent with Windows integrated authentication, the two bold lines in the previous code example must be used to attach the credentials to the message. Setting PreAuthenticate to true adds the credentials to the initial request, which prevents a round trip. The CredentialCache holds the credentials of the identity that was impersonated.

When you use message layer security, the lines in bold are not required. For an example of message layer security using the Kerberos protocol, see Implementing Message Layer Security with Kerberos in WSE 3.0 in Chapter 3, "Implementing Transport and Message Layer Security."

Implementation Context

This section describes some of the more significant benefits, liabilities, and security considerations of implementing protocol transition with constrained delegation.

**Note   **The information in this section is not intended to be comprehensive. However, it does discuss many of the issues that are most commonly encountered.

Benefits

The benefits of protocol transition with constrained delegation include the following:

• Access to the downstream resource is based on the identity of the client, and can therefore be traced back to the original client of the online application. This allows granular auditing and authorization that are based on the originating client's identity instead of the identity of the online application or service.
• An online application that does not support protocols that are normally used on the internal network can transition clients into a protocol that is supported.
• With protocol transition, it is possible to implement delegation and impersonation without storing a client's password on the Web server.

Liabilities

The liabilities of protocol transition with constrained delegation include the following:

• When impersonation or constrained delegation is used, it may not be possible to take advantage of optimizations, such as connection pooling. Most resource-sharing optimizations require the use of a common identity when they authenticate with the resource. For example, a separate connection exists for each client when you use impersonation or constrained delegation to access a database. This prevents the ability to share connections with multiple clients (connection pooling).
• Configuring a domain account to use the host-based HTTP SPN means that other Web applications and services on that Web server must also use the same application pool to support any authentication request that uses the HTTP SPN, which is the default behavior with Windows integrated authentication.
• If the account that is used to implement protocol transition is compromised, it is possible for an attacker to use any Active Directory account when he or she accesses resources. However, the number of resources is restricted because an identity that is created with protocol transition must use constrained delegation to access a resource.

Security Considerations

Security considerations associated with protocol transition with constrained delegation include the following:

• Establishing a security context for a client without proving its identity requires a high degree of trust in the system that performs the protocol transition. Because of its trusted responsibilities, the system that performs protocol transition is likely to be a high-interest target for attackers. You should mitigate this threat by limiting access to private networks and using a separate application pool with an identity that is configured for protocol transition.
• You cannot use constrained delegation across a domain boundary. Constrained delegation is restricted to services in a single domain. All domain controllers in the domain must run Windows Server 2003, and the domain must operate at the Windows Server 2003 functional level.

More Information

For more information about the Kerberos protocol extensions, see "Exploring S4U Kerberos Extensions in Windows Server 2003" on MSDN.

For more information about implementing protocol transition and constrained delegation, see "Kerberos Protocol Transition and Constrained Delegation" on Microsoft TechNet.

For more information about using the Kerberos protocol extensions, see "How To: Use Protocol Transition and Constrained Delegation in ASP.NET 2.0" on MSDN.

For more information about using client certificates for authentication with Web services, see "How to Call a Web Service Using Client Certificates from ASP.NET" on MSDN.

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.