Apps installieren, Zugriffstokens generieren, aktualisieren und widerrufen

Ein Systemnutzer steht für Serveraufrufe. Daher hat er keinen Facebook Login und kann keine App installieren oder den standardmäßigen Facebook-OAuth-Vorgang zum Generieren eines Zugriffstokens durchführen. Du musst hierfür API-Aufrufe verwenden.

Arten von System-Zugriffstokens

Typen	Zugriffstokens ohne Ablauf	Empfohlene Zugriffstokens mit Ablauf
Laufzeit	Läuft nie ab	60 Tage gültig
Aktualisierung erforderlich?	Nein	Ja
Empfehlung anhand von Anwendungsfällen	Du kannst das Risiko von gestohlenen Zugriffstokens in Kauf nehmen und möchtest, dass deine Drittanbieteranwendungen offline auf Daten zugreifen können.	Du möchtest das Risiko gestohlener Zugriffstokens begrenzen.

Apps installieren

Ein Systemnutzer oder ein Systemnutzer mit Admin-Rechten muss die App installieren, die zum Generieren eines Zugriffstokens verwendet wird. Das bedeutet, dass der App erlaubt werden muss, APIs im Namen dieses Systemnutzers oder des Systemnutzers mit Administratorrechten aufzurufen.

Der Systemnutzer und die App sollten zum gleichen Business Manager gehören. Als Mindestanforderung für das Installieren von Apps ist Standardzugriff auf die Ads Management API erforderlich.

Voraussetzung für das Installieren einer App für einen Systemnutzer:

access_token: eines*einer Admin, eines Systemnutzers mit Adminrechten oder eines anderen Systemnutzers
business_app: ID der zu installierenden App

Stelle eine POST-Anfrage, um eine App für einen Systemnutzer zu installieren:

curl \
-F "business_app=APP-ID" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/applications"

Dieser Aufruf gibt ein boolesches Ergebnis zurück, wenn die Installation erfolgreich ist. Wenn eine dieser Einschränkungen nicht erfüllt ist, wird eine entsprechende Fehlermeldung angezeigt.

Zugriffstoken generieren

Nachdem der Systemnutzer die App installiert hat, kann diese ein dauerhaftes Zugriffstoken generieren. Es gelten einige Einschränkungen:

Der Systemnutzer muss die App installiert haben, die im Parameter übergeben wird (siehe oben).
Apps können sich nur an Unternehmen (oder deren untergeordnete Unternehmen) richten, die sie beansprucht haben.
Der Systemnutzer und der Eigentümer des Zugriffstokens, der während dieses API-Aufrufs zum Generieren des Zugriffstokens verwendet wurde, müssen zum gleichen Business Manager gehören.
Die App kann im Besitz des gleichen Business Managers sein oder auch nicht. Ist dies nicht der Fall, gelten einige Einschränkungen. Siehe Abschnitt unten.

Parameter für den API-Aufruf:

business_app: die App, die sich im Besitz des Business Managers befindet, zu dem der Systemnutzer gehört.
appsecret_proof: berechnetes Feld für die App. Dies ist erforderlich, um sicherzustellen, dass der richtige Server den API-Aufruf durchführt. Weitere Details findest du unter Login-Sicherheit.
scope: kommagetrennter String mit erweiterten Berechtigungen.
access_token: Zugriffstoken im Besitz des Business Manager-Admins, Systemnutzers mit Administratorrechten oder regulären Systemnutzers.
set_token_expires_in_60_days: Auf true festgelegt, um ein Systemnutzer-Zugriffstoken mit Ablauf zu generieren. Empfohlen. Token mit Ablaufdatum sind eine Best Practice zu Sicherheitszwecken. Einige Unternehmen müssen Token verwenden, die ablaufen. Wenn dies für dein Unternehmen gilt, führt das Auslassen dieses Parameters oder das Festlegen auf false zu einem Fehler. Für alle Integrationen sollten ablaufende Token verwendet werden, um auf zukünftige Sicherheitsstandards der Plattform ausgerichtet zu sein.

Unterstützter Umfang für Systemnutzer:

ads_management
ads_read
attribution_read
business_management
catalog_management
commerce_account_manage_orders
commerce_account_read_orders
commerce_account_read_settings
instagram_basic
instagram_branded_content_ads_brand
instagram_branded_content_brand
instagram_content_publish
instagram_manage_comments
instagram_manage_insights
instagram_manage_messages
instagram_shopping_tag_products
leads_retrieval
page_events
pages_manage_ads
pages_manage_cta
pages_manage_engagement
pages_manage_instant_articles
pages_manage_metadata
pages_manage_posts
pages_messaging
pages_read_engagement
pages_read_user_content
pages_show_list
private_computation_access
publish_video
read_audience_network_insights
read_insights
read_page_mailboxes
whatsapp_business_management
whatsapp_business_messaging

Veraltete Berechtigung, nur sichtbar für Apps, die vor dem 24. April 2018 erstellt wurden

publish_actions

Nach Funktionen beschränkte Berechtigungen

