{"type":"doc","content":[{"type":"paragraph","content":[{"text":"File(s):","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"conf/attribute-filter.xml","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"},{"text":"Format: ","type":"text","marks":[{"type":"strong"}]},{"text":"Custom Schema","type":"text"},{"type":"hardBreak"},{"text":"Namespace: ","type":"text","marks":[{"type":"strong"}]},{"text":"urn:mace:shibboleth:2.0:afp","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"Schema: ","type":"text","marks":[{"type":"strong"}]},{"text":"http://shibboleth.net/schema/idp/shibboleth-afp.xsd","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/schema/idp/shibboleth-afp.xsd"}}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"4678d707-9c9d-4a7b-aec7-641cfc01c6fa"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"89662220-7c9b-4f26-974e-66eea9065ab4"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"Attribute Filtering occurs after most uses of the ","type":"text"},{"text":"Attribute Resolution","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199502864"}}]},{"text":" engine. It is about constraining the set of attributes and/or attribute values prior to them being used for some purpose, typically either for passing along to a relying party or less often to limit data passing into the IdP itself from another source. In this way, you can tailor the attributes seen by a specific relying party for a specific subject. The full range of environmental information, for instance about the relying party or (issuing party), about the specific request, and about the subject, is available to guide the filtering process.","type":"text"}]},{"type":"paragraph","content":[{"text":"Please note that filtering ","type":"text"},{"text":"never","type":"text","marks":[{"type":"em"}]},{"text":" changes or adds to the data, only limits it. The resolver manipulates data, not the filtering engine.","type":"text"}]},{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"paragraph","content":[{"text":"You can exercise and debug the behavior of this process for the most common case (release to a relying party) using the ","type":"text"},{"text":"AACLI","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199511404"}}]},{"text":" tool or the web interface it uses. This is particularly helpful if you're making changes, performing upgrades, etc., to validate the results match in any given case. At present, this is not supported for the \"inbound\" direction.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Constraining attribute resolution and encoding using ActivationConditions","type":"text"}]},{"type":"paragraph","content":[{"text":"The attributes which are released to a relying party can be influenced by adding ","type":"text"},{"text":"ActivationConditions","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199504951"}}]},{"text":" to ","type":"text"},{"text":"DataConnectors ","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3200516116"}}]},{"text":"and ","type":"text"},{"text":"AttributeDefinitions","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199502907"}}]},{"text":". This can limit the attributes available at the start of the filtering process, and can thus act as a form of filtering. Typically these activation conditions are used to avoid expensive operations which serve no purpose in a given situation. For instance you might not connect to an LDAP directory for attributes if you knew that those attributes would never be used in assertions for a specific relying party (or if the subject was not visible in that directory).","type":"text"}]},{"type":"paragraph","content":[{"text":"Equally ","type":"text"},{"text":"ActivationConditions ","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199504951"}}]},{"text":"can also be attached to ","type":"text"},{"text":"Transcoding Rules","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199510553"}}]},{"text":" and ","type":"text"},{"text":"Attribute Encoders","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199504645"}}]},{"text":". These can be used to limit the encoding an attribute into SAML under certain circumstances. This is often useful to control the format used to render a particular attribute for a particular relying party.","type":"text"}]},{"type":"paragraph","content":[{"text":"In general activation conditions should not be viewed as an alternative form of filtering. Rather they should be viewed as a way of achieving something which otherwise could only be achieved in more cumbersome ways. In most cases, it's simpler to start with \"resolving everything\" and by encoding attributes consistently, and use this feature for special situations.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"In a typical (and default) configuration, only one XML resource is configured to supply the attribute filtering configuration, a file called ","type":"text"},{"text":"attribute-filter.xml. ","type":"text","marks":[{"type":"em"}]},{"text":"All resources contain a \"root\" ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element in the ","type":"text"},{"text":"urn:mace:shibboleth:2.0:afp","type":"text","marks":[{"type":"code"}]},{"text":" namespace.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Simple Attribute-Filter.xml file","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n\t\n \n \n \n \n \n \n \n \n \n \n \n \n\n\t\n \n \n \n \n \n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"The semantics of the attribute language can be deceptive. Informally it is easy to see what is going on (for instance the last case in the example could read \"If the relying party has an ID of 'https://sp.example.org' or 'https://another.example.org/shibboleth' then release all values of eduPersonScopedAffiliation\". However the detailed semantics can be extremely confusing and often downright counterintuitive. This is explained in detail ","type":"text"},{"text":"below","type":"text","marks":[{"type":"link","attrs":{"href":"#AttributeFilterConfiguration-Semantics"}}]},{"text":". A good rule of thumb is \"If it seems like a cute trick and a good idea, it isn't. Do it the obvious way.\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"Formally, this is the configuration of the \"AttributeFilter\" service. By default, one file, ","type":"text"},{"text":"attribute-filter.xml, ","type":"text","marks":[{"type":"em"}]},{"text":"defines the attributes and values to be passed on. Multiple files can be specified by changing the bean referred to by the property ","type":"text"},{"text":"idp.service.attribute.filter.resources","type":"text","marks":[{"type":"strong"}]},{"text":" (default value \"shibboleth.AttributeFilterResources\") defined in the ","type":"text"},{"text":"services.xml ","type":"text","marks":[{"type":"em"}]},{"text":"file.","type":"text"}]},{"type":"paragraph","content":[{"text":"The bulk of the filter policy is contained in one or more <","type":"text"},{"text":"AttributeFilterPolicy","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199501835"}}]},{"text":"> elements.","type":"text"}]},{"type":"expand","attrs":{"title":"Properties"},"content":[{"type":"paragraph","content":[{"text":"While not all that common, the ","type":"text"},{"text":"attribute-filter.xml ","type":"text","marks":[{"type":"em"}]},{"text":"file can leverage ","type":"text"},{"text":"property","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507855"}}]},{"text":" replacement to externalize particular settings. Properties are referenced via a brace syntax (e.g., %{idp.home}).","type":"text"},{"type":"hardBreak"},{"text":"The built-in properties which impact the filtering process (moreso just the filter service itself) are names staring with ","type":"text"},{"text":"idp.service.attribute.filter","type":"text","marks":[{"type":"strong"}]},{"text":" as described ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199507931"}}]},{"text":".","type":"text"}]}]},{"type":"expand","attrs":{"title":"XML Attributes"},"content":[{"type":"table","attrs":{"layout":"default","localId":"60538bed-e368-4d4c-8302-02971b95191d"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[102.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[108.0]},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[1016.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[102.0]},"content":[{"type":"paragraph","content":[{"text":"id","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[108.0]},"content":[{"type":"paragraph","content":[{"text":"XML ID","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1016.0]},"content":[{"type":"paragraph","content":[{"text":"Optional but recommended, unique ID for policy group used for logging purposes","type":"text"}]}]}]}]}]},{"type":"expand","attrs":{"title":"XML Elements"},"content":[{"type":"table","attrs":{"layout":"default","localId":"3a23b317-a7e2-4774-904e-4daddd4802f2"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[293.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[182.0]},"content":[{"type":"paragraph","content":[{"text":"Cardinality","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[751.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[293.0]},"content":[{"type":"paragraph","content":[{"text":"<","type":"text"},{"text":"AttributeFilterPolicy","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199501835"}}]},{"text":">","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[182.0]},"content":[{"type":"paragraph","content":[{"text":"0 or more","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[751.0]},"content":[{"type":"paragraph","content":[{"text":"A list of policies to apply","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Semantics"}},"macroMetadata":{"macroId":{"value":"440e4224-d8c9-4851-b94d-a92a72986218"},"schemaVersion":{"value":"1"},"title":"Anchor"}},"localId":"0db03d5a-5e47-4c1d-a7db-31a803251b1f"}},{"text":"Semantics","type":"text"}]},{"type":"paragraph","content":[{"text":"During attribute filtering, the engine:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Examines all the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" elements provided (for instance across multiple files) in an unspecified order.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Examines all the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" elements within each ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":", again in an unspecified order.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For each policy, if the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" is true:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Applies each of the child ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" elements, such that:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The attributes (and their values) returned by ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" get added to a \"permit list\".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The attributes (and their values) returned by ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" get added to a \"deny list\".","type":"text"}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"At the end of filtering, the final results are calculated by:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Populating the result initially from the permit list.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Removing all attribute values found in the deny list.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Removing all attributes with no values.","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"In this way, it can be seen that a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" 'trumps' the result of a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" in the manner typically found in such policy languages.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is relatively uncontroversial, although some of the side effects of a deny rule can be surprising. For instance, denying is not the same as not permitting.","type":"text"}]},{"type":"paragraph","content":[{"text":"The difficulty arises in that anything that can be used in an ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" can be used in a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":". The fist example below is relatively obvious:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Obvious Example","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"\"If the RP is named 'https://sp.example.org', then (only) release the 'eduPersonPrincipalName' attribute value of 'jsmith'.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"But the rules can be swapped:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Non-obvious Example","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"This is valid and has a specific meaning. But what is the meaning?","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"PolicyRulesAndMatchers"}},"macroMetadata":{"macroId":{"value":"3c7539fa-39da-493a-a325-ee204636237f"},"schemaVersion":{"value":"1"},"title":"Anchor"}},"localId":"7d377e21-eae7-4ccb-93d4-eb0eadcbef88"}},{"text":"PolicyRules and Matchers","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to make this tractable, the implementation considers plugin types as being either 'PolicyRules' or 'Matchers'. PolicyRules can be expected to give a \"yes/no\" answer and are usually used within a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":". Matchers usually return sets of values when applied to an attribute and are usually used within an ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The rules used are as follows:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If a Matcher is specified inside a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":", then if the plugin returns a value when applied to ","type":"text"},{"text":"any","type":"text","marks":[{"type":"em"}]},{"text":" of the input attributes then it is taken as being true, otherwise it is taken as being false.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If a PolicyRule is specified inside an ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":", then if the plugin returns true then all the values of the attribute concerned are returned (and added to the permit or deny list, as appropriate for the containing rule).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"To confuse the issue further:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The logic rules (and, or, not), which are natural PolicyRules have specific semantics when they are being used inside Matcher rules","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Some value-based rules change from being Matchers to being PolicyRules when the ","type":"text"},{"text":"attributeId","type":"text","marks":[{"type":"code"}]},{"text":" attribute is specified.","type":"text"},{"type":"hardBreak"},{"text":"So ","type":"text"},{"text":"<...xsi:type=\"Value\" value=\"jsmith\" caseSentitive=\"false\" />","type":"text","marks":[{"type":"code"}]},{"text":" is a Matcher (return all values which case-insensitively match \"jsmith\"), but ","type":"text"},{"text":"<...xsi:type=\"Value\" value=\"jsmith\" caseSentitive=\"false\" attributeId=\"uid\" />","type":"text","marks":[{"type":"code"}]},{"text":" is a PolicyRule (true if and only if there is an attribute called \"uid\" with a value which case-insensitively matches jsmith).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"So to answer the question above, the non-obvious second example means \"If any value of any attribute matches 'jsmith' in a case-insensitive manner, then release all values of 'eduPersonPrincipalName' if the name of the SP is 'https://sp.example.org'\". This is intelligible, but probably useless in practice. Most \"swaps\" of plugin types result in similar meaning.","type":"text"}]},{"type":"paragraph","content":[{"text":"Once compounded with ","type":"text"},{"text":"NOT","type":"text","marks":[{"type":"code"}]},{"text":" and deny rules, working out what is going on becomes incredibly non-intuitive. A good guiding rule is to only ever use PolicyRules inside ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" and to only use Matchers inside ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Error Handling","type":"text"}]},{"type":"paragraph","content":[{"text":"Because of the dangers of the ","type":"text"},{"text":"NOT","type":"text","marks":[{"type":"code"}]},{"text":" plugin, it becomes impossible for any particular rule to \"do the right thing\" if a failure occurs during processing. The filtering engine handles this by special-casing errors to the fail-safe (release or accept nothing) case.","type":"text"}]},{"type":"paragraph"}],"version":1}