Obtenir des jetons d’accès et d’actualisation

  • Article

Importante

En juin 2022, nous avons introduit l’authentification multifacteur comme exigence pour Bing Ads. Vous devrez peut-être quand même apporter une modification au code pour vous conformer à cette exigence. Microsoft Advertising effectue des vérifications techniques de l’application au début du mois d’octobre.

Ce billet de blog décrit les étapes à suivre pour garantir la conformité.

Pour plus d’informations, consultez le guide des exigences d’authentification multifacteur .

Une fois qu’un utilisateur a donné son consentement pour gérer son compte Microsoft Advertising, vous pouvez utiliser l’autorisation code contre un jeton d’accès.

  1. Demandez un jeton d’accès en échangeant le code retourné après que l’utilisateur a accordé son consentement. Obtenez les valeurs access_token, refresh_token et expires_in à partir du flux de réponse JSON.
  2. Lorsque vous avez reçu un jeton d’accès, la valeur de expires_in représente la durée maximale en secondes, jusqu’à l’expiration du jeton d’accès. Avant l’expiration du jeton d’accès ou avant que vous n’ayez à nouveau besoin d’un accès à l’API, vous devez actualiser le jeton d’accès.
  3. Une fois que vous avez acquis un access_token, vous pouvez utiliser le jeton dans les requêtes adressées aux API Bing Ads. Consultez le guide Créer votre premier appel d’API pour obtenir un exemple.

Voici un exemple des étapes 1 et 2 ci-dessus.

Remarque

Remplacez your_client_id ci-dessous par l’ID d’application (client) que le Portail Azure - inscriptions d'applications portail a attribué à votre application.

# 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

Conseil

Pour obtenir de l’aide sur la résolution des problèmes, consultez le Guide des erreurs OAuth courantes .

Détails de la demande de jeton d’accès

Vous pouvez échanger contre code un access_token pour la ressource souhaitée. Pour ce faire, envoyez une POST requête au point de /token terminaison :

Remarque

Remplacez your_client_id ci-dessous par l’ID d’application (client) que le Portail Azure - inscriptions d'applications portail a attribué à votre application.

// 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

Le corps de la demande doit inclure les paramètres de la requête et l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded. Définissez le paramètre de code sur la valeur du code d’autorisation récupéré à l’étape précédente, et le type d’octroi défini sur authorization_code. Le redirect_uri doit correspondre exactement à l’URI de redirection utilisé pour obtenir le code d’autorisation. Veillez à encoder l’URL de redirection. Si vous avez inscrit une application web, incluez le paramètre client_secret et définissez-le sur la valeur provisionnée dans Inscrire une application.

Le tableau suivant inclut les paramètres que les clients de l’API Bing Ads peuvent inclure dans la demande de jeton d’accès initial. Pour plus d’informations sur les paramètres facultatifs, consultez la documentation sur le flux de code d’autorisation Plateforme d'identités Microsoft OAuth 2.0.

Paramètre Requis/Facultatif Description
client_id obligatoire ID d’application (client) attribué par le portail Portail Azure - inscriptions d'applications à votre application.
client_secret obligatoire pour les applications web Secret d’application que vous avez créé dans le portail d’inscription d’application pour votre application. Il ne doit pas être utilisé dans une application native, car client_secrets ne peut pas être stocké de manière fiable sur les appareils. Il est nécessaire pour les applications web et les API web, qui ont la possibilité de stocker les client_secret en toute sécurité côté serveur. La clé secrète client doit être encodée en URL avant d’être envoyée.
code obligatoire Le authorization_code que vous avez acquis à la suite de la demande de consentement de l’utilisateur.
code_verifier recommandé Le même code_verifier qui a été utilisé pour obtenir le authorization_code. Obligatoire si PKCE a été utilisé dans la demande d’octroi de code d’autorisation. Pour plus d’informations, consultez le RFC PKCE.
grant_type obligatoire Doit être authorization_code pour le flux de code d’autorisation.
redirect_uri obligatoire Même valeur d’URI de redirection qui a été utilisée pour acquérir le code d’autorisation.
scope obligatoire Liste d’étendues séparées par des espaces. Les étendues demandées dans cette étape doivent être équivalentes ou un sous-ensemble des étendues incluses lorsque vous avez demandé le consentement de l’utilisateur. Si les étendues spécifiées dans cette requête s’étendent sur plusieurs serveurs de ressources, le point de terminaison Plateforme d'identités Microsoft retourne un jeton pour la ressource spécifiée dans la première étendue. Pour obtenir une explication plus détaillée des étendues, consultez autorisations, consentement et étendues.
tenant obligatoire La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler qui peut se connecter à l’application. Pour vous assurer que votre application prend en charge les comptes personnels MSA et les comptes professionnels ou scolaires Azure AD, nous vous suggérons d’utiliser common comme locataire pour l’authentification de l’API Bing Ads.

Si votre application nécessite un autre locataire, consultez Plateforme d'identités Microsoft points de terminaison pour plus d’informations.

Détails de la demande de jeton d’actualisation

Les jetons d’accès sont de courte durée et vous devez les actualiser après leur expiration pour continuer à accéder aux ressources. Pour ce faire, envoyez une autre POST demande au /token point de terminaison, en fournissant cette fois au refresh_token lieu du code. Les jetons d’actualisation sont valides pour toutes les autorisations pour lesquelles votre client a déjà reçu le consentement.

Les jetons d’actualisation n’ont pas de durées de vie spécifiées. En règle générale, les durées de vie des jetons d’actualisation sont relativement longues. Toutefois, dans certains cas, les jetons d’actualisation expirent, sont révoqués ou ne disposent pas de privilèges suffisants pour l’action souhaitée. Votre application doit s’attendre à ce que et gérer correctement les erreurs retournées par le point de terminaison d’émission de jeton. Pour plus d’informations sur les erreurs OAuth, consultez Erreurs OAuth courantes et Codesd’erreur d’authentification et d’autorisation.

