59.6 Setting Up Microsoft Windows Impersonation

If you want to use a directory server other than Active Directory, use LDAP Membership provider. The OAMCustomMembership provider leverages the functionality of LDAP Membership provider.

This section describes how to set up impersonation, whether for SharePoint Server integration or for use by some other application.

Note:

Skip this section if you are integrating Microsoft SharePoint Server configured with LDAP Membership Provider. Windows impersonation is not used with the LDAP Membership Provider.

Task overview: Setting up impersonation

1. Create a trusted user account for only impersonation in the Active Directory connected to SharePoint Server, as described in "Creating Trusted User Accounts".
2. Give the trusted user the special right to act as part of the operating system, as described in "Assigning Rights to the Trusted User".
3. Bind the trusted user to the WebGate by supplying the authentication credentials for the trusted user, as described in "Binding the Trusted User to Your WebGate".
4. Add a header variable named IMPERSONATE to the Authorization Success Action in the Application Domain for impersonation, as described in "Adding an Impersonation Response to an Authorization Policy".
5. Configure IIS by adding the IISImpersonationModule.dll to your IIS configuration, as described in "Adding an Impersonation DLL to IIS".
6. Test impersonation, as described in "Testing Impersonation".

59.6.1 Creating Trusted User Accounts

You can create trusted user accounts. The special user should not be used for anything other than impersonation.

The example in the following procedure uses Impersonator as the New Object - User. Your environment will be different.

To create a trusted user account:

1. Perform the following steps on the computer hosting your SharePoint Server installation:

   • Windows 2008: Select Start, Programs, Administrative tools, Active Directory Users and Computers.

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 Impersonator.
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.

Note:

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 module 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 59-1 Setting up a Trusted User Account for Windows Impersonation

Description of "Figure 59-1 Setting up a Trusted User Account for Windows Impersonation"

59.6.2 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. Perform steps for your environment:

   • Windows 2008: Select Start, Programs, Administrative tools, Local 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 (SPPSImpersonator in our example) in the User and group names text entry box, then click OK to register the change.

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

Description of "Figure 59-2 Configuring Rights for the Trusted User in Windows Impersonation"

59.6.3 Binding the Trusted User to Your WebGate

You need to bind the trusted user to the 10g WebGate that communicates with Access Manager by supplying the authentication credentials for the trusted user.

The following procedure presumes that you have not yet registered a 10g WebGate with Access Manager. Values in the following procedure are provided as an example only. Your environment will be different.

To bind your trusted user to your WebGate

1. Go to the Oracle Access Management Console.

   For example:

   http://hostname:port/oamconsole
   

   where hostname is the fully-qualified DNS name of the computer hosting the Oracle Access Management Console; port is the listening port configured for the OAM Server; oamconsole leads to the Oracle Access Management Console.

2. Click Application Security at the top of the window.

3. In the Launch Pad tab, click SSO Agent Registration in the Quick Start Wizards section.

4. Select WebGate as the agent type and click Next..

5. Set the version to 10g and enter required details (those with an *) to register this WebGate.

6. Protected Resource List: In this table, enter individual resource URLs to be protected by this OAM Agent, as shown in Table 14–9.

7. Public Resource List: In this table, enter individual resource URLs to be public (not protected), as shown in Table 14–9.

8. Auto Create Policies: Check to create fresh policies (or clear and use the same host identifier as another WebGate to share policies (Table 14–9)).

9. Click Apply to submit the registration.

10. Check the Confirmation window for the location of generated artifacts, then close the window.

11. In the navigation tree, open the Agent page.

12. SharePoint Requirements: Enter trusted user credentials in the Sharepoint Impersonator fields and click Apply.

13. Copy the artifacts as follows (or install the WebGate and then copy these artifacts):

    1. On the Oracle Access Management Console host, locate the updated OAM Agent ObAccessClient.xml configuration file (and any certificate artifacts). For example:

       $DOMAIN_HOME/output/$Agent_Name/ObAccessClient.xml

    2. On the computer hosting the agent, copy the artifacts. For example

       • 10g WebGate/AccessClient: $WebGate_install_dir/oblix/lib/
       • ObAccessClient.xml

    3. Proceed to "Adding an Impersonation Response to an Authorization Policy".

59.6.4 Adding an Impersonation Response to an Authorization Policy

An Application Domain and basic policies to protect your SharePoint resources was created when you registered the WebGate with Access Manager. You must add an Authorization Success Action (Response) with a return type of Header, set the name to IMPERSONATE, with the Response value of $user.userid: "samaccountname" for a single-domain Active Directory installation or "userPrincipalName" for a multi-domain Active Directory forest.

To add an impersonation response to your Authorization Policy:

