20 Enabling Impersonation with the Access System

In a Windows environment, after a user authenticates, the authenticating application can impersonate that user's impersonation. Impersonation is implemented on a thread-by-thread basis. The primary purpose of impersonation is to trigger access checks against a client's identity.

This chapter discusses enabling impersonation in the Access System to override impersonation enabled with IIS. See the following topics:

• About Windows Impersonation

• About Impersonation and the Access System

• Enabling Impersonation With a Header Variable

• Setting Up Impersonation with Integrations

• Enabling Impersonation with a User Name and Password

• Setting Up Impersonation for OWA

• Windows Impersonation Background

• Negative Testing for Impersonation

Note:

"Integrating SharePoint Server" provides a detailed example of how to integrate with the SharePoint Portal Server as well as the extra measures you may have to take to get impersonation running in different contexts

20.1 About Windows Impersonation

When running in a client's security context, a service can to an extent become a client. After the user authenticates, the service can take on that user's identity through impersonation. One of the service's threads uses an access token, known as an impersonation token, to obtain access to objects the client can access. The access token is a protected object that represents the client's credentials.

The impersonation token identifies the client, the client's groups, and the client's privileges. The information in the token is used during access checks when the thread requests access to resources on the client's behalf. When the server is impersonating the client, any operations performed by the server are performed using the client's credentials.

Impersonation ensures that the server can or cannot do exactly what the client can or cannot do. Access to resources can be restricted or expanded, depending on what the client has permission to do. Impersonation requires the participation of both the client and the server. The client must indicate its willingness to let the server use its identity, and the server must explicitly assume the client's identity programmatically.

When impersonation concludes, the thread uses the primary token to operate using the service's own security context rather than the client's. The primary token describes the security context of the user account associated with the process (the person who started the application).

Services run under their own accounts and act as users in their own right. For example, system services that are installed with the operating system run under the Local System account. You can configure other services to run under the Local System account, or separate accounts on the local system or in Active Directory.

The IIS Web server provides impersonation capabilities. However, the Access System overrides IIS authentication, authorization, and impersonation functions. For more information, see:

• "About Impersonation and the Access System"

• "Windows Impersonation Background"

Single sign-on for Authenticated Oracle Access Manager Users into Exchange: This is also supported using the Windows Impersonation feature. OWA provides Web access to Exchange mail services and may be configured on either of the following:

• An IIS Web server that does not reside on the same server as the Exchange server, which is also known as a front-end server

• An IIS Web server running on the Exchange server, which is also known as the back-end server

In a front-end server configuration, the front-end OWA server authenticates the user, determines the back-end Exchange server that hosts the user's mailbox, then proxies the request to the appropriate back-end Exchange server. No additional credential information is passed. No delegation is performed. Setting up Impersonation on the back-end Exchange server ensures that the Exchange server does not need to request credentials before granting access.

For more information, see "Setting Up Impersonation for OWA" .

20.2 About Impersonation and the Access System

You can enable support for Windows impersonation to provide additional access control for protected applications. You bind a trusted user to a WebGate and protect the application with a policy domain that includes an impersonation action in the authorization rule. During the authorization process, the protected application creates an impersonation token.

Table 20-1 identifies Access System support for Windows impersonation.

Table 20-1 Support for Windows Impersonation

Access System Version 6.5 and Higher Supports	Previous Versions Supported
Microsoft Kerberos Service-for-User-to-Self (S4U2Self) extension	User name and password required.LOGON_USER, LOGON_PASSWORD (in authorization rule, action)
The Impersonate HeaderVar action type is as an authorization rule action in the Access System	User name (LOGON_USER) used in proper header variables.
No password needed	Password (LOGON_PASSWORD) stored in a directory in clear text or in a separate database, not set as a header variable.
REMOTE_USER may be set to any value in Authorization Rule, Action (type HTTP).	No change

For more information, see "The Kerberos Protocol" and "The S4U2Self Extension" . Also, see the following:

• "Enabling Impersonation With a Header Variable" provides prerequisites and details about implementing impersonation using header variables.

• "Enabling Impersonation with a User Name and Password" explains how to implement impersonation using features available before version 6.5.

20.3 Enabling Impersonation With a Header Variable

Enabling impersonation with a header variable involves the following procedures.

Task overview: Enabling impersonation with a header variable includes

1. Reviewing all Requirements

2. Creating an Impersonator as a Trusted User

3. Assigning Rights to the Trusted User

