Attribute in a Nutshell

Ein Identity Provider stellt mithilfe von Attributen Informationen über Nutzer*innen zur Verfügung. Diese Attribute bilden die Grundlage für die Autorisierung am Service Provider. Daneben gibt es Attribute, die der eindeutigen Identifizierung von Nutzer*innen dienen (z.B. givenName, sn, eduPersonPrincipalName oder mail). Diese Attribute können am SP zur Personalisierung des Dienstes dienen.

Ein Service Provider nimmt die Attribute entgegen und gibt sie an die geschützte Anwendung weiter. Die SP-Software und/oder die Anwendung entscheiden anhand ihrer konfigurierten Regeln über den Zugriff.

Wie es Ihnen möglicherweise von Verzeichnisdiensten bekannt ist, sind auch hier Schemata das Organisationsprinzip von Attributen. Ein Schema liegt fest, welche Attribute es gibt, welche und wie viele Werte ein Attribut haben kann und was es bedeutet. Im Föderationsumfeld haben sich folgende Schemata etabliert:

• eduPerson (international genutzt)
• SCHAC, Schema for Academia (international genutzt)
• dfnEduPerson (im e-Learning-Bereich in Deutschland verbreitet)
• weitere Attribute, etwa aus dem inetOrgPerson-Schema

Für ausführlichere Informationen schauen Sie bitte auch diese Seite an.

Hier sehen Sie ein paar Beispiele für gängige Attribute. Für weitere Informationen schauen Sie bitte auf unsere Liste der Attribute, die in der DFN-AAI überlichweise ausgetauscht werden.

Der IdP kann konfiguriert werden, verschiedene Dinge mit den Attributen aus dem Nutzerverzeichnis zu tun:

• Er kann sie so, wie sie sind, weiterverarbeiten. Hier wird ein „simple“ Attribut mit der id „sn“ (surname) definiert. Es wird befüllt mit dem Wert des Attributes „sn“, das der DataConnector myLDAP liefert.

      <AttributeDefinition id="sn" xsi:type="Simple">
          <InputDataConnector ref="myLDAP" attributeNames="sn"/>
      </AttributeDefinition>

• Er kann sie splitten, neu zusammenfügen oder umschreiben. In diesem Beispiel wird inline Javascript verwendet, um eine Berechtigung in Abhängigkeit vom Wert eines anderen Attributes zu vergeben. Die eduPersonAffiliation muss bereits definiert sein. Dann kann sie als Input für eine neue Definition verwendet werden. Wenn der Wert von eduPersonAffiliation „member“ enthält, dann soll dem Multi-Value-Attribut eduPersonEntitlement ein Wert hinzugefügt werden, nämlich „urn:mace:dir:entitlement:common-lib-terms“. Das ist laut Konvention das Entitlement, das das Bibliotheksnutzungsrecht ausdrückt.

   <AttributeDefinition xsi:type="ScriptedAttribute" id="eduPersonEntitlement">
      <InputAttributeDefinition ref="eduPersonAffiliation" />
          <Script>
              <![CDATA[
                  if (eduPersonAffiliation.getValues().contains("member")) {
                      eduPersonEntitlement.getValues().add("urn:mace:dir:entitlement:common-lib-terms");
                  }
               ]]>
          </Script>
   </AttributeDefinition>

• Er kann neue Attribute erstellen, die z.B. von vorhandenen Attributen oder Werten abhängen. Im folgenden Beispiel wird ein Attribut aus einem anderen gebildet: Die eduPersonAffiliation muss bereits definiert sein und wird weiterverwendet. „Scoped“ bedeutet, dass der in ./conf/idp.properties definierte IdP-Scope („hochschule-xy.de“) an den Attributwert angehängt wird. So wird aus der eduPersonAffiliation die eduPersonScopedAffiliation gemacht. Wenn eduPersonAffiliation den Wert „student“ hat, bekommt eduPersonScopedAffiliation den Wert „student@hochschule-xy.de“. (vgl. ScopedAttributeDefinition im Shibboleth-Wiki)

      <AttributeDefinition xsi:type="Scoped" id="eduPersonScopedAffiliation" scope="%{idp.scope}">
          <InputAttributeDefinition ref="eduPersonAffiliation" />
      </AttributeDefinition>

Diese Konfigurationen nehmen Sie in einer der zentralen Konfigurationsdateien ./conf/attribute-resolver.xml vor: Dort sind sowohl die Attributquellen (LDAP, AD, SQL) als auch die IdP-intern definierten Attribute hinterlegt. Es gibt verschiedene Typen von AttributeDefinition, u.a. Simple, Mapped, oder ScriptedAttribute, um mit den Attributen zu jonglieren. Alle Typen sind im Shibboleth-Wiki dokumentiert.

