Usare i token di accesso personale

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018

È possibile usare un token di accesso personale (PAT) come password alternativa per l'autenticazione in Azure DevOps. In questo articolo viene illustrato come creare, usare, modificare e revocare le API per Azure DevOps.

Informazioni sui token di accesso personale

Un token di accesso personale contiene le credenziali di sicurezza per Azure DevOps. Un token di accesso personale identifica l'utente, le organizzazioni accessibili e gli ambiti di accesso. Di conseguenza, sono fondamentali come le password, quindi è consigliabile gestirli allo stesso modo.

Se si usano gli strumenti Microsoft, l'uso dell'account Microsoft (account del servizio gestito) o di Azure Active Directory (Azure AD) rappresenta un approccio accettabile e ben supportato. Tuttavia, se si usano strumenti di terze parti che non supportano account Microsoft o Azure AD, oppure non si vogliono inserire le credenziali primarie nello strumento, usare i token di accesso personale per limitare il rischio.

È possibile creare e gestire i token di accesso personale tramite uno dei modi seguenti:

Per configurare le API per gli strumenti non Microsoft, usare i responsabili delle credenziali Git o crearli manualmente. È consigliabile esaminare le linee guida per l'autenticazione per scegliere il meccanismo di autenticazione corretto. Per i progetti più piccoli che richiedono una soluzione meno solida, i token di accesso personale sono un'alternativa semplice. A meno che gli utenti usino Gestione credenziali, devono immettere le credenziali ogni volta.

Creare un PAT

Nota

Le immagini visualizzate dal portale Web possono essere diverse dalle immagini visualizzate in questo articolo. Queste differenze derivano dagli aggiornamenti apportati alle funzionalità di anteprima di Azure DevOps o abilitate. È stata abilitata la funzionalità Nuova pagina gestione account . La funzionalità di base disponibile per l'utente rimane invariata, a meno che non sia esplicitamente menzionata.

  1. Accedere all'organizzazione (https://dev.azure.com/{yourorganization}).

  2. Nella home page aprire le impostazioni utente e selezionare Token di accesso personale.

    Screenshot che mostra la selezione, i token di accesso personale.

  3. Selezionare + Nuovo token.

    Screenshot che mostra la selezione, Nuovo token.

  4. Assegnare un nome al token, selezionare l'organizzazione in cui si vuole usare il token e quindi impostare il token per scadere automaticamente dopo un numero impostato di giorni.

    Screenshot che mostra la voce delle informazioni sul token di base.

  5. Selezionare gli ambiti per questo token per autorizzare le attività specifiche.

    Ad esempio, per creare un token per consentire a un agente di compilazione e rilascio di eseguire l'autenticazione in Azure DevOps Services, limitare l'ambito del token ai pool di agenti (Gestione lettura&). Per leggere gli eventi del log di controllo e gestire ed eliminare i flussi, selezionare Lettura log di controllo e quindi selezionare Crea.

    Screenshot che mostra gli ambiti selezionati per un pat.

    Nota

    È possibile limitare la creazione di IP con ambito completo. In tal caso, l'amministratore di Azure DevOps in Azure AD ha abilitato un criterio che limita un set personalizzato specifico di ambiti definiti. Per altre informazioni, vedere Gestire le API con criteri/Limitare la creazione di API con ambito completo. Per un pat definito personalizzato, l'ambito necessario per l'accesso all'API governance dei componenti, vso.governance, non è selezionabile nell'interfaccia utente.

  6. Al termine, copiare il token e archiviarlo in una posizione sicura. Per la sicurezza, non verrà nuovamente visualizzata.

    Screenshot che mostra come copiare il token negli Appunti.

Avviso