4. Binding the Trusted User to Your WebGate

5. Adding an Impersonation Action to a Policy Domain

6. Adding an Impersonation DLL to IIS

7. Testing Impersonation

Note:

The example in this chapter illustrates setting up the impersonation feature for the Access System to Microsoft SharePoint Portal Server integration. The principles are the same regardless of your application.

See also "Setting Up Impersonation for OWA".

20.3.1 Requirements

Prepare the environment and confirm that it is operating properly before implementing impersonation with the Access System.

Table 20-2 identifies the platform requirements for version 6.5 and later when you enable impersonation using a header variable.

Table 20-2 Version 6.5 and Later Requirements for Impersonation with a Header Variable

Item	Platform
WebGate (and Impersonation dll)	Microsoft IIS 6.x and Windows Server 2003Note: Other Access System components have no specific requirements.
Impersonation dll	WebGate_install_dir\access\oblix\apps\webgate\bin Must be installed as an IIS wildcard extension. May be installed at any level of the Web site tree. For details, see "Wildcard Extension".
Kerberos Key Distribution Center (KDC) and Active Directory	Windows Server 2003
Client and Server machines	Both must be in the same Windows Server 2003 domain with a trust relationship. A bidirectional trust path is required because the service, acting on the client's behalf, must request tickets from the client's domain.
Security context	Must have Act as operating system privileges. Note: IWAM_Machine is not recommended because it is the account used by the Microsoft Transaction Server (MTS) and various IIS entities to provide programmatic and transactional functions.
Mutual authentication is required	Mutual authentication is supported remotely.

20.3.2 Creating an Impersonator as a Trusted User

Whether you enable impersonation using a HeaderVar or user profile attribute, the return value must be a trusted user in Active Directory. This special user should not be used for anything other than impersonation.

To create a trusted user account

1. On the Windows 2003 machine hosting your SPPS installation, select Start; Programs; Manage Your Server; Domain Controller (Active Directory); Manage Users and Computers in Active Directory.

2. In the Active Directory Users and Computers window, right-click Users on the tree in the left pane, then select New; User.

3. In the First name field of the pane entitled New Object - User, enter an easy-to-remember name such as SPPSImpersonator.

4. Copy this same string to the User logon name field, then click Next.

5. In succeeding panels, you are asked to choose a password and then retype it to confirm.

Note:

Oracle recommends that you choose a very complex password, because your trusted user is being given very powerful permissions. Also, be sure to check the box marked Password Never Expires. Since the impersonation extension should be the only entity that ever sees the trusted user account, it would be very difficult for an outside agency to discover that the password has expired.

Figure 20-1 Setting up a Trusted User Account for Windows Impersonation

20.3.3 Assigning Rights to the Trusted User

You need to give the trusted user the right to act as part of the operating system

To give appropriate rights to the trusted user

1. From the desktop, click the Start menu, then click Control Panel, and open Administrative Tools.

2. Select Domain Controller Security Policy or Local Security Policy (depending on if the computer is a domain controller).

   You must modify the group policy object that applies to the computer where the WebGate is installed.

3. On the tree in the left pane, click the plus icon (+) next to Local Policies.

4. Click User Rights Assignment on the tree in the left pane.

5. Double-click "Act as part of the operating system" in the right pane.

6. Click Add User or Group.

7. In the Add User or Group panel, type the User logon name of the trusted user (SPPSImpersonator in our example) in the User and group names text entry box, then click OK to register the change.

Figure 20-2 Configuring Rights for the Trusted User in Windows Impersonation

To configure Active Directory settings for the trusted user

1. In Active Directory, assign the truster user (in this example, SPPSImpersonator) the Allowed to Authenticate permission for all user objects that the account will impersonate.

2. If the option Do Not Require Kerboeros Preauthentication is set on any user account that the SPSSImpersonate account will be impersonating, remove this option from the account.

3. Assign the following Property Right to the trusted user account (in this example, SPPSImpersonate): Read Remote Access Information.

20.3.4 Binding the Trusted User to Your WebGate

You need to bind the trusted user to the WebGate by supplying the authentication credentials for the trusted user, as described in the following paragraphs.

To bind your trusted user to your WebGate

• Point your browser to your Access System Console.

  For example:

  http://hostname.domain.com:port/access/oblix
  

  where hostname is the DNS name of the machine hosting your Policy Manager, domain is the name of the server domain to which the machine belongs, and port is the number of the port to which Policy Manager listens.

