Usare Azure DevOps OAuth 2.0 per creare un'app Web

Articolo
10/30/2024

Servizi di Azure DevOps

Importante

Azure DevOps OAuth è previsto per la deprecazione 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 l'app è stata registrata usando le API di anteprima, registrare nuovamente perché gli ambiti usati sono ora deprecati.
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 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

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.

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

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

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. A tale scopo, selezionare "Rigenera segreto", che conferma quindi di voler completare questa azione.

Screenshot che conferma la rigenerazione dei segreti.

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ù. Assicurarsi di impostare correttamente la rotazione del segreto client 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.
Assicurarsi di essere nella pagina del tenant corretta selezionando dal menu a discesa sotto il 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 visualizzato un modale 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?

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'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 - Autorizzare l'app

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 aggiornamento

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 - Autorizzare l'app

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 aggiornamento

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