Share via

Obter tokens de acesso e atualização

  • Artigo

Importante

Em junho de 2022, introduzimos a autenticação multifator como um requisito para anúncios do Bing. Poderá ainda ter de fazer uma alteração de código para se tornar compatível com este requisito. O Microsoft Advertising está a realizar verificações de imposição técnica no início de outubro.

Esta publicação de blogue descreve os passos que deve seguir para garantir a conformidade.

Para obter mais informações, veja o guia de requisitos de autenticação multifator .

Assim que um utilizador tiver dado consentimento para gerir a conta Microsoft Advertising, pode resgatar a autorização code de um token de acesso.

  1. Peça um token de acesso ao resgatar o code devolvido após o utilizador conceder o consentimento. Obtenha os valores access_token, refresh_token e expires_in do fluxo de resposta JSON.
  2. Quando recebeu um token de acesso, o valor de expires_in representa o tempo máximo em segundos, até que o token de acesso expire. Antes de o token de acesso expirar ou antes de precisar de acesso à API novamente, deve atualizar o token de acesso.
  3. Depois de adquirir access_tokenum , pode utilizar o token nos pedidos às APIs de Anúncios do Bing. Veja o guia Criar a sua primeira chamada à API para obter um exemplo.

Eis um exemplo dos passos 1 e 2 acima.

Nota

Substitua your_client_id abaixo pelo ID da aplicação (cliente) que o portal portal do Azure - Registos de aplicações atribuiu à sua aplicação.

# 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

Sugestão

Para obter ajuda para a resolução de problemas, veja o Guia de erros comuns do OAuth .

Detalhes do pedido de token de acesso

Pode resgatar o code para um access_token para o recurso pretendido. Para tal, envie um POST pedido para o /token ponto final:

Nota

Substitua your_client_id abaixo pelo ID da aplicação (cliente) que o portal portal do Azure - Registos de aplicações atribuiu à sua aplicação.

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

O corpo do pedido tem de incluir os parâmetros do pedido e o cabeçalho Content-Type tem de ser definido como application/x-www-form-urlencoded. Defina o parâmetro de código para o valor do código de autorização obtido no passo anterior e o tipo de concessão definido como authorization_code. O redirect_uri tem de corresponder exatamente ao URI de redirecionamento utilizado para obter o código de autorização. Certifique-se de que codifica o URL de redirecionamento. Se registou uma aplicação Web, inclua o parâmetro client_secret e defina-o como o valor aprovisionado em Registar uma aplicação.

A tabela seguinte inclui parâmetros que os clientes da API de Anúncios do Bing podem incluir no pedido de um token de acesso inicial. Para obter detalhes adicionais sobre os parâmetros opcionais, veja a documentação do fluxo de código de autorização plataforma de identidades da Microsoft OAuth 2.0.

Parâmetro Obrigatório/Opcional Descrição
client_id necessário O ID da aplicação (cliente) que o portal do Azure - Registos de aplicações portal atribuiu à sua aplicação.
client_secret necessário para aplicações Web O segredo da aplicação que criou no portal de registo de aplicações da sua aplicação. Não deve ser utilizada numa aplicação nativa, porque client_secrets não podem ser armazenadas em dispositivos de forma fiável. É necessário para aplicações Web e APIs Web, que têm a capacidade de armazenar o client_secret de forma segura no lado do servidor. O segredo do cliente tem de ser codificado com URL antes de ser enviado.
code necessário A authorization_code que adquiriu como resultado do pedido de consentimento do utilizador.
code_verifier recomendado O mesmo code_verifier que foi utilizado para obter o authorization_code. Necessário se o PKCE tiver sido utilizado no pedido de concessão do código de autorização. Para obter mais informações, veja o RFC do PKCE.
grant_type necessário Tem de ser authorization_code para o fluxo de código de autorização.
redirect_uri necessário O mesmo valor redirect_uri utilizado para adquirir o authorization_code.
scope necessário Uma lista separada por espaços de âmbitos. Os âmbitos pedidos nesta perna têm de ser equivalentes ou um subconjunto dos âmbitos incluídos quando pediu o consentimento do utilizador. Se os âmbitos especificados neste pedido abranger vários servidores de recursos, o ponto final plataforma de identidades da Microsoft devolverá um token para o recurso especificado no primeiro âmbito. Para obter uma explicação mais detalhada dos âmbitos, veja permissões, consentimento e âmbitos.
tenant necessário O {tenant} valor no caminho do pedido pode ser utilizado para controlar quem pode iniciar sessão na aplicação. Para garantir que a sua aplicação suporta contas pessoais msa e Azure AD contas escolares ou profissionais, sugerimos que utilize common como inquilino para a autenticação da API de Anúncios do Bing.

Caso a aplicação necessite de outro inquilino, veja plataforma de identidades da Microsoft pontos finais para obter mais informações.

Atualizar detalhes do pedido de token

Os tokens de acesso são de curta duração e tem de atualizá-los depois de expirarem para continuarem a aceder aos recursos. Pode fazê-lo ao submeter outro POST pedido para o /token ponto final, desta vez fornecendo o refresh_token em vez do code. Os tokens de atualização são válidos para todas as permissões que o cliente já recebeu.

Os tokens de atualização não têm durações especificadas. Normalmente, as durações dos tokens de atualização são relativamente longas. No entanto, em alguns casos, os tokens de atualização expiram, são revogados ou não têm privilégios suficientes para a ação pretendida. A aplicação tem de esperar e processar erros devolvidos corretamente pelo ponto final de emissão de tokens. Para obter mais detalhes sobre os erros OAuth, veja Common OAuth Errors and Authentication and authorization error codes (Erros comuns de OAuth e Códigos de erro de autenticação e autorização).

