Usare Azure DevOps OAuth 2.0 per creare un'app Web

Articolo
10/30/2024

Servizi di Azure DevOps

Importante

Azure DevOps OAuth sarà deprecato nel 2026. Queste informazioni sono solo per le app OAuth di Azure DevOps esistenti. Per creare nuove app, usare Microsoft Entra ID OAuth per l'integrazione con Azure DevOps. A partire da marzo 2025, verrà interrotta l'accettazione di nuove app OAuth di Azure DevOps. Per altre informazioni, vedere il post di blog.

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

Importante

La creazione di una nuova app verrà bloccata a partire da febbraio 2025.

Passare a https://app.vsaex.visualstudio.com/app/register per registrare l'app.
Selezionare gli ambiti necessari per l'applicazione e quindi usare gli stessi ambiti quando si autorizza l'app. Se hai registrato la tua app usando le API di anteprima, devi registrarla nuovamente perché gli ambiti che hai usato non sono più supportati.
Selezionare Crea applicazione.

Verrà visualizzata la pagina delle impostazioni dell'applicazione.
- 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.
- 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.
Chiamare l'URL di autorizzazione e passare l'ID app e gli ambiti autorizzati per consentire a un utente di autorizzare la tua app ad accedere alla propria 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

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	Tipo	Note
ID cliente	GUID	ID assegnato all'app al momento della registrazione.
tipo_di_risposta	string	`Assertion`
stato	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 la tua applicazione. Deve corrispondere esattamente all'URL registrato con l'app.

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=00001111-aaaa-2222-bbbb-3333cccc4444
        &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 - Autorizza l'applicazione

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}: "codice" codificato nell'URL fornito tramite il parametro di query code all'URL di callback
{2}: URL di callback registrata 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 }
}

Nota

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 bearer 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
Tipo di contenuto	`application/x-www-form-urlencoded`
Lunghezza del contenuto	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 rinnovo

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 per l'utente codificato in URL
{2}: URL di callback registrata 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 }
}

Nota

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 cinque anni, il segreto dell'applicazione scade. Rigenerare il segreto dell'app per continuare a creare e usare token di accesso e token di aggiornamento. Per farlo, selezionare "Rigenera segreto", dopodiché viene confermata l'intenzione di completare questa azione.

Screenshot che conferma la rigenerazione di un segreto.

Quando si conferma di voler rigenerare, il segreto dell'app precedente non funziona più e anche tutti i token precedenti coniati con questo segreto non funzionano più. Assicurati di gestire bene la rotazione del segreto del cliente per ridurre al minimo i tempi di inattività dei clienti.

Eliminare l'app

Se l'app non è più necessaria, eliminarla dal profilo.

Passare al profilo all'indirizzo: https://app.vssps.visualstudio.com/profile/view.
Assicurati di essere nella pagina del locatario corretta selezionando dal menu a discesa situato sotto il tuo nome nella barra laterale.
Trovare l'app sotto l'intestazione Applicazioni e servizi sulla barra laterale sinistra.
selezionare "Elimina" nella pagina di registrazione dell'applicazione. Viene visualizzata una finestra di dialogo per confermare l'eliminazione.
Dopo aver eliminato la registrazione dell'app, l'app si interrompe e smettiamo di coniare nuovi token o di accettare token coniati per questa app.

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?

Verifica che il tipo di contenuto sia impostato 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'amministratore dell'organizzazione non abbia disabilitato l'accesso alle applicazioni di terze parti tramite OAuth 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.

Condividi tramite

Usare Azure DevOps OAuth 2.0 per creare un'app Web

Introduzione ad Azure DevOps OAuth

1. Registrare l'app

2. Autorizzare l'app

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

URL - Autorizzare l'app

Intestazioni di richiesta HTTP - Autorizza l'applicazione

Corpo della richiesta HTTP - Autorizzare l'app

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

Risposta : autorizzare l'app

4. Usare il token di accesso

5. Aggiornare un token di accesso scaduto

URL - Token di aggiornamento

Intestazioni di richiesta HTTP - Token di aggiornamento

Corpo della richiesta HTTP - Token di rinnovo

Risposta - Token di aggiornamento

Esempi

Rigenerare il segreto client

Eliminare l'app

Domande frequenti

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

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

D: Si vuole eseguire il debug dell'app Web in locale. È possibile usare localhost per l'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?

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é?

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Usare Azure DevOps OAuth 2.0 per creare un'app Web

Introduzione ad Azure DevOps OAuth

1. Registrare l'app

2. Autorizzare l'app

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

URL - Autorizzare l'app

Intestazioni di richiesta HTTP - Autorizza l'applicazione

Corpo della richiesta HTTP - Autorizzare l'app

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

Risposta : autorizzare l'app

4. Usare il token di accesso

5. Aggiornare un token di accesso scaduto

URL - Token di aggiornamento

Intestazioni di richiesta HTTP - Token di aggiornamento

Corpo della richiesta HTTP - Token di rinnovo

Risposta - Token di aggiornamento

Esempi

Rigenerare il segreto client

Eliminare l'app

Domande frequenti

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

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

D: Si vuole eseguire il debug dell'app Web in locale. È possibile usare localhost per l'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?

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é?

Articoli correlati

Commenti e suggerimenti

Risorse aggiuntive