Usare entità servizio e identità gestite in Azure DevOps

Servizi di Azure DevOps

Le entità servizio e le identità gestite forniscono l'autenticazione sicura e scalabile per i flussi di lavoro di automazione di Azure DevOps. Questi tipi di identità Di Microsoft Entra offrono una sicurezza avanzata rispetto ai token di accesso personali tradizionali (PAT) con gestione automatica delle credenziali, durata dei token più breve e controlli di accesso di livello aziendale.

Vantaggi delle entità del servizio e delle identità gestite

Sicurezza avanzata

• Token di breve durata: i token di Microsoft Entra scadono ogni ora, riducendo il rischio di esposizione rispetto alle reti AP (che possono durare fino a un anno)
• Rotazione automatica: le identità gestite gestiscono automaticamente la rotazione delle credenziali
• Nessun segreto archiviato: elimina la necessità di archiviare le credenziali di lunga durata nel codice o nella configurazione

Eccellenza operativa

• Gestione centralizzata: controllare l'accesso tramite i criteri microsoft Entra ID e le autorizzazioni di Azure DevOps
• Funzionalità di controllo: tenere traccia dei modelli di autenticazione e accesso tramite la registrazione completa
• Scalabilità efficiente: supportare scenari di automazione aziendale senza dipendenze utente individuali

Autenticazione moderna

• Basato su standard: usa protocolli OAuth 2.0 e OpenID Connect
• Supporto per l'autenticazione a più fattori: eredita i criteri di sicurezza dell'organizzazione
• Accesso condizionale: applicare criteri di sicurezza avanzati in base al contesto

Informazioni sui principali del servizio e sulle identità gestite

Principali del servizio

Le entità servizio sono oggetti Microsoft Entra che rappresentano le applicazioni all'interno di un tenant. Definiscono le operazioni che un'applicazione può eseguire, quali risorse può accedere e chi può usarla. Le entità servizio vengono create automaticamente quando si registra un'applicazione in Microsoft Entra ID e si fornisce alle applicazioni un modo sicuro per autenticare e accedere alle risorse.

Caratteristiche chiave:

• Creato tramite registrazione dell'applicazione in Microsoft Entra ID
• Supportare scenari multi-tenant
• Richiedere la gestione esplicita delle credenziali (certificati o segreti client)
• Ideale per le applicazioni che devono eseguire l'autenticazione in ambienti diversi

Identità gestite

Le identità gestite sono un tipo speciale di entità servizio gestita automaticamente da Azure. Eliminano la necessità per gli sviluppatori di gestire le credenziali fornendo un'identità gestita automaticamente nell'ID Microsoft Entra per le risorse di Azure.

Tipi di identità gestite:

Identità gestita assegnata dal sistema

• Creazione automatica e associazione a una risorsa di Azure specifica
• Ciclo di vita gestito da Azure (eliminato quando la risorsa viene eliminata)
• Relazione uno-a-uno con la risorsa di Azure
• Ideale per le applicazioni distribuite in una singola risorsa di Azure

Identità gestita assegnata dall'utente

• Creato come risorsa di Azure autonoma
• Può essere assegnato a più risorse di Azure
• Ciclo di vita gestito indipendentemente da risorse associate
• Ideale per le applicazioni eseguite su più risorse o che richiedono un'identità condivisa

Guida all'implementazione

Seguire questa procedura per implementare entità servizio o identità gestite per l'autenticazione di Azure DevOps. Per esempi di codice completi, vedere le applicazioni di esempio.

Passaggio 1: Creare l'identità

Scegliere il tipo di identità appropriato in base allo scenario di distribuzione:

