Login-Vorgang manuell erstellen

Für ein browserbasiertes Login einer Web- oder Desktop-App ohne Verwendung unserer SDKs, etwa in einer Webansicht einer nativen Desktop-App (zum Beispiel Windows 8), oder einen Login-Vorgang mit rein serverseitigem Code kannst du deinen eigenen Login-Vorgang schaffen, indem du Browser-Umleitungen nutzt. In diesem Leitfaden wird jeder einzelne Schritt des Login-Vorgangs sowie dessen Implementierung ohne unsere SDKs genau beschrieben:

Prüfen des Anmeldestatus
Anmelden von Nutzer*innen
Bestätigen der Identität
Speichern von Zugriffsschlüsseln und Anmeldestatus
Abmelden von Nutzer*innen
Erkennen, wenn Personen Apps deinstallieren
Auf Anfragen zum Löschen von Nutzer*innendaten antworten

Um Facebook Login in einer Desktop-App zu verwenden, musst du einen Web-Browser (manchmal auch Webansicht genannt) in die App integrieren, der den Login-Vorgang übernimmt.

Prüfen des Login-Status

Apps, die unsere SDKs verwenden, können mit integrierten Funktionen prüfen, ob sich ein*e Nutzer*in bereits angemeldet hat. Alle anderen Apps müssen einen eigenen Weg finden, die Angabe zu speichern, wenn sich ein*e Nutzer*in angemeldet hat. Ist der Indikator nicht vorhanden, sollten die Apps mit der Annahme fortfahren, dass der*die Nutzer*in abgemeldet ist. Wenn ein*e Nutzer*in abgemeldet ist, sollte deine App sie*ihn zum richtigen Zeitpunkt zum Login-Dialog weiterleiten, z. B. wenn er*sie auf den Login-Button klickt.

Unabhängig davon, ob ein*e Nutzer*in deiner App nicht bei der App oder bei Facebook angemeldet ist, kannst du sie*inihn über den Login-Dialog dazu auffordern. Wenn ein*e Nutzer*in nicht bei Facebook angemeldet ist, erhält +er*sie die Aufforderung, sich dort anzumelden, bevor er*sie sich bei deiner App anmeldet. Das wird automatisch erkannt. Du musst hier also nicht mehr auf irgendeine Weise tätig werden.

Aufrufen des Login-Dialogs und Festlegen der Umleitungs-URL

Deine App muss eine Umleitung zu einem Endpunkt starten, an dem der Login-Dialog angezeigt wird:

https://www.facebook.com/v21.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}
  &state={state-param}

Für diesen Endpunkt sind die folgenden Parameter erforderlich:

client_id. Die ID deiner App befindet sich in deinem App-Dashboard.
redirect_uri. Die URL, zu der du die sich anmeldende Person umleiten möchtest. Diese URL erhält auch die Antwort vom Login-Dialog. Wenn du dies in einer Web-Ansicht innerhalb einer Desktop-App verwendest, musst du dafür https://www.facebook.com/connect/login_success.html festlegen. Im App-Dashboard kannst du bestätigen, dass diese URL für deine App festgelegt ist. Klicke im linken Navigationsmenü des App-Dashboards unter Produkte auf Facebook Login und anschließend auf Einstellungen. Überprüfe die gültigen OAuth Redirect URIs im Abschnitt Client-OAuth-Einstellungen.
state. Ein von deiner App erstellter Zeichenfolgewert, mit dem der Zustand zwischen Anfrage und Rückruf beibehalten wird. Dieser Parameter sollte verwendet werden, um Cross-Site-Request-Forgery-Angriffe zu verhindern, und wird in deiner Umleitungs-URI unverändert an dich zurückgegeben.

Wenn deine Login-Anfrage beispielsweise wie folgt aussieht:

https://www.facebook.com/v21.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={"https://www.domain.com/login"}
  &state={"{st=state123abc,ds=123456789}"}

wird deine Weiterleitungs-URI wie folgt aufgerufen:

https://www.domain.com/login?state="{st=state123abc,ds=123456789}"

Außerdem gibt es die folgenden optionalen Parameter:

