Impersonation Managed By Grouper
The examples in this page reflect certain approaches required by IdP V5. They are not entirely compatible with earlier versions, though the differences are fairly minor relative the point of the example.
Overview
This is a companion example to the more more general Grouper Integration Example. It demonstrates an approach to leveraging the IdP’s impersonation feature, while using a particular design pattern in Grouper to model and manage the authorization decisions that are required by that feature. It is not by any means the only way to manage impersonation, nor the only way to use Grouper to do that, as the feature is extremely generic and merely requires that a pair of access control policies exist to supply answers to the basic questions “can this user impersonate anybody to this service?” and “can this user impersonate this subject to this service?”.
In this example, these questions are answered via a single Grouper WS query that is parameterized by two inputs: the service involved and the original user identity, after the c14n process normalizes the username. The attribute resolver is programmed to query Grouper for that user’s group memberships in a particular tree specific to the service. If no such tree exists, or no memberships exist for the user in that tree, impersonation is disallowed. This is of course the typicall situation.
If at least one membership exists, then the group stem name(s) are processed to obtain the final portion of the stem name, which contains the identity of a subject that the user is permitted to impersonate. In doing so, this allows the UI to actually provide a drop down list of those names to pick from, and the system will perform a final validation by ensuring that the value selected is in fact one of the authorized groups. (This prevents an attack against the UI if a user were to manipulate their submission to inject a name of their own choosing.)
This model has some advantages:
Efficiency – only one group query is performed
Delegation – control over who can impersonate what users to which services can be delegated out via Grouper’s usual security features
Fails Safely – a failed query results in no group memberships, ensuring no impersonation is allowed
Usability – users can select from a predefined set of impersonatable identities instead of requiring data entry
Loose Coupling – Grouper does not treat the impersonated names as “subjects”, so they need not actually be present in any Grouper subject source
Low IdP Operational Overhead – the impersonation feature can be safely enabled globally, so changes in Grouper alone will be sufficient to add new impersonation permissions without modifying IdP configuration
With respect to the latter point, as with the original example, metadata tagging is used to actually trigger to Grouper query. Absent such a tag, no query is performed, and no impersonation is possible. The only added overhead is a relatively fast attempt to run the flow, evaluate an attribute-based access control check, determine that no impersonation values are available, and skip the flow.
Grouper Structure
The folder layout in Grouper that matches these examples looks like this:
OSU
WebLoginService
<SHA-1 hashed entityID of SP>
impersonate
Within that folder, each username to be impersonated is created as a group. The group’s member’s then contain the subjects (in the Grouper sense) that will be allowed to impersonate the group’s name to the service within which the whole tree is contained. The requirement to tie this together is that the authenticated user within the IdP must be known to Grouper, and the IdP must be able to obtain a piece of data about the user with which to query Grouper. In our case, we use our IDM ID as the unique subject ID in Grouper, so the IdP needs to obtain that data element to query with.
Tagging
The metadata extension attribute used in this example is the following:
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
Name="urn:mace:osu.edu:shibboleth:attribute-release">
<saml:AttributeValue>grouperImpersonation</saml:AttributeValue>
</saml:Attribute>
This can be embedded directly in an <mdattr:EntityAttributes>
extension, or added at runtime to an external metadata source using the EntityAttributesFilter feature.
This tag will be used in other parts of the example to control activation of components. Obviously it’s a custom Attribute I invented for my own use, but as with all of my work, URIs are always used to ensure uniqueness and prevent any possible conflicts with other settings. String naming should never be used in any SAML context under any circumstances.
Attribute Resolver
Most of the complex bits are in the resolver obviously, to pull in Grouper data and format it into impersonatable usernames. Most of this is accomplished with scripts of various sorts.
A note of caution: these examples are written using the pre-Java 8 Rhino scripting engine because that's what I've stuck with in my deployment as a personal preference (you'll see the language
attribute used explicitly to highlight this). Using the examples with Nashorn would require some re-writes, but nothing dramatic.
Supporting Beans
Often, advanced use cases require some native Spring wiring for certain kinds of objects, and this is definitely one of those cases. I load beans needed for the resolver in a separate Spring file added as an additional resource to conf/services.xml.
There are a variety of beans here, divided into two categories:
Some fairly simple beans needed to control or customize the behavior of the HTTPConnector itself.
More complex beans that define a custom-purpose HttpClient for the web service calls, including specialized security configuration to support pre-emptive HTTP Basic Authentication to authenticate via a service account to Grouper.
The custom client provides for better handling of timeout behavior, and the security beans provide appropriate TLS validation of the server, and avoid extra round trips by providing the HTTP credentials in every call instead of waiting for a 403 challenge from the server.
A description of some of the beans follows the example.