Share via

Usare Azure DevOps OAuth 2.0 per creare un'app Web

  • Articolo

Servizi di Azure DevOps

Importante

Queste informazioni sono solo per le app OAuth di Azure DevOps esistenti. I nuovi sviluppatori di app devono usare Microsoft Entra ID OAuth per l'integrazione con Azure DevOps.

Azure DevOps è un provider di identità per le app OAuth 2.0. L'implementazione di OAuth 2.0 consente agli sviluppatori di autorizzare l'app per gli utenti e ottenere i token di accesso per le risorse di Azure DevOps.

Introduzione ad Azure DevOps OAuth

1. Registrare l'app

  1. Passare a https://app.vsaex.visualstudio.com/app/register per registrare l'app.

  2. Selezionare gli ambiti necessari per l'applicazione e quindi usare gli stessi ambiti quando si autorizza l'app. Se l'app è stata registrata usando le API di anteprima, registrare nuovamente perché gli ambiti usati sono ora deprecati.

  3. Selezionare Crea applicazione.

    Verrà visualizzata la pagina delle impostazioni dell'applicazione.

    Screenshot showing Applications settings for your app.

    • Quando Azure DevOps Services presenta la pagina di approvazione dell'autorizzazione all'utente, usa il nome della società, il nome dell'app e le descrizioni. Usa anche gli URL per il sito Web aziendale, il sito Web dell'app e le condizioni per l'utilizzo del servizio e le informative sulla privacy.

      Screenshot showing Visual Studio Codespaces authorization page with your company and app information.

    • Quando Azure DevOps Services richiede l'autorizzazione di un utente e lo concede, il browser dell'utente viene reindirizzato all'URL di callback di autorizzazione con il codice di autorizzazione. L'URL di callback deve essere una connessione sicura (https) per trasferire di nuovo il codice all'app e corrispondere esattamente all'URL registrato nell'app. In caso contrario, viene visualizzata una pagina di errore 400 anziché una pagina che chiede all'utente di concedere l'autorizzazione all'app.

  4. Chiamare l'URL di autorizzazione e passare l'ID app e gli ambiti autorizzati quando si vuole che un utente autorizzi l'app ad accedere all'organizzazione. Chiamare l'URL del token di accesso quando si vuole ottenere un token di accesso per chiamare un'API REST di Azure DevOps Services.

Le impostazioni per ogni app registrata sono disponibili nel profilo https://app.vssps.visualstudio.com/profile/view.

2. Autorizzare l'app

  1. Se l'utente non ha autorizzato l'app ad accedere all'organizzazione, chiamare l'URL di autorizzazione. Viene chiamato di nuovo con un codice di autorizzazione, se l'utente approva l'autorizzazione.
https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type={Assertion}
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}
Parametro Type Note
client_id GUID ID assegnato all'app al momento della registrazione.
response_type string Assertion
state string Può essere qualsiasi valore. In genere un valore stringa generato che correla il callback alla richiesta di autorizzazione associata.
ambito string Ambiti registrati con l'app. Spazio separato. Vedere ambiti disponibili.
redirect_uri URL URL di callback per l'app. Deve corrispondere esattamente all'URL registrato con l'app.
  1. Aggiungere un collegamento o un pulsante al sito che porta l'utente all'endpoint di autorizzazione di Azure DevOps Services:
https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
        &response_type=Assertion
        &state=User1
        &scope=vso.work%20vso.code_write
        &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback

Azure DevOps Services chiede all'utente di autorizzare l'app.

Supponendo che l'utente accetti, Azure DevOps Services reindirizza il browser dell'utente all'URL di callback, incluso un codice di autorizzazione di breve durata e il valore di stato fornito nell'URL di autorizzazione:

https://fabrikam.azurewebsites.net/myapp/oauth-callback
        ?code={authorization code}
        &state=User1

3. Ottenere un token di accesso e aggiornamento per l'utente

Usare il codice di autorizzazione per richiedere un token di accesso (e un token di aggiornamento) per l'utente. Il servizio deve effettuare una richiesta HTTP da servizio a servizio ad Azure DevOps Services.

URL - Autorizzare l'app

POST https://app.vssps.visualstudio.com/oauth2/token

Intestazioni di richiesta HTTP - Autorizzare l'app

Intestazione Valore
Content-Type application/x-www-form-urlencoded 
Content-Type: application/x-www-form-urlencoded

Corpo della richiesta HTTP - Autorizzare l'app

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

Sostituire i valori segnaposto nel corpo della richiesta di esempio precedente:

  • {0}: segreto client codificato con URL acquisito al momento della registrazione dell'app
  • {1}: URL con codifica "codice" fornito tramite il parametro di query all'URL code di callback
  • {2}: URL di callback registrato con l'app

Esempio C# per formare il corpo della richiesta - Autorizzare l'app

public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
   return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
               HttpUtility.UrlEncode(appSecret),
               HttpUtility.UrlEncode(authCode),
               callbackUrl
        );
}

Risposta : autorizzare l'app