response_type. Legt fest, ob die Antwortdaten beim Umleiten an die App in URL-Parameter oder URL-Fragmente aufgenommen werden. Weitere Informationen dazu, welchen Typ deine App verwenden sollte, findest du im Abschnitt Bestätigen der Identität. Das kann einer der Folgenden sein:
- code. Die Antwortdaten werden als URL-Parameter hinzugefügt und enthalten den code-Parameter (einen verschlüsselten String, der für jede Anmeldeanfrage eindeutig ist). Das ist die Standardeinstellung, falls dieser Parameter nicht angegeben ist. Es ist die sinnvollste Einstellung, wenn dein Server den Schlüssel verwaltet.
- token. Die Antwortdaten werden als URL-Fragment hinzugefügt und enthalten einen Zugriffsschlüssel. Desktop-Apps müssen diese Einstellung für response_type verwenden. Dies ist die sinnvollste Einstellung, wenn der Client den Schlüssel verwaltet.
- code%20token. Die Antwortdaten werden als URL-Fragment hinzugefügt und enthalten sowohl einen Zugriffsschlüssel als auch einen code-Parameter.
- granted_scopes. Gibt eine kommagetrennte Liste aller Berechtigungen zurück, die der*die Nutzer*in der App zum Zeitpunkt der Anmeldung gewährt hat. Kann mit anderen response_type-Werten kombiniert werden. Wenn dieser Parameter mit token kombiniert wird, sind die Antwortdaten als URL-Fragment enthalten. Andernfalls sind sie als URL-Parameter enthalten.
scope. Eine mit Komma oder Leerzeichen getrennte Liste von Berechtigungen, die von der*dem App-Nutzer*in angefordert werden.

Für Windows 8-Apps

Wenn du einen Login für eine Windows-App baust, kannst du die Paketsicherheitserkennung als redirect_uri verwenden. Löse den Login-Dialog aus, indem du WebAuthenticationBroker.AuthenticateAsync aufrufst, und verwende den Login-Dialog-Endpunkt als requestUri. Hier siehst du ein Beispiel in JavaScript:

