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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15156 -->
<!-- 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 PHP 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 PHP Anwendung sollte einen Hyperlink zur Google URL bieten die die Authentifizierung durchführt.
            Die statische Funktion <classname>Zend_Gdata_AuthSub::getAuthSubTokenUri()</classname> liefert die richtige
            URL. Die Argumente dieser Funktion inkludieren die URL zur eigenen PHP 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 GET Anfrageparameter gesetzt der <code>token</code> heißt. Der Wert dieses Parameters
            ist ein einmal-verwendbarer Token der für authentifizierten Zugriff verwendet werden kann. Dieser
            Token kan in einen mehrfach-verwendbaren Token konvertiert und in der eigenen Session gespeichert werden.
        </para>

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

        <para>
            Nachfolgend ist ein Beispiel von PHP 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 Http Client verwendet.
        </para>

        <programlisting role="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
            <classname>Zend_Gdata_AuthSub::AuthSubRevokeToken()</classname> verwendet werden. Andernfalls bleibt der Token
            noch für einige Zeit gültig.
        </para>

        <programlisting role="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 <code>$php_self</code> Variable im obigen Beispiel ist eine generelle Sicherheits
            Richtlinie, die nicht nur für <classname>Zend_Gdata</classname> gilt. Inhalt der zu Http Headern ausgegeben wird sollte immer
            gefiltert werden.
        </para>
        <para>
            Betreffend der Beendigung des authentifizierten Tokens wird empfohlen das das 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>