Ottenere i token di accesso e aggiornamento

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.

# 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

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 :

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

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.

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

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

Vedere anche

Introduzione