var requestUri = new Windows.Foundation.Uri(
  "https://www.facebook.com/v21.0/dialog/oauth?
    client_id={app-id}
    &display=popup
    &response_type=token
    &redirect_uri=ms-app://{package-security-identifier}");

Windows.Security.Authentication.Web.WebAuthenticationBroker.authenticateAsync(
  options,
  requestUri)
  .done(function (result) {
    // Handle the response from the Login Dialog
  }
);

Dadurch wird der Kontrollvorgang zurück an deine App geleitet – mit einem Zugriffsschlüssel bei Erfolg oder einem Fehler bei Misserfolg.

Verarbeiten der Antwort des Login-Dialogs

An diesem Punkt im Anmeldevorgang sieht der*die Nutzer*in den Login-Dialog. Hier kann er*sie sich entscheiden, ob er*sie die Anmeldung abbrechen oder der App den Zugriff auf seine*ihre Daten erlauben möchte.

Wenn der*die App-Nutzer*in „OK“ im Login-Dialog auswählt, gewährt er*sie deiner App Zugriff auf sein*ihr öffentliches Profil sowie seine*ihre Freundesliste und akzeptiert alle anderen von deiner App angeforderten Berechtigungen.

In jedem Fall ruft der Browser erneut die App auf und die Antwortdaten, die angeben, ob sich der*die Nutzer*in angemeldet oder die Anmeldung abgebrochen hat, werden an deine App gesendet. Bei der oben genannten Umleitungsmethode enthält die redirect_uri, zu der deine App zurücksendet, URL-Parameter oder -Fragmente (je nach ausgewähltem response_type), die erfasst werden müssen.

Aufgrund der verschiedenen Kombinationen an Code-Sprachen, die in Web-Apps verwendet werden können, enthält unser Leitfaden keine spezifischen Beispiele. Die meisten modernen Code-Sprachen sind allerdings wie folgt dazu in der Lage, URL-Parsing durchzuführen:

Mit clientseitigem JavaScript können URL-Fragmente erfasst werden (zum Beispiel jQuery BBQ), während URL-Parameter sowohl mit client- als auch mit serverseitigem Code erfasst werden können (zum Beispiel $_GET in PHP, jQuery.deparam in jQuery BBQ, querystring.parse in Node.js oder urlparse in Python). Microsoft stellt einen Leitfaden samt Beispiel-Code für Windows 8-Apps zum Verbinden mit einem Online-Anbieter – in diesem Fall Facebook – zur Verfügung.

Wenn eine Person sich bei einer Desktop-App anmeldet, leitet Facebook sie an die oben genannte redirect_uri um und fügt dem URI-Fragment einen Zugriffsschlüssel sowie einige andere Metadaten (wie die Ablauffrist des Schlüssels) hinzu:

https://www.facebook.com/connect/login_success.html#
    access_token=ACCESS_TOKEN...

Deine App muss diese Umleitung erkennen und dann den Zugriffsschlüssel mit den vom Betriebssystem und Entwicklungs-Framework bereitgestellten Mitteln aus der URI auslesen können. Du kannst dann gleich mit dem Schritt Inspizieren von Zugriffsschlüsseln fortfahren.

Abgebrochene Anmeldung

Wenn ein*e Nutzer*in deiner App den Login-Dialog nicht akzeptiert und stattdessen auf „Abbrechen“ klickt, wird er*sie hierhin weitergeleitet:

YOUR_REDIRECT_URI?
 error_reason=user_denied
 &error=access_denied
 &error_description=Permissions+error.

Siehe Verhalten bei fehlenden Berechtigungen, um weitere Informationen dazu zu erhalten, wie sich Apps verhalten sollten, wenn eine Person die Anmeldung abbricht.

Bestätigen der Identität

Da bei diesem Umleitungsvorgang Browser über den Login-Dialog an URLs in deiner App umgeleitet werden, könnte diese URL mit falschen Fragmenten oder Parametern aufgerufen werden. Wenn deine App davon ausgeht, dass diese Parameter gültig sind, könnten diese falschen Daten von deiner App zu potenziell bösartigen Zwecken missbraucht werden. Deshalb sollte deine App immer prüfen, ob die Person, die die App verwendet, auch die Person ist, von der du die Antwortdaten erhalten hast, bevor du für sie einen Zugriffsschlüssel erstellst. Die Überprüfung der Identität wird je nach erhaltenem response_type unterschiedlich durchgeführt:

Wenn du einen code erhalten hast, muss er gegen einen Zugriffsschlüssel getauscht werden, der einen Endpunkt verwendet. Der Aufruf muss von Server zu Server stattfinden, da dein App-Geheimcode enthalten ist. (Dein App-Geheimcode sollte nie Teil des Client-Codes sein.)
Wenn du einen token erhalten hast, muss er geprüft werden. Du solltest einen API-Aufruf an einen Inspizierungsendpunkt senden, der angibt, von welcher App und für wen der Schlüssel generiert wurde. Da für diesen API-Aufruf ein App-Zugriffsschlüssel erforderlich ist, darfst du diesen Aufruf nie über einen Client starten. Führe den Aufruf stattdessen von einem Server aus, auf dem du den App-Geheimcode sicher speichern kannst.
Wenn du sowohl code als auch token erhältst, solltest du beide Schritte ausführen.

Beachte dabei, dass du auch deinen eigenen state-Parameter erstellen und zusammen mit der Anmeldeanfrage Schutz vor CSFR-Angriffen bieten kannst.

Austausch von Code durch einen Zugriffsschlüssel

Sende eine HTTP-GET-Anfrage an den folgenden OAuth-Endpunkt, um einen Zugriffsschlüssel zu erhalten:

GET https://graph.facebook.com/v21.0/oauth/access_token?
   client_id={app-id}
   &redirect_uri={redirect-uri}
   &client_secret={app-secret}
   &code={code-parameter}

Für diesen Endpunkt sind einige Parameter erforderlich:

client_id. Deine App-IDs.
redirect_uri. Dieses Argument ist erforderlich und muss mit der ursprünglichen request_uri übereinstimmen, die du beim Start des OAuth-Anmeldevorgangs verwendet hast.
client_secret. Der eindeutige App-Geheimcode, der im App-Dashboard angezeigt wird. Dieser App-Geheimcode sollte nie in clientseitigem Code oder in dekompilierbaren Binärdateien enthalten sein. Es ist äußerst wichtig, dass der App-Geheimcode geheim bleibt, da er das Kernstück der Sicherheit für deine App und alle ihre Nutzer*innen darstellt.
code. Der Parameter, den du über den Login-Dialog erhalten hast, leitet dich nach oben weiter.

Hinweis: Ab Version 2.3 gibt dieser Endpunkt eine korrekte JSON-Antwort zurück. Wenn dein Aufruf keine Version angibt, wird standardmäßig die älteste verfügbare Version verwendet.

Antwort

Die Antwort, die du von diesem Endpunkt erhältst, wird im JSON-Format gegeben und lautet, falls erfolgreich:

{
  "access_token": {access-token}, 
  "token_type": {type},
  "expires_in":  {seconds-til-expiration}
}

Falls die Übertragung nicht erfolgreich ist, erhältst du eine Fehlermeldung.

Inspizieren von Zugriffsschlüsseln

Unabhängig davon, ob deine App code oder token als response_type vom Login-Dialog verwendet, hat sie immer einen Zugriffsschlüssel erhalten. Du kannst diese Schlüssel über einen Graph API-Endpunkt automatisch prüfen lassen:

GET graph.facebook.com/debug_token?
     input_token={token-to-inspect}
     &access_token={app-token-or-admin-token}

Dieser Endpunkt akzeptiert die folgenden Parameter:

input_token: Der zu inspizierende Schlüssel.
access_token: Ein App-Zugriffsschlüssel oder ein Zugriffsschlüssel eines*einer Entwickler*in der App.

Bei der Antwort des API-Aufrufs handelt es sich um ein JSON-Array, das Daten zum inspizierten Schlüssel enthält. Beispiel:

{
    "data": {
        "app_id": 138483919580948, 
        "type": "USER",
        "application": "Social Cafe", 
        "expires_at": 1352419328, 
        "is_valid": true, 
        "issued_at": 1347235328, 
        "metadata": {
            "sso": "iphone-safari"
        }, 
        "scopes": [
            "email", 
            "publish_actions"
        ], 
        "user_id": "1207059"
    }
}

Die Felder app_id und user_id helfen deiner App dabei, zu prüfen, ob der Zugriffsschlüssel für den*die Nutzer*in und für deine App gültig ist. Eine vollständige Beschreibung der anderen Felder findest du im Leitfaden zum Abrufen von Informationen zu Zugriffsschlüsseln.

Überprüfen von Berechtigungen

Edge /me/permissions kann aufgerufen werden, um eine Liste von Berechtigungen zu erhalten, die von einem*einer bestimmten Nutzer*in gewährt oder abgelehnt wurden. Deine App kann damit prüfen, welche der angeforderten Berechtigungen sie bei einem*einer bestimmten Nutzer*in nicht verwenden kann.

Erneutes Anfordern abgelehnter Berechtigungen

Über Facebook Login kann sich ein*e Nutzer*in dazu entscheiden, gewisse Berechtigungen nicht mit deiner App zu teilen. Der Login-Dialog enthält einen Bildschirm, der so aussieht:

Die Berechtigung public_profile ist immer erforderlich und ausgegraut, weil sie nicht abgewählt werden kann.

Wenn ein*e Nutzer*in allerdings user_likes („Gefällt mir“-Angaben) in diesem Beispiel abwählt, würde das Auswählen von /me/permissions für die gewährten Berechtigungen dieses Ergebnis zur Folge haben:

{
  "data":
    [
      {
        "permission":"public_profile",
        "status":"granted"
      },
      {
        "permission":"user_likes",
        "status":"declined"
      }
    ]
}

Beachte, dass die Berechtigung user_likes verweigert und nicht gewährt wurde.

Es ist in Ordnung, wenn du von einem*einer Nutzer*in, der*die App-Berechtigungen abgelehnt hat, diese erneut anforderst. Du solltest dem*der Nutzer*in einen Informationsbildschirm anzeigen, auf dem erklärt wird, warum er*sie die Berechtigung gewähren sollte, und über den du die Berechtigung dann erneut anforderst. Wenn du den Login-Dialog aber wie zuvor auslöst, wird diese Berechtigung dieses Mal nicht mehr angefordert.

Das liegt daran, dass eine einmal abgelehnte Berechtigung nicht mehr über den Login-Dialog angefordert wird, sofern du dies nicht explizit festlegst.

Füge dazu der Login-Dialog-URL einfach den auth_type=rerequest-Parameter hinzu:

https://www.facebook.com/v21.0/dialog/oauth?
    client_id={app-id}
    &redirect_uri={redirect-uri}
    &auth_type=rerequest
    scope=email

Die abgelehnte Berechtigung wird dann erneut über den Login-Dialog angefordert.

Speichern von Zugriffsschlüsseln und Login-Status

An diesem Punkt deines Login-Vorgangs ist ein*e Nutzer*in authentifiziert und bei deiner App angemeldet. Deine App kann jetzt API-Aufrufe im Namen eines*einer Nutzer*in ausführen. Zuvor sollte die App den Zugriffsschlüssel und den Login-Status der Person speichern, die deine App verwendet.

Speichern von Zugriffsschlüsseln

Nachdem deine App den Zugriffsschlüssel im vorherigen Schritt erhalten hat, sollte er gespeichert werden, damit er allen Teilen der App zur Verfügung steht, wenn sie API-Aufrufe starten. Es gibt dafür keinen bestimmten Vorgang, aber wenn du eine Web-App entwickelst, solltest du den Schlüssel vorzugsweise als Sitzungsvariable zur Identifizierung der Browser-Sitzung für eine bestimmte Person hinzufügen. Wenn du dagegen eine native Desktop- oder mobile App entwickelst, solltest du den Datenspeicher verwenden, der deiner App zur Verfügung steht. Die App sollte den Schlüssel außerdem zusammen mit der user_id in einer Datenbank speichern, um ihn zu identifizieren.

Sieh dir dazu unseren Hinweis zur Größe von Zugriffsschlüsseln im Zugriffsschlüsseldokument an.

Nachverfolgen des Login-Status

Deine App sollte den Login-Status einer Person speichern, da dadurch das unnötige Aufrufen des Login-Dialogs vermieden wird. Egal, für welchen Vorgang du dich entscheidest, vergiss nicht, deine Login-Statusüberprüfung entsprechend anzupassen.

Abmelden von Personen

Du kannst Menschen von deiner App abmelden, indem du den von dir hinzugefügten Login-Statusindikator entfernst. Du kannst zum Beispiel die Sitzung löschen, die angibt, dass eine Person angemeldet ist. Du solltest auch den gespeicherten Zugriffsschlüssel löschen.

Das Abmelden einer Person ist nicht gleichzusetzen mit dem Entfernen der Anmeldeberechtigungen (damit wird die bereits gewährte Authentifizierung hinfällig). Dies kann separat durchgeführt werden. Achte bei der Entwicklung deiner App deshalb darauf, dass Personen, die abgemeldet wurden, nicht automatisch wieder zum Login-Dialog weitergeleitet werden.

Erkennen, wenn Personen Apps deinstallieren

Nutzer*innen können Apps über Facebook.com deinstallieren, ohne dabei mit der App selbst in Berührung zu kommen. Damit Apps dies leichter erkennen können, ermöglichen wir den Einsatz einer Rückruf-URL für das Zurücknehmen einer Autorisierung, die angepingt wird, wenn dieser Fall eintritt.

Einen Rückruf für das Zurücknehmen einer Autorisierung kannst du im App-Dashboard aktivieren.

Auf Anfragen zum Löschen von Nutzer*innendaten antworten

Nutzer*innen können eine Löschung all ihrer Informationen anfragen, die eine App von Facebook erhalten hat. Antworten auf solche Anforderungen findest du unter Rückruf zur Datenlöschungsanfrage.