Trattare e usare un PAT come la password e tenerlo segreto.

  1. Accedere al portale Web (https://{server}:8080/tfs/).

  2. Dalla home page aprire il profilo. Passare ai dettagli di sicurezza.

    Screenshot che mostra la home page, l'apertura del profilo e il pulsante Sicurezza.

  3. Creare un token di accesso personale.

    Screenshot che mostra l'aggiunta di un token di accesso personale.

  4. Assegnare un nome al token. Selezionare una durata per il token.

    Se sono presenti più organizzazioni, è anche possibile selezionare l'organizzazione in cui si vuole usare il token.

    Screenshot che mostra la voce delle informazioni, incluso il nome del token e la durata.

  5. Selezionare gli ambiti per questo token per autorizzare le attività specifiche.

    Ad esempio, per creare un token per abilitare un agente di compilazione e rilascio per l'autenticazione, limitare l'ambito del token a Pool di agenti (lettura, gestione).

  6. Al termine, assicurarsi di copiare il token. Per la sicurezza, non verrà nuovamente visualizzata. Usare questo token come password. Selezionare Chiudi.

    Screenshot che mostra il token creato.

Usare il pat ovunque le credenziali utente siano necessarie per l'autenticazione in Azure DevOps.

Importante

Per le organizzazioni supportate da Azure Active Directory, sono disponibili 90 giorni per accedere con il nuovo PAT, altrimenti è considerato inattivo. Per altre informazioni, vedere Frequenza di accesso utente per l'accesso condizionale.

Notifiche

Gli utenti ricevono due notifiche durante la durata di un pat, una dopo la creazione e l'altra sette giorni prima della scadenza.

Dopo aver creato un pat, viene ricevuta una notifica simile all'esempio seguente. Questa notifica conferma che il pat è stato aggiunto all'organizzazione.

Screenshot che mostra la notifica creata da PAT.

L'immagine seguente mostra un esempio della notifica di sette giorni prima della scadenza del pat.

Screenshot che mostra la notifica pat vicino alla scadenza.

Notifica imprevista

Se si riceve una notifica PAT imprevista, un amministratore o uno strumento potrebbero aver creato un PAT per conto dell'utente. Vedere gli esempi seguenti.

  • Quando ci si connette a un repository Git di Azure DevOps tramite git.exe. crea un token con un nome visualizzato come "git: https://MyOrganization.visualstudio.com/ in MyMachine".
  • Quando un amministratore configura una distribuzione di app Web Servizio app di Azure, crea un token con un nome visualizzato come "Service Hooks: : Servizio app di Azure: : Deploy Web app".
  • Quando un amministratore configura test di carico Web come parte di una pipeline, crea un token con un nome visualizzato come "WebAppLoadTestCDToken".
  • Quando viene configurata un'estensione di messaggistica di integrazione di Microsoft Teams, crea un token con un nome visualizzato come "Integrazione di Microsoft Teams".

Avviso

Se si ritiene che un PAT esista in errore, è consigliabile revocare il PAT. Modificare quindi la password. Come utente di Azure AD, controllare con l'amministratore di verificare se l'organizzazione è stata usata da un'origine o una posizione sconosciuta. Vedere anche le domande frequenti sul controllo accidentale in un repository GitHub pubblico.

Usare un PAT

Il PAT è l'identità e rappresenta l'utente quando lo si usa, proprio come una password.

Git

Le interazioni git richiedono un nome utente, che può essere qualsiasi elemento tranne la stringa vuota. Per usare un pat con l'autenticazione di base HTTP, usare Base64-encode per e $MyPat, incluso nel blocco di codice seguente.

In PowerShell immettere il codice seguente.

$MyPat = 'yourPAT'

$B64Pat = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("`:$MyPat"))

git -c http.extraHeader="Authorization: Basic $B64Pat" clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName


Per proteggere il token, usare i gestori delle credenziali in modo da non dover immettere le credenziali ogni volta. È consigliabile Git Credential Manager. Git per Windows è obbligatorio.

Repository esistenti

Per i repository esistenti, se l'origine è già stata aggiunta usando il nome utente, eseguire prima il comando seguente.

git remote remove origin

In caso contrario, eseguire il comando seguente.

git remote add origin https://<PAT>@<company_machineName>.visualstudio.com:/<path-to-git-repo> path to git repo = <project name>/_git/<repo_name> git push -u origin --all

Usare un token di accesso personale nel codice

È possibile usare un token di accesso personale nel codice, ma si noti l'avviso seguente.

Avviso

Alcune delle API pubbliche sono attualmente non associate a un ambito PAT e pertanto possono essere usate solo con le api con ambito completo. Per questo motivo, la limitazione della creazione di PT con ambito completo potrebbe bloccare alcuni flussi di lavoro. Microsoft sta lavorando per identificare e documentare le API interessate e associarle all'ambito appropriato. Per il momento, questi flussi di lavoro possono essere sbloccati usando l'elenco consenti.

Se si vuole fornire il pat tramite un'intestazione HTTP, convertirlo prima in una stringa Base64. L'esempio seguente illustra come eseguire la conversione in Base64 usando C#.


Authorization: Basic BASE64_USERNAME_PAT_STRING

La stringa risultante può quindi essere fornita come intestazione HTTP nel formato seguente.

L'esempio seguente usa la classe HttpClient in C#.

public static async void GetBuilds()
{
    try
    {
        var personalaccesstoken = "PATFROMWEB";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
                Convert.ToBase64String(
                    System.Text.ASCIIEncoding.ASCII.GetBytes(
                        string.Format("{0}:{1}", "", personalaccesstoken))));

            using (HttpResponseMessage response = client.GetAsync(
                        "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").Result)
            {
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
    }
}

Suggerimento

Quando si usano variabili, aggiungere un $ oggetto all'inizio della stringa, come nell'esempio seguente.