Remarque

Remplacez your_client_id ci-dessous par l’ID d’application (client) que le Portail Azure - inscriptions d'applications portail a attribué à votre application.

// 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

Le corps de la demande doit inclure les paramètres de la requête et l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded. Définissez le paramètre de jeton d’actualisation sur la valeur du jeton d’actualisation récupéré à l’étape précédente, et le type d’octroi défini sur refresh_token. Si vous avez inscrit une application web, incluez le paramètre client_secret et définissez-le sur la valeur provisionnée dans Inscrire une application.

Le tableau suivant inclut des paramètres que les clients de l’API Bing Ads peuvent inclure dans la demande d’actualisation d’un jeton d’accès. Pour plus d’informations sur les paramètres facultatifs, consultez la documentation sur le flux de code d’autorisation Plateforme d'identités Microsoft OAuth 2.0.

Paramètre Requis/Facultatif Description
client_id obligatoire ID d’application (client) attribué par le portail Portail Azure - inscriptions d'applications à votre application.
client_secret obligatoire pour les applications web Secret d’application que vous avez créé dans le portail d’inscription d’application pour votre application. Il ne doit pas être utilisé dans une application native, car client_secrets ne peut pas être stocké de manière fiable sur les appareils. Il est nécessaire pour les applications web et les API web, qui ont la possibilité de stocker les client_secret en toute sécurité côté serveur.
grant_type obligatoire Doit être défini sur refresh_token pour cette étape du flux de code d’autorisation.
refresh_token obligatoire Le refresh_token que vous avez acquis lorsque vous avez demandé un jeton d’accès.
scope obligatoire Liste d’étendues séparées par des espaces. Les étendues demandées dans cette étape doivent être équivalentes ou un sous-ensemble des étendues incluses lorsque vous avez demandé le consentement de l’utilisateur. Si les étendues spécifiées dans cette requête s’étendent sur plusieurs serveurs de ressources, le point de terminaison Plateforme d'identités Microsoft retourne un jeton pour la ressource spécifiée dans la première étendue. Pour obtenir une explication plus détaillée des étendues, consultez autorisations, consentement et étendues.
tenant obligatoire La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler qui peut se connecter à l’application. Pour vous assurer que votre application prend en charge les comptes personnels MSA et les comptes professionnels ou scolaires Azure AD, nous vous suggérons d’utiliser common comme locataire pour l’authentification de l’API Bing Ads.

Si votre application nécessite un autre locataire, consultez Plateforme d'identités Microsoft points de terminaison pour plus d’informations.

Bien que les jetons d’actualisation ne soient pas révoqués lorsqu’ils sont utilisés pour acquérir de nouveaux jetons d’accès, vous êtes censé ignorer l’ancien jeton d’actualisation. La spécification OAuth 2.0 indique : « Le serveur d’autorisation PEUT émettre un nouveau jeton d’actualisation, auquel cas le client DOIT ignorer l’ancien jeton d’actualisation et le remplacer par le nouveau jeton d’actualisation. Le serveur d’autorisation PEUT révoquer l’ancien jeton d’actualisation après avoir émis un nouveau jeton d’actualisation au client. »

Les jetons d’actualisation sont, et seront toujours, complètement opaques pour votre application. Ils sont de longue durée, par exemple, 90 jours pour les clients publics, mais l’application ne doit pas être écrite pour s’attendre à ce qu’un jeton d’actualisation dure pendant une période quelconque. Les jetons d’actualisation peuvent être invalidés à tout moment, et la seule façon pour une application de savoir si un jeton d’actualisation est valide consiste à tenter de l’utiliser en effectuant une demande de jeton. Même si vous actualisez en permanence le jeton sur le même appareil avec le jeton d’actualisation le plus récent, vous devez vous attendre à recommencer et à demander le consentement de l’utilisateur si, par exemple, l’utilisateur Microsoft Advertising a modifié son mot de passe, supprimé un appareil de sa liste d’appareils approuvés ou supprimé les autorisations permettant à votre application de s’authentifier en son nom. À tout moment, sans avertissement préalable, Microsoft peut déterminer que le consentement de l’utilisateur doit à nouveau être accordé. Dans ce cas, le service d’autorisation retourne une erreur d’octroi non valide, comme indiqué dans l’exemple suivant.

{"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."}

N’oubliez pas que les jetons d’actualisation publics sont uniquement liés à l’appareil accordé. Par exemple, si vous avez inscrit une application native et que vous l’utilisez https://login.microsoftonline.com/common/oauth2/nativeclient comme URI de redirection, nous garantissons uniquement qu’elle peut être actualisée sur le même appareil. Les clients exécutant des applications sur des services qui couvrent des régions et des appareils tels que Microsoft Azure doivent inscrire une application web avec une clé secrète client. L’URI de redirection peut être localhost, mais ne peut pas être https://login.microsoftonline.com/common/oauth2/nativeclient. Si vous utilisez https://login.microsoftonline.com/common/oauth2/nativeclient avec une clé secrète client, l’erreur suivante est retournée.

{"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.

Vous rencontrerez la même erreur si vous essayez de demander de nouveaux jetons d’accès et d’actualisation à l’aide d’un jeton d’actualisation qui a été provisionné sans clé secrète client.

Pour plus d’informations sur les erreurs OAuth, consultez Erreurs OAuth courantes et Codesd’erreur d’authentification et d’autorisation.

Étapes suivantes

Passer votre premier appel d’API

Voir aussi

Prise en main