Compartir a través de

Obtención de tokens de acceso y actualización

  • Artículo

Importante

En junio de 2022, introdujimos la autenticación multifactor como requisito para Bing Ads. Es posible que tenga que realizar un cambio de código para cumplir con este requisito. Microsoft Advertising está realizando comprobaciones técnicas de cumplimiento a principios de octubre.

En esta entrada de blog se describen los pasos que debe seguir para garantizar el cumplimiento.

Para obtener más información, consulte la guía de requisitos de autenticación multifactor .

Una vez que un usuario haya concedido su consentimiento para administrar su cuenta de Microsoft Advertising, puede canjear la autorización code por un token de acceso.

  1. Solicite un token de acceso mediante el canje del code devuelto después de que el usuario concediera el consentimiento. Obtenga los valores access_token, refresh_token y expires_in del flujo de respuesta JSON.
  2. Cuando recibió un token de acceso, el valor de expires_in representa el tiempo máximo en segundos, hasta que expire el token de acceso. Antes de que expire el token de acceso o antes de que vuelva a necesitar acceso a la API, debe actualizar el token de acceso.
  3. Una vez que haya adquirido correctamente un access_token, puede usar el token en las solicitudes a las API de Bing Ads. Consulte la guía Make your first API call (Hacer su primera llamada a la API ) para obtener un ejemplo.

Este es un ejemplo de los pasos 1 y 2 anteriores.

Nota:

Reemplace your_client_id siguiente por el identificador de aplicación (cliente) que el portal de Azure Portal Registros de aplicaciones asignó a la aplicación.

# 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

Sugerencia

Para obtener ayuda para solucionar problemas, consulte la guía de errores comunes de OAuth .

Detalles de la solicitud de token de acceso

Puede canjear por code un access_token objeto en el recurso deseado. Para ello, envíe una POST solicitud al punto de /token conexión:

Nota:

Reemplace your_client_id siguiente por el identificador de aplicación (cliente) que el portal de Azure Portal Registros de aplicaciones asignó a la aplicación.

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

El cuerpo de la solicitud debe incluir los parámetros de solicitud y el encabezado Content-Type debe establecerse en application/x-www-form-urlencoded. Establezca el parámetro de código en el valor del código de autorización recuperado en el paso anterior y el tipo de concesión establecido en authorization_code. El redirect_uri debe coincidir exactamente con el URI de redireccionamiento usado para obtener el código de autorización. Asegúrese de codificar la dirección URL de redireccionamiento. Si registró una aplicación web, incluya el parámetro client_secret y establézcalo en el valor aprovisionado en Registrar una aplicación.

En la tabla siguiente se incluyen los parámetros que los clientes de la API de Bing Ads pueden incluir en la solicitud de un token de acceso inicial. Para obtener más información sobre los parámetros opcionales, consulte la documentación del flujo de código de autorización de OAuth 2.0 de Plataforma de identidad de Microsoft.

Parámetro Obligatorio/opcional Description
client_id necesario Identificador de aplicación (cliente) que el Azure Portal Registros de aplicaciones portal asignó a la aplicación.
client_secret necesario para aplicaciones web Secreto de aplicación que creó en el portal de registro de aplicaciones de la aplicación. No se debe usar en una aplicación nativa, ya que client_secrets no se puede almacenar de forma confiable en los dispositivos. Es necesario para las aplicaciones web y las API web, que tienen la capacidad de almacenar el client_secret de forma segura en el lado servidor. El secreto de cliente debe estar codificado con dirección URL antes de enviarse.
code necesario El authorization_code que adquirió como resultado de solicitar el consentimiento del usuario.
code_verifier recomendado El mismo code_verifier que se usó para obtener el authorization_code. Obligatorio si PKCE se usó en la solicitud de concesión de código de autorización. Para obtener más información, consulte RFC de PKCE.
grant_type necesario Debe ser authorization_code para el flujo del código de autorización.
redirect_uri necesario Mismo valor del URI de redireccionamiento que se usó para adquirir el código de autorización.
scope necesario Lista de ámbitos separados por espacios. Los ámbitos solicitados en este segmento deben ser equivalentes a o un subconjunto de los ámbitos incluidos cuando solicitó el consentimiento del usuario. Si los ámbitos especificados en esta solicitud abarcan varios servidores de recursos, el punto de conexión Plataforma de identidad de Microsoft devolverá un token para el recurso especificado en el primer ámbito. Para obtener una explicación más detallada de los ámbitos, consulte permisos, consentimiento y ámbitos.
tenant necesario Se puede usar el valor {tenant} de la ruta de acceso de la solicitud para controlar quién puede iniciar sesión en la aplicación. Para asegurarse de que la aplicación admite cuentas personales de MSA y cuentas profesionales o educativas de Azure AD, se recomienda usar common como inquilino para la autenticación de bing Ads API.

En caso de que la aplicación requiera otro inquilino, consulte Plataforma de identidad de Microsoft puntos de conexión para obtener más información.

Detalles de la solicitud de token de actualización

Los tokens de acceso son de corta duración y debe actualizarlos después de que expiren para seguir accediendo a los recursos. Para ello, envíe otra POST solicitud al /token punto de conexión, esta vez proporcionando en refresh_token lugar de code. Los tokens de actualización son válidos para todos los permisos que el cliente ya ha recibido consentimiento.

