Attribute Conversion for eduGAIN - Laptörténet

Sitya(AT)niif.hu, 2013. május 2., 09:18-n

2013-05-02T09:18:23Z

Bajnokk(AT)niif.hu: /* Introduction */ fix dead link

2009-01-08T13:55:05Z

‎Introduction: fix dead link

Bajnokk(AT)niif.hu: /* Integration */ extend documentation

2008-10-09T06:43:22Z

‎Integration: extend documentation

Bajnokk(AT)niif.hu: /* Attribute Filtering */ describing concepts, rephrasing

2008-10-09T06:28:30Z

‎Attribute Filtering: describing concepts, rephrasing

Bajnokk(AT)niif.hu: /* Attribute conversion rule types */ correct XML indentation at examples

2008-10-09T05:52:18Z

‎Attribute conversion rule types: correct XML indentation at examples

Bajnokk(AT)niif.hu: /* Negating matches */ indentation

2008-10-09T05:46:13Z

‎Negating matches: indentation

Bajnokk(AT)niif.hu: /* Attribute conversion rule types */ minor changes

2008-10-08T12:16:51Z

‎Attribute conversion rule types: minor changes

Bajnokk(AT)niif.hu: /* MergeRule */ localprovidermatch

2008-10-08T12:12:07Z

‎MergeRule: localprovidermatch

Hege(AT)niif.hu: /* Example test configuration */

2008-10-07T22:34:33Z

‎Example test configuration

Hege(AT)niif.hu: /* Runtime */

2008-10-07T22:21:51Z

‎Runtime

← Régebbi változat		A lap 2013. május 2., 09:18-kori változata
446. sor:		446. sor:
	===== Home =====		===== Home =====
	===== Remote =====		===== Remote =====
		+
		+	[[Kategória: english]]
		+	[[Kategória: AAI]]

@@ 5. sor: / 5. sor: @@
 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 | 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 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].

@@ 255. sor: / 255. sor: @@
 == 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)
+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 to be invoked in BE initialization time (and not in runtime, as xml configuration parsing is a time-consuming process).
+This code needs to be invoked in BE initialization time (and not in runtime, as XML configuration parsing is a time-consuming process).
 <source lang="java">