{
    "access_token": { access token for the user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { refresh token to use to acquire a new access token }
}

Importante

Mantenere in modo sicuro il refresh_token in modo che l'app non debba richiedere di nuovo all'utente di autorizzare. I token di accesso scadono rapidamente e non devono essere salvati in modo permanente.

4. Usare il token di accesso

Per usare un token di accesso, includerlo come token di connessione nell'intestazione authorization della richiesta HTTP:

Authorization: Bearer {access_token}

Ad esempio, la richiesta HTTP per ottenere compilazioni recenti per un progetto:

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5. Aggiornare un token di accesso scaduto

Se il token di accesso di un utente scade, è possibile usare il token di aggiornamento acquisito nel flusso di autorizzazione per ottenere un nuovo token di accesso. È come il processo originale per lo scambio del codice di autorizzazione per un token di accesso e di aggiornamento.

URL - Token di aggiornamento

POST https://app.vssps.visualstudio.com/oauth2/token

Intestazioni di richiesta HTTP - Token di aggiornamento

Intestazione Valore
Content-Type application/x-www-form-urlencoded
Content-Length Lunghezza della stringa calcolata del corpo della richiesta (vedere l'esempio seguente) 
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

Corpo della richiesta HTTP - Token di aggiornamento

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

Sostituire i valori segnaposto nel corpo della richiesta di esempio precedente:

  • {0}: segreto client codificato con URL acquisito al momento della registrazione dell'app
  • {1}: token di aggiornamento codificato con URL per l'utente
  • {2}: URL di callback registrato con l'app

Risposta - Token di aggiornamento

{
    "access_token": { access token for this user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { new refresh token to use when the token has timed out }
}

Importante

Viene rilasciato un nuovo token di aggiornamento per l'utente. Rendere persistente questo nuovo token e usarlo alla successiva acquisizione di un nuovo token di accesso per l'utente.

Esempi

È possibile trovare un esempio C# che implementa OAuth per chiamare le API REST di Azure DevOps Services nell'esempio gitHub OAuth C#.

Rigenerare il segreto client

Ogni 5 anni, il segreto dell'applicazione scadrà. Si prevede di rigenerare il segreto dell'app per continuare a creare e usare i token di accesso e i token di aggiornamento. A tale scopo, è possibile fare clic sul pulsante "Rigenera segreto", che verrà visualizzata una finestra di dialogo per confermare che si vuole completare questa azione.

Screenshot confirming secret regeneration.

Quando si conferma di voler rigenerare, il segreto dell'app precedente non funzionerà più e anche tutti i token precedenti coniati con questo segreto smetteranno di funzionare. Assicurarsi di impostare correttamente la rotazione del segreto client per ridurre al minimo i tempi di inattività dei clienti.

Domande frequenti

D: È possibile usare OAuth con l'app per telefoni cellulari?

R: No. Azure DevOps Services supporta solo il flusso del server Web, quindi non è possibile implementare OAuth, perché non è possibile archiviare in modo sicuro il segreto dell'app.

D: Quali errori o condizioni speciali è necessario gestire nel codice?

R: Assicurarsi di gestire le condizioni seguenti:

  • Se l'utente nega l'accesso all'app, non viene restituito alcun codice di autorizzazione. Non usare il codice di autorizzazione senza verificare la presenza di rifiuto.
  • Se l'utente revoca l'autorizzazione dell'app, il token di accesso non è più valido. Quando l'app usa il token per accedere ai dati, viene restituito un errore 401. Richiedere nuovamente l'autorizzazione.

D: Si vuole eseguire il debug dell'app Web in locale. È possibile usare localhost per l'URL di callback quando si registra l'app?

R: Sì. Azure DevOps Services ora consente localhost nell'URL di callback. Assicurarsi di usare https://localhost come inizio dell'URL di callback quando si registra l'app.

D: Viene visualizzato un errore HTTP 400 quando si tenta di ottenere un token di accesso. Cosa potrebbe essere sbagliato?

R: Verificare di impostare il tipo di contenuto su application/x-www-form-urlencoded nell'intestazione della richiesta.

D: Viene visualizzato un errore HTTP 401 quando si usa un token di accesso basato su OAuth, ma un pat con lo stesso ambito funziona correttamente. Perché?

R: Verificare che l'accesso alle applicazioni di terze parti tramite OAuth non sia stato disabilitato dall'amministratore dell'organizzazione all'indirizzo https://dev.azure.com/{your-org-name}/_settings/organizationPolicy. In questo scenario, il flusso per autorizzare un'app e generare un token di accesso funziona, ma tutte le API REST restituiscono solo un errore, ad esempio TF400813: The user "<GUID>" is not authorized to access this resource.

D: È possibile usare OAuth con gli endpoint SOAP e le API REST?

R: No. OAuth è supportato solo nelle API REST a questo punto.

D: Come è possibile ottenere i dettagli degli allegati per l'elemento di lavoro usando le API REST di Azure DevOps?

R: Ottenere prima di tutto i dettagli dell'elemento di lavoro con Elementi di lavoro - Ottenere l'API REST dell'elemento di lavoro:

GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}

Per ottenere i dettagli degli allegati, è necessario aggiungere il parametro seguente all'URL:

$expand=all

Con i risultati, si ottiene la proprietà delle relazioni. È possibile trovare l'URL degli allegati e all'interno dell'URL è possibile trovare l'ID. Ad esempio:

$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.0

$workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json

$split = ($workitem.relations.url).Split('/')

$attachmentId = $split[$split.count - 1]

# Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs