32 Managing Impersonation

Manage and configure WebCenter Portal Impersonation, which lets designated WebCenter Portal users impersonate other users and perform operations as those users.

For instructions on how to initiate an impersonation session (by the impersonator) and how to allow an Impersonation session (by the impersonatee), see Using WebCenter Portal Impersonation in Oracle Fusion Middleware Using Oracle WebCenter Portal. For information about impersonation ELs and APIs, see ELs Related to Impersonation in Oracle Fusion Middleware Developing WebCenter Portal Assets and Custom Components with Oracle JDeveloper.

Permissions:

To perform the tasks in this chapter, you must be granted the WebLogic Server Admin role through the Oracle WebLogic Server Administration Console. Users with the Monitor or Operator roles can view security information but cannot make changes.

See also, Understanding Administrative Operations, Roles, and Tools.

Topics:

32.1 Introduction to WebCenter Portal Impersonation

This section includes the following topics:

32.1.1 About WebCenter Portal Impersonation

WebCenter Portal Impersonation lets a WebCenter Portal administrator or system administrator assign impersonation rights to a group of users ("impersonators"), such as support representatives or application administrators, so that they can perform operations as other users ("impersonatees"). Note that this is subject to the impersonatee granting the impersonator additional rights to impersonate them. This may be useful in the following instances:

  • A customer support representative may want to perform actions as another user in order to understand the issues being faced by that user.

  • An administrator may want to perform operations on behalf of a user.

  • A company executive may need to delegate someone to act on his or her behalf while away.

32.1.2 Best Practices for Using WebCenter Portal Impersonation

All applications participating in Oracle Access Manager (OAM) from an impersonatee's system will also be accessible to an impersonator. The only exception to this is that an impersonator will not be able to access the Impersonation task flow and grant or modify impersonation rights. Consequently, administrators should exercise extreme caution when granting impersonation rights because of what an impersonator could potentially access. Impersonators should be a very limited group.

Audit logging should be turned on for impersonation and the administrator should monitor the audit logs periodically to review the impersonation activities. For more information about audit logging, see Managing Audit Logs for WebCenter Portal Impersonation.

To initiate an impersonation session the impersonatee and impersonator should agree on an appropriate time slot for the impersonation session. The impersonatee should then grant impersonation rights for that time slot only. The impersonatee should revoke impersonation rights immediately after the impersonator is done.

Note that an impersonation session will end if the impersonator logs out. An impersonation session will also end when the specified impersonation time duration end point is reached. For example, if a user grants impersonation rights to an impersonator between 1:00 and 2:00 in the afternoon, although the impersonator can start an impersonation session anytime between 1:00 and 2:00, the session will end at 2:00.

Also note that if a user revokes an impersonation grant explicitly while the impersonator is in the middle of an impersonation session, the revoke will not affect any existing impersonation session for that user. It will only take effect the next time the impersonator tries to impersonate the user. The user will then not appear in the list of available impersonatees.

32.2 Preparing WebCenter Portal for Impersonation

