Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- de:attributes [2020/01/13 16:41] – Wolfgang Pempe
+++ de:attributes [2020/04/16 15:35] – Silke Meyer
@@ Zeile 2: / Zeile 2: @@
 ====== Attribute ======
 {{INLINETOC 2}}
-Diese Seite bietet eine Übersicht über die **Attribute**, die in der DFN-AAI üblicherweise zwischen den beteiligten Systemen ausgetauscht werden. **Das heißt nicht, dass diese Attribute bzw. Schema-Erweiterungen zwingend in ein vorhandenes IdM-System bzw. Nutzerverzeichnis integriert werden müssen!** In vielen Fällen kann in der Konfiguration eines Identity Providers ein Mapping von Informationen aus dem IDM auf die Attribute erfolgen, die bei der SAML-basierten Kommunikation relevant sind. Siehe hierzu auch unter [[de:shibidp3attributes|Attribut-Konfigurationen]].
-Zum grundlegenden Verständnis der Attribut-Generierung, -Freigabe und -Übertragung empfehlen wir die Lektüre dieser [[https://download.aai.dfn.de/ws/2019_cc/attributes.pdf|Präsentation von einem der DFN-AAI Workshops]].
+===== Attribute in a Nutshell =====
+==== IdP und SP ====
+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.
+==== Attributschemata ====
+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:
+  * [[https://wiki.refeds.org/pages/viewpage.action?pageId=50626629|eduPerson]] (international genutzt)
+  * [[https://wiki.refeds.org/display/STAN/SCHAC+Releases|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 [[de:attributes|diese Seite]] an.
+<callout color="#ff9900" title="Der Clou">
+Die Schemata können, müssen aber nicht in Ihrem IdM vorhanden sein! Der IdP kann zwischen den Attributen im IdM und den von SPs verlangten Attributen übersetzen.
+</callout>
+Hier sehen Sie ein paar Beispiele für gängige Attribute. Für weitere Informationen schauen Sie bitte auf unsere [[de:attributes|Liste der Attribute]], die in der DFN-AAI überlichweise ausgetauscht werden.
+^ Schema ^ Attributname ^ Bedeutung ^ Beispielwert ^
+|eduPerson | eduPersonScopedAffiliation | Status innerhalb der Heimateinrichtung mit Scope | student@beispiel-uni.de |
+| |eduPersonPrincipalName | eindeutiger, nicht anonymer Username | hugo@beispiel-uni.de |
+| | eduPersonEntitlement | Berechtigung | urn:mace:dir:entitlement:common-lib-terms |
+| SCHAC | schacPersonalUniqueCode | insbes. Matrikelnummer | urn:schac:personalUniqueCode:de:lmu.de:Matrikelnummer:1234567 |
+==== Attributdefinition am IdP ====
+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 "surname" definiert. Es wird befüllt mit dem Wert des Attributes "sn", das der DataConnector myLDAP liefert.<code xml>    <AttributeDefinition id="surname" xsi:type="Simple">
+        <InputDataConnector ref="myLDAP" attributeNames="sn"/>
+    </AttributeDefinition></code>
+  * 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.<code xml>
+ <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></code>
+  * 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. [[https://wiki.shibboleth.net/confluence/display/IDP4/ScopedAttributeDefinition|ScopedAttributeDefinition im Shibboleth-Wiki]])<code xml>    <AttributeDefinition xsi:type="Scoped" id="eduPersonScopedAffiliation" scope="%{idp.scope}">
+        <InputAttributeDefinition ref="eduPersonAffiliation" />
+    </AttributeDefinition></code>
+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 [[https://wiki.shibboleth.net/confluence/display/IDP4/AttributeDefinitionConfiguration|Shibboleth-Wiki]] dokumentiert.
+==== Attributfilter ====
+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:  [[https://wiki.shibboleth.net/confluence/display/IDP4/AttributeFilterConfiguration|AttributeFilterConfiguration]] und  [[https://wiki.shibboleth.net/confluence/display/IDP4/AttributeFilterPolicyConfiguration|AttributeFilterPolicyConfiguration]].)
+Eine einfache Filter-Policy, die //ein// Attribut an den SP mit der EntityID https://beispiel-sp.de/shibboleth herausgibt, könnte so aussehen:<code xml><AttributeFilterPolicy id="beispiel">
+    <PolicyRequirementRule xsi:type="Requester" value="https://beispiel-sp.de/shibboleth" />
+    <AttributeRule attributeID="mail"      permitAny="true"/>
+</AttributeFilterPolicy></code>
+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 Attribut''eduPersonScopedAffiliation'' wird immer dann übertragen, wenn der Wert "member" (= Hochschulangehörige*r) oder "library-walk-in" (Terminalnutzung in Bibliotheken) ist.<code xml>  <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>
+</code>
+==== Attribut-Encoding ====
+<callout color="#ff9900" title="Neuerung im IdP 4.x">
+Ab Shibboleth IdP 4.0.0 werden die Encoder in der Attribute Registry konfiguriert. Die alte Konfigurationsweise über ''./conf/attribute-resolver.xml'' ist weiterhin lauffähig!
+</callout>
+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:
+<code xml>
+<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></code>
+==== Attributübertragung ====
+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".
+<code xml>
+<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>
+</code>
+<callout color="#ff9900" title="DEBUG-Log zeigt SAML-Assertions">
+Wenn Sie möchten, dass Ihr IdP die Assertions loggt, stellen Sie ''idp.loglevel.messages'' und ''idp.loglevel.encryption'' auf DEBUG (siehe [[de:shibidp:config-log|Logging-Konfiguration]]). Dies ist nützlich, um die tatsächlich übertragenen Attributwerte einzusehen.
+</callout>
+Diese Seite bietet eine Übersicht über die Attributschemata, die in der DFN-AAI verwendet werden. Diese Schemata müssen //nicht// in Ihr IdM-System bzw. Nutzerverzeichnis integriert werden. Die Übersetzung zwischen IdM-Attributen und AAI-Attributen kann im IdP konfiguriert werden.
+**Das heißt nicht, dass diese Attribute bzw. Schema-Erweiterungen zwingend in ein vorhandenes IdM-System bzw. Nutzerverzeichnis integriert werden müssen!** In vielen Fällen kann in der Konfiguration eines Identity Providers ein Mapping von Informationen aus dem IDM auf die Attribute erfolgen, die bei der SAML-basierten Kommunikation relevant sind. Siehe hierzu auch unter [[de:shibidp3attributes|Attribut-Konfigurationen]].
 Im Hochschul- und Forschungsbereich haben sich verschiedene Attribut-Schemata etabliert, die sich inhaltlich weitestgehend ergänzen:
-==== Allgemein ====
+===== Allgemein =====
   * **eduPerson, person, inetOrgPerson, organizationalPerson**
     * [[https://wiki.refeds.org/x/RYAEAw|Ausführliche Dokumentation der eduPerson-Attribute sowie der gängigsten Attribute aus weiteren Schemata bzw. Klassen]]
@@ Zeile 15: / Zeile 160: @@
   * **Kommentierte [[de:common_attributes|Liste der am häufigsten verwendeten / empfohlenen Attribute]]**
-==== E-Learning und DFN-spezifische Erweiterungen ====
+===== E-Learning und DFN-spezifische Erweiterungen =====
   * **SCHAC** (**SCH**ema for **AC**ademia)
     * [[https://wiki.refeds.org/display/STAN/SCHAC+Releases|Offizielle Dokumentation]] (REFEDS, bitte auch die Seite [[https://wiki.refeds.org/display/STAN/SCHAC_1.5.0_issues|SCHAC_1.5.0_issues]] beachten)
@@ Zeile 25: / Zeile 170: @@
   * **Kommentierte [[de:elearning_attributes|Liste der DFN-spezifischen und der gängigsten Attribute aus dem Bereich E-Learning]]**
-==== E-Research / Forschungsinfrastrukturen ====
+===== E-Research / Forschungsinfrastrukturen =====
 Nationale und internationale Forschungsprojekte nutzen in zunehmendem Maße zentrale Dienste, die über "Federated Login" bzw. SAML-basiertes Web-Single-Sign-On zugänglich sind. Um im Sinne guter wissenschaftlicher Praxis einzelne Beiträge eindeutig einem Nutzer zuordnen zu können, müssen in der Regel Attribute mit personenbezogenen Angaben an den jeweiligen Service Provider übertragen werden. Siehe hierzu auch unter [[de:shibidp3attrfilter|Attribut-Konfiguration für E-Research SPs]].
 Ein weiterer Anwendungsfall sind sog. Attribute Authorities, über die Community- bzw. Projekt-spezifische Attribute abgerufen werden können. Um das Mapping zwischen dem/der bei der jeweiligen Heimateinrichtung angemeldeten Nutzer(in) und diesen Attributen herzustellen, ist ein global gültiger, eindeutiger Identifier erforderlich, z.B. [[de:common_attributes#a07|eduPersonPrincipalName]], [[de:common_attributes#a05|E-Mail-Adresse]] oder [[de:common_attributes#a12|eduPersonUniqueId]]. Zu technischen Details siehe auch die betreffenden Seiten im [[https://wiki.edugain.org/Identifier_Attributes|eduGAIN-]] sowie im [[https://wiki.shibboleth.net/confluence/display/CONCEPT/NameIdentifiers|Shibboleth Wiki]].
-===Virtuelle Organisationen===
+====Virtuelle Organisationen====
 Um den Anforderungen virtueller Organisationen zu genügen, die z.B. eine Infrastruktur gemäß der [[https://aarc-project.eu/architecture/|AARC Blueprint Architecture]] betreiben, wurde 2018 das [[https://github.com/voperson/voperson/blob/master/voPerson.md|voPerson Schema]] definiert.

attribute