Opzione A: Creare un account di servizio (registrazione dell'applicazione)

I principali servizio funzionano bene per le pipeline CI/CD, gli scenari multicloud e le applicazioni che richiedono opzioni di distribuzione flessibili.

1. Registrare un'applicazione nell'interfaccia di amministrazione di Microsoft Entra
2. Passare a Registrazioni app>Nuova registrazione.
3. Configurare l'applicazione:
   • Nome: nome descrittivo per l'applicazione
   • Tipi di account: selezionare il supporto appropriato per l'inquilino
   • URI di reindirizzamento: lasciare vuoto per gli scenari da servizio a servizio
4. Creare le credenziali di autenticazione:
   • Consigliato: caricare un certificato per una sicurezza avanzata
   • Alternativa: creare un segreto del client (richiede una rotazione periodica)

Per informazioni più dettagliate, vedi gli articoli seguenti:

• Oggetti applicazione ed entità servizio in Microsoft Entra ID
• Come creare un'entità servizio

Opzione B: Creare un'identità gestita

Le identità gestite offrono l'esperienza di autenticazione più semplice per le applicazioni ospitate in Azure.

Per l'identità gestita assegnata dal sistema:

1. Vai alla risorsa di Azure (Servizio App, Funzioni App e così via).
2. Passare a Identità>Assegnato dal sistema.
3. Cambia stato su Attivo.
4. Fare clic su Salva per salvare la configurazione.

Per l'identità gestita assegnata dall'utente:

1. Creare l'identità gestita nel portale di Azure.
2. Passare a Crea una risorsa>Identità gestita.
3. Configurare le impostazioni di base e creare la risorsa.
4. Assegnare alle risorse in base alle esigenze.

Per altre informazioni, vedere gli articoli seguenti:

• Panoramica delle identità gestite
• Come gestire le identità gestite assegnate dall'utente

Passaggio 2: Aggiungere l'identità ad Azure DevOps

Dopo aver creato l'identità in Microsoft Entra ID, aggiungerla all'organizzazione di Azure DevOps per concedere l'accesso alle risorse.

Prerequisiti:

• Ruolo Amministratore Raccolta Progetti (PCA), OR
• Ruolo Amministratore progetto o Amministratore team quando il criterio di invito consente agli amministratori del team di aggiungere utenti

Aggiungere tramite il portale di Azure DevOps:

1. Passare a Impostazioni> organizzazioneUtenti.
2. Seleziona Aggiungi utente.
3. Immettere il nome visualizzato dell'entità di servizio o dell'identità gestita.
4. Selezionare il livello di accesso appropriato e l'accesso al progetto.
5. Inviare l'invito.

Aggiungere a livello di codice: Usare l'API REST ServicePrincipalEntitlements per automatizzare il processo.

Passaggio 3: Configurare le autorizzazioni

Configurare autorizzazioni granulari per il principal del servizio o l'identità gestita all'interno di Azure DevOps. A differenza di altri servizi di Azure, Azure DevOps usa il proprio modello di autorizzazione anziché le autorizzazioni dell'applicazione Microsoft Entra.

Opzioni di autorizzazione:

• Assegnazione diretta: assegnare le autorizzazioni direttamente all'identità
• Appartenenza a gruppi: aggiungere a gruppi di sicurezza di Azure DevOps o Microsoft Entra
• Livelli di accesso: assegnare il livello di licenza appropriato (Basic, Basic + Test Plans, sottoscrittore di Visual Studio)

Procedure consigliate:

• Applica privilegi minimi: concedere solo le autorizzazioni minime necessarie
• Usare i gruppi: gestire le autorizzazioni tramite gruppi per semplificare la manutenzione
• Verifiche regolari: controlla periodicamente le autorizzazioni

Opzioni di gestione delle autorizzazioni:

• Portale di Azure DevOps: Autorizzazioni per le impostazioni > dell'organizzazione
• API REST: usare le API Graph dei Principali di Servizio per la gestione programmatica

Passaggio 4: Ottenere i token ID di Microsoft Entra

Ottenere i token di accesso per autenticare le applicazioni con le API e i servizi di Azure DevOps.

Principali del servizio

Uso del flusso di credenziali client:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client-id}
&scope=https://app.vssps.visualstudio.com/.default
&client_secret={client-secret}
&grant_type=client_credentials

Uso dell'autenticazione del certificato (scelta consigliata):

using Microsoft.Identity.Client;

var app = ConfidentialClientApplicationBuilder
    .Create(clientId)
    .WithCertificate(certificate)
    .WithAuthority(new Uri($"https://login.microsoftonline.com/{tenantId}"))
    .Build();

var result = await app
    .AcquireTokenForClient(new[] { "https://app.vssps.visualstudio.com/.default" })
    .ExecuteAsync();

string accessToken = result.AccessToken;

Per le identità gestite

Dalle risorse di Azure:

using Azure.Identity;
using Azure.Core;

var credential = new ManagedIdentityCredential();
var tokenRequest = new TokenRequestContext(new[] { "https://app.vssps.visualstudio.com/.default" });
var token = await credential.GetTokenAsync(tokenRequest);

string accessToken = token.Token;

Utilizzo del servizio metadati dell'istanza di Azure (IMDS):

GET http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://app.vssps.visualstudio.com/
Metadata: true

Interfaccia della riga di comando di Azure per operazioni ad hoc

Per operazioni o test monouso, usare l'interfaccia della riga di comando di Azure:

# For service principal
az login --service-principal --username {client-id} --password {client-secret} --tenant {tenant-id}
az account get-access-token --resource https://app.vssps.visualstudio.com/