WebCenter Portal impersonation relies on OAM 11.1.2.0. Before you can enable impersonation for a WebCenter Portal instance you must first install and configure OAM 11g (Oracle's single sign-on solution), and then turn on impersonation in OAM. For information about installing and configuring OAM 11g, see Configuring Oracle Access Manager.

This section includes the following topics:

32.2.1 WebCenter Portal Impersonation Requirements

To prepare WebCenter Portal for impersonation, you must first install and configure OAM 11.1.2.0 and then turn on impersonation in OAM. You will also need to add impersonation attributes for each participating user.

Note:

WebCenter Portal Impersonation requires that OAM 11.1.2.0 be installed and configured as the single sign-on solution, and that OID 11.1.2.0 is installed and configured as the identity store.

  • Install and configure OAM 11.1.2.0 with either the 10g or 11g WebGate (see Configuring Oracle Access Manager)

  • Turn on impersonation

  • Add impersonation attributes to each participating user in the identity store

  • Configure each participating WebCenter Portal instance for impersonation

  • Configure the people who have impersonation rights by adding them to a WebCenter Portal role

32.2.2 Turning on Impersonation in OAM

After installing and configuring OAM 11.1.2.0 (with either the 10g or 11g WebGate) as described in Configuring Oracle Access Manager, continue by enabling impersonation in OAM using idmConfigTool as shown below.

To enable impersonation:

  1. Use idmConfigTool to configure OAM
  2. Create the properties file as shown, but set OAM11G_IMPERSONATION_FLAG to true.

32.2.3 Adding Impersonation Attributes to the Identity Store

For users to be available as impersonators or impersonatees they need to have the following attributes available for storing the impersonation grants in OID:

  • orclImpersonationGrantee

  • orclImpersonationGranter

These attributes are a part of the orclIDXPerson object class that is available by default in OID. This object class must be added to the list of object classes for each user's user record that you want to participate as an impersonator or impersonatee. You can do this either by adding the object class to individual users, or as a bulk update for multiple users as described in the following topics:

32.2.3.1 Adding Impersonation Attributes for Individual Users

Follow the steps below to add the attributes for storing the impersonation grants in OID for individual users:

To add the object class to individual users:

  1. Log in to ODSM (typically http://host:port/odsm).

  2. Connect to the directory that is configured for OAM and WebCenter.

  3. For each participating user:

    1. Locate the user you want to change by drilling down in the DataBrowser, or by using the DataBrowser's search field.

    2. Open the Attributes screen and add the orclIDXPerson object class to the list of existing object classes as shown in Figure 32-1.

      Figure 32-1 ODSM Attributes Tab

      Description of Figure 32-1 follows
      Description of "Figure 32-1 ODSM Attributes Tab"

    3. Click Apply.

32.2.3.2 Adding Impersonation Attributes for Multiple Users

You can add the attributes available for storing the impersonation grants in OID as a bulk update using the bulkmodify tool. Note that to use this tool you need to be able to access the machine where OID is installed, have system administrator rights, and need to know the OID database password.

To add the attributes for storing impersonation grants in OID for multiple users:

  1. Stop OID.
  2. Go to $ORACLE_HOME/ldap/bin and run the bulkmodify tool.

    Specify basedn as the DN under which all users you wish to add the object class reside. The connect string is the OID DB connect string, which is typically OIDDB (determined from $ORACLE_INSTANCE/config/tnsnames.ora). Provide the DB password when prompted. The following shows a sample run of the command:

    bulkmodify connect="OIDDB" basedn="cn=Users,dc=us,dc=oracle,dc=com" attribute="objectclass" value="orclIDXPerson" add=true
This tool can only be executed if you know database user password for OID
Enter OID Password ::
 
------------------------------------------------------------
Modifying entries under "cn=users,dc=us,dc=oracle,dc=com" ...
------------------------------------------------------------
 
------------------------------------------------------------
Total 72 Entries are modified.
  3. Restart OID.

    All users under the specified DN should now have the orclIDXPerson object class configured. For more information about the bulkmodify tool, see Reference for Oracle Identity Management.

32.3 Configuring WebCenter Portal for Impersonation

After installing and configuring OAM and enabling Impersonation in OAM, you need to configure the OAM Impersonation trigger end points in your WebCenter Portal instance as shown below:

  1. Using WLST, connect as administrator to the Weblogic Administration Server and run the following command replacing oamhost and oamserverport with the corresponding host ID and port for OAM:

    addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication", logouturi="/oamsso/logout.html",
beginimpuri="http://oamhost:oamserverport/oam/server/impersonate/start",
endimpuri="http://oamhost:oamserverport/oam/server/impersonate/end")

  2. Restart all servers in the WebCenter Portal domain, including the Admin Server.

  3. You may also need to account for any time difference between your WebCenter Portal server and OAM. Although Impersonation start and end times are accepted in WebCenter Portal, they are enforced by OAM so the time settings must be consistent. To account for time differences:

    1. Log into WebCenter Portal as an administrator.

    2. Select Administration > Attributes.

      The Attributes page displays.

      Tip:

      You can also access the Attributes page directly by opening the page in your browser:

      http://host:port/webcenter/faces/oracle/webcenter/webcenterapp/view/pages/admin/WebCenterAdmin-CustomAttributes.jspx

      where host and port are the host and port IDs of the WC_Portal server.

    3. Specify the Impersonation time Delta in seconds using a + sign if the WebCenter Portal server is behind the OAM server, or a - sign if it is ahead. For example:

      oracle.webcenter.security.impersonation.timedelta = -480

      would indicate that there is a time difference of eight minutes between OAM and WebCenter Portal with the WebCenter Portal server being ahead.

      Tip:

      You can also add the setting to the $domain.home/bin/setDomainEnv.sh file:

      EXTRA_JAVA_PROPERTIES="-Doracle.webcenter.spaces.osso=true
-Doracle.webcenter.security.impersonation.timedelta=-480"
export EXTRA_JAVA_PROPERTIES

    4. Restart the WebCenter Portal managed server (WC_Portal).

32.4 Configuring Impersonators

After configuring OAM and WebCenter Portal, you must configure the users to whom you want to grant impersonation privileges by adding those users or groups to the webcenter#-#impersonators role. Out-of-the-box, no users are granted this role. Only users belonging to this role either by direct membership or through an enterprise role membership are eligible to impersonate users in a WebCenter Portal instance.

Caution:

Use caution when granting rights to users that would allow them to impersonate other users. Only users that have a business need for this feature should be granted impersonation rights. For information about best practices, see Best Practices for Using WebCenter Portal Impersonation.

Use the grantAppRole WLST command to grant the webcenter#-#impersonators role to one or more enterprise roles or users. For example:

  • To grant the impersonators role to an enterprise role called SupportRepresentatives:

    grantAppRole(appStripe="webcenter", appRoleName="webcenter#-#impersonators", principalClass="weblogic.security.principal.WLSGroupImpl", principalName="SupportRepresentatives")

  • To grant the impersonators role to a user named weblogic:

    grantAppRole(appStripe="webcenter", appRoleName="webcenter#-#impersonators", principalClass="weblogic.security.principal.WLSUserImpl", principalName="weblogic")

Use the revokeAppRole WLST to revoke impersonator permission from an enterprise role or user. For example:

  • To revoke the impersonators role from an enterprise role called SupportRepresentatives:

    revokeAppRole(appStripe="webcenter", appRoleName="webcenter#-#impersonators", principalClass="weblogic.security.principal.WLSGroupImpl", principalName="SupportRepresentatives")

  • To revoke the impersonators role from a user named weblogic:

    revokeAppRole(appStripe="webcenter", appRoleName="webcenter#-#impersonators", principalClass="weblogic.security.principal.WLSUserImpl", principalName="weblogic")

Note:

Changes to role assignments are available immediately. You do not need to restart the managed server.

32.5 Disabling Impersonation

WebCenter Portal Impersonation is disabled by default, so unless you have already enabled impersonation there is nothing that needs to be done to turn it off. However, if you have enabled it and now want to disable it, follow the steps below to turn it off in WebCenter Portal and OAM.

Note that turning off impersonation in WebCenter Portal only disables it for that particular instance. Any other WebCenter Portal instances for which impersonation was enabled will not be affected until you turn off impersonation in OAM.

To disable impersonation for WebCenter Portal:

  1. Log into Fusion Middleware Control as an administrator.

  2. Go to WebCenter Domain > Security > Security Provider Configuration.

  3. Navigate to the Properties section and click Configure.

  4. Under PropertySets, locate the property set that defines the impersonation start and stop URIs (typically "props.auth.uri.0").

  5. Delete the properties imp.begin.url and imp.end.url.

  6. Restart all servers in the WebCenter Portal domain, including the Admin server.

    Note that until you disable impersonation in OAM, impersonation in other WebCenter Portal domains will continue to be enabled.

To disable impersonation in OAM and turn off impersonation altogether:

  1. Back up the DOMAIN_HOME/config/fmwconfig/oam-config.xml file.
  2. Open the oam-config.xml file for editing.
  3. Set ImpersonationConfig to false as shown below: 
    <Setting Name="ImpersonationConfig"Type="htf:map"> <Setting Name="EnableImpersonation"Type="xsd:boolean">false</Setting> </Setting>
  4. Save oam-config.xml.
  5. Restart OAM and all of its components.

32.6 Turning off the Session Indicator

The session indicator is an overlay that appears on the impersonator's screen by default during an impersonation session. Although the overlay provides a visual clue that the impersonation session is active, and also provides a quick way to stop the session by clicking Stop Impersonation, it may obstruct a view of part of the user's (impersonatee's) screen as show in Figure 32-2.

Note:

When the impersonation session notification toolbar is turned off, users must use the Impersonation page to stop an impersonation session since the Stop Impersonation button will no longer be visible.

Figure 32-2 Impersonation Session - Session Indicator Overlay

Description of Figure 32-2 follows
Description of "Figure 32-2 Impersonation Session - Session Indicator Overlay"

You can turn off the session indicator overlay as shown below:

To turn off the session indicator:

  1. Log into WebCenter Portal as an administrator.
  2. Select Administration > Attributes.

    The Attributes page displays.

    Tip:

    You can also access the Attributes page directly by opening the page in your browser:

    http://host:port/webcenter/faces/oracle/webcenter/webcenterapp/view/pages/admin/WebCenterAdmin-CustomAttributes.jspx

    where host and port are the host and port IDs of the WC_Portal server.

  3. Set the notification property to false as shown below: 
    oracle.webcenter.security.impersonation.notification=false

    Note that impersonators will now need to end impersonation sessions using the Impersonation Preferences screen. For more information about using the Impersonation Preferences screen, see Using WebCenter Portal Impersonation in Oracle Fusion Middleware Using Oracle WebCenter Portal.

  4. Restart the WC_Portal managed server for the change to take effect.

32.7 Overriding the Impersonation Hotkey

The default Ctrl+Shift+I hotkey sequence used by the impersonator to view the list of impersonatees can be overridden, if needed.

To change the hotkey sequence:

  1. Log into WebCenter Portal as an administrator.
  2. In the portal browser, click the Administration tile, then click Attributes in the left pane.

    Tip:

    You can also access the Attributes page directly by opening the page in your browser:

    http://host:port/webcenter/faces/oracle/webcenter/webcenterapp/view/pages/admin/WebCenterAdmin-CustomAttributes.jspx

    where host and port are the host and port IDs of the WC_Portal server.

  3. On the Attributes page, click Add Attribute, and set the new hotkey sequence as follows: 
    oracle.webcenter.security.impersonation.key=new key

    where new key is a single character to be appended to Ctrl+Shift. Note that you can only override the default I with another single character. The Ctrl+Shift sequence is predefined and will always precede the key. Be sure to check that the overridden character is not already used by other components, tools or plug-ins. For example, Ctrl+Shift+M is used by menus, and Ctrl+Shift+K and Ctrl+Shift+J are sometimes used by browser plug-ins such as developer tools and the error console.

  4. Restart the WC_Portal server for the change to take effect.

32.8 Managing Audit Logs for WebCenter Portal Impersonation

WebCenter Portal Impersonation, when enabled, activates logging for Impersonation-related events as part of the Fusion Middleware Audit Service. Audit log events are stored in a file (the Audit Bus-stop) by default, but can also be uploaded to a database for persistency.

Note:

If you enable WebCenter Portal Impersonation, it is highly recommended that you also enable audit logging. When Impersonation is enabled, audit logging tracks the impersonator, impersonatee, and the context surrounding each impersonation event.

The Audit Bus-stop file has a limited capacity so storing log information in a database where events can be queried long after their occurrence is also recommended.

Impersonation audit logging provides the following key benefits:

  • Events that alter the security settings of Portal, Portal Server, and major Portal Server artifacts are traceable

  • Auditable events contain all relevant event payload to help define the impersonator, impersonatee and the context surrounding an event

  • Definable logging levels

  • Events logged are available in perpetuity when uploaded to a database

  • Reports on audit events are available through the Audit Service

For more information about managing audit logging for WebCenter Portal, see Managing WebCenter Portal Audit Logs. For information about configuring the Audit Service to use a database, see Configuring and Managing Auditing in Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services.