Nota

Substitua your_client_id abaixo pelo ID da aplicação (cliente) que o portal portal do Azure - Registos de aplicações atribuiu à sua aplicação.

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

O corpo do pedido tem de incluir os parâmetros do pedido e o cabeçalho Content-Type tem de ser definido como application/x-www-form-urlencoded. Defina o parâmetro do token de atualização para o valor do token de atualização obtido no passo anterior e o tipo de concessão definido como refresh_token. Se registou uma aplicação Web, inclua o parâmetro client_secret e defina-o como o valor aprovisionado em Registar uma aplicação.

A tabela seguinte inclui parâmetros que os clientes da API de Anúncios do Bing podem incluir no pedido para atualizar um token de acesso. Para obter detalhes adicionais sobre os parâmetros opcionais, veja a documentação do fluxo de código de autorização plataforma de identidades da Microsoft OAuth 2.0.

Parâmetro Obrigatório/Opcional Descrição
client_id necessário O ID da aplicação (cliente) que o portal do Azure - Registos de aplicações portal atribuiu à sua aplicação.
client_secret necessário para aplicações Web O segredo da aplicação que criou no portal de registo de aplicações da sua aplicação. Não deve ser utilizada numa aplicação nativa, porque client_secrets não podem ser armazenadas em dispositivos de forma fiável. É necessário para aplicações Web e APIs Web, que têm a capacidade de armazenar o client_secret de forma segura no lado do servidor.
grant_type necessário Tem de ser definido como refresh_token para esta etapa do fluxo de código de autorização.
refresh_token necessário O refresh_token que adquiriu quando pediu um token de acesso.
scope necessário Uma lista separada por espaços de âmbitos. Os âmbitos pedidos nesta perna têm de ser equivalentes ou um subconjunto dos âmbitos incluídos quando pediu o consentimento do utilizador. Se os âmbitos especificados neste pedido abranger vários servidores de recursos, o ponto final plataforma de identidades da Microsoft devolverá um token para o recurso especificado no primeiro âmbito. Para obter uma explicação mais detalhada dos âmbitos, veja permissões, consentimento e âmbitos.
tenant necessário O {tenant} valor no caminho do pedido pode ser utilizado para controlar quem pode iniciar sessão na aplicação. Para garantir que a sua aplicação suporta contas pessoais msa e Azure AD contas escolares ou profissionais, sugerimos que utilize common como inquilino para a autenticação da API de Anúncios do Bing.

Caso a aplicação necessite de outro inquilino, veja plataforma de identidades da Microsoft pontos finais para obter mais informações.

Embora os tokens de atualização não sejam revogados quando utilizados para adquirir novos tokens de acesso, espera-se que elimine o token de atualização antigo. A especificação OAuth 2.0 diz: "O servidor de autorização PODE emitir um novo token de atualização, caso em que o cliente TEM de eliminar o token de atualização antigo e substituí-lo pelo novo token de atualização. O servidor de autorização PODE revogar o token de atualização antigo após emitir um novo token de atualização para o cliente."

Os tokens de atualização são, e serão sempre, completamente opacos para a sua aplicação. São de longa duração, por exemplo, 90 dias para clientes públicos, mas a aplicação não deve ser escrita para esperar que um token de atualização dure um período de tempo. Os tokens de atualização podem ser invalidados a qualquer momento e a única forma de uma aplicação saber se um token de atualização é válido é tentar resgatá-lo ao fazer um pedido de token. Mesmo que atualize continuamente o token no mesmo dispositivo com o token de atualização mais recente, deverá começar novamente e pedir o consentimento do utilizador se, por exemplo, o utilizador do Microsoft Advertising tiver alterado a palavra-passe, removido um dispositivo da lista de dispositivos fidedignos ou removido as permissões para a sua aplicação se autenticar em seu nome. A qualquer momento, sem aviso prévio, a Microsoft pode determinar que o consentimento do utilizador deve ser concedido novamente. Nesse caso, o serviço de autorização devolveria um erro de concessão inválido, conforme mostrado no exemplo seguinte.

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

Tenha em atenção que os tokens de atualização pública só estão vinculados ao dispositivo concedido. Por exemplo, se registou uma aplicação Nativa e utilizou https://login.microsoftonline.com/common/oauth2/nativeclient como URI de redirecionamento, apenas garantimos que pode ser atualizada no mesmo dispositivo. Os clientes que executem aplicações em serviços que abrangem regiões e dispositivos, como o Microsoft Azure, devem registar uma aplicação Web com o segredo do cliente. O URI de redirecionamento pode ser localhost, mas não pode ser https://login.microsoftonline.com/common/oauth2/nativeclient. Se utilizar https://login.microsoftonline.com/common/oauth2/nativeclient com um segredo do cliente, será devolvido o seguinte erro.

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

Ocorrerá o mesmo erro se tentar pedir novos tokens de acesso e atualização através de um token de atualização que foi aprovisionado sem um segredo do cliente.

Para obter mais detalhes sobre os erros OAuth, veja Common OAuth Errors and Authentication and authorization error codes (Erros comuns de OAuth e Códigos de erro de autenticação e autorização).

Passos seguintes

Fazer a sua primeira chamada à API

See Also

Introdução