{"type":"doc","content":[{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"2"},"outline":{"value":"false"},"type":{"value":"list"},"printable":{"value":"false"}},"macroMetadata":{"macroId":{"value":"e4e0c23f-49db-481e-8321-0d79edf7131a"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"e0bd4ad3-0d84-43ec-a651-51b7539d355c"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"This is a companion example to the more more general ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://shibboleth.atlassian.net/wiki/spaces/KB/pages/1432060485"}},{"text":". It demonstrates an approach to leveraging the IdP’s ","type":"text"},{"text":"impersonation","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199510036"}}]},{"text":" 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?”.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.)","type":"text"}]},{"type":"paragraph","content":[{"text":"This model has some advantages:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Efficiency – only one group query is performed","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Delegation – control over who can impersonate what users to which services can be delegated out via Grouper’s usual security features","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Fails Safely – a failed query results in no group memberships, ensuring no impersonation is allowed","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Usability – users can select from a predefined set of impersonatable identities instead of requiring data entry","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Loose Coupling – Grouper does not treat the impersonated names as “subjects”, so they need not actually be present in any Grouper subject source","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Grouper Structure","type":"text"}]},{"type":"paragraph","content":[{"text":"The folder layout in Grouper that matches these examples looks like this:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"OSU","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"WebLoginService","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"impersonate","type":"text"}]}]}]}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tagging","type":"text"}]},{"type":"paragraph","content":[{"text":"The metadata extension attribute used in this example is the following:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n grouperImpersonation\n","type":"text"}]},{"type":"paragraph","content":[{"text":"This can be embedded directly in an ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" extension, or added at runtime to an external metadata source using the ","type":"text"},{"text":"EntityAttributesFilter","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507147"}}]},{"text":" feature.","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"never","type":"text","marks":[{"type":"em"}]},{"text":" be used in any SAML context under any circumstances.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Attribute Resolver","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"language","type":"text","marks":[{"type":"code"}]},{"text":" attribute used explicitly to highlight this). Using the examples with Nashorn would require some re-writes, but nothing dramatic.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Supporting Beans","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"conf/services.xml","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"There are a variety of beans here, divided into two categories:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Some fairly simple beans needed to control or customize the behavior of the ","type":"text"},{"text":"HTTPConnector","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199503637"}}]},{"text":" itself.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"More complex beans that define a custom-purpose ","type":"text"},{"text":"HttpClient","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199510442"}}]},{"text":" for the web service calls, including specialized security configuration to support pre-emptive HTTP Basic Authentication to authenticate via a service account to Grouper.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"A description of some of the beans follows the example.","type":"text"}]},{"type":"expand","attrs":{"title":"attribute-resolver-spring.xml"},"content":[{"type":"codeBlock","content":[{"text":" \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 %{idp.home}/credentials/usertrust.pem\n \n \n \n \n \n\n \n \n \n \n \n \n \n \n\n \n \n \n ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"I'm not going to cover all of this because you should be able to look up the Javadocs for most of it yourself, but the HTTP client security is fairly involved and needs explanation. It's easier to explain from the bottom up.","type":"text"}]},{"type":"paragraph","content":[{"text":"The bottom of the stack here is the \"grouperAuthMap\", which is a way of priming the client with information about specific web servers that require authentication so that it doesn't wait to be prompted by the server and cause extra round trips. This is only safe to do if you have good control over the TLS validation process to make sure connections are only made to trusted servers, which is handled later.","type":"text"}]},{"type":"paragraph","content":[{"text":"The \"grouperHttpSecurity\" bean is the Shibboleth-defined object that encapsulates the securing of the HTTP client. Some of the aspects of this class are discussed on the ","type":"text"},{"text":"HttpClientConfiguration","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199510442"}}]},{"text":" page. The map mentioned above is injected into one property. A trust engine is also injected that handles verification of the server's certificate. The CA certificate is defined with a property, and the depth of the chain is extended to allow for intermediate CAs. Because the built-in code does not understand wildcard certificates (which are a bad thing in general, but...) the name of the certificate has to be manually added to the configuration to allow it to be matched.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that the \"grouperHttpClient\" and \"grouperHttpSecurity\" beans are not tied together here. In general, client objects are independent of security, and the security features are applied separately to the object using the client (in this case the eventual ","type":"text"},{"text":"HTTPConnector","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199503637"}}]},{"text":"). This allows a single client to be used against different servers if appropriate.","type":"text"}]},{"type":"paragraph","content":[{"text":"Lastly, note that the activation condition there is not strictly “check for the metadata tag” but “check for the tag AND that the resolution label is NOT “intercept/impersonate” (there’s a bang symbol in front of that check). That bypasses the Grouper lookup after impersonation is authorized and in use, when resolving attributes for the impersonated identity since that would be silly and redundant.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Data Connector","type":"text"}]},{"type":"paragraph","content":[{"text":"The most interesting part of this example is the ","type":"text"},{"text":"HTTPConnector","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199503637"}}]},{"text":" itself, and how it forms the request and handles the response. For convenience the script that parses the JSON response is in a separate file, so the connector itself is shorter:","type":"text"}]},{"type":"expand","attrs":{"title":"Connector in attribute-resolver.xml"},"content":[{"type":"codeBlock","content":[{"text":"\n\n \n\n \n && $IDMUID.size() == 1)$IDMUID.get(0)#end/groups?wsLiteObjectType=WsRestGetGroupsLiteRequest&stemName=OSU%3AWebLoginService%3A$custom.apply($resolutionContext.attributeRecipientID)%3Aimpersonate&stemScope=ALL_IN_SUBTREE\n ]]>\n \n\n \n %{idp.home}/conf/js/grouperImpersonation.js\n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The main element contains a lot of the references to the objects defined in the other file, mentioned earlier, like the activation condition, the HTTP client bean, and the security bean. The other interesting property is one that causes the client to advertise it supports JSON using a MIME type that Grouper understands. Without that, the web service returns XML instead.","type":"text"}]},{"type":"paragraph","content":[{"text":"The bottom part just defines the script file to run to process the response and is covered later.","type":"text"}]},{"type":"paragraph","content":[{"text":"The <","type":"text"},{"text":"URLTemplate","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631571"}}]},{"text":"> element is the interesting bit but it's mostly obvious except for the encoding of the entityID and if you weren't aware that, as a Velocity template, these kinds of query templates can do conditionals, though it's a bit unreadable. The conditional just error-guards a missing input attribute. The stem for the search here is the part that standardizes the interaction. We hash the entityID using the custom bean defined earlier, so the stem format in Grouper is \"OSU:WebLoginService::impersonate\". The hashing avoids encoding issues in Grouper, and we use display names on that side to hide them from the application owners.","type":"text"}]},{"type":"paragraph","content":[{"text":"The response parsing script is below, and it's a \"real-time\" handler, meaning it consumes the data exactly once, so it's suitable for streaming responses without a content length. The helper method enforces a limit on size as it consumes the data.","type":"text"}]},{"type":"expand","attrs":{"title":"grouperImpersonation.js"},"content":[{"type":"codeBlock","content":[{"text":"importClass(Packages.java.util.ArrayList);\nimportClass(Packages.net.shibboleth.shared.httpclient.HttpClientSupport);\nimportPackage(Packages.net.shibboleth.idp.attribute);\n\nvar body = HttpClientSupport.toString(response.getEntity(), \"UTF-8\", 65536);\nvar result = JSON.parse(body);\n\nif (result != null\n && result.WsGetGroupsLiteResult != null\n && result.WsGetGroupsLiteResult.resultMetadata != null\n && result.WsGetGroupsLiteResult.resultMetadata.resultCode == \"SUCCESS\") {\n var groups = result.WsGetGroupsLiteResult.wsGroups;\n if (groups != null) {\n var values = new ArrayList();\n for (var i=0; i\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}