• From the Access System Console, click Access System Configuration, then click AccessGate Configuration.

• Select the name of the WebGate you want to modify.

  The Details for AccessGate page appears with a summary of the configuration information for this WebGate. At the bottom of this Web page are fields for Impersonation Username and Impersonation Password.

• Click the Modify button at the bottom of the page.

• In the Modify AccessGate page, scroll to the bottom and enter the user name and password for the trusted user account you created through the task in "Assigning Rights to the Trusted User".

  For example:

  
  

• Click the Save button to commit the changes and return to the Details page.

  A bind has been created for the WebGate and the trusted user. The WebGate is now ready to provide impersonation on demand. The demand is created by an Authorization Success Action in a policy domain created for impersonation.

20.3.5 Adding an Impersonation Action to a Policy Domain

You must create or configure a policy domain to protect your SharePoint resources. You do this by adding an Authorization Success Action with a return type of headerVar, the name parameter set to the name of the trusted user (SPPSImpersonator in our example), and the return attribute parameter set to samaccountname for a single-domain Active Directory installation or userPrincipalName for a multi-domain Active Directory forest.

You must also choose an easy-to-remember name for the domain, such as ImpersonationPolicyDomain.

For details on creating a policy domain, see the chapter on protecting resources with policy domains in the Oracle Access Manager Access System Administration Guide.

To add an impersonation action to your policy domain

1. Point your browser to the Access System Console. For example:

   http://hostname.domain.com:port/access/oblix
   

   where hostname is the DNS name of the machine hosting your Policy Manager, domain is the name of the server domain to which the machine belongs, and port is the number of the port to which Policy Manager listens.

2. Navigate to the Authorization Definitions page of the policy domain you want to change:

   In the Policy Manager, click My Policy Domains, then click PolicyName, then click Authorization Rules

   where PolicyName refers to the policy domain you created specifically for impersonation (ImpersonationPolicyDomain in our example).

   Note:

   Currently defined authorization rules are listed. If none are listed, click the Add button and complete the form to create one.

3. Click the link to the rule to which you want to add the impersonation action. The description will expand.

4. Click the Actions link, which appears directly under the Authorization Rules tab.

   The Authorization Success page appears. If no actions are identified, you must add them. If actions are provided, you can modify them.

   You need to add a header variable named impersonate to Authorization Success Action in the policy domain for impersonation.

5. On the Authorization Success page appears, click Add or Modify.

6. Complete the form using headerVar as the Return Type, the User log on name of the trusted user you have bound to the WebGate, and the appropriate return value for your environment. For example:

   Type: HeaderVar
   Name: IMPERSONATE
   Return value: uid or samAccountName (Active Directory username, the Windows domain user for the desired folder)
   

   Your completed form may look something like the following:

   
   

7. Save the rule.

This rule is used for the second WebGate request (for authorization).

20.3.6 Adding an Impersonation DLL to IIS

You are ready to configure IIS by adding the IISImpersonationExtension.dll to your IIS configuration.

To add the impersonation DLL to your IIS configuration

1. Select Start; Administrative Tools; Internet Information Services (IIS) Manager.

2. Click the plus icon (+) to the left of the local computer icon on the tree in the left pane.

3. Click Web Service Extensions on the tree in the left pane.

4. Double-click WebGate in the right panel to open the Properties panel.

5. Click the Required Files tab.

6. Click Add.

7. In the Path to file text box, type the full path to IISImpersonationExtension.dll.

   By default, the path is:

   WebGate_install_dir \access\oblix\apps\webgate\bin\IISImpersonation\Extension.dll

   where WebGate_install_dir is the root directory of your WebGate installation.

   Note:

   If any spaces exist in the path (for example, C:\Program Files\Oracle\...) surround the entire string with double quotes (" ").

8. Click OK.

9. Add the IISImpersonationExtension.dll to the Wildcard Application Maps for the WebSite or IIS Virtual directory.

   To do this, from the Internet Services Manager, go to WebSite/Virtual Directory Properties, then to the Home Directory, then to Configuration, then to Mappings and add IISImpersonationExtension.dll in Wildcard Applications maps.

10. Verify that the Allow button to the left of the WebGate icon is greyed out, which indicates that the dll is allowed to run as a Web service extension.

    Note:

    If Allow is not greyed out, click it so that it becomes greyed out. When Allow is greyed out, this indicates that the highlighted file is permitted to run on the IIS virtual server.

    Figure 20-3 Configuring IIS Security Settings

    
    

