6 Developing an Application to Manage Impersonation

Access Manager impersonation support enables a user to designate other users to act on their behalf within a constrained time frame. While impersonation grants are natively supported by Access Manager, you will need to develop a custom user interface or modify an existing interface in order to manage impersonation grants. This chapter provides information about enabling impersonation and developing a custom user interface. It includes the following sections:

See Also:

"Integrating Oracle ADF Application with Oracle Access Manager 11g SSO" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

6.1 About Impersonation

Access Manager user impersonation feature enables one user to perform operations and access resources on the behalf of another. Impersonation grants, specified with a user identifier and start and end time, are required for a user to be able to impersonate another.

The following topics are discussed:

6.1.1 Impersonation Concepts and Terminology

Table 6-1 introduces common Access Manager impersonation concepts and terms.

Table 6-1 Impersonation Terminology

Term Definition

Impersonator

A user who acts on another user's behalf.

Impersonatee

The user who is being impersonated by another.

Impersonation grant

Security metadata created by the impersonatee to designate a particular impersonator to impersonate her within a specified time window.

Impersonation trigger

An act of an impersonator choosing to initiate an impersonation session on behalf of another user.

Access Manager impersonation session

A distinct type of Access Manager session that can be distinguished from regular user session by the target application.

Impersonation consent

A consent given by the impersonator to acknowledge the awareness that Access Manager impersonation session is in effect.


Access Manager user impersonation support allows an end user (the impersonatee) to designate one or more other users (impersonators) to act on her behalf within a constrained window of time. This information is collected using a custom user interface you develop, and persisted as a set of impersonation grants in the user directory.

The impersonator, while holding an authenticated session and interacting with a custom user interface, may choose to initiate an impersonation session on behalf of another named user. Access Manager performs required authorization checks to ascertain that the impersonator is allowed to impersonate the impersonatee. If allowed, the impersonation session is created.

The Access Manager-protected application behaves as if the impersonated user was accessing it. The application can determine whether the user is the impersonator or the impersonatee.

The impersonation session terminates when the impersonator chooses to do so through the application user interface. The impersonator will return to their regular user session and be able to access the application as himself once again. The impersonator is not allowed to switch the impersonatee user during his impersonation session (that is, nested or recursive impersonation is not allowed).

Access Manager provides the runtime enforcement of the impersonation semantics as described above, while all of the user interface aspects and associated metadata (impersonation grant) lifecycle are provided by your custom interface. The integration between Access Manager and a custom user interface can be codified in terms of the following three interfaces (touch points):

  • Impersonation grant syntax, persistence, and lifecycle

  • Impersonation trigger invocation

  • Impersonator identity communication during Access Manager impersonation session

6.1.2 Impersonation Grant Syntax

The following two impersonation grants are part of the orclIDXPerson object class:

  • orclImpersonationGrantee: If this attribute contains grants for a user, then that user can impersonate the current user. This is the attribute checked by OAM Server during an impersonation request.

  • orclImpersonationGranter: If this attribute contains grants for a user, then that user can be impersonated by the current user. This attribute is not used to enforce impersonation, it is used to start the impersonation session from the application.

Impersonation grants of an impersonatee are persisted in the user's record in the LDAP directory as a multi-valued attribute. Each of the values represents a specific grant to a named impersonator and a specified time window. Each value of the multi-valued attribute is a composite string, with individual fields delineated by a separator character. For this release, Oracle Identity Directory is supported when using impersonation feature.

You can create or modify a custom user interface to enable users to create, view, update, or delete impersonation grants within their user profile. The user interface must be constructed to persist impersonation grants in the designated LDAP directory in the multi-valued attribute named orclImpersonationGrantee. The format of individual values is <Impersonator orclGUID> | <begin LDAP timestamp> | <end LDAP timestamp> . For example:

orclImpersonationGrantee: xyz123abcd|20100604224517Z|20100604234517Z; 
klmn980nopr|20100604224517Z|20100604234517Z