public static async void GetBuilds()
{
   try
  {
      var personalaccesstoken = "PATFROMWEB";

      using (HttpClient client = new HttpClient())
       {
           client.DefaultRequestHeaders.Accept.Add(
              new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

           client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
               Convert.ToBase64String(
                   System.Text.ASCIIEncoding.ASCII.GetBytes(
                       string.Format("{0}:{1}", "", personalaccesstoken))));

          using (HttpResponseMessage response = client.GetAsync(
                       $"https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").Result)
           {
               response.EnsureSuccessStatusCode();
               string responseBody = await response.Content.ReadAsStringAsync();
               Console.WriteLine(responseBody);
           }
       }
   }
   catch (Exception ex)
   {
       Console.WriteLine(ex.ToString());
   }
}

Quando il codice funziona, è consigliabile passare dall'autenticazione di base a OAuth.

Per altre informazioni ed esempi su come usare i PT, vedere gli articoli seguenti:

Se si abilita l'autenticazione di base di IIS per TFS, le interfacce PAW non sono valide. Per altre informazioni, vedere Uso dell'autenticazione di base di IIS con TFS locale.

Modificare un token di accesso personale

È possibile rigenerare o estendere un pat e modificarne l'ambito. Dopo la rigenerazione, il pat precedente non è più autorizzato.

  1. Nella home page aprire le impostazioni utente e quindi selezionare Profilo.

    Screenshot che mostra la sequenza di pulsanti da selezionare per modificare un pat.

  2. In Sicurezza selezionare Token di accesso personali. Selezionare il token da modificare e quindi Modifica.

    Screenshot che mostra il pulsante Modifica evidenziato per modificare pat.

  3. Modificare il nome del token, l'organizzazione a cui si applica, la scadenza del token o l'ambito di accesso associato al token e quindi selezionare Salva.

    Screenshot che mostra il pat salvato.

Revocare un token di accesso personale

È possibile revocare un PAT in qualsiasi momento, per vari motivi.

  1. Nella home page aprire le impostazioni utente e quindi selezionare Profilo.

    Screenshot che mostra la sequenza di pulsanti da selezionare, Team Services, pagina di anteprima e revocare un pat.

  2. In Sicurezza selezionare Token di accesso personali. Selezionare il token per il quale si vuole revocare l'accesso e quindi selezionare Revoca.

    Screenshot che mostra la selezione per revocare un singolo token o tutti i token.

  3. Selezionare Revoca nella finestra di dialogo di conferma.

    Screenshot che mostra la schermata di conferma per revocare pat.

Domande frequenti

D: Cosa accade a un pattema se un account utente è disabilitato?

R: Dopo che un utente è stato rimosso da Azure DevOps, il token di accesso personale viene invalidato entro 1 ora. Se l'organizzazione è connessa ad Azure Active Directory (Azure AD), il token di accesso personale viene invalidato anche in Azure AD, perché appartiene all'utente. È consigliabile che l'utente ruota il proprio pat a un altro account utente o di servizio per mantenere i servizi in esecuzione.

D: Esiste un modo per rinnovare un pat tramite l'API REST?

R: Sì, esiste un modo per rinnovare, gestire e creare le api di gestione del ciclo di vita pat. Per altre informazioni, vedere Gestire le api REST usando l'API REST e le domande frequenti.

D: È possibile usare l'autenticazione di base con tutte le API REST di Azure DevOps?

R: No. È possibile usare l'autenticazione di base con la maggior parte delle API REST di Azure DevOps, ma le organizzazioni e i profili supportano solo OAuth. Per altre informazioni, vedere Gestire le API REST.

D: Cosa accade se si verifica accidentalmente il token di accesso personale in un repository pubblico in GitHub?

R: Azure DevOps esegue l'analisi dei PT verificati nei repository pubblici in GitHub. Quando viene rilevato un token persa, viene immediatamente inviata una notifica di posta elettronica dettagliata al proprietario del token e viene registrato un evento nel log di controllo dell'organizzazione di Azure DevOps. Invitiamo gli utenti interessati a mitigare immediatamente ruotando o revocando la pat persa.

C'è un criterio per la gestione di PAT perse! Per altre informazioni, vedere Revocare automaticamente le API perse.

D: È possibile usare un token di accesso personale come ApiKey per pubblicare pacchetti NuGet in un feed di Azure Artifacts usando la riga di comando dotnet/nuget.exe?

R: No. Azure Artifacts non supporta il passaggio di un token di accesso personale come ApiKey. Quando si usa un ambiente di sviluppo locale, è consigliabile installare il provider di credenziali di Azure Artifacts per l'autenticazione con Azure Artifacts. Per altre informazioni, vedere dotnet e NuGet.exe. Per pubblicare i pacchetti usando Azure Pipelines, usare l'attività Autenticazione NuGet per eseguire l'autenticazione con l'esempio di feed.