Ottenere i token di accesso e aggiornamento

Importante

A giugno 2022 è stata introdotta l'autenticazione a più fattori come requisito per Bing Ads. Potrebbe comunque essere necessario apportare una modifica al codice per essere conforme a questo requisito. Microsoft Advertising esegue controlli tecnici all'inizio di ottobre.

Questo post di blog descrive i passaggi da eseguire per garantire la conformità.

Per altre informazioni, vedere la guida ai requisiti di autenticazione a più fattori .

Dopo che un utente ha concesso il consenso per gestire il proprio account Microsoft Advertising, è possibile riscattare l'autorizzazione code per un token di accesso.

1. Richiedere un token di accesso riscattando l'oggetto code restituito dopo che l'utente ha concesso il consenso. Ottenere i valori access_token, refresh_token e expires_in dal flusso di risposta JSON.
2. Quando è stato ricevuto un token di accesso, il valore di expires_in rappresenta il tempo massimo in secondi, fino alla scadenza del token di accesso. Prima che il token di accesso scada o prima di dover nuovamente accedere all'API, è necessario aggiornare il token di accesso.
3. Dopo aver acquisito un oggetto access_token, è possibile usare il token nelle richieste alle API Bing Ads. Per un esempio, vedere la guida Creare la prima chiamata API .

Ecco un esempio dei passaggi 1 e 2 precedenti.

Nota

Sostituire your_client_id seguente con l'ID applicazione (client) assegnato dall'portale di Azure al portale Registrazioni app.

# 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

Consiglio

Per la guida alla risoluzione dei problemi, vedere la guida agli errori OAuth comuni .

Dettagli della richiesta di token di accesso

È possibile riscattare per code un access_token oggetto nella risorsa desiderata. A tale scopo, inviare una POST richiesta all'endpoint /token :

Nota

Sostituire your_client_id seguente con l'ID applicazione (client) assegnato dall'portale di Azure al portale Registrazioni app.

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

Il corpo della richiesta deve includere i parametri della richiesta e l'intestazione Content-Type deve essere impostata su application/x-www-form-urlencoded. Impostare il parametro di codice sul valore del codice di autorizzazione recuperato nel passaggio precedente e il tipo di concessione impostato su authorization_code. Il redirect_uri deve corrispondere esattamente all'URI di reindirizzamento usato per ottenere il codice di autorizzazione. Assicurarsi di codificare l'URL di reindirizzamento. Se è stata registrata un'applicazione Web, includere il parametro client_secret e impostarlo sul valore di cui è stato effettuato il provisioning in Registrare un'applicazione.

La tabella seguente include parametri che i client API Bing Ads possono includere nella richiesta di un token di accesso iniziale. Per altre informazioni sui parametri facoltativi, vedere la documentazione relativa al flusso di codice di autorizzazione Microsoft Identity Platform OAuth 2.0.

Parametro	Obbligatorio/Facoltativo	Descrizione
client_id	Obbligatorio	ID dell'applicazione (client) assegnato dall'portale di Azure- Registrazioni app portale all'app.
client_secret	obbligatorio per le app Web	Segreto dell'applicazione creato nel portale di registrazione dell'app per l'app. Non deve essere usato in un'app nativa, perché client_secrets non può essere archiviato in modo affidabile nei dispositivi. È necessario per le app Web e le API Web, che hanno la possibilità di archiviare il client_secret in modo sicuro sul lato server. Il segreto client deve essere codificato con URL prima di essere inviato.
code	Obbligatorio	Il authorization_code acquisito in seguito alla richiesta del consenso dell'utente.
code_verifier	Consigliato	Lo stesso code_verifier utilizzato per ottenere il authorization_code. Obbligatorio se PKCE è stato usato nella richiesta di concessione del codice di autorizzazione. Per altre informazioni, vedere PKCE RFC.
grant_type	Obbligatorio	Deve essere authorization_code per il flusso del codice di autorizzazione.
redirect_uri	Obbligatorio	Lo stesso valore redirect_uri usato per acquisire il authorization_code.
scope	Obbligatorio	Elenco di ambiti separati da spazi. Gli ambiti richiesti in questa parte devono essere equivalenti o un subset degli ambiti inclusi quando è stato richiesto il consenso dell'utente. Se gli ambiti specificati in questa richiesta si estendono su più server risorse, l'endpoint Microsoft Identity Platform restituirà un token per la risorsa specificata nel primo ambito. Per una spiegazione più dettagliata degli ambiti, vedere autorizzazioni, consenso e ambiti.
tenant	Obbligatorio	Il {tenant} valore nel percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. Per assicurarsi che l'applicazione supporti sia gli account personali del servizio gestito che gli account aziendali o dell'istituto di istruzione di Azure AD, è consigliabile usare common come tenant per l'autenticazione dell'API Bing Ads. Nel caso in cui l'applicazione richieda un altro tenant, vedere endpoint Microsoft Identity Platform per altre informazioni.

Dettagli della richiesta di token di aggiornamento

I token di accesso sono di breve durata ed è necessario aggiornarli dopo la scadenza per continuare ad accedere alle risorse. A tale scopo, inviare un'altra POST richiesta all'endpoint/token, questa volta specificando invece di .coderefresh_token I token di aggiornamento sono validi per tutte le autorizzazioni che il client ha già ricevuto il consenso.

I token di aggiornamento non hanno una durata specificata. In genere, la durata dei token di aggiornamento è relativamente lunga. In alcuni casi, tuttavia, i token di aggiornamento scadono, vengono revocati o non dispongono di privilegi sufficienti per l'azione desiderata. L'applicazione deve prevedere e gestire correttamente gli errori restituiti dall'endpoint di rilascio del token. Per altre informazioni sugli errori OAuth, vedere Errori OAuth comuni e Codici di errore di autenticazione e autorizzazione.

