repo_zf1/documentation/manual/de/module_specs/Zend_Gdata_AuthSub.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.gdata.authsub">
    <title>Authentifizierung mit AuthSub</title>

    <para>
        Der AuthSub Mechanismum erlaubt es Web Anwendungen zu schreiben die einen authentifizierten
        Zugang zu Google Data Services benötigen, ohne das Code geschrieben werden muß der
        Benutzerzugangsdaten behandelt.
    </para>

    <para>
        Siehe <ulink
            url="http://code.google.com/apis/accounts/AuthForWebApps.html">http://code.google.com/apis/accounts/AuthForWebApps.html</ulink>
        für weitere Informationen über Google Data AuthSub Authentifizierung.
    </para>

    <para>
        Die Google Dokumentation sagt das der ClientLogin Mechanismum ausreichend für "installierte
        Anwendungen" ist, und der AuthSub Mechanismum für "Web Anwendungen". Der Unterschied ist das
        AuthSub Interaktion vom Benutzer benötigt, und ein Browser Interface das auf
        Umleitungsanfragen reagieren kann. Die ClientLogin Lösung verwendet <acronym>PHP</acronym>
        Code um die Benutzerzugangsdaten anzubieten; der Benutzer wird nicht benötigt um seine
        Zugangsdaten einzugeben.
    </para>

    <para>
        Die Zugangsdaten die über den AuthSub Mechanismum bereitgestellt werden, werden vom Benutzer
        über die Web Anwendung eingegeben. Deswegen müssen es Zugangsdaten sein die dem Benutzer
        bekannt sind.
    </para>

    <note>
        <title>Registrierte Anwendungen</title>

        <para>
            <classname>Zend_Gdata</classname> unterstützt aktuell die Verwendung von sicheren Tokens
            nicht, weil die AuthSub Authentifizierung die Übergabe von Digitalen Zertifikaten, um
            ein sicheres Token zu erhalten, nicht unterstützt.
        </para>
    </note>

    <sect2 id="zend.gdata.authsub.login">
        <title>Einen AuthSub authentifizierten Http Clienten erstellen</title>

        <para>
            Die <acronym>PHP</acronym> Anwendung sollte einen Hyperlink zur Google
            <acronym>URL</acronym> bieten welche die Authentifizierung durchführt. Die statische
            Funktion <methodname>Zend_Gdata_AuthSub::getAuthSubTokenUri()</methodname> liefert die
            richtige <acronym>URL</acronym>. Die Argumente dieser Funktion inkludieren die
            <acronym>URL</acronym> zur eigenen <acronym>PHP</acronym> Anwendung so das Google den
            Browser des Benutzers um zur eigenen Anwendung zurück umleiten kann, nachdem die
            Benutzerdaten verifiziert wurden.
        </para>

        <para>
            Nachdem Google's Authentifizierungs Server den Browser des Benutzers zur aktuellen
            Anwendung umgeleitet haben, wird eine <constant>GET</constant> Anfrageparameter gesetzt
            der <emphasis>token</emphasis> heißt. Der Wert dieses Parameters ist ein
            einmal-verwendbarer Token der für authentifizierten Zugriff verwendet werden kann.
            Dieser Token kann in einen mehrfach-verwendbaren Token konvertiert und in der eigenen
            Session gespeichert werden.
        </para>

        <para>
            Um den Token dann zu verwenden muß
            <methodname>Zend_Gdata_AuthSub::getHttpClient()</methodname> aufgerufen werden. Diese
            Funktion gibt eine Instanz von <classname>Zend_Http_Client</classname> zurück, mit
            gültigen Headern gesetzt, sodas eine nachfolgende Anfrage der Anwendung, die diesen
            <acronym>HTTP</acronym> Clienten verwenden, auch authentifiziert sind.
        </para>

        <para>
            Nachfolgend ist ein Beispiel von <acronym>PHP</acronym> Code für eine Web Anwendung um
            eine Authentifizierung zu erlangen damit der Google Calender Service verwendet werden
            kann, und der ein <classname>Zend_Gdata</classname> Client Objekt erstellt das diesen
            authentifizierten <acronym>HTTP</acronym> Client verwendet.
        </para>

        <programlisting language="php"><![CDATA[
$my_calendar = 'http://www.google.com/calendar/feeds/default/private/full';

if (!isset($_SESSION['cal_token'])) {
    if (isset($_GET['token'])) {
        // Ein einmal-verwendbarer Token kann in einen Session Token konvertiert werden
        $session_token =
            Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
        // Speichert den Session Token in der Session
        $_SESSION['cal_token'] = $session_token;
    } else {
        // Zeigt einen Link zur Erstellung eines einmal-verwendbaren Tokens
        $googleUri = Zend_Gdata_AuthSub::getAuthSubTokenUri(
            'http://'. $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI'],
            $my_calendar, 0, 1);
        echo "Klicke <a href='$googleUri'>hier</a> um diese Anwendung " .
             "zu authorisieren.";
        exit();
    }
}

// Erstellt einen authentifizierten Http Client um mit Google zu sprechen
$client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['cal_token']);

// Erstellt ein Gdara Objekt das den authentifizierten Http Client verwendet
$cal = new Zend_Gdata_Calendar($client);
]]></programlisting>
    </sect2>

    <sect2 id="zend.gdata.authsub.logout">
        <title>Beenden der AuthSub Authentifizierung</title>

        <para>
            Um den authentifizierten Status eines gegebenen Status zu beenden, kann die statische
            Funktion <methodname>Zend_Gdata_AuthSub::AuthSubRevokeToken()</methodname> verwendet
            werden. Andernfalls bleibt der Token noch für einige Zeit gültig.
        </para>

        <programlisting language="php"><![CDATA[
// Vorsichtig den Wert erstellen um Sicherheitsprobleme mit der Anwendung zu vermeiden
$php_self = htmlentities(substr($_SERVER['PHP_SELF'],
                         0,
                         strcspn($_SERVER['PHP_SELF'], "\n\r")),
                         ENT_QUOTES);

if (isset($_GET['logout'])) {
    Zend_Gdata_AuthSub::AuthSubRevokeToken($_SESSION['cal_token']);
    unset($_SESSION['cal_token']);
    header('Location: ' . $php_self);
    exit();
}
]]></programlisting>

        <note>
            <title>Sicherheitshinweise</title>

            <para>
                Das Vermeiden der <varname>$php_self</varname> Variable im obigen Beispiel ist eine
                generelle Sicherheits Richtlinie, die nicht nur für
                <classname>Zend_Gdata</classname> gilt. Inhalt der zu <acronym>HTTP</acronym>
                Headern ausgegeben wird sollte immer gefiltert werden.
            </para>

            <para>
                Betreffend der Beendigung des authentifizierten Tokens wird empfohlen dass dies
                gemacht wird, sobald der Benutzer mit seiner Google Data Session fertig ist. Die
                Möglichkeit das jemand das Token herausfindet und für seine eigenen miesen Zwecke
                verwendet ist sehr klein, aber trotzdem ist es eine gute Praxis einen
                authentifizierten Zugriff auf jegliche Services zu beenden.
            </para>
        </note>
    </sect2>
</sect1>