In the following example, assume:

  • Impersonator: jdoe

  • Impersonatee: lsmith

jdoe is trying to impersonate lsmith. The following command can be used to obtain the OrclGuid of the impersonator (jdoe):

ldapsearch -h <hostname> -w <password>  -p <port> -D"cn=orcladmin" -b"dc=us,dc=example,dc=com"  "cn=jdoe" orclguid

For example, LDAP search for orclguid:

ldapsearch -h myhost1.us.example.com -w welcome1 -p 16890 -b"dc=us,dc=example,dc=com" -D"cn=orcladmin"  "cn=jdoe" orclguid
version: 1

where:

  • dn: cn=jdoe,cn=Users,dc=us,dc=example,dc=com

  • orclguid: A14BEB42E822D605E040E50AB29327E7

For example, LDAP search for orclImpersonationGrantee:

ldapsearch -h host1.us.example.com -w welcome1 -p 16890 -b"dc=us,dc=example,dc=com" -D"cn=orcladmin"  "cn=lsmith" orclImpersonationGrantee
version: 1

where:

  • dn: cn=lsmith,cn=Users,dc=us,dc=example,dc=com

  • orclImpersonationGrantee: A14BEB42E822D605E040E50AB29327E7|20100324163000Z|20120524172000Z

Add this value to the orclImpersonationGrantee entry to impersonatee user in OID as follows:

A14BEB42E822D605E040E50AB29327E7|20100324163000Z|20120524172000Z

Note:

No spaces are permitted in the list of individual values.

Object class and attribute definition for this attribute must be bootstrapped in the LDAP server's schema. OID 11.1.1.3 and later contains the necessary object class.

Access Manager retrieves impersonation grants of a given impersonatee when an impersonator attempts to create an impersonation session. However, if the grant doesn't exist for the given impersonator or if the current time is not within the time window of any such grants, impersonation session creation fails. Access Manager does not otherwise read or modify the grants within user profiles.

Subsequent revocation of the impersonation grant (for example, by modifying the orclImpersonationGrantee attribute) that authorized the impersonation session will not affect the impersonation sessions still in progress.

6.1.3 Impersonation Trigger Invocation Using the SSO Service

An authenticated user can select to impersonate another user. The user interface to select which user to impersonate is provided by an application. After the information has been collected, the application invokes the impersonation trigger. This can be done by invoking one of the methods in the SSO Service as shown in Example 6-1 or directly by redirecting the user's browser to Access Manager trigger URLs.

For more information about the SSO Service, see "Configuring the Identity Provider, Property Sets, and SSO" in Oracle Fusion Middleware Application Security Guide.

Example 6-1 illustrates the methods required to use the SSO Service to abstract the specifics of the triggering mechanism (preferred).

Example 6-1 Required Method to Abstract Triggering Mechanism Using SsoService API

void beginImpersonation(HttpServletRequest request, HttpServletResponse response, 
Map<String, ?> props) throws SsoServiceException
void endImpersonation(HttpServletRequest request, HttpServletResponse response, 
Map<String, ?> props) throws SsoServiceException

In this example props contains IMP_USER_ID of the impersonatee, SUCCESS_URL, FAILURE_URL, and TARGET_URL similar to login/logout/auto-login API of the SSOService. Example 6-2 shows an abbreviated example.

Example 6-2 Abbreviated SsoService API Triggering Example

import oracle.security.jps.JpsException;
import oracle.security.jps.service.JpsServiceLocator;
import oracle.security.jps.service.ServiceLocator;
import oracle.security.jps.service.sso.SsoService;

public void doGet (HttpServletRequest req, HttpServletResponse res)
 throws ServletException, IOException