Nota

Sostituire your_client_id seguente con l'ID applicazione (client) assegnato dall'portale di Azure al portale Registrazioni app.

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

Il corpo della richiesta deve includere i parametri della richiesta e l'intestazione Content-Type deve essere impostata su application/x-www-form-urlencoded. Impostare il parametro del token di aggiornamento sul valore del token di aggiornamento recuperato nel passaggio precedente e il tipo di concessione impostato su refresh_token. Se è stata registrata un'applicazione Web, includere il parametro client_secret e impostarlo sul valore di cui è stato effettuato il provisioning in Registrare un'applicazione.

La tabella seguente include parametri che i client API Bing Ads possono includere nella richiesta di aggiornamento di un token di accesso. Per altre informazioni sui parametri facoltativi, vedere la documentazione relativa al flusso di codice di autorizzazione Microsoft Identity Platform OAuth 2.0.

Parametro	Obbligatorio/Facoltativo	Descrizione
client_id	Obbligatorio	ID dell'applicazione (client) assegnato dall'portale di Azure- Registrazioni app portale all'app.
client_secret	obbligatorio per le app Web	Segreto dell'applicazione creato nel portale di registrazione dell'app per l'app. Non deve essere usato in un'app nativa, perché client_secrets non può essere archiviato in modo affidabile nei dispositivi. È necessario per le app Web e le API Web, che hanno la possibilità di archiviare il client_secret in modo sicuro sul lato server.
grant_type	Obbligatorio	Deve essere impostato su refresh_token per questa parte del flusso del codice di autorizzazione.
refresh_token	Obbligatorio	Il refresh_token acquisito quando è stato richiesto un token di accesso.
scope	Obbligatorio	Elenco di ambiti separati da spazi. Gli ambiti richiesti in questa parte devono essere equivalenti o un subset degli ambiti inclusi quando è stato richiesto il consenso dell'utente. Se gli ambiti specificati in questa richiesta si estendono su più server risorse, l'endpoint Microsoft Identity Platform restituirà un token per la risorsa specificata nel primo ambito. Per una spiegazione più dettagliata degli ambiti, vedere autorizzazioni, consenso e ambiti.
tenant	Obbligatorio	Il {tenant} valore nel percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. Per assicurarsi che l'applicazione supporti sia gli account personali del servizio gestito che gli account aziendali o dell'istituto di istruzione di Azure AD, è consigliabile usare common come tenant per l'autenticazione dell'API Bing Ads. Nel caso in cui l'applicazione richieda un altro tenant, vedere endpoint Microsoft Identity Platform per altre informazioni.

Anche se i token di aggiornamento non vengono revocati quando vengono usati per acquisire nuovi token di accesso, si prevede di eliminare il token di aggiornamento precedente. La specifica OAuth 2.0 dice: "Il server di autorizzazione può emettere un nuovo token di aggiornamento, nel qual caso il client DEVE eliminare il token di aggiornamento precedente e sostituirlo con il nuovo token di aggiornamento. Il server di autorizzazione PUÒ revocare il token di aggiornamento precedente dopo aver emesso un nuovo token di aggiornamento al client."

I token di aggiornamento sono e saranno sempre completamente opachi per l'applicazione. Sono di lunga durata, ad esempio 90 giorni per i client pubblici, ma l'app non deve essere scritta per prevedere che un token di aggiornamento durerà per qualsiasi periodo di tempo. I token di aggiornamento possono essere invalidati in qualsiasi momento e l'unico modo per un'app di sapere se un token di aggiornamento è valido consiste nel tentare di riscattarlo effettuando una richiesta di token. Anche se si aggiorna continuamente il token nello stesso dispositivo con il token di aggiornamento più recente, è consigliabile ricominciare e richiedere il consenso dell'utente se, ad esempio, l'utente di Microsoft Advertising ha modificato la password, ha rimosso un dispositivo dall'elenco di dispositivi attendibili o ha rimosso le autorizzazioni per l'autenticazione dell'applicazione per suo conto. In qualsiasi momento senza preavviso Microsoft può determinare che il consenso dell'utente deve essere nuovamente concesso. In tal caso, il servizio di autorizzazione restituirà un errore di concessione non valido, come illustrato nell'esempio seguente.

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

Tenere presente che i token di aggiornamento pubblico sono associati solo al dispositivo concesso. Ad esempio, se è stata registrata un'app nativa e si usa https://login.microsoftonline.com/common/oauth2/nativeclient come URI di reindirizzamento, si garantisce solo che possa essere aggiornata nello stesso dispositivo. I client che eseguono app in servizi che si estendono su aree e dispositivi, ad esempio Microsoft Azure, devono registrare un'app Web con il segreto client. L'URI di reindirizzamento può essere localhost, ma non può essere https://login.microsoftonline.com/common/oauth2/nativeclient. Se si usa https://login.microsoftonline.com/common/oauth2/nativeclient con un segreto client, verrà restituito l'errore seguente.

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

Si verificherà lo stesso errore se si tenta di richiedere nuovi token di accesso e aggiornamento usando un token di aggiornamento di cui è stato effettuato il provisioning senza un segreto client.

Per altre informazioni sugli errori OAuth, vedere Errori OAuth comuni e Codici di errore di autenticazione e autorizzazione.

Passaggi successivi

Effettuare la prima chiamata API

Vedere anche

Introduzione