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

<callout color="#ff9900" title="Dokumentation nur gültig für Shib IdP Version 4.0.x!">
Mit dem Wegfall sowohl des ./system Verzeichnisses als auch der damit verbundenen Verfügbarkeit der entsprechenden *-bean.xml und *-flow.xml Dateien in Version 4.1.x muss die Umsetzung grundlegend anders erfolgen. Siehe hierzu [[de:shibidp:config-consent-dsgvo|diese Seite]]. 
</callout>

<callout color="#ff9900" title="Vorsicht beim Upgrade von Shib IdP 3.4.x auf Version 4.x">
Bei Shib IdP Version 4 haben sich Details an den Standard-Flows geändert. Wir empfehlen daher, nach dem Upgrade auf Version 4.x die unten beschriebenen Flows unter ./flows/intercept neu anzulegen und die entsprechenden Anpassungen vorzunehmen.
</callout>

Die im folgenden dokumentierte Beispielkonfiguration beruht sowohl auf den Vorschlägen der Forschungsstelle Recht im DFN, [[https://www2.dfn.de/fileadmin/3Beratung/Betriebstagungen/bt69/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 unter [[de:shibidp:config-tou#aktivierung_der_nutzungsbedingungen|Aktivierung der Nutzungsbedingungen]] 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) 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 ü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]].

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), muss kein separater Flow definiert werden!** 

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

==== Attribute Release aufgrund unterschiedlicher Rechtsgrundlagen ====
Wenn die Attributfreigabe fallweise aufgrund anderer Erlaubnisnormen erfolgt, bedarf es entsprechend angepasster [[https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631714/ProfileInterceptConfiguration|Interceptor Flows]], die je nach anfragendem SP und ggf. Nutzergruppe aufgerufen werden. Siehe hierzu die Lösungsmodelle aus der Präsentation [[https://www2.dfn.de/fileadmin/3Beratung/Betriebstagungen/bt69/BT69_AAI_DS-AAI-Verfahren_Strobel_Moerike.pdf|"Datenschutzrechtliche Analyse das AAI-Verfahrens"]] von der [[https://www2.dfn.de/veranstaltungen/bt/vortraege/69-betriebstagung-2509-bis-26092018/|69. DFN-Betriebstagung]] und die Präsentation [[https://download.aai.dfn.de/ws/2018_fub/interceptor_dsgvo.pdf|"Wir basteln einen Interceptor Flow"]]. 

Neben der angepassten Datei **[[de:shibidp:config-consent-dsgvo-attribute-release|./views/intercept/attribute-release.vm]]** (siehe oben) werden hierfür noch die Velocity Templates **attribute-info.vm** und **attribute-must.vm**, die von der selben **[[de:shibidp:config-consent-dsgvo-attribute-release|Wiki Seite]]** heruntergeladen werden können (Varianten 2 und 3) und die ebenfalls in ''./views/intercept'' abgelegt werden. 

Weiterhin sind folgende Konfigurationsschritte erforderlich:
\\

**1. Flow aus bestehendem Interceptor erstellen:**

.''/system/flows/intercept/attribute-release-beans.xml'' und \\
''./system/flows/intercept/attribute-release-flow.xml'' \\
jeweils kopieren nach: \\
''./flows/intercept/attribute-info/attribute-info-beans.xml'' \\
''./flows/intercept/attribute-info/attribute-info-flow.xml'' \\
und \\
''./flows/intercept/attribute-must/attribute-must-beans.xml'' \\
''./flows/intercept/attribute-must/attribute-must-flow.xml'' 

\\

**2. In den kopierten Dateien die Pfade anpassen:**

In den *-flow.xml Dateien die Referenzen auf die bean-Dateien anpassen:
   <     <bean-import resource="attribute-release-beans.xml" />
   ---
   >     <bean-import resource="attribute-info-beans.xml" />
bzw.
   <     <bean-import resource="attribute-release-beans.xml" />
   ---
   >     <bean-import resource="attribute-must-beans.xml" />

\\

**3. Dafür sorgen, dass Bezeichnung des Events im Log dem jeweils aufgerufenen Flow entspricht (--> Nachweispflichten)**

<file xml ./flows/intercept/attribute-info/attribute-info-flow.xml> 
     <action-state id="ExtractConsent">
        <evaluate expression="ExtractConsent" />
        <evaluate expression="'AttributeReleaseInfo'" />
        
        <transition on="AttributeReleaseInfo" to="AttributeReleaseInfo" />
    </action-state>

    <!-- Write 'AttributeReleaseInfo' event to consent audit log. -->
    <action-state id="AttributeReleaseInfo">
        <evaluate expression="PopulateConsentAuditContext" />
        <evaluate expression="WriteAttributeReleaseConsentAuditLog" />
        <evaluate expression="'proceed'" />
        
        <transition on="proceed" to="TestForDoNotRememberConsent" />
    </action-state>
</file>

und

<file xml ./flows/intercept/attribute-must/attribute-must-flow.xml>
     <action-state id="ExtractConsent">
        <evaluate expression="ExtractConsent" />
        <evaluate expression="'AttributeReleaseMust'" />
        
        <transition on="AttributeReleaseMust" to="AttributeReleaseMust" />
    </action-state>

    <!-- Write 'AttributeReleaseMust' event to consent audit log. -->
    <action-state id="AttributeReleaseMust">
        <evaluate expression="PopulateConsentAuditContext" />
        <evaluate expression="WriteAttributeReleaseConsentAuditLog" />
        <evaluate expression="'proceed'" />
        
        <transition on="proceed" to="TestForDoNotRememberConsent" />
    </action-state>
</file>

\\

**4. Neue Flows deklarieren und mit Activation Conditions verknüpfen**

Dies geschieht am besten in **[[de:shibidp:config-consent-dsgvo-profile-intercept|./conf/intercept/profile-intercept.xml (Beispiel)]]** 

\\

**5. Neue Flows in der Relying Party Konfiguration dem SSO-Profil als Post Authentication Flows zuordnen**

<file xml ./conf/relying-party.xml>
    <bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
                <bean parent="SAML2.SSO" p:postAuthenticationFlows="#{{'terms-of-use', 'attribute-release', 'attribute-info', 'attribute-must'}}" />
                <ref bean="SAML2.ECP" />
                <ref bean="SAML2.Logout" />
                <ref bean="SAML2.AttributeQuery" />
                <ref bean="SAML2.ArtifactResolution" />
            </list>
        </property>
    </bean>
</file>

\\

**HTML-Ansicht ''attribute-info.vm''**\\
{{:de:02_user_consent.png?200|}}

**HTML-Ansicht ''attribute-must.vm''**\\
{{:de:03_user_consent.png?200|}}

==== Attribute Query und User Consent ====
Bei Attribute Queries kann die jeweils letzte Entscheidung des Users zur Attributfreigabe berücksichtigt werden. Dies funktioniert natürlich nur, wenn die (virtuellen) Entscheidungen zur Attributfreigabe in einer IdP-seitigen Datenbank abgelegt werden und eine entsprechende Condition gesetzt ist. Siehe hierzu unter [[de:shibidp:config-storage#user_consent_zu_attributfreigabe_bei_attribute_queries_beruecksichtigen|Server-Side-Storage - User Consent]].

Damit Attribute Queries unter diesen Rahmenbedingungen auch im oben skizzierten Setup funktionieren, sind weitere Konfigurationsschritte erforderlich:

Zunächst die Dateien \\
''./system/flows/intercept/attribute-release-query-beans.xml'' und \\
''./system/flows/intercept/attribute-release-query-flow.xml'' \\
in ein Verzeichnis namens \\
''./flows/intercept/attribute-release-query'' \\
kopieren.

Anschließend müssen diverse Anpassungen vorgenommen werden:

<file xml ./flows/intercept/attribute-release-query/attribute-release-query-beans.xml>
    <!-- Use 'intercept/attribute-release' as storage context. -->

    <bean id="AttributeReleaseStorageContextLookupStrategy" parent="shibboleth.Functions.Constant"
        c:target="intercept/attribute-release" />

    <bean id="ReadAttributeReleaseConsentFromStorage"
        class="net.shibboleth.idp.consent.flow.storage.impl.ReadConsentFromStorage" scope="prototype"
        p:storageKeyLookupStrategy-ref="shibboleth.consent.UserAndRelyingPartyStorageKey"
        p:storageSerializer-ref="shibboleth.consent.ConsentSerializer"
        p:storageContextLookupStrategy-ref="AttributeReleaseStorageContextLookupStrategy" />

    <!-- Use 'intercept/attribute-info' as storage context. -->

    <bean id="AttributeReleaseInfoStorageContextLookupStrategy" parent="shibboleth.Functions.Constant"
        c:target="intercept/attribute-info" />

    <bean id="ReadAttributeReleaseInfoConsentFromStorage"
        class="net.shibboleth.idp.consent.flow.storage.impl.ReadConsentFromStorage" scope="prototype"
        p:storageKeyLookupStrategy-ref="shibboleth.consent.UserAndRelyingPartyStorageKey"
        p:storageSerializer-ref="shibboleth.consent.ConsentSerializer"
        p:storageContextLookupStrategy-ref="AttributeReleaseInfoStorageContextLookupStrategy" />

    <!-- Use 'intercept/attribute-must' as storage context. -->

    <bean id="AttributeReleaseMustStorageContextLookupStrategy" parent="shibboleth.Functions.Constant"
        c:target="intercept/attribute-must" />

    <bean id="ReadAttributeReleaseMustConsentFromStorage"
        class="net.shibboleth.idp.consent.flow.storage.impl.ReadConsentFromStorage" scope="prototype"
        p:storageKeyLookupStrategy-ref="shibboleth.consent.UserAndRelyingPartyStorageKey"
        p:storageSerializer-ref="shibboleth.consent.ConsentSerializer"
        p:storageContextLookupStrategy-ref="AttributeReleaseMustStorageContextLookupStrategy" />
</file>

In der Flow-Definition den Block nach ''<!-- Read consent from storage -->'' anpassen und erweitern:

<file xml ./flows/intercept/attribute-release-query/attribute-release-query-flow.xml>
    <!-- Read consent from storage. -->

    <action-state id="ReadConsentFromStorage">
        <evaluate expression="ReadAttributeReleaseConsentFromStorage" />
        <evaluate expression="'proceed'" />

        <transition on="proceed" to="ReadInfoConsentFromStorage" />
    </action-state>

    <action-state id="ReadInfoConsentFromStorage">
        <evaluate expression="ReadAttributeReleaseInfoConsentFromStorage" />
        <evaluate expression="'proceed'" />

        <transition on="proceed" to="ReadMustConsentFromStorage" />
    </action-state>

    <action-state id="ReadMustConsentFromStorage">
        <evaluate expression="ReadAttributeReleaseMustConsentFromStorage" />
        <evaluate expression="'proceed'" />

        <transition on="proceed" to="TestForReadGlobalAttributeConsentFromStorage" />
    </action-state>

    <decision-state id="TestForReadGlobalAttributeConsentFromStorage">
        <if test="attributeReleaseFlowDescriptor.globalConsentAllowed"
            then="ReadGlobalAttributeConsentFromStorage" else="CheckPreviousConsents" />
    </decision-state>

    <action-state id="ReadGlobalAttributeConsentFromStorage">
        <evaluate expression="ReadAttributeReleaseGlobalConsentFromStorage" />
        <evaluate expression="'proceed'" />

        <transition on="proceed" to="TestForGlobalAttributeConsent" />
    </action-state> 
    
    <!-- hier noch der angepasste Pfad fürs Import-Statement der Attribute Release Bohne -->
    <bean-import resource="../../../system/flows/intercept/attribute-release-beans.xml" />
</file>

Anschließend noch den flow in ''./conf/intercept/profile-intercept.xml'' bekannt machen:
<file xml ./conf/intercept/profile-intercept.xml>
    <bean id="shibboleth.AvailableInterceptFlows" parent="shibboleth.DefaultInterceptFlows" lazy-init="true">
        <property name="sourceList">
            <list merge="true">
               <!-- ... -->
               <bean id="intercept/attribute-release-query" parent="shibboleth.consent.AttributeReleaseFlow" />
               <!-- ... -->
            </list>
        </property>
   </bean>
</file>

{{tag>idp4 fixme}}