-// get a reference to the AttributeConverterFactory singleton object
+  // get a reference to the AttributeConverterFactory singleton object
-AttributeConverterFactory factory = AttributeConverterFactory.getInstance();
+  AttributeConverterFactory factory = AttributeConverterFactory.getInstance();
-// set the configuration file paths (which paths can be set in web.xml for example)
+  // set the configuration file paths (which paths can be set in web.xml for example)
-factory.setAttributeConverterFilePath("path-to-converter.xml");
+  factory.setAttributeConverterFilePath("path-to-converter.xml");
-factory.setAttributeFilterFilePath("path-to-filter.xml");
+  factory.setAttributeFilterFilePath("path-to-filter.xml");
-factory.setAttributeNameMapperFilePath("path-to-namemapper.xml");
+  factory.setAttributeNameMapperFilePath("path-to-namemapper.xml");
-−
-// create converter and filter objects
+  // create converter and filter objects
-try {
+  try {
-  AttributeConverter converter = factory.createAttributeConverter();
+    AttributeConverter converter = factory.createAttributeConverter();
-  AttributeFilter filter = factory.createAttributeFilter();
+    AttributeFilter filter = factory.createAttributeFilter();
-} catch (ConfigurationException ex) {
+  } catch (ConfigurationException ex) {
- // handle configuration errors (missing files, not valid xmls and more issues)
+    // handle configuration errors (missing files, not valid xmls and more issues)
-  log.error(ex);
+    log.error(ex);
-−
+  }
 </source>
 === Runtime ===
-This code is invoked in BE 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>.
 <source lang="java">
-String remote = "remote-federation-peer-identifier";
+  String remote = "remote-federation-peer-identifier";
-String local = "local-federation-peer-identifier";
+  String local = "local-federation-peer-identifier";
 // get Attributes from the assertion
-List<AttributeValues> input = ...;
+  // get Attributes from the assertion
+  List<AttributeValues> input = ...;
-// process output here, create new assertion, etc.
+  // Call converter and filter in order.
 </source>

@@ 192. sor: / 192. sor: @@
 == Attribute Filtering ==
-=== Concepts ===
+Filter uses name mappers in the same way as Converter. So you should define your attributes there before you start using 'friendly' attribute names here.
 === Allowing and denying attributes ===
-Three main rules of the filtering framework:
+Three main rules of the filtering:
-* Default action is Deny ALL Attributes.
+# Default action is to deny ALL attributes.
-* You can allow/deny whole attributes or specific values of the 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. So start with the special rules and leave the generic rules to the end.
+# 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.
-Note that attribute names are all flowed through the attribute name mapping subsystem.
+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.
-Here is an example.
+{{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.}}
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ 218. sor: / 228. sor: @@
         <DenyAttribute attributeName="uid" />
         <DenyAttribute attributeName="homeOrganization" />
     </FilterRule>
@@ 225. sor: / 236. sor: @@
             <LocalProviderMatch>^urn:.*\.hu$</LocalProviderMatch>
         </Condition>
-        <AllowAttribute attributeNme="eduPersonScopedEntitlement">
+        <AllowAttribute attributeName="eduPersonEntitlement">
             <AttributeValue>^.*@.*\.hu$</AttributeValue>
         </AllowAttribute>
@@ 235. sor: / 246. sor: @@
             <AttributeMatch attributeName="homeOrganization">niif.hu</AttributeMatch>
         </Condition>
-        <AllowAttribute attributeName="eduPersonScopedEntitlement">
+        <AllowAttribute attributeName="eduPersonEntitlement">
             <AttributeValue>^.*@niif\.hu$</AttributeValue>
         </AllowAttribute>
@@ 242. sor: / 253. sor: @@
 </AttributeFilter>
 </source>
 == Integration ==

@@ 27. sor: / 27. sor: @@
 <source lang="xml">
- <BasicRule>
+<BasicRule>
    <Description>Create static attribute (or append to existing if attribute with this name already exists)</Description>
    <Attribute attributeName="eduPersonScopedAffiliation" replaceValues="false">
-   <AttributeValue>staff@niif.hu</AttributeValue>
+    <AttributeValue>staff@niif.hu</AttributeValue>
-   <AttributeValue>member@href.hu</AttributeValue>
+    <AttributeValue>member@href.hu</AttributeValue>
    </Attribute>
- </BasicRule>
+</BasicRule>
 </source>
@@ 40. sor: / 40. sor: @@
 <source lang="xml">
- <BasicRule>
+<BasicRule>
-   <Description>Create static attribute for some remote providers</Description>
+  <Description>Create static attribute for some remote providers</Description>
-   <Condition>
+  <Condition>
      <RemoteProviderMatch>^urn:geant:edugain:be:[^:]+\.hu$</RemoteProviderMatch>
-   </Condition>
+  </Condition>
-   <Attribute attributeName="homeOrganization">
+  <Attribute attributeName="homeOrganization">
      <AttributeValue>niif.hu</AttributeValue>
-   </Attribute>
+  </Attribute>
- </BasicRule>
+</BasicRule>
 </source>
@@ 55. sor: / 55. sor: @@
 <source lang="xml">
- <BasicRule>
+<BasicRule>
    <Description>Rename attribute uid to edupersonPrincipalName</Description>
    <Condition>
-   <AttributeMatch attributeName="uid"/>
+    <AttributeMatch attributeName="uid"/>
    </Condition>
    <Attribute attributeName="edupersonPrincipalName">
-   <AttributeValue>${uid}</AttributeValue>
+    <AttributeValue>${uid}</AttributeValue>
    </Attribute>
- </BasicRule>
+</BasicRule>
 </source>
@@ 70. sor: / 70. sor: @@
 <source lang="xml">
- <BasicRule>
+<BasicRule>
    <Decription>Transform 'o=org,c=country'-style OrgDN to DNS-based homeOrganization</Decription>
    <Condition>
-   <AttributeMatch attributeName="edupersonOrgDN" id="regex">o=(.*),c=(.*)</AttributeMatch>
+    <AttributeMatch attributeName="edupersonOrgDN" id="regex">o=(.*),c=(.*)</AttributeMatch>
    </Condition>
    <Attribute attributeName="homeOrganization">
-   <AttributeValue>${regex[1]}.${regex[2]}</AttributeValue>
+    <AttributeValue>${regex[1]}.${regex[2]}</AttributeValue>
    </Attribute>
- </BasicRule>
+</BasicRule>
 </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 expressions.}}
