Pedir consentimento do utilizador

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 .

Depois de registar uma aplicação, tem de obter o consentimento do utilizador para gerir a conta microsoft Advertising.

Sugestão

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

Importante

Tem de ser pedido a cada utilizador e dar consentimento através de um controlo de browser, pelo menos, uma vez para que a sua aplicação faça a gestão das respetivas contas do Microsoft Advertising. Este é um fluxo OAuth 2.0 padrão e é definido em detalhe na secção Concessão de Código de Autorização da especificação OAuth 2.0.

O fluxo de código de autorização começa com o cliente a direcionar o utilizador para o /authorize ponto final. Neste pedido, o cliente indica as permissões necessárias para adquirir ao utilizador:

Nota

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

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=your_client_id
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&state=12345

1. Copie o URL abaixo e cole-o no browser para executar este pedido de exemplo de consentimento do utilizador.

Nota

Substitua your_client_id no URL abaixo pelo ID da aplicação (cliente) que o portal do Azure – Portal de registos de aplicações atribuiu à sua aplicação.

<https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=your_client_id&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage&state=12345>

1. Inicie sessão com as credenciais da sua conta Microsoft e conceda o consentimento da sua aplicação para gerir as suas contas do Microsoft Advertising.
2. Depois de iniciar sessão, o browser deve ser redirecionado para https://localhost/myapp/ com um code na barra de endereço. Pode ignorar a mensagem de erro na página.
3. Em seguida, irá utilizar o código para obter tokens de acesso e atualização.

O ponto final da plataforma de identidades da Microsoft também garantirá que o utilizador consentiu as permissões indicadas no scope parâmetro de consulta. Se o utilizador não tiver consentido nenhuma dessas permissões, pedirá ao utilizador para consentir as permissões necessárias. Embora este guia se concentre principalmente na gestão de contas do Microsoft Advertising através scope=https://ads.microsoft.com/msads.managedo , são fornecidos mais detalhes sobre permissões e consentimento na plataforma de identidades da Microsoft aqui.

Assim que o utilizador autenticar e conceder consentimento, o ponto final da plataforma de identidades da Microsoft devolverá uma resposta à sua aplicação no , indicado redirect_uri, utilizando o método especificado no response_mode parâmetro . Por exemplo, o URI de chamada de retorno inclui um código de autorização da seguinte forma se o utilizador tiver concedido permissões para a sua aplicação gerir as respetivas contas microsoft Advertising: ;http://localhost/myapp/?code=CodeGoesHere& state=12345.

Se o utilizador tiver concedido permissões à sua aplicação para gerir as respetivas contas do Microsoft Advertising, deverá utilizar o código imediatamente no próximo passo. A curta duração do código de autorização, aproximadamente 5 minutos, está sujeita a alterações. Se o utilizador tiver negado as permissões da aplicação para gerir as respetivas contas do Microsoft Advertising, o URI de chamada de retorno inclui um campo de descrição de erros e erros da seguinte forma: http://localhost/myapp/?error=access_denied& error_description=ERROR_DESCRIPTION&state=ClientStateGoesHere. 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).

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

Parâmetro	Obrigatório/Opcional	Descrição
client_id	Necessário	O ID da aplicação (cliente) que o portal do Azure - Portal de registos de aplicações atribuiu à sua aplicação.
code_challenge	recomendado	Utilizado para proteger as concessões de código de autorização através da Chave de Prova para o Code Exchange (PKCE). Necessário se code_challenge_method estiver incluído. Para obter mais informações, veja o RFC do PKCE. Isto é agora recomendado para todos os tipos de aplicações – aplicações nativas, SPAs e clientes confidenciais, como aplicações Web.
code_challenge_method	recomendado	O método utilizado para codificar o code_verifier para o code_challenge parâmetro . Pode ser um dos seguintes valores: - plain - S256 Se excluído, code_challenge assume-se que é texto simples, se code_challenge estiver incluído. A plataforma de identidades da Microsoft suporta e plainS256. Para obter mais informações, veja o RFC do PKCE.
prompt	opcional	Indica o tipo de interação do utilizador de que a sua aplicação necessita. Os valores suportados incluem o seguinte: - prompt=login forçará o utilizador a introduzir as respetivas credenciais nesse pedido, anulando o início de sessão único. - prompt=none é o oposto de "início de sessão", ou seja, garantirá que o utilizador não é apresentado com qualquer tipo de pedido interativo. Se o pedido não puder ser concluído automaticamente através do início de sessão único, o ponto final da plataforma de identidades da Microsoft devolverá um erro de interaction_required. - prompt=consent irá acionar a caixa de diálogo de consentimento do OAuth após o utilizador iniciar sessão, pedindo ao utilizador para conceder permissões à aplicação. - prompt=select_account interromperá o início de sessão único e fornecerá a experiência de seleção da conta, listando todas as contas em sessão ou qualquer conta memorizada ou uma opção para optar por utilizar uma conta diferente.
redirect_uri	Necessário	O redirect_uri da sua aplicação, onde as respostas de autenticação podem ser enviadas e recebidas pela sua aplicação. Tem de corresponder exatamente a uma das redirect_uris que registou no portal, exceto que tem de ter codificação de URL. Para aplicações móveis nativas &, deve utilizar o valor predefinido de https://login.microsoftonline.com/common/oauth2/nativeclient.
response_mode	recomendado	Especifica o método que deve ser utilizado para enviar o token resultante de volta para a sua aplicação. Pode ser um dos seguintes: - query - fragment - form_post query fornece o código como um parâmetro de cadeia de consulta no URI de redirecionamento. Se estiver a pedir um token de ID com o fluxo implícito, não pode utilizar query conforme especificado na especificação OpenID. Se estiver a pedir apenas o código, pode utilizar query, fragmentou form_post. form_post executa um POST que contém o código para o URI de redirecionamento. Para obter mais informações, consulte o protocolo OpenID Connect.
response_type	Necessário	Tem de incluir code para o fluxo de código de autorização.
scope	Necessário	Uma lista separada por espaços de âmbitos aos quais pretende dar consentimento ao utilizador. Certifique-se de que inclui https://ads.microsoft.com/msads.manage para pedir ao utilizador o acesso ao Microsoft Advertising. Inclua offline_access para garantir que um token de atualização está incluído na resposta.
state	recomendado	Um valor incluído no pedido que também será devolvido na resposta do token. Pode ser uma cadeia de qualquer conteúdo que pretenda. Normalmente, é utilizado um valor exclusivo gerado aleatoriamente para impedir ataques de falsificação de pedidos entre sites. O valor também pode codificar informações sobre o estado do utilizador na aplicação antes de o pedido de autenticação ter ocorrido, como a página ou vista em que se encontravam.
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 contas escolares ou profissionais do Azure AD, 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, consulte Pontos finais da plataforma de identidades da Microsoft para obter mais informações.

Passos seguintes

Obter tokens de acesso e atualização

See Also

Introdução