547
szerkesztés
Módosítások
nincs szerkesztési összefoglaló
Attributes are travelling on the wire in eduGAIN-defined format, ie. SAML. Naming attributes and defining their contents might be a standardization task of eduGAIN operators; however it should be possible for federations to agree on custom set of attributes ''beyond "eduGAIN commons"''.
Attribute Conversion only adds attributes (or values) to the attribute set; use [[JRA5AttributeFiltering JRA5AttributeConversion#Attribute_Filtering | Attribute Filtering]] for filtering out unnecessary attributes. It also means that if no rules match an attribute, then it will go to the filter unmodified - so conversion works with a '''default by-pass policy'''.
== Attribute conversion rule concepts==
Most of the rules are based on standard [http://en.wikipedia.org/wiki/Regular_expression regular expressions] and [http://en.wikipedia.org/wiki/Unified_Expression_Language Unified Expression Language].
Every rule consists of two parts: condition and action. The condition element is used to determine whether this particular rule is to be processed or not. Thus, the rule action is only processed when all the conditions are met (a rule without any conditions is processed by default).
The condition engine now only supports regular expression -based matching rules. There is two type are three types of matching rules* local federation peer's identifier (LocalProviderMatch)* remote federation peer's name identifier (RemoteProviderMatch)
* attribute values (AttributeMatch)
<source lang="xml">
<Description>Create static attribute (or append to existing if attribute with this name already exists)</Description>
<Attribute attributeName="eduPersonScopedAffiliation" replaceValues="false">
</Attribute>
</source>
<source lang="xml">
<RemoteProviderMatch>^urn:geant:edugain:be:[^:]+\.hu$</RemoteProviderMatch>
<AttributeValue>niif.hu</AttributeValue>
</source>
<source lang="xml">
<Description>Rename attribute uid to edupersonPrincipalName</Description>
<Condition>
</Condition>
<Attribute attributeName="edupersonPrincipalName">
</Attribute>
</source>
<source lang="xml">
<Decription>Transform 'o=org,c=country'-style OrgDN to DNS-based homeOrganization</Decription>
<Condition>
</Condition>
<Attribute attributeName="homeOrganization">
</Attribute>
</source>
This last example needs some more explanation. When you want to reference the regular expression matching groups (enclosed by parentheses), you must define the reference name with the 'id' parameter of <code>AttributeMatch</code>. Then, use <code>${id[0]}</code> to refer to the whole regular expression match (ie. the whole attribute value), and <code>${id[N]}</code> to refer to the Nth. matching group of the regular expression.
{{INFO_EN|You cannot reference other rule's regular expressionsfrom another rule.}}
=== MergeRule ===
The merge rule can merge two or more attributes into one. The attributes whose values you want to merge is declared using the InputAttribute node. You can also use the condition node, but only with <code>RemoteProviderMatch</code> and <code>LocalProviderMatch</code> (<code>AttributeMatch</code> is ignored).
This example shows how to combine two attribute values:
<source lang="xml">
<Description>Merges the uid and homeOrganization to edupersonPrincipalName</Description>
<InputAttribute attributeName="homeOrganization" />
<InputAttribute attributeName="uid" />
<Attribute attributeName="edupersonPrincipalName" replaceValues="true">
</Attribute>
</source>
<source lang="xml">
<Description>Split the edupersonScopedAffiliation to edupersonAffiliation and homeOrganization</Description>
<InputAttribute attributeName="edupersonScopedAffiliation" id="scopedAffiliation" >^([^@]+)@(.+)$</InputAttribute>
<Attribute attributeName="edupersonAffiliation">
</Attribute>
<Attribute attributeName="homeOrganization">
</Attribute>
</source>
=== CustomRule ===
If you need to create new attributes from program (eg. appending generated identifiers), you can use the '''CustomRule ''' type.
<source lang="xml">
<Configuration>
</Configuration>
</source>
=== Negating matches ===
If your federation has ''optional'' attributes then sometimes it is desirable to process rules '''only if a particular attribute does not exist.''' Therefore it is possible to append a '''<code>negate</code>''' boolean attribute (setting it to '''true''') to the '''<AttributeMatchcode><*Match>''' and the '''<RemoteProviderMatch/code>''' nodes (inside '''the <code><Condition>''' </code> element) to revert the match. It means that the rule is only processed if there is no match in the attribute set (or to for the remote provider string)given value.
The following example creates <code>preferredLanguage</code> only if it is not set by the IdP (or by the peer's home bridging element):
<source lang="xml">
<Decription>Create preferredLanguage only if source has not supplied it</Decription>
<Condition>
</Condition>
<Attribute attributeName="preferredLanguage">
</Attribute>
</source>
== Attribute Filtering ==
=== Concepts ===
At Home BE, Filtering normally gets its incoming attribute set from Conversion; at Remote BE, it gets incoming attributes from the other bridging element.
=== Allowing and denying attributes ===
Three main rules of the filtering:
# Default action is to deny ALL attributes.
# You can allow/deny whole attributes or specific values of the attributes.
# The first rule decides. If you allowed something, you can not deny it later and vice versa. So start with the special rules and leave the generic rules to the end.
You can allow an attribute by using <code><AllowAttribute></code> element and deny it with <code><DenyAttribute></code>. Each element can optionally have child elements <code><AttributeValue></code>, which means that the action is only performed on certain values of the attribute.
{{INFO_EN|An attribute is removed from the set if its last value is removed. It means that it's not possible to pass through attributes without at least one value.}}
=== Using conditions ===
You can use the <code><Condition></code> node in a filter rule just like with converter. The syntax is the same. So if you omit the <code>Condition</code> element then the rule is evaluated unconditionally.
There is one slight difference: in FilterRule, '''AttributeMatch is always evaluated on the original input attribute set'''. It means that you can reference attributes in conditions even if they were allowed or denied before. (This is what you would normally expect, though.)
You can allow or deny multiple attributes within one <code><FilterRule></code>. Note that the rule only applies if all the conditions within its <code><Condition></code> element evaluate to true.
=== Examples ===
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<AttributeFilter xmlns='urn:geant:edugain:attribute-mangling:1.0'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='urn:geant:edugain:attribute-mangling:1.0 AttributeMangling.xsd'>
<FilterRule>
<Description>Unconditional allowing and denying. The main rule is to deny ALL attributes.</Description>
<AllowAttribute attributeName="mail" />
<AllowAttribute attributeName="cn" />
<AllowAttribute attributeName="eppn" />
<DenyAttribute attributeName="userPassword" />
<DenyAttribute attributeName="uid" />
<DenyAttribute attributeName="homeOrganization" />
<AllowAttribute attributeName="schacHomeOrganization" />
</FilterRule>
<FilterRule>
<Description>Use conditions - allow only specific attribute values</Description>
<Condition>
<LocalProviderMatch>^urn:.*\.hu$</LocalProviderMatch>
</Condition>
<AllowAttribute attributeName="eduPersonEntitlement">
<AttributeValue>^.*@.*\.hu$</AttributeValue>
</AllowAttribute>
</FilterRule>
<FilterRule>
<Description>Use conditions - reference any attribute</Description>
<Condition>
<AttributeMatch attributeName="homeOrganization">niif.hu</AttributeMatch>
</Condition>
<AllowAttribute attributeName="eduPersonEntitlement">
<AttributeValue>^.*@niif\.hu$</AttributeValue>
</AllowAttribute>
</FilterRule>
</AttributeFilter>
</source>
== Integration ==
You can integrate Attribute Conversion and Filtering into your Bridging Element by using these java code snippets. (Of course, edugain.jar and converter.jar need to be placed on the classpath.)
=== Initialization time ===
This code is need needs to be invoked in BE initialization time (and not in runtime, as xml XML configuration parsing is a time-consuming process).
<source lang="java">
// get a reference to the AttributeConverterFactory singleton object AttributeConverterFactory factory = AttributeConverterFactory.getInstance(); // set the configuration file paths (which paths can be set in web.xml for example) factory.setAttributeConverterFilePath("path-to-converter.xml"); factory.setAttributeFilterFilePath("path-to-filter.xml"); factory.setAttributeNameMapperFilePath("path-to-namemapper.xml"); // create converter and filter objects try { AttributeConverter converter = factory.createAttributeConverter(); AttributeFilter filter = factory.createAttributeFilter(); } catch (ConfigurationException ex) { // handle configuration errors (missing files, not valid xmls and more issues) log.error(ex); }
</source>
=== Runtime ===
This code is invoked in BE runtime. You should have a List of AttributeValues, which was either received from the IdP or from the H-BE. You will get the output attribute set after invoking <code>process()</code> method. Note that <code>process()</code> takes two more arguments: <code>remote</code> and <code>local</code>. These represent the local and remote peers that your BE bridges together. Use of these identifiers is optional, you can pass <code>null</code>. {{ATTENTION_EN|If you do not pass <code>local</code> or <code>remote</code> then rules containing <code>LocalProviderMatch</code> or <code>RemoteProviderMatch</code> will '''NOT''' be executed.}}
<source lang="java">
String remote = "remote-federation-peer-identifier"; String local = "local-federation-peer-identifier"; // get Attributes from the assertion List<AttributeValues> input = ...;
// Call converter and filter in order. // Home BE should call attribute converterfirst, remote BE should call filter first. if (isHomeBE) { List<AttributeValues> output = converter.process(input, remote, local);// call attribute output = filter.process(output, remote, local); } else { List<AttributeValues> output = filter.process(input, remote, local); output = converter.process(output, remote, local); } // process output here, create new assertion, etc.
</source>
<?xml version="1.0" encoding="UTF-8"?>
<AttributeConverter
xmlns='urn:geant:edugain:attribute-convertermangling:1.0'>
<BasicRule>
<Description>Create static attribute</Description>
===== Home =====
===== Remote =====
[[Kategória: english]]
[[Kategória: AAI]]
