6 Developing an Application to Manage Impersonation
6.1 About the Impersonation feature in Access Manager
The Access Manager user impersonation feature enables a user to perform operations and access resources on behalf of another user. 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 About Impersonation 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. |
6.1.2 Understanding Impersonation Concepts
Access Manager user impersonation support allows an end user (the impersonatee) to designate one or more users (impersonators) to act on their 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.3 About 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 also 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.4 Understanding 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 SSOin 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).
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-3 provides a snippet from jps-config.xml showing the configuration changes needed (imp.begin.url
and imp.end.url
properties):
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
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 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.5 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.
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-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
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.6 Impersonator Identity Communication During Impersonation Sessions
Use the header names provided for communicating the identity of the impersonator to the downstream application.
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
Use the information in the topics provided to enable the impersonation feature.
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. The following sections contain details.
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. Example 6-6 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>
Impersonation requires that the login request context be preserved either with a serverRequestCacheType
setting of COOKIE or BASIC. The default setting is COOKIE. This OAM Server parameter can be set in the oam-config.xml
file or using the configRequestCacheType
WLST command. For more information about the configRequestCacheType
command, see configRequestCacheType in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for Identity and Access Management.
6.2.2 Configuring Impersonation Using idmConfigTool
Use the procedure to configure the impersonation feature.
Follow this procedure to configure the impersonation feature using idmConfigTool
. For information about the idmConfigTool
command and input parameters, See Using the idmConfigTool Command in Oracle Fusion Middleware Integration Guide for Oracle Identity Management Suite.
6.2.3 Configuring the Authentication Scheme
Use these steps to set the authentication scheme to LDAPScheme.
For impersonation support the authentication scheme for the protected application must be set to LDAPScheme. This must be done before initiating an impersonation session. To set the authentication scheme to LDAPScheme:
- In the Oracle Access Management Administration Console, go to the Policy Configuration tab, App Domain, Authentication Policies, Protected Resource Policy.
- From the Authentication Scheme list, select LDAPScheme.
For more information about the LDAPScheme, See Managing Authentication Schemes.
6.3 Testing SSO Login and Impersonation
Use these steps to test the impersonation set up according to your environment and your custom user interface.
The steps to test impersonation set up will vary according to your environment and your custom user interface. The following general advice is provided as an example of the steps to take. Adjust the steps as needed for your environment.