{"type":"doc","content":[{"type":"paragraph","content":[{"text":"File(s):","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"conf/idp.properties","type":"text","marks":[{"type":"em"}]},{"text":",","type":"text"},{"text":" views/intercept/impersonate.vm, conf/access-control.xml","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"},{"text":"Format:","type":"text","marks":[{"type":"strong"}]},{"text":" Native Spring, Properties, Velocity","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"4a0b97e4-c210-4316-89fc-321c33621442"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"8e8323d9-3e8a-4270-8499-f7177ea0993a"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"The \"impersonate\" interceptor flow is an example of how to use an interceptor to implement a testing capability that allows a user to represent themselves as a different user to a downstream service, subject to appropriate authorization. It does not affect the user's overall session and has no persistent effect on access to other services within the same session; it is a per-request feature that changes the set of attributes resolved by re-running the attribute resolver as though the user had a different identity.","type":"text"}]},{"type":"paragraph","content":[{"text":"All interceptors are enabled or disabled on a per-relying-party basis using properties in the profile bean(s) you want to enable the flow for. See the ","type":"text"},{"text":"ProfileInterceptConfiguration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199509815"}}]},{"text":" topic for an example.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Enabling Module","type":"text"}]},{"type":"paragraph","content":[{"text":"Configuring and using this feature requires that you first enable the \"idp.intercept.Impersonate\" module if it isn't already enabled. Systems upgraded from older releases generally come pre-enabled due to the prior state of the configuration tree.","type":"text"}]},{"type":"codeBlock","content":[{"text":"(Windows)\nC:\\opt\\shibboleth-idp> bin\\module.bat -t idp.intercept.Impersonate || bin\\module.bat -e idp.intercept.Impersonate\n \n(Other)\n$ bin/module.sh -t idp.intercept.Impersonate || bin/module.sh -e idp.intercept.Impersonate","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"General Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"The primary configuration involved with this flow is to define ","type":"text"},{"text":"AccessControl","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199501767"}}]},{"text":" policies to control who can impersonate whom. And of course, one can customize the view template displayed.","type":"text"}]},{"type":"paragraph","content":[{"text":"The properties named ","type":"text"},{"text":"idp.impersonate.generalPolicy","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"idp.impersonate.specificPolicy","type":"text","marks":[{"type":"strong"}]},{"text":" control the named ","type":"text"},{"text":"AccessControl","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199501767"}}]},{"text":" policies you want to apply. They default to \"GeneralImpersonationPolicy\" and \"SpecificImpersonationPolicy\" respectively. There are examples below.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"If the legacy file ","type":"text"},{"text":"conf/intercept/impersonate-intercept-config.xml","type":"text","marks":[{"type":"em"}]},{"text":" remains present, the beans in that file supersede the property definition(s) but you may remove the file if the default values or properties are used instead.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The \"general\" policy runs first up front and determines whether to actually offer the impersonation option. This is logically equivalent to attaching an activation condition to the flow itself, but the AccessControl service is ","type":"text"},{"text":"reloadable","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507931"}}]},{"text":", so using a policy is more flexible.","type":"text"}]},{"type":"paragraph","content":[{"text":"The \"specific\" policy runs after an account name is selected to decide whether to allow it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Since retrieving a policy by name that doesn't exist results in denial of access, the system is safe out of the box. Enabling the flow won't actually cause it to run due to the lack of a matching policy defined to allow access to it.","type":"text"}]},{"type":"paragraph","content":[{"text":"The view to display is contained in ","type":"text"},{"text":"views/intercept/impersonate.vm,","type":"text","marks":[{"type":"em"}]},{"text":" and it provides an example allowing the user to enter the account to impersonate using a form field, or to bypass the impersonation and just continue normally.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Flow Behavior","type":"text"}]},{"type":"paragraph","content":[{"text":"If the general policy grants access, the view is rendered. Assuming a username is entered and the impersonation is attempted, the flow runs the specific policy. This policy is evaluated with its \"resource\" input set to the intended account name to impersonate, allowing the policy to react accordingly.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the policy denies access, the failed attempt is logged and an event named \"ImpersonationViolation\" terminates the entire request. This is an event you can configure whatever error handling you prefer in response to (see ","type":"text"},{"text":"ErrorHandlingConfiguration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199506653"}}]},{"text":"), but for new installs it's defined to be a \"local error\". Upgraded systems will need to add that event to the map of local events (you can compare your copy of ","type":"text"},{"text":"conf/errors.xml","type":"text","marks":[{"type":"em"}]},{"text":" to the one in the ","type":"text"},{"text":"dist","type":"text","marks":[{"type":"strong"}]},{"text":" directory).","type":"text"}]},{"type":"paragraph","content":[{"text":"If the policy allows access, the flow will:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"log an informational message","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"destroy any existing attributes resolved for the user","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"move the original username into an \"impersonatingPrincipalName\" property in the attached ","type":"text"},{"text":"SubjectContext","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.context.SubjectContext"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"populate the impersonated principal name into the attached ","type":"text"},{"text":"SubjectContext","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.context.SubjectContext"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"re-run the ","type":"text"},{"text":"AttributeResolver","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199502864"}}]},{"text":" with the effective subject name set to the selected value","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"add an audit field (\"uu\") containing the impersonating account so that it can be recorded in the ","type":"text"},{"text":"audit log","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199509698"}}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Attribute Resolver Considerations","type":"text"}]},{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"most","type":"text","marks":[{"type":"strong"}]},{"text":" configurations, the only user-specific element of the resolution process will be derived from the ","type":"text"},{"text":"principalName","type":"text","marks":[{"type":"code"}]},{"text":" property of the ","type":"text"},{"text":"AttributeResolutionContext","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-attribute.cgi/net.shibboleth.idp.attribute.resolver.context.AttributeResolutionContext"}}]},{"text":" provided to the resolver, which will be set by this flow to the impersonated name instead of the original one.","type":"text"}]},{"type":"paragraph","content":[{"text":"However, you should thoroughly examine and test your configuration to be sure that you're getting the output you expect. In particular, if you have behavior (likely via scripts or the advanced ","type":"text"},{"text":"SubjectDerivedAttributeAttributeDefinition","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199503385"}}]},{"text":") that depends on content internal to the user's authentication state, this will ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" be effectively overridden by this flow.","type":"text"}]},{"type":"paragraph","content":[{"text":"To facilitate attaching conditions or adding script logic that can be made dependent on whether impersonation is happening, a new property has been added to the ","type":"text"},{"text":"AttributeResolutionContext","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-attribute.cgi/net.shibboleth.idp.attribute.resolver.context.AttributeResolutionContext"}}]},{"text":", the ","type":"text"},{"text":"resolutionLabel","type":"text","marks":[{"type":"code"}]},{"text":", and it will be set to \"intercept/impersonate\" (the flow ID) when this flow is doing the resolution (it will be empty in the traditional case).","type":"text"}]},{"type":"paragraph","content":[{"text":"As a general matter, unless all of your attributes come from a persistent store you can re-query, this feature is not likely to work, or be safe to use.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Properties","type":"text"}]},{"type":"paragraph","content":[{"text":"The following properties in ","type":"text"},{"text":"conf/idp.properties","type":"text","marks":[{"type":"em"}]},{"text":" may be used to override the default policy names used:","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1242.0,"localId":"cee45e5c-8ab3-4a22-b8a4-52b348593ce4"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[257.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[240.0]},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[745.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[257.0]},"content":[{"type":"paragraph","content":[{"text":"idp.impersonate.generalPolicy","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[240.0]},"content":[{"type":"paragraph","content":[{"text":"GeneralImpersonationPolicy","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[745.0]},"content":[{"type":"paragraph","content":[{"text":"Named ","type":"text"},{"text":"AccessControl","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199501767"}}]},{"text":" policy to run to determine whether to run this flow ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[257.0]},"content":[{"type":"paragraph","content":[{"text":"idp.impersonate.specificPolicy","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[240.0]},"content":[{"type":"paragraph","content":[{"text":"SpecificImpersonationPolicy","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[745.0]},"content":[{"type":"paragraph","content":[{"text":"Named ","type":"text"},{"text":"AccessControl","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199501767"}}]},{"text":" policy to run to determine whether to allow the requested impersonation","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Note that these are not Spring bean IDs, but rather keys into the map of policies defined to the access control service.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Example","type":"text"}]},{"type":"paragraph","content":[{"text":"Aside from the UI, all of the flow's configuration is actually just defining policies, either in ","type":"text"},{"text":"conf/access-control.xml","type":"text","marks":[{"type":"em"}]},{"text":" or an included file. In practice, a \"real world\" implementation of such policies would likely rely on some kind of directory or database of rules controlling which users can impersonate which users to which services, perhaps through group memberships resolved during initial attribute resolution.","type":"text"}]},{"type":"paragraph","content":[{"text":"For illustrative purposes, consider a rule that the flow is authorized only to users possessing a particular entitlement value, and then are allowed to impersonate any users named by a second custom attribute to services named by a third. This fully devolves the decision making to data that could be supplied from any directory or database, instead of internal rules hardcoded into the configuration.","type":"text"}]},{"type":"paragraph","content":[{"text":"The \"general\" policy is a simple test of an entitlement attribute for a specific value that is intended to mean \"allow this logged-in user to at least attempt impersonation\", and uses the ","type":"text"},{"text":"SimpleAttributePredicate","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-profile.cgi/net.shibboleth.profile.context.logic.SimpleAttributePredicate"}}]},{"text":" Java class. This class is often used to implement authorization rules in the ","type":"text"},{"text":"context-check","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199509927"}}]},{"text":" interceptor.","type":"text"}]},{"type":"paragraph","content":[{"text":"The \"specific\" policy could be implemented by a somewhat-involved script, but the example below relies on an advanced Java class that checks the values of a resolved IdPAttribute against a dynamically computed candidate value (or values) produced by functions, which can themselves be scripts or expressions. This ","type":"text"},{"text":"DynamicAttributePredicate","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-profile.cgi/net.shibboleth.profile.context.logic.DynamicAttributePredicate"}}]},{"text":" class relies on an injected map of attribute names to functions, instead of attribute names to strings. The mapped function objects return the data values that have to be found in the named attribute at runtime to be a valid match. It's indirect instead of static/direct.","type":"text"}]},{"type":"paragraph","content":[{"text":"The example uses this trick to derive the values to look for from the actual impersonation attempt. The ID of the service and the ID of the impersonated user come from functions and those functions are what the example is putting in the map that the Java class calls.","type":"text"}]},{"type":"paragraph","content":[{"text":"Instead of a rule saying \"can impersonate jdoe to service xyz\", which would be static and hard to manage, the rule is saying \"allow the impersonation of jdoe to xyz if jdoe is one of the values of the impersonatableUsernames IdPAttribute and xyz is one of the values of the impersonatableServices IdPAttribute\".","type":"text"}]},{"type":"paragraph","content":[{"text":"Once you understand the idea, it's not a lot of configuration to maintain and supports a plausible real-world approach to authorizing the impersonation feature.","type":"text"}]},{"type":"expand","attrs":{"title":"conf/access-control.xml"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n\n \n \n\t\t\n \n \n \n \n \n \n \n \n https://example.org/entitlement/impersonation\n \n \n \n \n \n \n \n \n\n\t\t\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n\n","type":"text"}]}]},{"type":"paragraph"}],"version":1}