547
szerkesztés
Módosítások
nincs szerkesztési összefoglaló
[[Image:JRA5Attributes_bigpicture.png|Attributes:The Big Attribute Picture]]
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 [[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)
The rule's action is to create new attributes (or to modify existing ones). Please refer to the detailed BasicRule, MergeRule, SplitRule documentation below.
== Attribute conversion rule types ==
The Basic rule is the simplest attribute conversion rule type. It can create one attribute and optionally use one attribute and regular expressions to transform attribute values.
Basic Rule can create static attributes. You can archieve achieve this by omitting the Condition node. The <code>replaceValues </code> parameter is true by default, so if you want to append values to (probably) existing attributes, you must declare it using <code>replaceValues="false"</code>. Also note that you can use multiple AttributeValue nodes.
<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>
The next rule is using remote provider matching to determine whether the remote side has an identifier of 'urn:geant:edugain:be:' and any hungarian Hungarian domain appended to it.
<source lang="xml">
<RemoteProviderMatch>^urn:geant:edugain:be:[^:]+\.hu$</RemoteProviderMatch>
<AttributeValue>niif.hu</AttributeValue>
</source>
This example shows how to rename an attribute without converting its values. Note that you must use <code>AttributeMatch </code> without regular expressions to archieve achieve this.
<source lang="xml">
<Description>Rename attribute uid to edupersonPrincipalName</Description>
<Condition>
</Condition>
<Attribute attributeName="edupersonPrincipalName">
</Attribute>
</source>
The next example demonstrates the use of regular expression matching groups.
<source lang="xml">
<Condition>
</Condition>
<Attribute attributeName="homeOrganization">
</Attribute>
</source>
This latter 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 which 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>
You can also use regular expressions, as with '''BasicRule'''.
=== SplitRule ===
The '''SplitRule ''' is very similar to the '''MergeRule''', the only difference is that the '''SplitRule containes ''' contains one <code>InputAttribute </code> and more <code>Attribute </code> nodes.
<source lang="xml">
</Attribute>
<Attribute attributeName="homeOrganization">
</Attribute>
</source>
=== CustomRule ===
<source lang="xml">
<Configuration>
</Configuration>
</CustomRule></source> '''CustomRule''' class must implement the <code>net.geant.edugain.attributes.rules.Rule</code> interface, configuration can be read with the DOM API. Please refer to the Attribute Converter JavaDOC, and see the test package as it contains a sample implementation. === 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 <code><*Match></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 for the 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"><BasicRule> <Decription>Create preferredLanguage only if source has not supplied it</Decription> <Condition> <AttributeMatch attributeName="preferredLanguage" negate="true"/> </Condition> <Attribute attributeName="preferredLanguage"> <AttributeValue>hu, en-gb;q=0.8, en;q=0.7</AttributeValue> </Attribute></BasicRule></source> == Using attribute name mapper ==For interoperability, SAML AttributeStatement carries attribute names with URN-style attribute naming scheme. For example, the 'mail' logical attribute name can be named as <code>'urn:mace:dir:attribute-def:mail'</code>, or <code>'urn:oid:0.9.2342.19200300.100.1.3'</code>. Shibboleth2 further encourages federations to use the latter form (ie. the LDAP oid). The eduGAIN Attribute Converter library comes with an attribute name mapping subsystem. With the help of the attribute name mapper, system administrators can '''write the attribute converter configuration independently of the currently used attribute name format in AttributeStatement'''. === Attribute name mapper concepts ===As the attribute conversion sits between two federations (and probably two attribute naming schemes), there are two types of physical attributes: the 'input' and 'output' attributes. Note that these notation is different in Home and Remote BEs: Home BE releases attributes to the eduGAIN federation, Remote BE releases attributes to the local federation. So the eduGAIN format is the''' 'output' attribute format of the Home BE, and the 'input' format of the Remote BE.''' The following example shows the difference between logical and physical attribute names. {| {{wikitable}}|+ '''Input and output attribute names'''! Physical input attribute name !! Logical attribute name !! Physical output attribute name|-|urn:mace:dir:attribute-def:mail|rowspan="2"| <center>'''mail'''</center>|rowspan="2"| urn:mace:dir:attribute-def:mail|-|urn:oid:0.9.2342.19200300.100.1.3|-|} === Configuration of the attribute name mapper ===The configuration xml of the attribute name mapper consists of one or more AttributeDefinition nodes. Each AttributeDefinition node specifies one logical attribute name (called 'id') and one physical AttributeName - which is the physical 'output' attribute name format. You can also specify AttributeNamespace (for SAML1.0). The 'input' attribute names are configured using the 'Attribute' node. Note that the output name is also interpreted as input name, so it is not necessary to declare it twice. <source lang="xml"> <AttributeDefinition Id="mail" AttributeName="urn:mace:dir:attribute-def:mail"> <Attribute AttributeName="urn:oid:0.9.2342.19200300.100.1.3" /CustomRule> </AttributeDefinition>
</source>
== Testing ==
=== XMLTest.sh ===
Attribute conversion library comes with XML-based test framework. The test can be invoked by the <code>net.geant.edugain.attributes.xmltest.AttributeConverterTest</code> main class. There is the '''<code>XMLTest.sh</code>''' script attached to the project, which makes it easy to execute the testing framework.
$ ./XMLTest.sh
Attribute Converter Test usage
java AttributeConverterTest
[-debug]
[-converterconfig AttributeConverter.xml]
[-filteringconfig AttributeFilter.xml]
[-attributenameconfig AttributeNameMapping.xml]
[-output output.xml]
input.xml
==== Example test configuration ====
The <code>xmltest/</code> directory contains the following examples
'''<code>AttributeNameMapper.xml</code>''' converter name mapper configuration
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<AttributeMapper
xmlns='urn:geant:edugain:attribute-mapper:1.0'>
<AttributeDefinition
Id="mail"
AttributeName="urn:mace:dir:attribute-def:mail">
<Attribute AttributeName="urn:oid:0.9.2342.19200300.100.1.3" />
</AttributeDefinition>
<AttributeDefinition
Id="edupersonAffiliation"
AttributeName="urn:mace:dir:attribute-def:eduPersonAffiliation" />
<AttributeDefinition
Id="homeOrganization"
AttributeName="urn:mace:dir:attribute-def:homeOrganization" />
<AttributeDefinition
Id="cn"
AttributeName="urn:mace:dir:attribute-def:cn">
<Attribute AttributeName="urn:oid:2.5.4.3"/>
</AttributeDefinition>
</AttributeMapper>
</source>
'''<code>AttributeConverter.xml</code>''' converter configuration
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<AttributeConverter
xmlns='urn:geant:edugain:attribute-mangling:1.0'>
<BasicRule>
<Description>Create static attribute</Description>
<Attribute attributeName="eduPersonAffiliation" replaceValues="false">
<AttributeValue>staff@niif.hu</AttributeValue>
</Attribute>
</BasicRule>
<BasicRule>
<Description>Create static attribute for some remote providers</Description>
<Condition>
<RemoteProviderMatch>^urn:geant:edugain:be:[^:]+\.hu$</RemoteProviderMatch>
</Condition>
<Attribute attributeName="homeOrganization">
<AttributeValue>niif.hu</AttributeValue>
</Attribute>
</BasicRule>
<MergeRule>
<Description>Merges the common name to the email address(es)</Description>
<InputAttribute attributeName="cn" />
<InputAttribute attributeName="mail" />
<Attribute attributeName="mail" replaceValues="true">
<AttributeValue>${cn} <${mail}></AttributeValue>
</Attribute>
</MergeRule>
</AttributeConverter>
</source>
'''<code>AttributeTest.xml</code>''' test input xml
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<AttributeTest
xmlns='urn:geant:edugain:attribute-test:1.0'
Remote="urn:geant:edugain:be:niif.hu" >
<Attribute AttributeName="urn:oid:0.9.2342.19200300.100.1.3">
<AttributeValue>adam.lantos@niif.hu</AttributeValue>
<AttributeValue>hege@niif.hu</AttributeValue>
</Attribute>
<Attribute AttributeName="urn:mace:dir:attribute-def:eduPersonAffiliation">
<AttributeValue>staff</AttributeValue>
</Attribute>
<Attribute AttributeName="urn:oid:2.5.4.3">
<AttributeValue>Adam Lantos</AttributeValue>
</Attribute>
</AttributeTest>
</source>
==== Output of the example ====
$ ./XMLTest.sh \
-converterconfig xmltest/AttributeConverter.xml \
-attributenameconfig xmltest/AttributeNameMapper.xml \
xmltest/AttributeTest.xml
AttributeConverter.<init> (80) : Creating new rule: class net.geant.edugain.attributes.rules.BasicRule
AttributeConverter.<init> (81) : Rule Description: Create static attribute
AttributeConverter.<init> (80) : Creating new rule: class net.geant.edugain.attributes.rules.BasicRule
AttributeConverter.<init> (81) : Rule Description: Create static attribute for some remote providers
AttributeConverter.<init> (80) : Creating new rule: class net.geant.edugain.attributes.rules.MergeRule
AttributeConverter.<init> (81) : Rule Description: Merges the common name to the email address(es)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AttributeTest xmlns="urn:geant:edugain:attribute-test:1.0">
<Attribute AttributeName="urn:mace:dir:attribute-def:eduPersonAffiliation">
<AttributeValue>staff</AttributeValue>
<AttributeValue>staff@niif.hu</AttributeValue>
</Attribute>
<Attribute AttributeName="urn:mace:dir:attribute-def:mail">
<AttributeValue>Adam Lantos &lt;adam.lantos@niif.hu&gt;</AttributeValue>
<AttributeValue>Adam Lantos &lt;hege@niif.hu&gt;</AttributeValue>
</Attribute>
<Attribute AttributeName="urn:mace:dir:attribute-def:homeOrganization">
<AttributeValue>niif.hu</AttributeValue>
</Attribute>
<Attribute AttributeName="urn:mace:dir:attribute-def:cn">
<AttributeValue>Adam Lantos</AttributeValue>
</Attribute>
</AttributeTest>
=== Real-life examples ===
{{TODO_EN|Please post your BE configuration here.}}
==== Hungarnet ====
===== Home =====
===== Remote =====
[[Kategória: english]]
[[Kategória: AAI]]