# For managed identity (from Azure resource)
az login --identity
az account get-access-token --resource https://app.vssps.visualstudio.com/

Per indicazioni dettagliate, vedere Acquisizione di token Microsoft Entra.

Passaggio 5: Usare i token con Azure DevOps

Usare i token acquisiti per autenticare le chiamate API REST e altre operazioni di Azure DevOps.

Esecuzione di chiamate API autenticate:

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync(
    "https://dev.azure.com/{organization}/_apis/projects?api-version=7.1");

Esempi video:

Scenari di integrazione comuni:

• Feed NuGet: connettersi con NuGet.exe o dotnet CLI
• Pubblicazione nel Marketplace: pubblicare le estensioni tramite la riga di comando
• Azure Pipelines: creare connessioni al servizio supportate dalle identità gestite
• Operazioni Git: Clonare i repository con Git Credential Manager

Per esempi di codice completi, vedere le applicazioni di esempio.

Considerazioni sulla gestione

Le entità servizio e le identità gestite hanno caratteristiche di gestione diverse rispetto agli account utente:

Licenze:

• Ogni identità richiede una licenza in ogni organizzazione a cui partecipa
• La fatturazione in più organizzazioni non si applica alle entità servizio
• Le regole di licenza basate sui gruppi non si applicano automaticamente: assegnare direttamente le licenze

Gestione delle identità:

• Nessun indirizzo di posta elettronica: non può essere invitato tramite posta elettronica
• Non è possibile modificare il nome visualizzato o l'avatar in Azure DevOps
• I nomi visualizzati vengono ereditati da Microsoft Entra ID

Appartenenza a gruppi:

• Può essere aggiunto ai gruppi di Microsoft Entra e ai gruppi di Azure DevOps
• La limitazione tecnica impedisce di visualizzarle negli elenchi dei membri del gruppo di Microsoft Entra (solo limitazioni dell'interfaccia utente)
• Ereditano comunque le autorizzazioni dai gruppi di Microsoft Entra a cui appartengono

Materializzazione:

• Deve essere aggiunto esplicitamente alle organizzazioni (nessuna creazione automatica come per gli utenti)
• Obbligatorio perché i principali del servizio non possono effettuare l'accesso in modo interattivo

Differenze principali tra gli account utente

Le entità servizio e le identità gestite presentano limitazioni specifiche rispetto agli utenti normali:

Funzionalità:

• ✅ Generare token Microsoft Entra per l'accesso all'API
• ✅ Accedere alle risorse di Azure DevOps con autorizzazioni appropriate
• ✅ Partecipare a gruppi di sicurezza e team di sicurezza
• ❌ Creare token di accesso personale (PAT) o chiavi SSH
• ❌ Accedere in modo interattivo o accedere all'interfaccia utente Web
• ❌ Creare o possedere organizzazioni
• ❌Supportare i flussi OAuth di Azure DevOps

Fatturazione:

• Conteggiato come licenza separata in ogni organizzazione (nessun sconto per più organizzazioni)
• Deve assegnare direttamente il livello di accesso (le regole di gruppo non vengono applicate automaticamente)

Domande frequenti

Q: Perché è consigliabile usare un'entità servizio o un'identità gestita anziché un token di accesso personale?

R: Le entità servizio e le identità gestite offrono vantaggi significativi per la sicurezza rispetto ai token di accesso personali:

Vantaggi a livello di sicurezza:

• Durata più breve: i token Di Microsoft Entra scadono ogni ora rispetto ai token PAT che possono durare fino a un anno
• Rotazione automatica: le identità gestite ruotano automaticamente le credenziali
• Nessun segreto condiviso: elimina il rischio di archiviare o esporre accidentalmente i token di lunga durata
• Controllo centralizzato: gestito tramite Microsoft Entra ID con criteri di sicurezza aziendali

Vantaggi operativi:

• Audit trail: registrazione completa dei modelli di autenticazione e di accesso
• Accesso condizionale: applicare criteri in base alla posizione, al dispositivo e ai fattori di rischio
• Nessun account di servizio: elimina la dipendenza da singoli account utente per l'automazione

Per esempi di migrazione, vedere Sostituire i token PAT con i token Microsoft Entra.

D: Quali sono i limiti di frequenza per le entità servizio e le identità gestite?

R: Le entità servizio e le identità gestite hanno gli stessi limiti di frequenza degli utenti.

D: L'uso di questa funzionalità costa più?

R: I principali di servizio e le identità gestite sono valutati come gli utenti in base al livello di accesso. Differenze principali:

• Nessun sconto sulla fatturazione multi-organizzazioni: ogni identità viene conteggiata come una licenza separata in ogni organizzazione
• Assegnazione delle licenze: è necessario assegnare direttamente i livelli di accesso (le regole di gruppo non vengono applicate automaticamente)
• Stessi piani tariffari: Basic, Basic + Test Plans, si applicano le tariffe per i sottoscrittori di Visual Studio

D: È possibile aggiungere un'identità gestita da un tenant diverso all'organizzazione?

R: È possibile aggiungere direttamente le identità solo dal tenant connesso dell'organizzazione. Per gli scenari tra tenant, usare questa soluzione alternativa:

Configurazione dell'identità gestita multi-tenant:

1. Creare un'identità gestita assegnata dall'utente nel tenant delle risorse
2. Assegnare alla risorsa di Azure (macchina virtuale, app per le funzioni e così via)
3. Creare Key Vault** e generare un certificato (formato non PEM)
4. Concedere l'accesso all'identità gestita a Key Vault con autorizzazioni Get/List secret
5. Scaricare il certificato in formato CER (solo chiave pubblica)
6. Registrare l'applicazione nel tenant di destinazione
7. Caricare il certificato nella registrazione dell'applicazione
8. Aggiungere un service principal all'organizzazione di Azure DevOps
9. Configurare l'autenticazione usando il certificato di Key Vault

// Example: Acquire token using managed identity certificate
public static async Task<string> GetSecret(string keyVaultName, string secretName)
{
    var keyVaultUri = new Uri($"https://{keyVaultName}.vault.azure.net");
    var client = new SecretClient(keyVaultUri, new ManagedIdentityCredential());
    var keyVaultSecret = await client.GetSecretAsync(secretName);
    return keyVaultSecret.Value.Value;
}

private static async Task<AuthenticationResult> GetAppRegistrationAADAccessToken(
    string applicationClientID, string appTenantId)
{
    byte[] privateKeyBytes = Convert.FromBase64String(await GetSecret(keyVaultName, secretName));
    var certificate = new X509Certificate2(privateKeyBytes, (string)null, X509KeyStorageFlags.MachineKeySet);

    var app = ConfidentialClientApplicationBuilder.Create(applicationClientID)
        .WithCertificate(certificate)
        .WithAuthority(new Uri($"https://login.microsoftonline.com/{appTenantId}"))
        .Build();

    var result = await app.AcquireTokenForClient(
        new[] { "499b84ac-1321-427f-aa17-267ca6975798/.default" })
        .ExecuteAsync();

    return result;
}

Errori comuni e soluzioni

Il repository Git con nome o identificatore non esiste o non si dispone delle autorizzazioni

Soluzione: Verificare che il principale del servizio disponga almeno di una licenza Basic. Le licenze degli stakeholder non forniscono accesso al repository.

Impossibile creare un service principal con ID oggetto

Soluzione: Verificare di utilizzare l'ID dell'oggetto del servizio principale nelle Applicazioni aziendali, e non l'ID dell'oggetto della registrazione dell'applicazione.

Trovare l'ID corretto:

1. Vai al centro di amministrazione di Microsoft Entra > Applicazioni aziendali
2. Cercare il nome dell'applicazione
3. Usa l'ID dell'oggetto dalla pagina dell'applicazione aziendale

Accesso negato: richiede le autorizzazioni per l'aggiunta di utenti

Possibili cause e soluzioni:

• Ruolo insufficiente: deve essere Amministratore della raccolta di progetti o Amministratore del progetto/squadra con le autorizzazioni di invito abilitate.
• Restrizione dei criteri: controllare se è abilitato il criterio "Consenti agli amministratori del team e del progetto di invitare nuovi utenti"
• Assegnazione di licenza: gli amministratori del progetto non possono assegnare licenze durante l'invito: contattare PCA per le modifiche alle licenze

L'API Elenco grafici di Azure DevOps restituisce un elenco vuoto

Soluzione: Usare continuationToken per scorrere tutte le pagine. Le risorse rappresentative di servizio potrebbero essere visualizzate nelle pagine successive a causa del comportamento di paginazione dell'API.

TF401444: errore di accesso richiesto

Soluzione: Assicurarsi che il principale del servizio venga aggiunto correttamente all'organizzazione con le autorizzazioni richieste. Questo errore indica che l'identità non è riconosciuta nell'organizzazione.

Contenuti correlati

• Esempi di codice ed applicazioni di esempio
• Riferimento all'API sui diritti del principale del servizio
• Informazioni di riferimento sulle API Graph dell'entità servizio
• Opzioni di autenticazione di Microsoft Entra
• Linee guida per l'autenticazione per Azure DevOps