{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"3"}},"macroMetadata":{"macroId":{"value":"c7628cb46dcf162934ae607fe07277e1"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"75b9b7df-3fe2-4abd-a4de-9d8ceb0fcb44"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Concepts","type":"text"}]},{"type":"paragraph","content":[{"text":"A widespread pattern throughout much of the IdP configuration is the concept of an \"activation condition\". This is a mechanism by which functions and settings can be selectively enabled or disabled at runtime based on an arbitrary condition that is evaluated for each request. This addresses the ability to easily extend the behavior of components and handle new use cases. For consistency, we've tried to use the property name \"activationCondition\" across many of the components with this feature.","type":"text"}]},{"type":"paragraph","content":[{"text":"An activation condition, formally, is a Java bean of type ","type":"text"},{"text":"Predicate","type":"text","marks":[{"type":"code"}]},{"text":". A Predicate is a very simple generic interface that implements a single method:","type":"text"}]},{"type":"codeBlock","content":[{"text":"public interface Predicate {\n\tboolean apply(T input)\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"That is, it lets the IdP run a method against an input object to get a yes/no answer. The input in the majority of cases is the \"root\" object of the context state tree that tracks a request from start to finish, of type ","type":"text"},{"text":"org.opensaml.profile.context.ProfileRequestContext","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.profile.context.ProfileRequestContext"}}]},{"text":". By consistently basing everything off of that abstraction, it's possible to build up a library of condition objects that can be used in many different places to implement some kind of check.","type":"text"}]},{"type":"paragraph","content":[{"text":"The IdP includes a ","type":"text"},{"text":"fairly extensive library of such conditions","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199508946"}}]},{"text":", and there are a number of pre-defined beans provided to help make configuration simpler for a lot of common use cases and we can extend that set over time (and it's easy to submit more examples here that people can cut and paste).","type":"text"}]},{"type":"paragraph","content":[{"text":"We also supply public implementations of this interface such that the logic can be supplied via a ","type":"text"},{"text":"script","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199509530"}}]},{"text":" or via a ","type":"text"},{"text":"Spring Expression","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199509349"}}]},{"text":", avoiding the overhead of creating a new Java class in a separate extension library.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Use Cases","type":"text"}]},{"type":"paragraph","content":[{"text":"Some of the advanced uses you might have for this feature include:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Creating custom ","type":"text"},{"text":"relying party overrides","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199508044"}}]},{"text":" beyond the ones supplied","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Limiting when ","type":"text"},{"text":"authentication flows","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199505085"}}]},{"text":" may be used","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Limiting when NameID ","type":"text"},{"text":"generation","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199507810"}}]},{"text":" or ","type":"text"},{"text":"consumption","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199507773"}}]},{"text":" plugins may be used","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Controlling the use of attribute resolver ","type":"text"},{"text":"connectors","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3200516116"}}]},{"text":", ","type":"text"},{"text":"definitions","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199502907"}}]},{"text":", or ","type":"text"},{"text":"encoders","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199504645"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Determining when profile intercept flows run, such as ","type":"text"},{"text":"attribute consent","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199509862"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Extending the ","type":"text"},{"text":"attribute filter policy","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199501794"}}]},{"text":" language","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In most cases, using this feature amounts to setting a bean implementing the condition you want into a component bean's ","type":"text"},{"text":"activationCondition","type":"text","marks":[{"type":"code"}]},{"text":" property. With the older configuration files that are not Spring bean files, there will usually be some kind of XML attribute used to reference to condition (e.g. ","type":"text"},{"text":"activationConditionRef","type":"text","marks":[{"type":"code"}]},{"text":") and you will have to define the condition bean in a separate file. This isn't ideal, but it allows for essentially any condition to be attached without regard for how complex its own configuration might be.","type":"text"}]},{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Defining the condition bean","type":"text"}]},{"type":"paragraph","content":[{"text":"The location where the condition bean would be defined depends on the use case. It's generally safe to define them in ","type":"text"},{"text":"global.xml,","type":"text","marks":[{"type":"em"}]},{"text":" as long as the naming is unique. For the most isolation, and to support reloadability of their definitions, it's better to define them inside specific ","type":"text"},{"text":"service","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199507931"}}]},{"text":" contexts when possible, generally by adding a bean resource file to the set of resources defined in ","type":"text"},{"text":"services.xml","type":"text","marks":[{"type":"em"}]},{"text":" for a given service.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Attaching Conditions","type":"text"}]},{"type":"paragraph","content":[{"text":"The various examples below demonstrate the creation of stand-alone beans of the appropiate type. To actually use them in specific cases typically requires injecting the bean ID into a property named ","type":"text"},{"text":"activationCondition-ref","type":"text","marks":[{"type":"code"}]},{"text":" in another bean, or using a custom XML attribute.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Native Spring Syntax","type":"text"}]},{"type":"paragraph","content":[{"text":"For instance, attaching a condition bean named \"MyCondition\" to control the execution of a NameID generator bean in ","type":"text"},{"text":"conf/saml-nameid.xml","type":"text","marks":[{"type":"em"}]},{"text":" looks like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Custom Syntax","type":"text"}]},{"type":"paragraph","content":[{"text":"In contrast, attaching a condition to an attribute defintion looks like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"In this case the bean definition for the activation condition (","type":"text"},{"text":"MyCondition","type":"text","marks":[{"type":"code"}]},{"text":" above) should be included in a suitable native spring file.","type":"text"}]},{"type":"paragraph","content":[{"text":"Simple conditions, and those requiring to be reloadable, should be placed in a standalone file loaded via ","type":"text"},{"text":"conf/services.xml","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"expand","attrs":{"title":"Bean defintion for selection by Relying Party ID"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"This file must be supplied to the appropriate resource list in ","type":"text"},{"text":"conf/services.xml","type":"text","marks":[{"type":"em"}]},{"text":". For instance for the Attribute Resolver:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n ${idp.home}/conf/attribute-resolver.xml\n ${idp.home}/conf/THE_NEW_FILE.xml\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Complex beans that will never need to be reloaded can be put in ","type":"text"},{"text":"conf/global.xml","type":"text","marks":[{"type":"em"}]},{"text":" (or a file imported into it).","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"paragraph","content":[{"text":"If you develop useful examples, please consider adding them to this page. The examples below are not fully tested in a few cases, so please report any problems using them to the mailing list or make corrections as you find them.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Specific Relying Parties","type":"text"}]},{"type":"paragraph","content":[{"text":"This is a common use case, and simple to grasp, so we use it to demonstrate a variety of different approaches that you can apply to other use cases once the syntax makes sense to you.","type":"text"}]},{"type":"paragraph","content":[{"text":"A built-in bean is provided to make this use case simple. You should provide a list of names, providing a single name may not have the expected result.","type":"text"}]},{"type":"expand","attrs":{"title":"Specific Relying Parties by Name"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n\n\n\n\n\n\n \n \n https://sp.example.com/shibboleth\n https://another.example.com/shibboleth\n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"A more advanced option supported by the same parent bean is the ability to plug-in an arbitrary condition to run against the relying party name. The input to such a condition is a String rather than the ProfileRequestContext.","type":"text"}]},{"type":"expand","attrs":{"title":"Test a Regular Expression"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"You can also write a script (Javascript being the default language):","type":"text"}]},{"type":"expand","attrs":{"title":"Javascript Example"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n // The IdP environment provides two variables \"profileContext\" and \"custom\". \n // profileContext is of type org.opensaml.profile.context.ProfileRequestContext\n // custom is whatever you injected \n // The value of the last statement in this function is the reurn value\n var id = \"https://sp.example.com/shibboleth\"; // an entityID\n \n // specify the child context of the root ProfileRequestContext\n if (profileContext!== null) {\n // check the entityID of the relying party\n var subcontext = profileContext.getSubcontext(\"net.shibboleth.profile.context.RelyingPartyContext\");\n if (subcontext !== null) {\n result = subcontext.getRelyingPartyId().equals(id);\n }\n }\n result;\n ]]>\n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Finally, you can write Spring Expressions, sort of a more concise scripting format:","type":"text"}]},{"type":"expand","attrs":{"title":"Spring Expression Example"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n #profileContext.getSubcontext(T(net.shibboleth.profile.context.RelyingPartyContext)).getRelyingPartyId().equals(\"https://sp.example.com/shibboleth\")\n \n \n","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Relying Parties By Group","type":"text"}]},{"type":"paragraph","content":[{"text":"In this context, grouping RPs is historically done by containing SAML metadata entities in ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" elements, something common to aggregated files produced by many federations. This is more of a historical use case, because it's dangerous to use with aggregates you don't control. The containment model is very limiting and often doesn't mean what people think it does, so it's better to use the \"tag\" approach illustrated below.","type":"text"}]},{"type":"paragraph","content":[{"text":"But for aggregates you control locally, it's a simple way to apply policy and solve certain problems, such as grouping together SAML 1-only systems or grouping systems that don't support encryption, or grouping together systems by their attribute needs.","type":"text"}]},{"type":"paragraph","content":[{"text":"As of V3.4, group matching is extended to check for ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" content in metadata, which is a way of providing explicit \"out of band\" groups of entities (analagous to creating an LDAP group that lists its members, rather than embedding the memberships into each member's entry).","type":"text"}]},{"type":"paragraph","content":[{"text":"Most use cases for this feature tend to be for ","type":"text"},{"text":"relying party overrides","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199508044"}}]},{"text":", which are already supported separately. If you need to use this kind of condition elsewhere, you can reuse the same code with this example:","type":"text"}]},{"type":"expand","attrs":{"title":"Relying Parties By Group"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n\n\n\n\n \n \n \n\n\n\n\n \n \n \n \n group1\n group2\n \n \n \n \n","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Relying Parties By Tag","type":"text"}]},{"type":"paragraph","content":[{"text":"The \"modern\" approach to attaching policy to relying parties is to leverage so-called tags, which refers to a metadata extension called an \"Entity Attribute\", a SAML attribute embedded in a system's metadata that is about the system rather than an individual user. Entity attributes have a variety of use cases, essentially anything one can think of saying about a system, and they're more flexible than groups because they can be attached directly to the entity's metadata regardless of where it's published. If you will, this is the equivalent of an LDAP \"memberOf\" attribute as opposed to a directory object that contains all the members of a group.","type":"text"}]},{"type":"paragraph","content":[{"text":"Most use cases for this feature tend to be for ","type":"text"},{"text":"relying party overrides","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199508044"}}]},{"text":", which are already supported separately. If you need to use this kind of condition elsewhere, you can reuse the same code with this example. The example shows the use of two different tag “values” to check for, one that’s standardized and one that’s custom, just to show how to handle two values at once.","type":"text"}]},{"type":"expand","attrs":{"title":"Relying Party By Tag"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n \n \n \n \n \n \n","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Client Address Ranges","type":"text"}]},{"type":"paragraph","content":[{"text":"Some components may be sensitive to the address of the client, perhaps to distinguish users running on an enterprise network vs. working remotely. A condition class has been created to make this check simple using CIDR masks. Note that a servlet request bean declared by the Shibboleth software MUST be injected into any bean that needs access to the current request (the same is true of the servlet response in other cases).","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Address Range Examples","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"this link","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199500962"}}]},{"text":" for more details","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Attribute Checking","type":"text"}]},{"type":"paragraph","content":[{"text":"Some components may need to check for the presence (or absence) of a particular attribute or value for a user. A basic condition is provided for this purpose, or may be a useful code example to follow to implement something more complex.","type":"text"}]},{"type":"paragraph","content":[{"text":"The class provided supports only simple string-valued attributes, and supports a simple form of wildcarding to indicate that any value is acceptable as long as one exists.","type":"text"}]},{"type":"expand","attrs":{"title":"Attribute Checking Examples"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n \n urn:mace:dir:entitlement:common-lib-terms\n \n \n \n \n\n\n\n\n \n \n \n \n *\n \n \n \n \n","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Compound Boolean Conditions","type":"text"}]},{"type":"paragraph","content":[{"text":"The usual boolean operators (AND/OR/NOT) are available as predicates to allow the construction of complex compound conditions out of inividual parts. It's somewhat similar in structure to using boolean operators in the ","type":"text"},{"text":"attribute filter policy","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199501794"}}]},{"text":" language. It is of course possible to arbitrarily nest AND/OR/NOT conditions together to create complex expressions, although the (lack of) readability is such that it may be easier to use a script.","type":"text"}]},{"type":"paragraph","content":[{"text":"The first example demonstrates an OR operation that is equivalent to earlier examples but illustrates the syntax. The argument to the condition is a collection of condition beans to OR together.","type":"text"}]},{"type":"expand","attrs":{"title":"Either of Two Relying Parties"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n \n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The second example demonstrates a compound condition that checks a specific SP AND for a particular client network range.","type":"text"}]},{"type":"expand","attrs":{"title":"Specific Relying Party AND Client Address Range"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n \n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Finally, a simple NOT example checking for any SP except for one:","type":"text"}]},{"type":"expand","attrs":{"title":"NOT a Specific Relying Party"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n","type":"text"}]}]},{"type":"paragraph"}],"version":1}