Los tokens de actualización no tienen vigencias especificadas. Normalmente, la duración de los tokens de actualización es relativamente larga. Sin embargo, en algunos casos, los tokens de actualización expiran, se revocan o carecen de privilegios suficientes para la acción deseada. La aplicación debe esperar y controlar los errores devueltos por el punto de conexión de emisión de tokens correctamente. Para obtener más información sobre los errores de OAuth, consulte Errores comunes de OAuth y Códigos de error de autenticación y autorización.

Nota:

Reemplace your_client_id siguiente por el identificador de aplicación (cliente) que el portal de Azure Portal Registros de aplicaciones asignó a la aplicación.

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

El cuerpo de la solicitud debe incluir los parámetros de solicitud y el encabezado Content-Type debe establecerse en application/x-www-form-urlencoded. Establezca el parámetro del token de actualización en el valor del token de actualización recuperado en el paso anterior y el tipo de concesión establecido en refresh_token. Si registró una aplicación web, incluya el parámetro client_secret y establézcalo en el valor aprovisionado en Registrar una aplicación.

En la tabla siguiente se incluyen los parámetros que los clientes de la API de Bing Ads pueden incluir en la solicitud para actualizar un token de acceso. Para obtener más información sobre los parámetros opcionales, consulte la documentación del flujo de código de autorización de OAuth 2.0 de Plataforma de identidad de Microsoft.

Parámetro Obligatorio/opcional Description
client_id necesario Identificador de aplicación (cliente) que el Azure Portal Registros de aplicaciones portal asignó a la aplicación.
client_secret necesario para aplicaciones web Secreto de aplicación que creó en el portal de registro de aplicaciones de la aplicación. No se debe usar en una aplicación nativa, ya que client_secrets no se puede almacenar de forma confiable en los dispositivos. Es necesario para las aplicaciones web y las API web, que tienen la capacidad de almacenar el client_secret de forma segura en el lado servidor.
grant_type necesario Debe establecerse en refresh_token para este tramo del flujo de código de autorización.
refresh_token necesario El refresh_token que adquirió cuando solicitó un token de acceso.
scope necesario Lista de ámbitos separados por espacios. Los ámbitos solicitados en este segmento deben ser equivalentes a o un subconjunto de los ámbitos incluidos cuando solicitó el consentimiento del usuario. Si los ámbitos especificados en esta solicitud abarcan varios servidores de recursos, el punto de conexión Plataforma de identidad de Microsoft devolverá un token para el recurso especificado en el primer ámbito. Para obtener una explicación más detallada de los ámbitos, consulte permisos, consentimiento y ámbitos.
tenant necesario Se puede usar el valor {tenant} de la ruta de acceso de la solicitud para controlar quién puede iniciar sesión en la aplicación. Para asegurarse de que la aplicación admite cuentas personales de MSA y cuentas profesionales o educativas de Azure AD, se recomienda usar common como inquilino para la autenticación de bing Ads API.

En caso de que la aplicación requiera otro inquilino, consulte Plataforma de identidad de Microsoft puntos de conexión para obtener más información.

Aunque los tokens de actualización no se revocan cuando se usan para adquirir nuevos tokens de acceso, se espera que descarte el token de actualización antiguo. La especificación de OAuth 2.0 indica: "El servidor de autorización PUEDE emitir un nuevo token de actualización, en cuyo caso el cliente DEBE descartar el token de actualización antiguo y reemplazarlo por el nuevo token de actualización. El servidor de autorización PUEDE revocar el token de actualización anterior después de emitir un nuevo token de actualización al cliente."

Los tokens de actualización son, y siempre serán, completamente opacos para la aplicación. Son de larga duración, por ejemplo, 90 días para los clientes públicos, pero la aplicación no debe escribirse para esperar que un token de actualización dure cualquier período de tiempo. Los tokens de actualización se pueden invalidar en cualquier momento y la única manera de que una aplicación sepa si un token de actualización es válido es intentar canjearlo mediante una solicitud de token. Incluso si actualiza continuamente el token en el mismo dispositivo con el token de actualización más reciente, debe esperar iniciar de nuevo y solicitar el consentimiento del usuario si, por ejemplo, el usuario de Microsoft Advertising cambió su contraseña, quitó un dispositivo de su lista de dispositivos de confianza o quitó permisos para que la aplicación se autentique en su nombre. En cualquier momento sin previo aviso, Microsoft puede determinar que se debe conceder de nuevo el consentimiento del usuario. En ese caso, el servicio de autorización devolvería un error de concesión no válido, como se muestra en el ejemplo siguiente.

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

Tenga en cuenta que los tokens de actualización pública solo están enlazados al dispositivo concedido. Por ejemplo, si registró una aplicación nativa y la usa https://login.microsoftonline.com/common/oauth2/nativeclient como uri de redireccionamiento, solo garantizamos que se pueda actualizar en el mismo dispositivo. Los clientes que ejecutan aplicaciones en servicios que abarcan regiones y dispositivos como Microsoft Azure deben registrar una aplicación web con el secreto de cliente. El URI de redireccionamiento puede ser localhost, pero no puede ser https://login.microsoftonline.com/common/oauth2/nativeclient. Si usa https://login.microsoftonline.com/common/oauth2/nativeclient con un secreto de cliente, se devolverá el siguiente error.

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

Se producirá el mismo error si intenta solicitar nuevos tokens de acceso y actualización mediante un token de actualización aprovisionado sin un secreto de cliente.

Para obtener más información sobre los errores de OAuth, consulte Errores comunes de OAuth y Códigos de error de autenticación y autorización.

Pasos siguientes

Realización de la primera llamada API

Consulta también

Introducción