20.3.7 Extending Impersonation to Resources Beyond the WebGate's Host Computer

In addition to configuring impersonation for resources on the computer that is protected by a WebGate, you can extend impersonation to other resources on the network. This is known as assigning a Delegate impersonation level to the client.

Note:

More information on delegation is provided at the following URL:

http://www.microsoft.com/technet/prodtechnol/windows2000serv/reskit/distrib/dsce_ctl_awdg.mspx?mfr=true

To extend impersonation to resources beyond the computer protected by a WebGate

1. In Active Directory Users and Computers, right-click the trusted user account that performs impersonation.

2. Click Properties, then click Accounts.

3. In the Account Options dialog box, de-select the option "Account is sensitive and cannot be delegated" if it is selected.

4. In Active Directory Users and Computers, right-click the user account for the OblixService.

5. Click Properties, then click Accounts.

6. In the Account Options dialog box, select the option "Account is trusted for delegation."

20.3.8 Testing Impersonation

You can test Impersonation in the following two ways:

• Testing Impersonation Using the Event Viewer

• Testing Impersonation using a Web Page

20.3.8.1 Creating an IIS Virtual Site Not Protected by SPPS

To test the impersonation feature outside the SPPS context or to test single sign-on, you will need a target Web page on an IIS virtual Web site that is not protected by SPPS. You create such a virtual Web site by completing the following task.

To create an IIS virtual site not protected by SPPS

1. Click the Start menu, then click Administrative Tools, then click Internet Information Services (IIS) Manager.

2. Click the plus icon (+) to the left of the local computer icon on the tree in the left pane.

3. Right-click Web Sites on the tree in the left pane, then select New, then select Web Site on the menu.

4. Respond to the prompts by the Web site creation wizard.

5. After you create the virtual site, you must protect it with a policy domain, as described elsewhere in this guide.

20.3.8.2 Testing Impersonation Using the Event Viewer

When you complete impersonation testing using the Windows 2003 Event Viewer, you must configure the event viewer before conducting the actual test.

To test impersonation through the Event Viewer

1. Select Start Menu; Event Viewer.

2. In the left pane, right-click Security, then click Properties.

3. Click the Filter tab on the Security property sheet.

4. Verify that all Event Types are checked, and the Event Source and Category lists are set to All, then click OK to dismiss the property sheet.

   Your Event Viewer is now configured to display information about the headerVar associated with a resource request.

   Figure 20-4 Verifying Event Viewer Settings

   
   

5. Create a new IIS virtual server (virtual site).

6. Place a target Web page anywhere in the tree on the virtual site.

7. Point your browser at the Web page

   If impersonation is working correctly, the Event Viewer will report the success of the access attempt.

20.3.8.3 Testing Impersonation using a Web Page

You can also test impersonation using a dynamic test page, such as an .asp page or a perl script, that can return and display information about the request.

To test impersonation through a Web page that displays server variables

1. Create an .asp page or perl script that will display the parameters AUTH_USER and IMPERSONATE. It can resemble the sample page presented in the following listing:

   Example 20-1 Sample .ASP Page Code

   <TABLE border=1>
   <TR>
   <TD>Variable</TD>
   <TD>&nbsp&nbsp</TD>
   <TD>Value</TD></TR>
   <%for each servervar in request.servervariables%>
   <TR>
   <TD><%=servervar%></TD> 
   <TD>&nbsp&nbsp</TD>
   <TD><%=request.servervariables(servervar)%>&nbsp</TD>
   </TR>
   

2. Create an IIS virtual site, or use the one you created for the previous task.

3. Place an .asp page or perl script (such as the sample in the preceding listing) anywhere in the tree of the new virtual site.

4. Point your browser at the page. The page should display, with both AUTH_USER and IMPERSONATE set to the name of the user making the request.

20.4 Setting Up Impersonation with Integrations

The Oracle Access Manager Integration Guide provides a detailed example of how to integrate the Access System with the SharePoint Portal Server (SPPS) and the extra measures you may have to take to get impersonation running in different contexts:

• Configuring IIS Security

• Configuring the Wildcard Extension

• Editing web.config (this is not needed with the integration between the Access System and the Microsoft Content Management Server)

20.5 Enabling Impersonation with a User Name and Password

The method to enable impersonation before version 6.5 remains valid and may also be used with version 6.5 and later, as described in the following paragraphs.

