Abrufen von Zugriffs- und Aktualisierungstoken
Wichtig
Im Juni 2022 haben wir die mehrstufige Authentifizierung als Anforderung für Bing Ads eingeführt. Möglicherweise müssen Sie dennoch eine Codeänderung vornehmen, um diese Anforderung erfüllen zu können. Microsoft Advertising führt Anfang Oktober technische Erzwingungsprüfungen durch.
In diesem Blogbeitrag werden die Schritte beschrieben, die Sie ausführen sollten, um die Konformität sicherzustellen.
Weitere Informationen finden Sie im Anforderungsleitfaden für die mehrstufige Authentifizierung .
Nachdem ein Benutzer Ihnen die Zustimmung zur Verwaltung seines Microsoft Advertising-Kontos erteilt hat, können Sie die Autorisierung code für ein Zugriffstoken einlösen.
- Fordern Sie ein Zugriffstoken an, indem Sie den einlösen, der
codezurückgegeben wurde, nachdem der Benutzer seine Zustimmung erteilt hat. Rufen Sie die werte access_token, refresh_token und expires_in aus dem JSON-Antwortdatenstrom ab. - Wenn Sie ein Zugriffstoken erhalten haben, stellt der Wert von expires_in die maximale Zeit in Sekunden dar, bis das Zugriffstoken abläuft. Bevor das Zugriffstoken abläuft oder Sie erneut API-Zugriff benötigen, sollten Sie das Zugriffstoken aktualisieren.
- Nachdem Sie erfolgreich einen
access_tokenerworben haben, können Sie das Token in Anforderungen an Bing Ads-APIs verwenden . Ein Beispiel finden Sie im Leitfaden zum ersten API-Aufruf .
Hier sehen Sie ein Beispiel für die obigen Schritte 1 und 2.
Hinweis
Ersetzen Sie your_client_id unten durch die Anwendungs-ID (Client), die Azure-Portal App-Registrierungen Portal Ihrer App zugewiesen wurde.
# Replace your_client_id with your registered application ID.
$clientId = "your_client_id"
Start-Process "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=$clientId&scope=openid%20profile%20https://ads.microsoft.com/msads.manage%20offline_access&response_type=code&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient&state=ClientStateGoesHere&prompt=login"
$code = Read-Host "Grant consent in the browser, and then enter the response URI here:"
$code = $code -match 'code=(.*)\&'
$code = $Matches[1]
# Get the initial access and refresh tokens.
$response = Invoke-WebRequest https://login.microsoftonline.com/common/oauth2/v2.0/token -ContentType application/x-www-form-urlencoded -Method POST -Body "client_id=$clientId&scope=https://ads.microsoft.com/msads.manage%20offline_access&code=$code&grant_type=authorization_code&redirect_uri=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fnativeclient"
$oauthTokens = ($response.Content | ConvertFrom-Json)
Write-Output "Access token: " $oauthTokens.access_token
Write-Output "Access token expires in: " $oauthTokens.expires_in
Write-Output "Refresh token: " $oauthTokens.refresh_token
# The access token will expire e.g., after one hour.
# Use the refresh token to get new access and refresh tokens.
$response = Invoke-WebRequest https://login.microsoftonline.com/common/oauth2/v2.0/token -ContentType application/x-www-form-urlencoded -Method POST -Body "client_id=$clientId&scope=https://ads.microsoft.com/msads.manage%20offline_access&code=$code&grant_type=refresh_token&refresh_token=$($oauthTokens.refresh_token)"
$oauthTokens = ($response.Content | ConvertFrom-Json)
Write-Output "Access token: " $oauthTokens.access_token
Write-Output "Access token expires in: " $oauthTokens.expires_in
Write-Output "Refresh token: " $oauthTokens.refresh_token
Tipp
Hilfe zur Problembehandlung finden Sie im Leitfaden zu häufigen OAuth-Fehlern .
Details zur Zugriffstokenanforderung
Sie können für eine codeaccess_token für die gewünschte Ressource einlösen. Senden Sie dazu eine POST Anforderung an den /token Endpunkt:
Hinweis
Ersetzen Sie your_client_id unten durch die Anwendungs-ID (Client), die Azure-Portal App-Registrierungen Portal Ihrer App zugewiesen wurde.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=your_client_id
&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only applicable for web apps
Der Text der Anforderung muss die Anforderungsparameter enthalten, und der Content-Type-Header muss auf application/x-www-form-urlencoded festgelegt werden. Legen Sie den Codeparameter auf den Wert des Autorisierungscodes fest, den Sie im vorherigen Schritt abgerufen haben, und legen Sie den Gewährungstyp auf authorization_code fest. Die redirect_uri muss genau mit dem Umleitungs-URI übereinstimmen, der zum Abrufen des Autorisierungscodes verwendet wird. Achten Sie darauf, die Umleitungs-URL zu codieren. Wenn Sie eine Webanwendung registriert haben, schließen Sie den parameter client_secret ein, und legen Sie ihn auf den unter Registrieren einer Anwendung bereitgestellten Wert fest.
Die folgende Tabelle enthält Parameter, die Bing Ads-API-Clients in die Anforderung für ein anfängliches Zugriffstoken einschließen können. Weitere Informationen zu optionalen Parametern finden Sie in der Dokumentation zum Microsoft Identity Platform OAuth 2.0-Autorisierungscodefluss.
| Parameter | Erforderlich/Optional | Beschreibung |
|---|---|---|
client_id |
erforderlich | Die Anwendungs- (Client-) ID, die vom Azure-Portal – App-Registrierungen Portal Ihrer App zugewiesen wurde. |
client_secret |
erforderlich für Web-Apps | Das Anwendungsgeheimnis, das Sie im App-Registrierungsportal für Ihre App erstellt haben. Sie sollte nicht in einer nativen App verwendet werden, da client_secrets nicht zuverlässig auf Geräten gespeichert werden können. Sie ist für Web-Apps und Web-APIs erforderlich, die die client_secret sicher auf serverseitiger Seite speichern können. Der geheime Clientschlüssel muss vor dem Senden URL-codiert sein. |
code |
erforderlich | Die authorization_code, die Sie aufgrund der Anforderung der Benutzergenehmigung erhalten haben. |
code_verifier |
empfohlen | Die gleiche code_verifier, die zum Abrufen der authorization_code verwendet wurde. Erforderlich, wenn PKCE in der Autorisierungscodegenehmigungsanforderung verwendet wurde. Weitere Informationen finden Sie unter PKCE RFC. |
grant_type |
erforderlich | Muss authorization_code für den Autorisierungscodefluss sein. |
redirect_uri |
erforderlich | Die gleiche Umleitungs-URI-Wert, der zum Abrufen des Autorisierungscodes verwendet wurde. |
scope |
erforderlich | Eine durch Leerzeichen getrennte Liste von Bereichen. Die in diesem Abschnitt angeforderten Bereiche müssen mit oder einer Teilmenge der Bereiche übereinstimmen, die beim Anfordern der Benutzereinwilligung enthalten sind. Wenn die in dieser Anforderung angegebenen Bereiche mehrere Ressourcenserver umfassen, gibt der Microsoft Identity Platform-Endpunkt ein Token für die im ersten Bereich angegebene Ressource zurück. Eine ausführlichere Erläuterung der Bereiche finden Sie unter Berechtigungen, Zustimmung und Bereiche. |
tenant |
Erforderlich | Mit dem Wert {tenant} im Pfad der Anforderung kann gesteuert werden, wer sich bei der Anwendung anmelden kann. Um sicherzustellen, dass Ihre Anwendung sowohl persönliche MSA-Konten als auch Azure AD-Geschäfts-, Schul- oder Unikonten unterstützt, sollten Sie als Mandant für die Bing Ads-API-Authentifizierung verwenden common .Falls Ihre Anwendung einen anderen Mandanten erfordert, finden Sie weitere Informationen unter Microsoft Identity Platform Endpunkte. |
Details der Tokenanforderung aktualisieren
Zugriffstoken sind kurzlebig, und Sie müssen sie nach ablaufen aktualisieren, um weiterhin auf Ressourcen zugreifen zu können. Hierzu können Sie eine weitere POST Anforderung an den /token Endpunkt senden, wobei dieses Mal anstelle refresh_token von codebereitgestellt wird. Aktualisierungstoken sind für alle Berechtigungen gültig, für die Ihr Client bereits die Zustimmung erhalten hat.
Aktualisierungstoken weisen keine angegebene Lebensdauer auf. In der Regel sind die Lebensdauern von Aktualisierungstoken relativ lang. In einigen Fällen laufen Aktualisierungstoken jedoch ab, werden widerrufen oder verfügen nicht über ausreichende Berechtigungen für die gewünschte Aktion. Ihre Anwendung muss Fehler erwarten und behandeln, die vom Tokenausstellungsendpunkt zurückgegeben werden. Weitere Informationen zu OAuth-Fehlern finden Sie unter Häufige OAuth-Fehler und Authentifizierungs- und Autorisierungsfehlercodes.
Hinweis
Ersetzen Sie your_client_id unten durch die Anwendungs-ID (Client), die Azure-Portal App-Registrierungen Portal Ihrer App zugewiesen wurde.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=your_client_id
&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only applicable for web apps
Der Text der Anforderung muss die Anforderungsparameter enthalten, und der Content-Type-Header muss auf application/x-www-form-urlencoded festgelegt werden. Legen Sie den Aktualisierungstokenparameter auf den Wert des Aktualisierungstokens fest, das im vorherigen Schritt abgerufen wurde, und legen Sie den Gewährungstyp auf refresh_token fest. Wenn Sie eine Webanwendung registriert haben, schließen Sie den parameter client_secret ein, und legen Sie ihn auf den unter Registrieren einer Anwendung bereitgestellten Wert fest.
Die folgende Tabelle enthält Parameter, die Bing Ads-API-Clients in die Anforderung zum Aktualisieren eines Zugriffstokens einschließen können. Weitere Informationen zu optionalen Parametern finden Sie in der Dokumentation zum Microsoft Identity Platform OAuth 2.0-Autorisierungscodefluss.
| Parameter | Erforderlich/Optional | Beschreibung |
|---|---|---|
client_id |
erforderlich | Die Anwendungs- (Client-) ID, die vom Azure-Portal – App-Registrierungen Portal Ihrer App zugewiesen wurde. |
client_secret |
erforderlich für Web-Apps | Das Anwendungsgeheimnis, das Sie im App-Registrierungsportal für Ihre App erstellt haben. Sie sollte nicht in einer nativen App verwendet werden, da client_secrets nicht zuverlässig auf Geräten gespeichert werden können. Sie ist für Web-Apps und Web-APIs erforderlich, die die client_secret sicher auf serverseitiger Seite speichern können. |
grant_type |
erforderlich | Muss für diesen Teil des Autorisierungscodeflows auf refresh_token festgelegt werden. |
refresh_token |
Erforderlich | Die refresh_token, die Sie beim Anfordern eines Zugriffstokens erworben haben. |
scope |
Erforderlich | Eine durch Leerzeichen getrennte Liste von Bereichen. Die in diesem Abschnitt angeforderten Bereiche müssen mit oder einer Teilmenge der Bereiche übereinstimmen, die beim Anfordern der Benutzereinwilligung enthalten sind. Wenn die in dieser Anforderung angegebenen Bereiche mehrere Ressourcenserver umfassen, gibt der Microsoft Identity Platform-Endpunkt ein Token für die im ersten Bereich angegebene Ressource zurück. Eine ausführlichere Erläuterung der Bereiche finden Sie unter Berechtigungen, Zustimmung und Bereiche. |
tenant |
Erforderlich | Mit dem Wert {tenant} im Pfad der Anforderung kann gesteuert werden, wer sich bei der Anwendung anmelden kann. Um sicherzustellen, dass Ihre Anwendung sowohl persönliche MSA-Konten als auch Azure AD-Geschäfts-, Schul- oder Unikonten unterstützt, sollten Sie als Mandant für die Bing Ads-API-Authentifizierung verwenden common .Falls Ihre Anwendung einen anderen Mandanten erfordert, finden Sie weitere Informationen unter Microsoft Identity Platform Endpunkte. |
Aktualisierungstoken werden zwar nicht widerrufen, wenn sie zum Abrufen neuer Zugriffstoken verwendet werden, es wird jedoch erwartet, dass Sie das alte Aktualisierungstoken verwerfen. Die OAuth 2.0-Spezifikation besagt: "Der Autorisierungsserver KANN ein neues Aktualisierungstoken ausstellen. In diesem Fall MUSS der Client das alte Aktualisierungstoken verwerfen und durch das neue Aktualisierungstoken ersetzen. Der Autorisierungsserver KANN das alte Aktualisierungstoken widerrufen, nachdem er ein neues Aktualisierungstoken für den Client ausgestellt hat."
Aktualisierungstoken sind und sind für Ihre Anwendung immer völlig undurchsichtig. Sie sind langlebig, z. B. 90 Tage für öffentliche Clients, aber die App sollte nicht so geschrieben werden, dass sie erwartet, dass ein Aktualisierungstoken für einen beliebigen Zeitraum gültig ist. Aktualisierungstoken können jederzeit ungültig gemacht werden, und die einzige Möglichkeit für eine App zu wissen, ob ein Aktualisierungstoken gültig ist, besteht darin, es durch eine Tokenanforderung einzulösen. Auch wenn Sie das Token auf demselben Gerät kontinuierlich mit dem neuesten Aktualisierungstoken aktualisieren, sollten Sie davon ausgehen, dass Sie erneut starten und die Zustimmung des Benutzers anfordern , wenn der Microsoft Advertising-Benutzer beispielsweise sein Kennwort geändert, ein Gerät aus der Liste der vertrauenswürdigen Geräte entfernt hat oder die Berechtigungen für die Authentifizierung ihrer Anwendung in ihrem Namen entfernt hat. Microsoft kann jederzeit ohne vorherige Warnung festlegen, dass die Zustimmung des Benutzers erneut erteilt werden sollte. In diesem Fall würde der Autorisierungsdienst einen Fehler aufgrund einer ungültigen Genehmigung zurückgeben, wie im folgenden Beispiel gezeigt.
{"error":"invalid_grant","error_description":"The user could not be authenticated or the grant is expired. The user must first sign in and if needed grant the client application access to the requested scope."}
Beachten Sie, dass öffentliche Aktualisierungstoken nur an das gewährte Gerät gebunden sind. Wenn Sie beispielsweise eine native App registriert und als Umleitungs-URI verwenden https://login.microsoftonline.com/common/oauth2/nativeclient , garantieren wir nur, dass sie auf demselben Gerät aktualisiert werden kann. Clients, die Apps in Diensten ausführen, die Regionen und Geräte umfassen, wie z. B. Microsoft Azure, sollten eine Web-App mit einem geheimen Clientschlüssel registrieren. Der Umleitungs-URI kann localhost, aber nicht sein https://login.microsoftonline.com/common/oauth2/nativeclient. Wenn Sie mit einem geheimen Clientschlüssel verwenden https://login.microsoftonline.com/common/oauth2/nativeclient , wird der folgende Fehler zurückgegeben.
{"error":"invalid_request","error_description":"Public clients can't send a client secret."} Likewise for Web apps please note that refresh tokens can be invalidated at any moment.
Der gleiche Fehler tritt auf, wenn Sie versuchen, mithilfe eines Aktualisierungstokens, das ohne einen geheimen Clientschlüssel bereitgestellt wurde, neue Zugriffs- und Aktualisierungstoken anzufordern.
Weitere Informationen zu OAuth-Fehlern finden Sie unter Häufige OAuth-Fehler und Authentifizierungs- und Autorisierungsfehlercodes.