{

  try {
   ServiceLocator serviceLocator = JpsServiceLocator.getServiceLocator();
   SsoService sso = (SsoService)serviceLocator.lookup(SsoService.class);

   Map m = new HashMap();

   m.put(SsoService.SUCCESS_URL, "https://login01.example.com:7777/appl2.html"); 
   m.put(SsoService.FAILURE_URL, "https://login01.example.com:7777/fail.html");
   m.put(SsoService.IMP_USER_ID, "mcooper");

    sso.beginImpersonation(req, res, m);


    [....]

   m.put(SsoService.TARGET_URL, "https://login02.example.com:8080/ 
   normalSession.html");    
   sso.endImpersonation(req, res, m);

  } catch(JpsException jpse) {
    jpse.printStackTrace();
  }
}

Example 6-3 provides a snippet from jps-config.xml showing the configuration changes needed (imp.begin.url and imp.end.url properties):

Example 6-3 jps-config.xml With Changes For imp.begin.url and imp.end.url

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jpsConfig xmlns="http://xmlns.example.com/oracleas/schema/11/jps-config-11_1.xsd" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://xmlns.example.com/oracleas/schema/11/jps-config-11_1
1.xsd">
    <property value="off" name="oracle.security.jps.jaas.mode"/>
    <propertySets>
        <propertySet name="saml.trusted.issuers.1">
            <property value="www.example.com" name="name"/>
        </propertySet>

[...]

        <propertySet name="props.auth.uri.0">
            <property value="/oamsso/logout.html" name="logout.url"/>
            <property value="https://login01.example.com:7777/oam/server/impersonate/end
              name="imp.end.url"/>
            <property value="https://login01.example.com:7777/oam/server/impersonate/start
              name="imp.begin.url"/>
            <property value="/${app.context}/adfAuthentication" name="login.url
             .BASIC"/>
            <property value="/${app.context}/adfAuthentication" name="login.
             url.ANONYMOUS"/>
            <property value="/${app.context}/adfAuthentication" name="login.
             url.FORM"/>
        </propertySet>
        <propertySet name="props.auth.level.0">
            <property value="0" name="type-level:ANONYMOUS"/>
            <property value="1" name="type-level:BASIC"/>
            <property value="2" name="type-level:FORM"/>
        </propertySet>
    </propertySets>

[...]

6.1.4 Triggering Impersonation Without API Abstraction

To invoke the Access Manager impersonation triggers directly, without the use of an API abstraction, the redirection to Access Manager maintained trigger end point has to contain a specification of query parameters for userid, success_url, and failure_url. The userid field carries the Impersonatee's userid, the success_url/failure_url is where the impersonator's browser should be pointed to after the impersonation session has been created or failed to be created, respectively. The URLs provided must include protocol and host:port information, as shown in Example 6-4.

Example 6-4 Triggering Impersonation Without API Abstraction

https://login.example.com/oam/server/impersonate/start?userid=impersonatee userid&success_url=SuccessRedirect URL&failure_url=FailureRedirect URL

To terminate the impersonation session and restore the original impersonator's Access Manager session, the user interface must force a browser redirect to an Access Manager maintained end point, and provides the target URL for the impersonator to come back to shown in Example 6-5. Use of failure_url is optional.

Example 6-5 Restore Original Impersonator's Session

https://login.example.com/oam/server/impersonate/end?end_url=TargetRedirect URL&failure_url=FailureRedirect URL

6.1.5 Impersonator Identity Communication During Impersonation Sessions

Table 6-2 provides the header names for communicating the identity of the impersonator to the downstream application. The WebGate uses an additional HTTP header injected into the request. The interested application may detect that the Access Manager impersonation session is in progress by inspecting the HTTP headers of inbound requests.

Table 6-2 Headers For Identity Information

Header Name Description

OAM_IMPERSONATOR_USER

The header name that carries the impersonator userID.

OAM_REMOTE_USER

The header that carries the end userID, which is the same as with a standard Access Manager user session.


6.2 Configuring Impersonation Support

The impersonation feature is not enabled by default. You enable the impersonation feature by either configuring oam-config.xml or by using the idmConfigTool command.

This section contains the following topics:

6.2.1 Configuring Impersonation Using oam-config.xml

The impersonation feature for the OAM Server is enabled by configuring the oam-config.xml file as shown in Example 6-6.

This example shows the relevant section of the file and the parameters that can be set. EnableImpersonation must be set to 'true' to enable impersonation. The default setting is 'false'.

Example 6-6 Enabling Impersonation Feature in oam-config.xml

<Setting Name="ImpersonationConfig" Type="htf:map">
<Setting Name="EnableImpersonation" Type="xsd:boolean">true</Setting>
    <Setting Name="UserAttributeName"
    Type="xsd:string">orclImpersonationGrantee</Setting>
    <Setting Name="ErrorPage" Type="xsd:string">/pages/servererror.jsp</Setting>
</Setting>

6.2.2 Configuring Impersonation Using idmConfigTool

For more information about the idmConfigTool command, see "Using the idmConfigTool Command" in Oracle Fusion Middleware Integration Guide for Oracle Identity Management Suite.

To configure the impersonation feature using idmConfigTool:

  1. Use idmConfigTool with the -prepareStoreID command to seed the Identity Store with the users required by Access Manager. The command syntax is ./idmConfigTool.sh -prepareIDStore mode=OAM input_file=input_parameters.

  2. Configure the impersonation feature using idmConfigTool with the configOAM command with the parameter OAM11G_IMPERSONATION_FLAG:true. The command syntax is ./idmConfigTool.sh -configOAM input_file=input_parameters.

  3. Define the impersonator grant permissions by providing the session timestamps for the impersonation session duration. The format of individual values is <Impersonator orclGUID> | <begin LDAP timestamp> | <end LDAP timestamp>. No spaces are permitted.

    For example, in OID add similar timestamp values to orclImpersonationGrantee entry as shown in the following:

    83295E092B2F9FD4E040E50AEBB91998|20100604224517Z|20110604224517Z;90FE8C8083CEBC1FE040E50AEBB9176A|20100704224517Z|20110604224517Z
    

    where:

    • The first block is the GUID of the impersonator. As shown here, 83295E092B2F9FD4E040E50AEBB91998 is the GUID of the impersonator.

    • The second block is the timestamp start date.

    • The third block is the timestamp end date.

  4. Submit the data to the LDAP server.

6.2.3 Configuring the Authentication Scheme

For impersonation support the authentication scheme for the protected application must be set to LDAPScheme. This must be done before initiating an impersonation session. For more information about the LDAPScheme, see "Managing Authentication Schemes" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

To set the authentication scheme to LDAPScheme:

  1. In the Oracle Access Management administration console, go to the Policy Configuration tab, App Domain, Authentication Policies, Protected Resource Policy.

  2. From the Authentication Scheme list, select LDAPScheme.

6.3 Testing SSO Login and Impersonation

The steps to test impersonation set up will vary according to your environment and your custom user interface. The following general advise is provided as an example of the steps to take, adjust as needed for your environment.

To test SSO login and impersonation

  1. Log in to Oracle Access Management using your own userID and credentials.

  2. Access a resource for which you have authorization to verify that Access Manager is working with your credentials as expected.

  3. Start your impersonation session.

  4. In the impersonation confirmation form that appears, enter your own (that is, impersonator's) password and click Submit to provide impersonation consent.

  5. In the same browser, access a resource for which the impersonated user has authorization.

  6. Confirm the Impersonating column in the Access Manager Session Management Page displays true.

    For more information, see "About the Session Management Page" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

  7. Confirm that HTTP header variables (OAM_REMOTE_USER and OAM_IMPERSONATOR_USER) are set in the impersonation session by using a script or Perl program that will print header variable.

    For more information, see Section 6.1.5, "Impersonator Identity Communication During Impersonation Sessions".

  8. Terminate your impersonation session.

  9. Confirm that OAM_REMOTE_USER is set to user before impersonation trigger, and OAM_IMPERSONATOR_USER HTTP header variable is empty or blank, by using a script or Perl program that will print header var.