The Access System provides an API that tells IIS which user to impersonate. To use this API, you must provide the user name and password to IIS. The user name is used in the proper header variables. This causes IIS to change the owner of the thread for downstream applications.

To have IIS log in as the user, you set the following two success actions in the authorization policy:

• LOGON_USER: The NT user name of the user you want to impersonate

• LOGON_PASSWORD: The NT password of the user.

The LOGON_PASSWORD is not set as a header variable. This prevents downstream applications from learning the password. This variable is only used to impersonate the user. The following are methods for providing the Windows NT or Active Directory (AD) password:

• Store the NT or AD password in clear text in the directory, then configure the Access System security policy to set the proper header variable with the password value.

• Store the password in a separate database. This requires an authorization plug-in to be written to access the password and set the appropriate header variable. The authorization plug-in supplies the action with the password. The store would have to be kept synchronized using the Identity System's PPP mechanisms.

• Create a static header variable that impersonates the user for a particular role (for instance, manager) that provides the proper security settings. This provides a more granular option if you do not require the actual individual to be impersonated.

The Access System supports additional IIS header variables for integration with Microsoft environments and Windows Impersonation, as shown in Table 20-3.

Table 20-3 Support for Additional IIS Header Variables

REMOTE_USER	AUTH_USER	AUTH_PASSWORD	AUTH_TYPE

These are special case headers that show downstream applications that the user is logged in. If you set the REMOTE_USER header by creating a REMOTE_USER http header action, the Access System will set the AUTH_USER and AUTH_PASSWORD headers. You set REMOTE_USER in the same place as LOGON_USER and LOGON_Password, as a success action in the authorization policy. Setting this action accomplishes the following for each of the variables:

• The REMOTE_USER will contain the static or attribute value

• The AUTH_USER will have the same value

• The AUTH_PASSWORD header will always contain HiddenByOblixNetpoint so the password remains hidden

• The AUTH_TYPE header will contain Basic

For more information:

• See "Windows Impersonation Background" for an introduction to access tokens, security IDs, access control lists, wildcard extensions, and Kerberos.

• See the Microsoft documentation for details about single sign-on integration through Windows Impersonation.

20.6 Setting Up Impersonation for OWA

In a distributed Exchange/OWA single sign-on environment, each server needs the Access System to impersonate the current user. When you enable Impersonation, you need to include additional HTTP Headers in "Authorization Success" for your impersonation policy domain:

The following solution has been tested in both standalone and distributed OWA environments.

Task overview: Setting up impersonation for OWA

1. Install Oracle Access Manager, including a WebGate on the OWA front-end server and on all Exchange back-end servers, as described in the Oracle Access Manager Installation Guide.