+{{INFO_EN|You cannot reference regular expressions from another rule.}}
 === MergeRule ===
@@ 90. sor: / 90. sor: @@
 <source lang="xml">
- <MergeRule>
+<MergeRule>
    <Description>Merges the uid and homeOrganization to edupersonPrincipalName</Description>
    <InputAttribute attributeName="homeOrganization" />
    <InputAttribute attributeName="uid" />
    <Attribute attributeName="edupersonPrincipalName" replaceValues="true">
-   <AttributeValue>${uid}@${homeOrganization}</AttributeValue>
+    <AttributeValue>${uid}@${homeOrganization}</AttributeValue>
    </Attribute>
- </MergeRule>
+</MergeRule>
 </source>
@@ 106. sor: / 106. sor: @@
 <source lang="xml">
- <SplitRule>
+<SplitRule>
    <Description>Split the edupersonScopedAffiliation to edupersonAffiliation and homeOrganization</Description>
    <InputAttribute attributeName="edupersonScopedAffiliation" id="scopedAffiliation" >^([^@]+)@(.+)$</InputAttribute>
    <Attribute attributeName="edupersonAffiliation">
-   <AttributeValue>${scopedAffiliation[1]}</AttributeValue>
+    <AttributeValue>${scopedAffiliation[1]}</AttributeValue>
    </Attribute>
    <Attribute attributeName="homeOrganization">
-   <AttributeValue>${scopedAffiliation[2]}</AttributeValue>
+    <AttributeValue>${scopedAffiliation[2]}</AttributeValue>
    </Attribute>
- </SplitRule>
+</SplitRule>
 </source>
@@ 122. sor: / 122. sor: @@
 <source lang="xml">
- <CustomRule className="org.test.MyCustomRuleImpl">
+<CustomRule className="org.test.MyCustomRuleImpl">
    <Configuration>
-   <!-- any xml here -->
+    <!-- any xml here -->
    </Configuration>
- </CustomRule>
+</CustomRule>
 </source>

@@ 119. sor: / 119. sor: @@
 === CustomRule ===
-If you need to create new attributes from program (eg. appending generated identifiers), you can use the CustomRule type.
+If you need to create new attributes from program (eg. appending generated identifiers), you can use the '''CustomRule''' type.
 <source lang="xml">
@@ 132. sor: / 132. sor: @@
 === 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 '''<AttributeMatch>''' and the '''<RemoteProviderMatch>''' nodes (inside '''<Condition>''' element) to revert the match. It means that the rule is only processed if there is no match in the attribute set (or to the remote provider string).
+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):

@@ 85. sor: / 85. sor: @@
 === 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> (<code>AttributeMatch</code> is ignored).
+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:

@@ 347. sor: / 347. sor: @@
 <?xml version="1.0" encoding="UTF-8"?>
 <AttributeConverter
-    xmlns='urn:geant:edugain:attribute-converter:1.0'>
+    xmlns='urn:geant:edugain:attribute-mangling:1.0'>
      <BasicRule>
          <Description>Create static attribute</Description>

@@ 278. sor: / 278. sor: @@
 List<AttributeValues> input = ...;
-// call attribute converter
+// Call converter and filter in order.
-List<AttributeValues> output = converter.process(input, remote, local);
+// Home BE should call converter first, remote BE should call filter first.
-// call attribute filter
+if (isHomeBE) {
-output = filter.process(output, remote, local);
+ List<AttributeValues> output = converter.process(input, remote, local);
 // process output here, create new assertion, etc.