====== Beispiel für eine EU-DSGVO-konforme Konfiguration des User Consent Moduls ======

<callout color="#ff9900" title="Dokumentation gültig für Shibboleth IdP ab Version 4.1">
Für ältere Versionen des Shib IdP siehe [[de:shibidp:config-consent-dsgvo_shib-idp_4.0.x|diese Seite]]
</callout>

Die im folgenden dokumentierte Beispielkonfiguration beruht sowohl auf den Vorschlägen der Forschungsstelle Recht im DFN, [[https://download.aai.dfn.de/praesentationen/betriebstagungen/69/BT69_AAI_DS-AAI-Verfahren_Strobel_Moerike.pdf|"Datenschutzrechtliche Analyse das AAI-Verfahrens", 69. BT]] als auch auf hausinternen Konsultationen mit dem Justiziariat des DFN-Vereins. 

**Beachten Sie bitte, dass es sich hierbei um unverbindliche Vorschläge handelt! Der DFN-Verein übernimmt keine Verantwortung für etwaige juristische Streitfälle, die sich aus diesen Beispielen oder daraus abgeleiteten Konfigurationen ergeben!**

==== Vorarbeiten ====
Führen Sie zunächst die auf der Seite [[de:shibidp:config-tou|Nutzungsbedingungen und Zustimmung zur Attributfreigabe]] beschrieben Arbeitsschritte durch.

==== Message Properties ====

Die im folgenden vorgestellten Beispiele benötigen die hier verlinkte, angepasste Version der **[[de:shibidp:config-consent-dsgvo-messages|messages.properties]]**. Bitte lesen Sie die Inline-Kommentare und passen die Properties den jeweiligen Erfordernissen und Rahmenbedingungen entsprechend an!

==== Terms of Use ====

Unabhängig davon, auf welcher Rechtsgrundlage die Übertragung von Attributen an einen Service Provider erfolgt, kann der **Terms-of-Use Consent** unter anderem dazu verwendet werden, eine Einwilligung in die Generierung und Speicherung der [[de:shibidp:config-storage|SAML2 Persistent Name ID]] (Persistent Id) in einer IdP-seitigen Datenbank einzuholen. Dies ist insofern sinnvoll, als es sich bei bei der Persistent Id um kein Attribut handelt und Endnutzer beim Zugriff auf einen SP nicht steuern können, ob eine Persistent Id generiert oder übertragen wird. Die Übertragung der Persistent Id wird per Default zwischen IdP und SP ausgehandelt und kann ggf. seitens des IdP-Admins durch eine entsprechend angepasste Relying Party Konfiguration gesteuert werden. Siehe hierzu unter [[de:shibidp:config-storage#weitergabe_der_persistent_id|Weitergabe der Persistent Id]]. \\ 
**Hinweis:** Die in der Datenbank abgelegten Werte für Persistent Ids können auch zur Bildung der Attribute [[de:shibidp:config-attributes-edupersontargetedid|eduPersonTargetedID]] und [[de:shibidp:config-storage#umstellung_auf_saml_pairwise-id|SAML Pairwise Id]] verwendet werden.   

Unser Beispiel stellt noch eine allgemeine Funktionsbeschreibung des IdP voran. Konkret handelt es sich um die Properties ''my-service-description'' und ''my-tou.text''. Selbstverständlich kann und soll dieser Text durch weitere, für die jeweilige Einrichtung relevante Punkte ergänzt werden.

Hier ein Beispiel für ein Velocity Template, das diese Properties zum Einholen der Einwilligung der EndnutzerInnen anzeigt: **[[de:shibidp:config-consent-dsgvo-tou|terms-of-use.vm]]** sowie für eine statische JSP-Datei, die es EndnutzerInnen erlaubt, auf den aktuellen Wortlaut der Einwilligungserklärung zuzugreifen: **[[de:shibidp:config-consent-dsgvo-tou-jsp|tou.jsp]]**. Die letztgenannte Datei muss unter ''./edit-webapp'' abgelegt werden. Änderungen an dieser Datei erfordern daher eine erneute Generierung des IdP-Servlets via ''./bin/build.sh'' (bzw. ''./bin/build.bat''). 
Diese Datei (tou.jsp) kann an beliebiger Stelle verlinkt werden, z.B. im Footer und/oder auf der Login-Seite des IdP:
<file xml ./views/login.vm>
<div class="column two">
  <ul class="list list-help">
     <li class="list-help-item"><a href="#springMessageText("idp.url.password.reset", "#")"><span class="item-marker">&rsaquo;</span> #springMessageText("idp.login.forgotPassword", "Forgot your password?")</a></li>
     <li class="list-help-item"><a href="$request.getContextPath()/tou.jsp" target="_blank"><span class="item-marker">&rsaquo;</span> Wortlaut Einwilligungserklärung</a></li>
  </ul>
  <!-- usw. -->
</file>

Die Anzeige der Daten sieht dann in etwa so aus: \\
{{:de:tou.png?200|}}

==== Attribute Release ====
**Sofern die Übertragung von Attributen ausschließlich freiwillig, aufgrund einer Einwilligung der EndnutzerInnen erfolgt (DSGVO Art. 6.1 lit a), müssen keine weiteren Konfigurationsschritte unternommen werden!** 

Hier ein Beispiel für ein entsprechendes Velocity Template: **[[de:shibidp:config-consent-dsgvo-attribute-release_shib-idp_4.1.x#variante_1einwilligung|./views/intercept/attribute-release.vm]] (Variante 1)**. \\
{{:de:01_user_consent.png?200|}}

\\

<callout type="danger" title="Wichtiger Hinweis">
**Die im folgenden beschriebenen Konfigurationsschritte sind nur erforderlich, wenn seitens der Heimateinrichtung bzw. IdP-Betreibers Anwendungsfälle existieren, bei denen die Übertragung von Attributen nicht (nur) aufgrund der Einwilligung der Nutzenden, sondern (auch) aufgrund anderer Rechtsgrundlagen erfolgt.**
</callout>

==== Attribute Release aufgrund unterschiedlicher Rechtsgrundlagen ====
Wenn die Übertragung von Attributen fallweise aufgrund anderer Erlaubnisnormen erfolgt, bedarf es weiterer IdP-seitiger Anpassungen, die je nach anfragendem SP und ggf. Nutzergruppe die Nutzenden über die jeweilige Rechtsgrundlage informieren und auch beim Schreiben ins Consent Audit Log (''./logs/idp-consent-audit.log'') die entsprechende Unterscheidung vornehmen. Siehe hierzu die Lösungsmodelle aus der Präsentation [[https://download.aai.dfn.de/praesentationen/betriebstagungen/69/BT69_AAI_DS-AAI-Verfahren_Strobel_Moerike.pdf|"Datenschutzrechtliche Analyse das AAI-Verfahrens"]] von der 69. DFN-Betriebstagung. 

Im folgenden werden diese Schlüsselbegriffe bzw. Kürzel verwendet, die auch im Consent Audit Log eingetragen werden:
  * ''consent'' - "Sonstige Dienste" (FS Recht) - Einwilligung der Nutzenden, DSGVO Art. 6 Abs. 1 lit. a)
  * ''info'' - „Nützliche Dienste“ (FS Recht) – berechtigtes Interesse der Einrichtung, DSGVO Art. 6 Abs. 1 lit. f) oder e), letzteres in Verb. mit spezieller Erlaubnisnorm
  * ''must'' - „Notwendige Dienste“ (FS Recht) – Beschäftigungsverhältnis DSGVO Art. 88 mit § 26 BDSG)
Selbstverständlich können hierfür auch andere Begriffe verwendet werden. Wichtig ist nur, dass der Bezug zur jeweiligen Rechtsgrundlage bekannt und dokumentiert ist! 

**Wichtiger Hinweis:** Die Dateien des IdP Consent Audit Log (''idp-consent-audit*'') dienen im Zweifelsfall als Nachweis und sollten daher sorgfältig archiviert werden!

Neben der angepassten Datei **[[de:shibidp:config-consent-dsgvo-attribute-release_shib-idp_4.1.x#variante_2weitere_rechtsgrundlagen|./views/intercept/attribute-release.vm]]** (Variante 2) und den o.g. [[#message_properties|Message Properties]] sind weitere Anpassungen am Identity Provider erforderlich, die im folgenden dokumentiert sind. \\
**Achtung:** Die u.g. Dateien dürfen **nicht** durch die jeweiligen Konfigurationsbeispiele **ersetzt** werden! Die Konfigurationsschnipsel müssen in die entsprechenden Dateien **eingefügt** werden! 

\\

=== IdP-Plugin installieren ===
Die Java-Klassen, die die IdP-seitige Unterscheidung der Rechtsgrundlagen anhand intern definierter Attribute ermöglichen, werden als Plugin installiert:
== bis IdP-Version 4.1.7 ==
<code>
%{idp.home}/bin/plugin.sh -i https://identity.fu-berlin.de/downloads/shibboleth/idp/plugins/dsgvo/1.0.0/fudis-shibboleth-idp-plugin-dsgvo-1.0.0.tar.gz
</code>
== ab IdP-Version 4.2.0 ==
<code>
%{idp.home}/bin/plugin.sh -i https://identity.fu-berlin.de/downloads/shibboleth/idp/plugins/dsgvo/1.1.0/fudis-shibboleth-idp-plugin-dsgvo-1.1.0.tar.gz
</code>
== ab IdP-Version 5.0.0 ==
<code>
%{idp.home}/bin/plugin.sh -i https://identity.fu-berlin.de/downloads/shibboleth/idp/plugins/dsgvo/current/fudis-shibboleth-idp-plugin-dsgvo-current.tar.gz
</code>

Dabei wird diese Datei angelegt:
<file properties ./conf/dsgvo.properties>
## FUDIS/DFN dsgvo options
#dsgvo.attribute_name=dfnEduPersonAttributeReleaseType
#dsgvo.release_attribute=false
</file>
Es wird empfohlen, mit den Voreinstellungen zu arbeiten. Sollte ''dsgvo.attribute_name'' geändert werden, muss der Name des Attributs auch in der Attribute Filter und Resolver Konfiguration (siehe unten) und in ''/views/intercept/attribute-release.vm'' angepasst werden.

Erweiterung des Log-Formats um das Kürzel für die Rechtsgrundlage: 
<file properties ./conf/idp.properties>
idp.consent.attribute-release.auditFormat = %T|%SP|%e|%u|%CCI|%CCV|%CCA|%DSGVO
</file>

**Herzlichen Dank hierfür an Steffen Hofmann! (FU Berlin)**

\\

=== Anpassungen der Attribute Filter Konfiguration ===
Damit das o.g. Attribut ins User Consent Modul gelangt, muss eine entsprechende Attribute Filter Policy konfiguriert werden. Ob das gewählte Attribut tatsächlich an einen SP übertragen wird, lässt sich über die o.g. Property ''dsgvo.release_attribute'' steuern.

<file xml ./conf/attribute-filter.xml>

   <AttributeFilterPolicy id="ReleaseAttributeReleaseType">
        <PolicyRequirementRule xsi:type="ANY" />
        <AttributeRule attributeID="dfnEduPersonAttributeReleaseType" permitAny="true" />
   </AttributeFilterPolicy>

</file>

\\

=== Anpassungen im Attribute Resolver ===
Die Unterscheidungen der Kriterien, aufgrund derer unterschiedliche Rechtsgrundlagen für die Attributübertragung gelten, werden im Attribute Resolver vorgenommen und über das Attribut ''dfnEduPersonAttributeReleaseType'' innerhalb des IdP transportiert. Im folgenden ein einfaches Beispiel, bei dem die Unterscheidung anhand der Entity ID des anfragenden SP erfolgt.

<file xml ./conf/attribute-resolver.xml>
    <!-- ========================================== -->
    <!--      Attribute Definitions                 -->
    <!-- ========================================== -->

    <AttributeDefinition xsi:type="Mapped" id="dfnEduPersonAttributeReleaseType">
        <InputDataConnector ref="attributeReleaseInfo" attributeNames="attributeReleaseType" />
        <InputDataConnector ref="attributeReleaseMust" attributeNames="attributeReleaseType" />
        <DefaultValue>consent</DefaultValue>
        <ValueMap>
            <ReturnValue>info</ReturnValue>
            <SourceValue>info</SourceValue>
        </ValueMap>
        <ValueMap>
            <ReturnValue>must</ReturnValue>
            <SourceValue>must</SourceValue>
        </ValueMap>
    </AttributeDefinition>


    <!-- ========================================== -->
    <!--      Data Connectors                       -->
    <!-- ========================================== -->

    <!-- 
        hier die Liste der SPs festlegen, für die DSGVO Art. 6.1 Buchst. e/f gilt 
        Achtung: bei allen Entity IDs handelt es sich um Beispiele!!!
    -->
    <DataConnector id="attributeReleaseInfo" xsi:type="Static"
                   relyingParties="https://testsp2.aai.dfn.de/shibboleth">
        <Attribute id="attributeReleaseType">
            <Value>info</Value>
        </Attribute>
    </DataConnector>

    <!-- hier die Liste der SPs festlegen, für die DSGVO Art. 88 gilt -->
    <DataConnector id="attributeReleaseMust" xsi:type="Static"
                   relyingParties="https://testsp.aai.dfn.de/shibboleth https://testsp3.aai.dfn.de/shibboleth">
        <Attribute id="attributeReleaseType">
            <Value>must</Value>
        </Attribute>
    </DataConnector>


</file>

Falls neben den Entity IDs der betreffenden SPs weitere Bedingungen bei der Unterscheidung der Rechtsgrundlagen berücksichtigt werden sollen, können diese z.B. in einer Scripted Attribute Definition behandelt werden. Alternativ (und eleganter) lassen sich entsprechende [[https://shibboleth.atlassian.net/l/c/3PUgHxMC|Activation Conditions]] definieren, die in den Static Data Connectors über ''activationConditionRef'' zu referenzieren wären (anstatt über ''relyingParties'').