1. Click Application Security at the top of the Console window.
2. In the Launch Pad tab, click Application Domains in the Access Manager section.
3. Search for the desired domain and open it for editing.
4. Click the Authorization Policies tab and open the desired policy for editing.

   "Desired domain" refers to the Application Domain created specifically for impersonation (Impersonation for example). "Desired policy" is your default policy created during agent registration. By default, no policy Responses exist until you create them.

5. On the Policy page, click the Responses tab, click the Add (+) button, and:

   • From the Type list, choose Header.

   • In the Name field, enter a unique name for this response: IMPERSONATE

   • In the Value field, enter a value for this Response. For example: $user.userid.

6. Click Add to save the Response, which is used for the second WebGate request (for authorization).

59.6.5 Adding an Impersonation DLL to IIS

You can add an impersonation DLL to IIS.

You can configure IIS Web server for the integration by registering and configuring the IISImpersonationModule.dll across all sites including central administration and web services.

Alternatively, if you have multiple Web sites, where some are integrated with Access Manager while others are not, you might want to enable impersonation only for those Web sites that are integrated with Access Manager. To do this, you must configure the Native Module only at those sites that require integration. See:

• Configuring and Registering ImpersonationModule to IIS.

• Configuring Site Level Native Modules for Web Sites

59.6.5.1 Configuring and Registering ImpersonationModule to IIS.

You can configure and register ImpersonationModule to IIS

To configure and register ImpersonationModule to IIS

1. Select Start, Administrative Tools, Internet Information Services (IIS) Manager.
2. In the left pane of IIS 7, click the hostname.
3. In the middle pane, under the IIS header, double click Modules.
4. In the right pane, click Configure Native Modules and click Register.
5. In the window, provide a module Name (for example, Oracle Impersonation Module).
6. In the Path field, type the full path to IISImpersonationModule.dll.

   By default, the path is:

   WebGate_install_dir\access\oblix\apps\Webgate\bin\IISImpersonation
   

   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 (" ").

7. Click OK to register the module.
8. Check the name of the newly created module and click OK to apply the module across the Web sites.

Figure 59-3 Registering the Impersonation Module

Description of "Figure 59-3 Registering the Impersonation Module"

59.6.5.2 Configuring Site Level Native Modules for Web Sites

You can configure site level Native Modules for Web sites.

To configure:

1. Click the plus icon (+) icon to left of Sites.
2. Click the site where you want to enable Impersonation.
3. In the Middle pane, under IIS, double click Modules.
4. In the right pane, click Configure Native Modules and select the Impersonation Module registered earlier.
5. Click OK.
   
   Description of the illustration GUID-63267DAB-EC25-40E7-A0CE-B1349C5E7E1D-default.png
6. Proceed with:

   • Testing Impersonation

   • Completing the SharePoint Server Integration

59.6.6 Testing Impersonation

You can test to ensure that impersonation is working properly before you complete the integration.

Following are the ways to test impersonation:

• Outside the SharePoint Server context or test single sign-on, as described in "Creating an IIS Virtual Site Not Protected by SharePoint Server"

• Using the Event Viewer, as described in "Testing Impersonation Using the Event Viewer"

• Using a Web page, as described in "Testing Impersonation using a Web Page"

• Using negative testing as described in "Negative Testing for Impersonation"

See Also:

"Completing the SharePoint Server Integration" after confirming impersonation configuration is working properly

59.6.6.1 Creating an IIS Virtual Site Not Protected by SharePoint Server

To test the impersonation feature outside the SharePoint Server 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 SharePoint Server.

You create such a virtual Web site by completing the following task.

To create an IIS virtual site not protected by SharePoint Server

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. Right-click Web Sites on the tree in the left pane, then navigate to New, 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 policies in an Application Domain.

59.6.6.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 59-4 Verifying Event Viewer Settings

   
   Description of "Figure 59-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.

59.6.6.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, which can resemble the sample page presented in the following listing:

   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, which should appear, with both AUTH_USER and IMPERSONATE set to the name of the user making the request.

59.6.6.4 Negative Testing for Impersonation

To conduct negative testing for impersonation, you need to unbind the trusted user from the WebGate.

To unbind the trusted user from your WebGate:

1. In the Oracle Access Management Console, locate the WebGate.
2. Open the desired WebGate registration page and remove the credentials for the trusted user.
3. Click Apply to save the change.
4. Restart the IIS server and in a browser window, go to a protected code page (previously accessible to the trusted user).
5. Confirm that you receive an message page should appear. Values for AUTH_USER and IMPERSONATE are necessary for impersonation credentials to be bound to a WebGate.
6. Restore the trusted user to the WebGate registration page.