60.3 Enabling Impersonation With a Header Variable

Enabling impersonation with a header variable involves completing the procedures in the following sections.

1. Reviewing all Requirements for Impersonation with a Header Variable

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 Response to An Application Domain

6. Adding an Impersonation DLL to IIS

7. Testing Impersonation

See Also:

"Setting Up Impersonation for Outlook Web Application (OWA)".

60.3.1 Requirements for Impersonation with a Header Variable

Prepare the environment and confirm that it is operating properly before implementing Windows impersonation with the OAM Server.

Table 60-1 identifies the Access Manager platform requirements when you enable impersonation using a header variable.

Table 60-1 Requirements for Impersonation with a Header Variable

Item	Platform
11g WebGate (and Impersonation dll)	Microsoft IIS 7.x and Windows Server 2008 and 2013
Impersonation dll	Webgate_install_dir\webgate\iis\lib\IISImpersonationModule.dll Must be installed as an IIS Module. May be installed at any level of the Web site tree.
Kerberos Key Distribution Center (KDC) and Active Directory	Windows Server 2008 and 2013
Client and Server machines	Both must be in the same Windows Server 2008 domain with a trust relationship. A bi-directional 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
Mutual authentication is required	Mutual authentication is supported remotely.

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

The example in the following procedure uses SPPSImpersonator as the New Object - User. With OWAImpersonator as SPPSImpersonator denotes SharePoint impersonation specifically. Your environment will be different.

1. Perform the steps for your environment on the computer hosting your Microsoft Exchange Server 2013 installation:

   • Windows 2008 or 2012: 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 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 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 60-1 Setting up a Trusted User Account for Windows Impersonation

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

60.3.3 Assigning Rights to the Trusted User

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

To assign rights to the trusted user:

1. Perform the appropriate step for your environment:

   • Windows 2008: Select Start > Programs > Administrative tools > Local Security Policy.

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

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 (Microsoft Exchange Server 2010 Impersonator in our example) in the User and group names text entry box, then click OK to register the change.

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

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

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

The procedure presumes that you have registered an 11g WebGate with Access Manager. The values in the procedure are provided as an example only. Your environment will be different.

See Also:

Registering and Managing OAM 11g Agents

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. In the Launch Pad tab, click Agents.
3. Find the desired 11g WebGate registration to modify for this integration:

   • Find All Enabled: Select State All, click the Search button, click the desired Webgate name in the results list.

4. On the WebGate registration page, enter the SharePoint username and password for the trusted user account, which you created earlier.
5. Click Apply to commit the changes.

   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 the application domain created for impersonation.

60.3.5 Adding an Impersonation Response to An Application Domain

You must create or configure an application domain to protect your OWA resources.

For this you must add Responses in Authorization Policies (Header type Responses), as described in this procedure.

See Also:

Managing Policies to Protect Resources and Enable SSO in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

The procedure presumes that you have an application domain created for the 11g WebGate you registered. The application domain in this example is MyImpersonationDomain. Your environment will be different.

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. Click Application Domains in the Access Manager section.
3. Search for and open the OWA Application Domain (the relevant application domain for impersonation).

   Navigate as follows:

   •         Authorization Policies
   •              Protected Resource Policy
   •                    Responses
4. Click the Add button, then Add Response.

   Complete the form as follows:

   • From the Type list, choose Header.

   • In the Name field, type a unique name for this response. For example, IMPERSONATE.

   • In the Value field, type a value for this response. For example, $user.userid.

5. Click Add, then click Apply to submit the changes.

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

60.3.6 Adding an Impersonation DLL to IIS

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

To add an Impersonation DLL to IIS:

1. Select Start > Administrative Tools > Internet Information Services (IIS) Manager.
2. In the left pane of IIS 7.x, click the hostname.
3. In the middle pane, under the "IIS" header, double click on "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\webgate\iis\lib\IISImpersonationModule.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 (" ").

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.
9. Remove the module from the Default site level (otherwise, it inherits when you add it on the machine level).
10. Ensure that the IISImpersonationModule.dll file added in these steps is applied only to "owa" and "ecp" applications and removed from the site level.

    Go to OWA, double-click modules, Configure Native Modules, and check the desired module (for example, Oracle Impersonation Module).

    Go to (ecp): Double-click modules, Configure Native Modules, and check the desired module (for example, Oracle Impersonation Module).

60.3.7 Testing Impersonation

You can test Impersonation using an Event Viewer or a web page.

Following are the two ways of testing Impersonation:

• Testing Impersonation Using the Event Viewer

• Testing Impersonation using a Web Page

60.3.7.1 Creating an IIS Virtual Site

To test the impersonation feature outside the Microsoft OWA 2010 context or to test single sign-on, you will need a target Web page on an IIS virtual Web site.

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

1. Click 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 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 an application domain, as described elsewhere in this guide.

60.3.7.2 Testing Impersonation Using the Event Viewer

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

To test impersonation:

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 60-3 Verifying Event Viewer Settings

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

60.3.7.3 Testing Impersonation using a Web Page

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

To test impersonation:

1. Create a .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:

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