Attribute Conversion for eduGAIN

Innen: KIFÜ Wiki
A lap korábbi változatát látod, amilyen Hege(AT)niif.hu (vitalap | szerkesztései) 2008. szeptember 3., 15:48-kor történt szerkesztése után volt. (Using attribute name mapper)

JRA5 Attribute Conversion allows a Bridging Element administrator to define rules to transform attributes being released or received. The same logic can work in both Home and Remote Bridging Elements.

Introduction

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 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 regular expressions and Unified Expression Language.

Each rule works on the actual attribute set which is not necessarily the initial set, as each rule can alter the set (ie. by changing values or names, adding new attributes to the set). This means that the order of the rules is important.

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 of matching rules

  • remote peer's name (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

BasicRule

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 this by omitting the Condition node. The replaceValues parameter is true by default, so if you want to append values to (probably) existing attributes, you must declare it using replaceValues="false". Also note you can use multiple AttributeValue nodes.

 <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>member@href.hu</AttributeValue>
  </Attribute>
 </BasicRule>

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 domain appended to it.

 <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>

This example shows how to rename an attribute without converting its values. Note that you must use AttributeMatch without regular expressions to archieve this.

 <BasicRule>
  <Description>Rename attribute uid to edupersonPrincipalName</Description>
  <Condition>
   <AttributeMatch attributeName="uid"/>
  </Condition>
  <Attribute attributeName="edupersonPrincipalName">
   <AttributeValue>${uid}</AttributeValue>
  </Attribute>
 </BasicRule>

The next example demonstrates the use of regular expression matching groups.

 <BasicRule>
  <Decription>Transform o=org,c=country style OrgDN to dns-based homeOrganization</Decription>
  <Condition>
   <AttributeMatch attributeName="edupersonOrgDN" id="regex">o=(.*),c=(.*)</AttributeMatch>
  </Condition>
  <Attribute attributeName="homeOrganization">
   <AttributeValue>${regex[1]}.${regex[2]}</AttributeValue>
  </Attribute>
 </BasicRule>

This latter 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 AttributeMatch. Then, use ${id[0]} to refer to the whole regular expression match (ie. the whole attribute value), and ${id[N]} to refer to the Nth. matching group of the regular expression. You cannot reference other rule's regular expressions.

MergeRule

The merge rule can merge two or more attributes into one. The attributes which values you want to merge is declared using the InputAttribute node. You can also use the condition node, but only with RemoteProviderMatch (AttributeMatch is ignored).

This example shows how to combine two attribute values:

 <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>
  </Attribute>
 </MergeRule>

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 one InputAttribute and more Attribute nodes.

 <SplitRule>
  <Description>Split the edupersonScopedEntitlement to edupersonEntitlement and homeOrganization</Description>
  <InputAttribute attributeName="edupersonScopedEntitlement" id="scopedEntitlement" >^([^@]+)@(.+)$</InputAttribute>
  <Attribute attributeName="edupersonEntitlement">
   <AttributeValue>${scopedEntitlement[1]}</AttributeValue>
  </Attribute>
  <Attribute attributeName="homeOrganization">
   <AttributeValue>${scopedEntitlement[2]}</AttributeValue>
  </Attribute>
 </SplitRule>

CustomRule

When you need to programatically create new attributes (eg. appending generated identifiers), you can use the CustomRule type.

 <CustomRule className="org.test.MyCustomRuleImpl">
  <Configuration>
   <!-- any xml here -->
  </Configuration>
 </CustomRule>

CustomRule class must implement the net.geant.edugain.attributes.rules.Rule interface, configuration can be read with the DOM API. Please refer to the Attribute Converter JavaDOC, and see the test package as it containes a sample implementation.

Using attribute name mapper

In order to archieve interoperability, the SAML AttributeStatement carries attribute names with URN-style attribute naming scheme. For example, the 'mail' logical attribute name can be named as 'urn:mace:dir:attribute-def:mail', or 'urn:oid:0.9.2342.19200300.100.1.3'. Shibboleth2 further encourages federations to use the latter form (ie. the LDAP oid).

The eduGAIN Attribute Converter library comes with AttributeName mapping subsystem. With the help of the attribute name mapper, system administrators can write the attribute converter configuration independently of the currently used AttributeStatement Attribute name format.

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.

Input and output attribute names
Physical input attribute name Logical attribute name Physical output attribute name
urn:mace:dir:attribute-def:mail mail 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.

 <AttributeDefinition
  Id="mail"
  AttributeName="urn:mace:dir:attribute-def:mail">
   <Attribute AttributeName="urn:oid:0.9.2342.19200300.100.1.3" />
 </AttributeDefinition>

Using logical attribute names

When attribute name is referenced in a conversion rule, attribute mapper tries to interpret it as logical attribute name. Note that the logical attribute names are case-insensitive.

Testing

XMLTest.sh

Real-life examples