2. Disable IP Checking for the WebGates on the back-end server using the AccessGate (because the request comes from the front-end server, not from the user's browser).

3. Create a trusted user account for only impersonation in the Active Directory, as described in "Creating a Trusted User Account for OWA".

4. Give the trusted user the special right to act as part of the operating system, as described in "Assigning Rights to the OWA Trusted User".

5. Bind the trusted user to the WebGate by supplying the authentication credentials for the trusted user, as described in "Binding the Trusted OWA User to Your WebGate".

6. Add a header variable named impersonate to Authorization Success Action in the policy domain for impersonation, as described in "Adding an Impersonation Action to a Policy Domain".

7. Configure IIS by adding IISImpersonationExtension.dll to your IIS configuration, as described in "Adding an Impersonation dll to IIS".

8. Test Impersonation, as described in "Testing Impersonation for OWA".

20.6.1 Creating a Trusted User Account for OWA

This special user should not be used for anything other than impersonation.

Oracle recommends that you chose a very complex password, because your trusted user is being given very powerful permissions. Also, be sure to check the box marked Password Never Expires. Since the impersonation extension should be the only entity that ever sees the trusted user account, it would be very difficult for an outside agency to discover that the password has expired.

To create a trusted user account for OWA

1. On the Windows 2003 machine, select Start; Programs; Manage Your Server; Domain Controller (Active Directory); Manage Users and Computers in Active Directory.

2. In the Active Directory Users and Computers window, right-click Users on the tree in the left pane, then select New; User.

3. In the First name field of the pane entitled New Object - User, enter an easy-to-remember name such as OWAImpersonator.

4. Copy this same string to the User logon name field, then click Next.

5. In succeeding panels, you will be asked to choose a password and then retype it to confirm.

6. Proceed to "Assigning Rights to the OWA Trusted User".

20.6.2 Assigning Rights to the OWA Trusted User

You need to give the trusted user the right to act as part of the operating system.

To give appropriate rights to the trusted user

1. Select Control Panel; Administrative Tools; Domain Controller Security Policy.

2. On the tree in the left pane, click the plus icon (+) next to Local Policies.

3. Click User Rights Assignment on the tree in the left pane.

4. Double-click "Act as part of the operating system" in the right pane.

5. Click Add User or Group.

6. In the Add User or Group panel, type the User logon name of the trusted user (OWAImpersonator in our example) in the User and group names text entry box, then click OK to register the change.

7. Proceed to "Binding the Trusted OWA User to Your WebGate".

20.6.3 Binding the Trusted OWA User to Your WebGate

You need to bind the trusted user to the WebGate by supplying the authentication credentials for the trusted user, as described in the following procedure.

To bind your trusted OWA user to your WebGate

1. Point your browser to your Access System Console. For example:

   http://hostname.domain.com:port/access/oblix

   where hostname is the DNS name of the machine hosting your Policy Manager; domain is the name of the server domain to which the machine belongs; and port is the number of the port to which Policy Manager listens.

2. Navigate to Access System Console, Access System Configuration, AccessGate Configuration.

3. Select the name of the Webgate you want to modify.

   The Details for AccessGate page appears with a summary of the configuration information for this WebGate. At the bottom of this Web page are fields for Impersonation Username and Impersonation Password.

4. Click the Modify button at the bottom of the Details for AccessGate page.

   The Modify AccessGate page appears.

5. Scroll to the bottom and enter the user name and password for the trusted user account you created (OWAImpersonator).

6. Click the Save button to commit the changes and return to the Details page.

   A bind has been created for the WebGate and the trusted user. The WebGate is now ready to provide impersonation on demand. The demand is created by an Authorization Success Action in a policy domain created for impersonation.

7. Proceed to "Adding an Impersonation Action to a Policy Domain".

20.6.4 Adding an Impersonation Action to a Policy Domain

You must create or configure a policy domain to protect your OWA resources. This policy must set several HTTP Header variables.

Note:

You should choose an easy-to-remember name for the domain, such as ImpersonationPolicyDomain.

To add an impersonation action to your policy domain

1. Navigate to the Access System Console and log in. For example:

   http://hostname.domain.com:port/access/oblix
   

   where hostname is the DNS name of the machine hosting your WebPass and Policy Manager; domain is the name of the server domain to which the machine belongs; and port is the number of the port to which Policy Manager listens.

2. Navigate to the Authorization Definitions page of the policy domain you want to change:

   Policy Manager; My Policy Domains; PolicyName; Authorization Rules

   where PolicyName refers to the policy domain you created specifically for impersonation (ImpersonationPolicyDomain in this example).

3. Currently defined authorization rules are listed. If none are listed, click the Add button and complete the form to create one.

4. Click the link to the rule to which you want to add the impersonation action to expand the description.

5. Click the Actions tab, directly under the Authorization Rules tab.

   The Authorization Success page appears, with a separate section for Authorization Success and Authorization Failure. If no actions are identified, you must add them. If actions are provided, you can modify them.

   You need to add header variables named "impersonate", "auth_type", "remote_user", and "npusername" to the Authorization Success Action in the policy domain for impersonation.

6. On the Authorization Success page, click the Add or Modify button.

7. In the Authorization Success area, fill in the Return details.

   Type: HeaderVar Name: IMPERSONATE Return value: uid (or samaccountname)

   Type: HeaderVar Name: AUTH_TYPE Return value: NTLM

   Type: HeaderVar Name: REMOTE_USER Return value: uid (or samaccountname)

   Type: HeaderVar Name: NPUSERNAME Return value: uid (or samaccountname)

8. Save the rule, which is used for the second WebGate request for authorization.

9. Proceed with an "Adding an Impersonation dll to IIS".

20.6.5 Adding an Impersonation dll to IIS

You are ready to configure IIS by adding the IISImpersonationExtension.dll to your IIS configuration.

To add the impersonation dll to your IIS configuration

1. Select Start; Administrative Tools; Internet Information Services (IIS) Manager.

2. Click the plus icon (+) to the left of the local computer icon on the tree in the left pane.

3. Click Web Service Extensions on the tree in the left pane.

4. Double-click WebGate in the right panel to open the Properties panel.

5. Click the Required Files tab.

6. Click Add.

7. In the Path to file text box, type the full path to IISImpersonationExtension.dll.

   An example:

   WebGate_install_dir\access\oblix\apps\webgate\bin\IISImpersonation\ Extension.dll
   

   where WebGate_install_dir is the directory of your WebGate installation.

   Note:

   If any spaces exist in the path (for example, C:\Program Files\Oracle\...) surround the entire string with double quotes (" ")

8. Click OK.

9. Add the IISImpersonationExtension.dll in Wildcard Application Maps for the Exchange virtual directory, as follows.

   From the Internet Services Manager, go to WebSite/Virtual Directory Properties, then to the Home Directory, then to Configuration, then to Mappings, and add IISImpersonationExtension.dll in Wildcard Applications maps.

   IISImpersonationExtension.dll should be the first entry in the wildcard application maps order.If you add IISImpersonationExtension.dll to the WebSite level, the wildcard application maps for the Exchange virtual directory is overridden and the existing OWA-related extensions are removed at the Exchange virtual directory level. This causes OWA to fail. To retrieve the OWA settings, see the Microsoft knowledge base article at the following URL:

   http://support.microsoft.com/kb/298513.

10. Verify that the Allow button to the left of the WebGate icon is greyed out, which indicates that the dll is allowed to run as a Web service extension.

    Note:

    If Allow is not greyed out, click it so that it becomes greyed out.

11. Proceed to "Testing Impersonation for OWA".

20.6.6 Testing Impersonation for OWA

The following options are provided to test the Impersonation configuration for OWA.

• Testing Impersonation Using the Event Viewer

• Testing Impersonation using a Web Page

20.6.6.1 Testing Impersonation Using the Event Viewer

To test impersonation through the Event Viewer

1. Select Start Menu; Event Viewer.

2. In the left pane, right-click Security, then click Properties.

3. Click the Filter tab on the Security property sheet.

4. Verify that all Event Types are checked, and the Event Source and Category lists are set to All, then click OK to dismiss the property sheet.

5. Your Event Viewer is now configured to display information about the headerVar associated with a resource request.

6. Create a new IIS virtual server (virtual site).

7. Place a target Web page anywhere in the tree on the virtual site.

8. Point your browser at the Web page.

   If impersonation is working correctly, the Event Viewer will report the success of the access attempt.

20.6.6.2 Testing Impersonation using a Web Page

You can also test impersonation using a dynamic test page, such as an .asp that can return and display information about the request.

To test impersonation through a Web page

1. Create an .asp page or perl script that will display the parameters AUTH_USER and IMPERSONATE, which can resemble the sample page presented in the following listing:

   <TABLE border=1>
   <TR>
   <TD>Variable</TD>
   <TD>&nbsp&nbsp</TD>
   <TD>Value</TD></TR>
   <%for each servervar in request.servervariables%>
   <TR>
   <TD><%=servervar%></TD>
   <TD>&nbsp&nbsp</TD>
   <TD><%=request.servervariables(servervar)%>&nbsp</TD>
   </TR>
   

2. Create an IIS virtual site, or use the one you created for the previous task.

3. Place an .asp page or perl script (such as the sample in the preceding listing) anywhere in the tree of the new virtual site.

4. Point your browser at the page, which should appear, with both AUTH_USER and IMPERSONATE set to the name of the user making the request.

20.7 Windows Impersonation Background

The information here provides a simple overview of several Windows impersonation concepts. Topics include:

• Access Tokens

• Security IDs

• Access Control Lists and Entries

• Wildcard Extension

• The Kerberos Protocol

• The S4U2Self Extension

For more information, see your Microsoft documentation.

20.7.1 Access Tokens

The access token describes the security context of a process or thread and includes the identity and privileges of the user account associated with the process or thread. The access token is created when authentication is successful. For example:

• The logon process returns a security ID (SID) for the user and a list of SIDs for the user's security groups.

• The Local Security Authority (LSA) creates an access token that includes:

  • The SIDs returned by the logon process

  • A list of privileges assigned to the user and to the user's security groups by local security policy

A copy of the access token is attached to every process and thread that is executed on the user's behalf. When a thread interacts with a securable object, or tries to perform a system task that requires privileges, the operating system checks the access token associated with the thread to determine its level of authorization.

20.7.2 Security IDs

A security ID (SID) is a unique value of variable length used to identify a security principal or security group. SIDs are equal to Access System single sign-on tokens and represent a unique user within the Windows operating system.

The SID that identifies a particular account or group is generated by the system at the time the account or group is created. As mentioned previously, the SID for a local account or group is generated by the Local Security Authority (LSA) and stored with other account information in a secure area of the registry. The SID for a domain account or group is generated by the domain security authority and stored as an attribute of the User or Group object in Active Directory.

SIDs are unique within the scope of the account or group they identify. The SID for every local account and group is unique on the computer on which it was created. No two accounts or groups on the same machine can have the same SID. The SID for every domain account and group is unique within an enterprise. The SID for an account or group created in a domain never matches the SID for any other account or group created in the same domain.

One or more SIDs are included:

• In access tokens, where one SID identifies the user represented by the token and additional SIDs identify the security groups to which the user belongs.

• In security descriptors, where one SID in an object's security descriptor identifies the object's owner and another SID identifies the owner's primary group.

• In access control entries (ACEs), the SID identifies the user or group for whom access is allowed, denied, or audited.

20.7.3 Access Control Lists and Entries

An access control list (ACL) contains an ordered list of access control entries (ACEs) that define the policies used to control access to resources, such as directories and applications protected by the Access System.

All ACLs are based on your logon identity. An object's security descriptor can contain two ACLs:

• A discretionary access control list (DACL) that identifies the users and groups who are allowed or denied access

• A system access control list (SACL) that controls how access is audited

Each ACE includes:

• The type of the ACE (generic vs. object specific)

• Child-object inheritance attributes

• Access rights

• A SID that identifies a user or group

20.7.4 Wildcard Extension

The Web server normally runs in a security context called "IWAM_xxx" This security context does not have rights to impersonate another user. The Access System designates a special user that does have the right to impersonate another user by configuring it using the impersonation username/password on the AccessGate configuration page. That designated user must have "act as operating system" rights, as explained elsewhere.

The wildcard extension for the impersonation DLL behaves like a filter, which means that the wildcard extension is enabled for each request to the Web server. The DLL executes after WebGate, after all filters, and before any downstream applications.

20.7.5 The Kerberos Protocol

The Kerberos protocol defines how clients interact with a network authentication service. The client obtains a ticket from the Kerberos Key Distribution Center (KDC). The Kerberos ticket represents the client's network credentials. The ticket is presented to a server when the connection is established.

The Kerberos protocol handles all domain lookups in all trusted domains. As the client's identity, this protocol uses:

• The Active Directory domain name

• User name

• Password

The initial ticket that is obtained from the KDC when the user logs on is based on an encrypted hash of the user's password. This initial ticket is cached.

When the user tries to connect to a server, the Kerberos protocol checks the ticket cache for a valid ticket for that server. If one is not available, the initial ticket for the user is sent to the KDC along with a request for a ticket for the specified server. That session ticket is added to the cache and can be used to connect to the same server until the ticket expires.

20.7.6 The S4U2Self Extension

Windows Server 2003 domain controllers accept a new type of Kerberos request, the Service-for-User-to-Self (S4U2Self) extension. This extension enables the service to request a ticket from the client to itself, presenting its own credentials instead of the client's.

20.8 Negative Testing for Impersonation

To conduct negative testing for impersonation, you need to unbind the trusted user from the WebGate, as explained in the following procedure.

To unbind the trusted user from your WebGate

1. Log in to the Access System Console at a URL similar to the following:

   http://hostname.domain.com:port/access/oblix

   Where hostname is the DNS name of the computer hosting your Access Manager, domain is the name of the server domain to which the machine belongs, and port is the number of the port to which Access Manager listens.

2. Select Access System Console, then click Access System Configuration, then click AccessGate Configuration.

3. Select the name of the Webgate that you want to modify.

   The Details for AccessGate page appears with a summary of the configuration information for this WebGate. At the bottom of this Web page are fields for Impersonation Username and Impersonation Password.

4. Click the Modify button at the bottom of the Details for AccessGate page.

   The Modify AccessGate page appears.

5. Remove the credentials for the trusted user.

6. Click Save.

   You return to the Details page.

7. Restart the IIS server.

8. Point your browser at a protected code page that previously was accessible to the trusted user.

   An error message page should appear. Values for AUTH_USER and IMPERSONATE are necessary for impersonation credentials to be bound to a WebGate.