<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: 20763 -->
<sect1 id="zend.acl.introduction">
    <title>Einführung</title>

    <para>
        <classname>Zend_Acl</classname> stellt eine Implementation von leichtgewichtigen und
        flexiblen Zugriffskontrolllisten (englisch "access control list",
        <acronym>ACL</acronym>) für die Rechteverwaltung bereit. Im Allgemeinen kann eine Anwendung
        derartige <acronym>ACL</acronym>s verwenden, um den Zugriff auf bestimmte, geschützte
        Objekte durch andere anfordernde Objekte zu kontrollieren.
    </para>

    <para>
        In dieser Dokumentation:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                ist eine <emphasis>Ressource</emphasis> ein Objekt, auf das der
                Zugriff kontrolliert wird.
            </para>
        </listitem>

        <listitem>
            <para>
                ist eine <emphasis>Rolle</emphasis> ein Objekt, das den Zugriff
                auf eine Ressource anfordern kann.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Einfach ausgedrückt <emphasis>fordern Rollen den Zugriff auf Ressourcen
        an</emphasis>. Wenn z.B. ein Parkplatzwächter den Zugriff auf ein Auto anfordert, ist der
        Parkplatzwächter die anfordernde Rolle und das Auto die Ressource, weil der Zugriff auf das
        Auto nicht jedem erlaubt ist.
    </para>

    <para>
        Durch die Spezifikation und die Verwendung einer <acronym>ACL</acronym> kann eine Anwendung
        kontrollieren, wie Rollen den Zugriff auf Ressourcen eingeräumt bekommen.
    </para>

    <sect2 id="zend.acl.introduction.resources">
        <title>Ressourcen</title>

        <para>
            Das Erstellen einer Ressource ist in <classname>Zend_Acl</classname> sehr einfach.
            <classname>Zend_Acl</classname> stellt die Ressource
            <classname>Zend_Acl_Resource_Interface</classname> bereit, um das Erstellen von
            Ressourcen in Anwendungen zu ermöglichen. Eine Klasse muss nur dieses Interface
            implementieren, das nur aus einer einzelnen Methode
            <methodname>getResourceId()</methodname> besteht, damit <classname>Zend_Acl</classname>
            das Objekt als Ressource erkennen kann. Zusätzlich ist
            <classname>Zend_Acl_Resource</classname> in <classname>Zend_Acl</classname> als einfache
            Ressourcen-Implementation enthalten, damit Entwickler sie wenn nötig erweitern können.
        </para>

        <para>
            <classname>Zend_Acl</classname> stellt eine Baumstruktur bereit, in die mehrere
            Ressourcen aufgenommen werden können. Weil Ressourcen in solch einer Baumstruktur
            abgelegt werden, können sie vom Allgemeinen (von der Baumwurzel) bis zum Speziellen (zu
            den Baumblättern) organisiert werden. Abfragen auf einer bestimmten Ressource
            durchsuchen automatisch die Ressourcenhierarchie nach Regeln, die einer übergeordneten
            Ressource zugeordnet wurden, um die einfache Vererbung von Regeln zu ermöglichen. Wenn
            zum Beispiel eine Standardregel für jedes Gebäude einer Stadt gelten soll, würde man
            diese Regel einfach der Stadt zuordnen, anstatt die selbe Regel jedem Gebäude
            zuzuordnen. Einige Gebäude können dennoch Ausnahmen zu solch einer Regel erfordern, und
            dies kann in <classname>Zend_Acl</classname> einfach durch die Zuordnung solcher
            Ausnahmeregeln zu jedem der Gebäude erreicht werden, die eine Ausnahme erfordern. Eine
            Ressource kann nur von einer einzigen übergeordneten Ressource erben, obwohl diese
            übergeordnete Ressource ihre eigenen übergeordneten Ressourcen haben kann, und so
            weiter.
        </para>

        <para>
            <classname>Zend_Acl</classname> unterstützt außerdem Rechte auf Ressourcen (z.B.
            "erstellen", "lesen", "aktualisieren", "löschen"), damit der Entwickler Regeln zuordnen
            kann, die alle Rechte oder bestimmte Rechte von einer oder mehreren Ressourcen
            beeinflussen.
        </para>
    </sect2>

    <sect2 id="zend.acl.introduction.roles">
        <title>Rollen</title>

        <para>
            Wie bei den Ressourcen ist auch das Erstellen einer Rolle sehr einfach. Alle Rollen
            müssen <classname>Zend_Acl_Role_Interface</classname> implementieren. Dieses Interface
            besteht aus einer einzelnen Methode, <methodname>getRoleId()</methodname>, zusätzlich
            wird <classname>Zend_Acl_Role</classname> von <classname>Zend_Acl</classname> als
            einfache Rollen Implementation angeboten, damit Entwickler sie bei Bedarf erweitern
            können.
        </para>

        <para>
            In <classname>Zend_Acl</classname> kann eine Rolle von einer oder mehreren Rollen
            erben. Dies soll die Vererbung von Regeln zwischen den Rollen ermöglichen. Zum Beispiel
            kann eine Benutzerrolle, wie "Sally" zu einer oder mehreren übergeordneten Rollen
            gehören, wie "Editor" und "Administrator". Der Entwickler kann zu "Editor" und
            "Administrator" getrennt Regeln zuordnen und "Sally" würde diese Regeln von beiden
            erben, ohne dass "Sally" direkt Regeln zugeordnet werden müssen.
        </para>

        <para>
            Auch wenn die Möglichkeit der Vererbung von verschiedenen Rollen sehr nützlich ist,
            führt die mehrfache Vererbung auch einen gewissen Grad an Komplexität ein. Das folgende
            Beispiel illustriert die mehrdeutigen Bedingungen und wie
            <classname>Zend_Acl</classname> sie auflöst.
        </para>

        <example id="zend.acl.introduction.roles.example.multiple_inheritance">
            <title>Mehrfache Vererbung zwischen Rollen</title>

            <para>
                Der folgende Code definiert drei Basisrollen - "guest", "member" und "admin" - von
                denen andere Rollen erben können. Dann wird eine Rolle "someUser" eingerichtet, die
                von den drei anderen Rollen erbt. Die Reihenfolge, in der diese Rollen im
                <varname>$parents</varname> Array erscheinen, ist wichtig. Wenn notwendig, sucht
                <classname>Zend_Acl</classname> nach Zugriffsregeln nicht nur für die abgefragte
                Rolle (hier "someUser"), sondern auch für die Rollen, von denen die abgefragte
                Rolle erbt (hier "guest", "member" und "admin"):
            </para>

            <programlisting language="php"><![CDATA[
$acl = new Zend_Acl();

$acl->addRole(new Zend_Acl_Role('guest'))
    ->addRole(new Zend_Acl_Role('member'))
    ->addRole(new Zend_Acl_Role('admin'));

$parents = array('guest', 'member', 'admin');
$acl->addRole(new Zend_Acl_Role('someUser'), $parents);

$acl->add(new Zend_Acl_Resource('someResource'));

$acl->deny('guest', 'someResource');
$acl->allow('member', 'someResource');

echo $acl->isAllowed('someUser', 'someResource') ? 'allowed' : 'denied';
]]></programlisting>

            <para>
                Da keine Regel speziell für die Rolle "someUser" und "someResource" definiert
                wurde, muss <classname>Zend_Acl</classname> nach Regeln suchen, die für Rollen
                definiert wurden, von denen "someUser" erbt. Zuerst wird die "admin"-Rolle besucht,
                aber dort ist keine Zugriffsregel definiert. Als nächste wird die "member"-Rolle
                besucht und <classname>Zend_Acl</classname> findet hier eine Regel, die angibt,
                dass "member" der Zugriff auf "someResource" erlaubt ist.
            </para>

            <para>
                Wenn <classname>Zend_Acl</classname> fortfahren würde, die für weitere
                übergeordnete Rollen definierten Regeln zu untersuchen, würde herausgefunden
                werden, dass "guest" der Zugriff auf "someResource" verboten ist.
                Diese Tatsache führt eine Mehrdeutigkeit ein, weil nun "someUser" der Zugriff auf
                "someResource" sowohl verboten als auch erlaubt ist, aufgrund der vererbten Regeln
                von verschiedenen übergeordnete Rollen, die miteinander im Konflikt stehen.
            </para>

            <para>
                <classname>Zend_Acl</classname> löst diese Mehrdeutigkeit dadurch auf, dass eine
                Abfrage beendet wird, wenn die erste Regel gefunden wird, die direkt auf die
                Abfrage passt. In diesem Fall würde der Beispiel Code "allowed"
                ausgeben, weil die "member"-Rolle vor der "guest"-Rolle untersucht wird.
            </para>
        </example>

        <note>
            <para>
                Wenn man mehrere übergeordnete Rollen angibt, sollte man beachten, dass die zuletzt
                gelistete Rolle als erstes nach Regeln durchsucht wird, die auf die
                Autorisierungsabfrage passen.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.acl.introduction.creating">
        <title>Erstellen einer Zugriffskontrollliste</title>

        <para>
            Eine Zugriffskontrollliste (<acronym>ACL</acronym>) kann jeden gewünschten Satz von
            körperlichen oder virtuellen Objekten repräsentieren. Zu Demonstrationszwecken werden
            wir eine grundlegende <acronym>ACL</acronym> für ein Redaktionssystem
            (<acronym>CMS</acronym>) erstellen, die mehrere Schichten von Gruppen über eine
            Vielzahl von Bereichen verwaltet soll. Um ein <acronym>ACL</acronym>-Objekt zu
            erstellen, instanzieren wir die <acronym>ACL</acronym> ohne Parameter:
        </para>

        <programlisting language="php"><![CDATA[
$acl = new Zend_Acl();
]]></programlisting>

        <note>
            <para>
                Solange der Entwickler keine "allow"-Regel spezifiziert, verweigert
                <classname>Zend_Acl</classname> den Zugriff auf jegliche Rechte für jede Ressource
                durch jede Rolle.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.acl.introduction.role_registry">
        <title>Rollen registrieren</title>

        <para>
            <acronym>CMS</acronym> brauchen fast immer eine Hierarchie von Genehmigungen, um die
            Autorenfähigkeiten seiner Benutzer festzulegen. Es kann eine 'Guest'-Gruppe geben, um
            beschränkten Zugriff zur Demonstration zu ermöglichen, eine 'Staff'-Gruppe für die
            Mehrheit der <acronym>CMS</acronym> Nutzer, welche die meisten der alltäglichen
            Aufgaben erledigen, eine 'Editor'-Gruppe für diejenigen, die für das Veröffentlichen,
            Überprüfen, Archivieren und Löschen von Inhalten zuständig sind, sowie eine
            'Administrator'-Gruppe, dessen Aufgaben alle der anderen Gruppen sowie die
            Pflege sensibler Informationen, die Benutzerverwaltung, die
            Backend-Konfigurationsdaten, die Datensicherung und den Export beinhalten. Diese
            Genehmigungen können durch eine Rollenregistrierung repräsentiert werden, die es jeder
            Gruppe erlaubt, die Rechte von 'übergeordneten' Gruppen zu erben sowie eindeutige
            Rechte nur für deren Gruppe bereit zu stellen. Diese Genehmigungen können wie folgt
            ausgedrückt werden:
        </para>

        <table id="zend.acl.introduction.role_registry.table.example_cms_access_controls">
            <title>Zugangsbeschränkung für ein Beispiel-CMS</title>
            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Name</entry>
                        <entry>Eindeutige Genehmigung</entry>
                        <entry>Erbe Genehmigungen von</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>Guest</entry>
                        <entry>View</entry>
                        <entry>N/A</entry>
                    </row>

                    <row>
                        <entry>Staff</entry>
                        <entry>Edit, Submit, Revise</entry>
                        <entry>Guest</entry>
                    </row>

                    <row>
                        <entry>Editor</entry>
                        <entry>Publish, Archive, Delete</entry>
                        <entry>Staff</entry>
                    </row>

                    <row>
                        <entry>Administrator</entry>
                        <entry>(bekommt kompletten Zugriff gewährt)</entry>
                        <entry>N/A</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Für dieses Beispiel wird <classname>Zend_Acl_Role</classname> verwendet, aber jedes
            Objekt wird akzeptiert, das <classname>Zend_Acl_Role_Interface</classname>
            implementiert. Diese Gruppen können zur Rollenregistrierung wie folgt hinzugefügt
            werden:
        </para>

        <programlisting language="php"><![CDATA[
$acl = new Zend_Acl();

// Fügt Gruppen zur Rollenregistrierung hinzu unter Verwendung von Zend_Acl_Role
// Gast erbt keine Zugriffsrechte
$roleGuest = new Zend_Acl_Role('guest');
$acl->addRole($roleGuest);

// Mitarbeiter erbt von Gast
$acl->addRole(new Zend_Acl_Role('staff'), $roleGuest);

/*
Alternativ kann das obige wie folgt geschrieben werden:
$acl->addRole(new Zend_Acl_Role('staff'), 'guest');
*/

// Redakteur erbt von Mitarbeiter
$acl->addRole(new Zend_Acl_Role('editor'), 'staff');

// Administrator erbt keine Zugriffsrechte
$acl->addRole(new Zend_Acl_Role('administrator'));
]]></programlisting>

    </sect2>

    <sect2 id="zend.acl.introduction.defining">
        <title>Zugangsbeschränkung definieren</title>

        <para>
            Nun, da die <acronym>ACL</acronym> die relevanten Rollen enthält, können Regeln
            eingerichtet werden, die definieren, wie auf Ressourcen durch Rollen zugegriffen werden
            darf. Es ist zu beachten, dass wir keine bestimmten Ressourcen in diesem Beispiel
            definiert haben, das vereinfacht wurde, um zu illustrieren, dass die Regeln für alle
            Ressourcen gelten. <classname>Zend_Acl</classname> stellt eine Implementation bereit,
            bei der Regeln nur vom Allgemeinen zum Speziellen definiert werden müssen, um die
            Anzahl der benötigten Regeln zu minimieren, weil Ressourcen und Rollen die Regeln
            erben, die in ihren Vorfahren definiert worden sind.
        </para>

        <note>
            <para>
                Generell wendet <classname>Zend_Acl</classname> eine angegebene Regel dann und nur
                dann an, wenn eine speziellere Regel nicht passt.
            </para>
        </note>

        <para>
            Folglich können wir einen einigermaßen komplexen Regelsatz mit sehr wenig Code
            definieren. Um die grundlegenden Genehmigungen von oben anzugeben:
        </para>

        <programlisting language="php"><![CDATA[
$acl = new Zend_Acl();

$roleGuest = new Zend_Acl_Role('guest');
$acl->addRole($roleGuest);
$acl->addRole(new Zend_Acl_Role('staff'), $roleGuest);
$acl->addRole(new Zend_Acl_Role('editor'), 'staff');
$acl->addRole(new Zend_Acl_Role('administrator'));

// Gäste dürfen Inhalte nur sehen
$acl->allow($roleGuest, null, 'view');

/*
Alternativ kann das obige wie folgt geschrieben werden:
$acl->allow('guest', null, 'view');
*/

// Mitarbeiter erbt 'ansehen' Rechte von Gast, benötigt aber zusätzliche Rechte
$acl->allow('staff', null, array('edit', 'submit', 'revise'));

// Redakteuer erbt 'ansehen', 'bearbeiten', 'absenden' und die 'revidieren'
// Rechte vom Mitarbeiter, benötigt aber zusätzliche Rechte
$acl->allow('editor', null, array('publish', 'archive', 'delete'));

// Administrator erbt gar nichts, aber erhält alle Rechte
$acl->allow('administrator');
]]></programlisting>

        <para>
            Die <constant>NULL</constant>-Werte in obigen <methodname>allow()</methodname>-Aufrufen
            werden verwendet, um anzugeben, dass diese Regeln für alle Ressourcen gelten.
        </para>
    </sect2>

    <sect2 id="zend.acl.introduction.querying">
        <title>Abfragen einer ACL</title>

        <para>
            Wir haben nun eine flexible <acronym>ACL</acronym>, die in der gesamten Anwendung
            verwendet werden kann, um zu ermitteln, ob Anfragende die Genehmigung haben, Funktionen
            auszuführen. Abfragen durchzuführen ist recht einfach mit Hilfe der
            <methodname>isAllowed()</methodname>-Methode:
        </para>

        <programlisting language="php"><![CDATA[
echo $acl->isAllowed('guest', null, 'view') ?
     "allowed" : "denied";
// erlaubt

echo $acl->isAllowed('staff', null, 'publish') ?
     "allowed" : "denied";
// verweigert

echo $acl->isAllowed('staff', null, 'revise') ?
     "allowed" : "denied";
// erlaubt

echo $acl->isAllowed('editor', null, 'view') ?
     "allowed" : "denied";
// erlaubt wegen der Vererbung von Gast

echo $acl->isAllowed('editor', null, 'update') ?
     "allowed" : "denied";
// verweigert, weil es keine erlaubte Regel für 'update' gibt

echo $acl->isAllowed('administrator', null, 'view') ?
     "allowed" : "denied";
// erlaubt, weil Administrator alle Rechte haben

echo $acl->isAllowed('administrator') ?
     "allowed" : "denied";
// erlaubt, weil Administrator alle Rechte haben

echo $acl->isAllowed('administrator', null, 'update') ?
     "allowed" : "denied";
// erlaubt, weil Administrator alle Rechte haben
]]></programlisting>
    </sect2>
</sect1>