Welche Attribute an welche SPs herausgegeben werden, reguliert man über Attribute Filter Policies in ./conf/attribute-filter.xml. Dort werden die freizugebenden Attribute über ihre ID aus ./conf/attribute-resolver.xml angesprochen. Die Kriterien, nach denen Filterregeln greifen sollen, sind sehr flexibel. Die gängigsten Fälle sind das Filtern nach EntityIDs, also einzelnen SPs, und nach Entity-Attributen, also nach Markern, die eine ganze Gruppe von SPs trägt. (Siehe auch im Shibboleth-Wiki: AttributeFilterConfiguration und AttributeFilterPolicyConfiguration.)

Eine einfache Filter-Policy, die ein Attribut an den SP mit der EntityID https://beispiel-sp.de/shibboleth herausgibt, könnte so aussehen:

<AttributeFilterPolicy id="beispiel">
    <PolicyRequirementRule xsi:type="Requester" value="https://beispiel-sp.de/shibboleth" />
    <AttributeRule attributeID="mail"      permitAny="true"/>
</AttributeFilterPolicy>

Eine von uns empfohlene Filterregel gibt einige anonyme Informationen grundsätzlich heraus: Egal, wer fragt, das Attribut eduPersonEntitlement geht immer raus, wenn es den Wert urn:mace:dir:entitlement:common-lib-terms (Bibliotheksnutzung) hat. Und das AttributeduPersonScopedAffiliation wird immer dann übertragen, wenn der Wert „member“ (= Hochschulangehörige*r) oder „library-walk-in“ (Terminalnutzung in Bibliotheken) ist.

  <AttributeFilterPolicy id="LibraryTermsToAnyone">
    <PolicyRequirementRule xsi:type="ANY" />
    <AttributeRule attributeID="eduPersonEntitlement">
      <PermitValueRule xsi:type="Value" value="urn:mace:dir:entitlement:common-lib-terms"/>
    </AttributeRule>
    <AttributeRule attributeID="eduPersonScopedAffiliation">
      <PermitValueRule xsi:type="OR">
        <Rule xsi:type="Value" value="member"                ignoreCase="true"/>
        <Rule xsi:type="Value" value="library-walk-in"       ignoreCase="true"/>
      </PermitValueRule>
    </AttributeRule>
  </AttributeFilterPolicy>

Service Provider verstehen die im IdP konfigurierten, menschenlesbaren Attributnamen nicht. Der IdP muss sie mithilfe eines Encoders konvertieren. Momentan werden von Shibboleth IdP von Haus aus drei Encoder unterstützt, nämlich SAML1 (veraltet), SAML2 und CAS. In Zukunft wird auch OIDC dazukommen. https://wiki.shibboleth.net/confluence/display/IDP4/AttributeEncoderPluginConfiguration

Ab Shibboleth IdP 4.0.0 werden die Transcoding-Regeln in der neuen Attribute Registry konfiguriert. Bis Shibboleth IdP 3.4.6 standen die Encoder mit in der Attributdefinition in ./conf/attribute-resolver.xml drin. Dies ist auch weiterhin eine funktionierende Konfiguration. Bei einer Neuinstallation sollten Sie jedoch den Weg der Attribute Registry gehen. Sie macht die Attributdefinition übersichtlicher.

Die mitgelieferten Transcoding-Regeln liegen in ./conf/attributes/default-rules.xml. Sie können sie zunächst einfach lassen, wie sie sind, obwohl sie umfangreicher sind als nötig. Hier eine gekürzte Regel (lauffähige) für das mail-Attribut auf einem IdP, der nur SAML2 spricht:

<bean parent="shibboleth.TranscodingProperties">
    <property name="properties">
        <props merge="true">
            <!-- das Attribut, um das es geht -->
            <prop key="id">mail</prop>
            <!-- Es soll nur SAML2 unterstützt werden. -->
            <prop key="transcoder">SAML2StringTranscoder</prop>
            <!-- Die standardisierte oid für mail lautet urn:oid:0.9.2342.19200300.100.1.3 -->
            <prop key="saml2.name">urn:oid:0.9.2342.19200300.100.1.3</prop>
            <!-- Anzeigenamen für die Zustimmungsabfrage vor der Attributfreigabe --> 
            <prop key="displayName.en">E-mail</prop>
            <prop key="displayName.de">E-Mail</prop>
        </props>
    </property>
</bean>

Nachdem die Benutzer*innen der Attributübertragung zugestimmt haben, schickt der IdP eine SAML-Assertion an den SP. Ein Teil der SAML-Assertion ist das Attribute Statement. Der empfangende SP erkennt die Attribute anhand der URIs (meist urn:oid) im Feld „Name“.

<saml2:AttributeStatement>
    <saml2:Attribute FriendlyName="eduPersonEntitlement"
        Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue>urn:mace:dir:entitlement:common-lib-terms</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="eduPersonScopedAffiliation"
        Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue>member@testscope.aai.dfn.de</saml2:AttributeValue>
    </saml2:Attribute>
</saml2:AttributeStatement>