Funktion	Berechtigung
business_creative_management	`business_creative_managementbusiness_creative_insights` `business_creative_insights_sharebusiness_data_management`
commerce_public_api_beta_testing	`commerce_manage_accountscommerce_account_read_reports`

Zum Generieren des appsecret_proof kannst du PHP-Code verwenden:

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

Im Code-Beispiel oben verweist app_secret_for_the_app_used_in_the_call auf den App-Geheimcode für die App, die zum Generieren des Zugriffstokens verwendet wurde. Du findest den App-Geheimcode in deinem App-Dashboard.

Der gehashte appsecret_proof sollte ein String wie der folgende sein: "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Stelle zum Generieren eines Systemnutzer-Zugriffstokens ohne Ablauf eine POST-Anfrage:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,pages_read_engagement,pages_show_list" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Stelle zum Generieren eines Systemnutzer-Zugriffstokens mit Ablauf eine POST-Anfrage:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,pages_read_engagement,pages_show_list" \
-F "set_token_expires_in_60_days=true" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Der Endpunkt hieß vorher /SYSTEM-USER-ID/ads_access_token. Aufrufe dieses Namens funktionieren nicht mehr.

Die Antwort gibt den Zugriffstoken-String zurück. Sollte eine der Einschränkungen nicht erfüllt werden, werden entsprechende Fehlermeldungen ausgegeben. Antwort:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Du kannst auch über die Business Manager-Benutzungsoberfläche ein Systemnutzer-Zugriffstoken generieren.

Zugriffstoken aktualisieren

Ein Systemnutzer-Zugriffstoken ist ab dem Generierungs- oder Aktualisierungsdatum 60 Tage lang gültig. Um Kontinuität zu schaffen, sollte der*die Entwickler*in das Zugriffstoken innerhalb von 60 Tagen aktualisieren. Andernfalls verfällt das Zugriffstoken und der*die Entwickler*in muss ein neues abrufen, um wieder API-Zugriff zu erhalten.

Um ein ablaufendes Systemnutzer-Zugriffstoken zu aktualisieren, benötigst du Folgendes:

fb_exchange_token: Ein gültiges Systemnutzer-Zugriffstoken
client_id: App-ID
client_secret: App-Geheimcode
set_token_expires_in_60_days: Auf „true“ festgelegt, um ein Systemnutzer-Zugriffstoken mit Ablauf zu aktualisieren.

Frage den „GET oauth/access_token“-Endpunkt ab.

Beispielanfrage

curl -i -X GET 
"https://graph.facebook.com/{graph-api-version}/oauth/access_token?  
    grant_type=fb_exchange_token&          
    client_id={app-id}&
    client_secret={app-secret}&
    set_token_expires_in_60_days=true&
    fb_exchange_token={your-access-token}"

Beispielantwort

{
  "access_token":"{expiring-system-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944    // Time left in seconds until the token expires
}

Zugriffstoken widerrufen

Dieser Endpunkt ist für die regelmäßige Token-Rotation oder das Widerrufen von Zugriffstokens für kompromittierte Systemnutzer ausgelegt, um dein System zu schützen.

Um ein Systemnutzer-Zugriffstoken zu widerrufen, benötigst du Folgendes:

revoke_token: Das zu widerrufende Zugriffstoken
client_id: App-ID
client_secret: App-Geheimcode
access_token: Zugriffstoken zum Identifizieren des*der Aufrufer*in

Dies sind die Anforderungen:

Die client_id muss mit der tatsächlichen App übereinstimmen und du musst sicherstellen, dass die App nicht gedrosselt, deaktiviert oder gelöscht ist.
client_id zusammen mit der installierten App von revoke_token, der installierten App von access_token und client_secret müssen alle gleich sein.

Frage den „GET oauth/revoke“-Endpunkt ab.

Beispielanfrage

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/revoke?   
    client_id={app-id}&
    client_secret={app-secret}&
    revoke_token={system-user-access-token-to-revoke}&
    access_token={your-access-token}"

Beispielantwort

{
  "success":"true",
}

Zugriffstoken-Rotation

Die Token-Rotation ist eine Sicherheitsmaßnahme, die Risiken verringern kann, z. B. den Schaden durch geleakte Tokens. Durch regelmäßiges Ändern von Zugriffstokens kann der potenzielle Schaden, der durch ein gestohlenes oder abhanden gekommenes Token verursacht wird, begrenzt werden, ähnlich wie bei der Passwortänderung. Aktuell unterstützt unser System die Rotation von Systemnutzern ohne Ausfallzeit. Das geht so:

Aktualisiere das Systemnutzer-Zugriffstoken über die Refresh API. Diese gibt ein neues Systemnutzer-Zugriffstoken zurück, das ab dem Aktualisierungsdatum 60 Tage lang gültig ist. Das alte Zugriffstoken funktioniert weiterhin bis zu seinem Ablauf (d. h. Erstellungsdatum + 60).
Stelle das neue Systemnutzer-Zugriffstoken bereit.
Widerrufe das alte Systemnutzer-Zugriffstoken über die Revocation API. Das Token wird sofort ungültig und kann nach dem Widerrufen nicht mehr verwendet werden.