Usare entità servizio e identità gestite in Azure DevOps

Servizi di Azure DevOps

L'aggiunta di entità servizio e identità gestite di Microsoft Entra alle organizzazioni di Azure DevOps Services consentirà loro di accedere alle risorse dell'organizzazione. Per molti team, questa funzionalità può essere un'alternativa valida e preferita ai token di accesso personali (PAT) quando si autenticano le applicazioni che alimentano i flussi di lavoro di automazione nell'azienda.

Informazioni sulle entità servizio e sulle identità gestite

Le entità servizio sono oggetti di sicurezza all'interno di un'applicazione Microsoft Entra che definiscono le operazioni che un'applicazione può eseguire in un determinato tenant. Vengono configurati nel portale di Azure durante il processo di registrazione dell'applicazione e configurati per accedere alle risorse di Azure, ad esempio Azure DevOps. Aggiungendo le entità servizio all'organizzazione e configurando le autorizzazioni, è possibile determinare se un'entità servizio è autorizzata ad accedere alle risorse dell'organizzazione e a quali.

Le identità gestite sono un'altra funzionalità di Microsoft Entra che agisce in modo analogo alle entità servizio di un'applicazione. Questi oggetti forniscono identità per le risorse di Azure e consentono un modo semplice per i servizi che supportano l'autenticazione di Microsoft Entra per condividere le credenziali. Si tratta di un'opzione interessante perché Microsoft Entra ID si occupa della gestione e della rotazione delle credenziali. Anche se la configurazione per un'identità gestita potrebbe avere un aspetto diverso nella portale di Azure, Azure DevOps considera entrambi gli oggetti di sicurezza uguali a una nuova identità in un'organizzazione con autorizzazioni definite. Nel resto di questo articolo si fa riferimento alle identità gestite e alle entità servizio in modo intercambiabile come entità servizio, a meno che non sia specificato.

Usare la procedura seguente per autenticare queste identità in Azure DevOps per consentire loro di eseguire azioni per conto proprio.

Configurare le identità gestite e le entità servizio

L'implementazione può variare, ma a livello generale, i passaggi seguenti consentono di iniziare a usare le entità servizio nel flusso di lavoro. È consigliabile esaminare una delle nostre app di esempio per seguirne lo sviluppo.

1. Creare una nuova identità gestita o un'entità servizio dell'applicazione

Creare un'entità servizio applicazione o un'identità gestita nella portale di Azure.

Creare un'entità servizio dell'applicazione

Quando si crea una nuova registrazione dell'applicazione, viene creato un oggetto applicazione in Microsoft Entra ID. L'entità servizio dell'applicazione è una rappresentazione di questo oggetto applicazione per un determinato tenant. Quando si registra un'applicazione come applicazione multi-tenant, è presente un oggetto entità servizio univoco che rappresenta l'oggetto applicazione per ogni tenant a cui viene aggiunta l'applicazione.

Altre informazioni:

• Oggetti applicazione ed entità servizio in Microsoft Entra ID
• Protezione delle entità servizio
• Usare il portale per creare un'applicazione e un'entità servizio Microsoft Entra in grado di accedere alle risorse

Creare un'identità gestita

La creazione di identità gestite nel portale di Azure differisce in modo significativo rispetto alla configurazione di applicazioni con entità servizio. Prima di iniziare il processo di creazione, è necessario considerare il tipo di identità gestita da creare:

• Identità gestita assegnata dal sistema: alcuni servizi di Azure consentono di abilitare un'identità gestita direttamente in un'istanza del servizio. Quando si abilita un'identità gestita assegnata dal sistema, viene creata un'identità in Microsoft Entra ID. L'identità viene associata al ciclo di vita di quell'istanza del servizio. Quando la risorsa viene eliminata, Azure elimina automaticamente anche l'identità. Per impostazione predefinita, solo questa specifica risorsa di Azure può usare questa identità per richiedere token ad Microsoft Entra ID.
• Identità gestita assegnata dall'utente È anche possibile creare un'identità gestita come risorsa di Azure autonoma creando un'identità gestita assegnata dall'utente e assegnandola a una o più istanze di un servizio di Azure. Le identità gestite assegnate dall'utente vengono gestite separatamente rispetto alle risorse che le usano.

Per altre informazioni, vedere gli articoli e i video seguenti:

• Cosa sono le identità gestite per le risorse di Azure?
• Gestire le identità gestite assegnate dall'utente
• Configurare le identità gestite per le risorse di Azure in una macchina virtuale tramite il portale di Azure

2. Aggiungere un'entità servizio a un'organizzazione di Azure DevOps

Dopo aver configurato le entità servizio nell'interfaccia di amministrazione di Microsoft Entra, è necessario eseguire le stesse operazioni in Azure DevOps aggiungendo le entità servizio all'organizzazione. È possibile aggiungerli tramite la pagina Utenti o con le API ServicePrincipalEntitlements. Poiché non possono accedere in modo interattivo, un account utente che può aggiungere utenti a un'organizzazione, a un progetto o a un team deve aggiungerli. Tali utenti includono amministratori della raccolta di progetti (PCA) o amministratori del progetto e amministratori del team quando è abilitato il criterio "Consenti agli amministratori del team e del progetto di invitare nuovi utenti".

Se si è un PCA, è anche possibile concedere a un'entità servizio l'accesso a progetti specifici e assegnare una licenza. Se non sei un PCA, devi contattare il PCA per aggiornare eventuali appartenenze al progetto o livelli di accesso alle licenze.

3. Impostazione delle autorizzazioni per un'entità servizio

Dopo aver aggiunto le entità servizio all'organizzazione, è possibile gestirle in modo analogo agli account utente standard. È possibile assegnare le autorizzazioni direttamente in un'entità servizio, aggiungerla a gruppi di sicurezza e team, assegnarla a qualsiasi livello di accesso e rimuoverla dall'organizzazione. È anche possibile usare Service Principal Graph APIs per eseguire operazioni CRUD sulle entità servizio.

L'impostazione di queste autorizzazioni potrebbe essere diversa da quella usata per configurare le autorizzazioni dell'applicazione in un'applicazione Microsoft Entra per altre risorse di Azure. Azure DevOps non si basa sulla configurazione delle "autorizzazioni dell'applicazione" disponibile per le registrazioni dell'applicazione tramite il portale di Azure. Queste autorizzazioni dell'applicazione si applicano a un'entità servizio attraverso tutte le organizzazioni legate a un tenant e non dispongono di informazioni sulle autorizzazioni dell'organizzazione, del progetto o degli oggetti disponibili in Azure DevOps. Per offrire autorizzazioni più granulari ai principali di servizio, ci affidiamo al nostro modello di autorizzazioni anziché a quello di Entra ID.

4. Gestione di un'entità servizio

La gestione delle entità servizio è diversa dagli account utente nei modi principali seguenti:

• Le entità servizio non hanno messaggi di posta elettronica e, di conseguenza, non possono essere invitati a un'organizzazione tramite posta elettronica.
• Le regole di gruppo per le licenze attualmente non si applicano alle entità servizio. Se si vuole assegnare un livello di accesso a un'entità servizio, è consigliabile farlo direttamente.
• Le entità servizio possono essere aggiunte ai gruppi di Microsoft Entra (nel portale di Azure). Esiste attualmente una limitazione tecnica che impedisce di visualizzarli in un elenco dei membri del gruppo Microsoft Entra. Questa limitazione non è vera per i gruppi di Azure DevOps. Detto questo, un'entità servizio eredita comunque tutte le autorizzazioni di gruppo impostate su un gruppo Microsoft Entra a cui appartengono.
• Gli utenti di un gruppo Microsoft Entra non fanno parte di un'organizzazione di Azure DevOps immediatamente perché un amministratore crea un gruppo e aggiunge un gruppo Microsoft Entra. È disponibile un processo denominato "materializzazione" che avviene una volta che un utente di un gruppo di Microsoft Entra accede all'organizzazione per la prima volta. Un utente che accede a un'organizzazione consente di determinare gli utenti a cui concedere una licenza. Poiché l'accesso non è possibile per le entità servizio, un amministratore deve aggiungerlo in modo esplicito a un'organizzazione come descritto in precedenza.
• Non è possibile modificare il nome visualizzato o l'avatar di un'entità servizio in Azure DevOps.
• Le entità servizio ottengono licenze in ogni organizzazione a cui vengono aggiunte, anche se è selezionata di fatturazione multi-organizzazione.

5. Ottenere un token Microsoft Entra ID

(a) Acquisire un token ID Microsoft Entra in modo programmatico

L'acquisizione di un token di accesso per un'identità gestita può essere eseguita seguendo la documentazione di Microsoft Entra ID. Vedere gli esempi per entità servizio e identità gestite.

Il token di accesso restituito è un token Web JSON (JWT) con i ruoli definiti, che può essere usato per accedere alle risorse dell'organizzazione usando il token come Bearer.

(b) Acquisire un token ID Microsoft Entra con Azure CLI

Per le operazioni ad hoc, potrebbe essere più semplice acquisire un token ID Microsoft Entra una tantum tramite Azure CLI. Questo approccio è preferibile per le operazioni che non richiedono una rotazione regolare di un token permanente, ad esempio chiamate API o operazioni di clonazione Git.

Prerequisiti

• ID tenant di Azure e ID sottoscrizione: assicurarsi che la sottoscrizione sia associata al tenant connesso all'organizzazione Azure DevOps a cui si sta provando ad accedere. Se non conosci il tenant o l'ID sottoscrizione, è possibile trovarlo nel portale di Azure .
• ID client dell'app di Azure e segreto dell'applicazione cliente
• CLI di Azure

Queste istruzioni sono disponibili nella documentazione di Databricks e altri dettagli sono disponibili in pagina.

1. Accedi alla CLI di Azure come principal del servizio utilizzando il comando az devops login.
2. Seguire le istruzioni visualizzate e completare l'accesso.

# To authenticate a service principal with a password or cert:
az login --service-principal -u <app-id> -p <password-or-cert> --tenant <tenant>

# To authenticate a managed identity:
az login --identity

3. Impostare la sottoscrizione corretta per il principale del servizio connesso immettendo il comando:

az account set -s <subscription-id>

4. Generare un token di accesso Microsoft Entra ID con az account get-access-token l'ID risorsa Azure DevOps: 499b84ac-1321-427f-aa17-267ca6975798.

$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv

5. È ora possibile usare az cli i comandi per ogni consueto. Proviamo a chiamare un'API di Azure DevOps passandovi nelle intestazioni un token Bearer:

$apiVersion = "7.1-preview.1"
$uri = "https://dev.azure.com/${yourOrgname}/_apis/projects?api-version=${apiVersion}"
$headers = @{
    Accept = "application/json"
    Authorization = "Bearer $accessToken"
}
Invoke-RestMethod -Uri $uri -Headers $headers -Method Get | Select-Object -ExpandProperty value ` | Select-Object id, name

6. Usare il token ID Microsoft Entra per eseguire l'autenticazione alle risorse di Azure DevOps

Nell'esempio di video seguente si passa dall'autenticazione con un pat all'uso di un token da un'entità servizio. Per iniziare si usa un segreto client per l'autenticazione, quindi si passa all'uso di un certificato client.

Un altro esempio illustra come connettersi ad Azure DevOps usando un'identità gestita assegnata dall'utente all'interno di una funzione di Azure.

Seguire questi esempi trovando il codice dell'app nella raccolta di app di esempio.

In queste risorse sono disponibili alcuni scenari comuni per l'autenticazione con le entità servizio oltre all'esecuzione di chiamate api REST di Azure DevOps:

• Connetti la tua entità servizio a un feed NuGet con Nuget.exe o dotnet.
• Pubblicare estensioni in Visual Studio Marketplace tramite della riga di comando con l'entità servizio.
• Creare connessioni al servizio senza segreto in Azure Pipelines supportate da entità servizio o identità gestite.
• Clonare repository usando un'entità servizio con Git Credential Manager

In che modo le entità servizio differiscono dagli utenti?

• Non è possibile modificare il nome visualizzato o l'avatar di un'entità servizio in Azure DevOps.
• Un'entità servizio viene conteggiato come licenza per ogni organizzazione a cui viene aggiunto, anche se è selezionata la fatturazione a più organizzazioni.
• Le entità servizio non possono essere proprietari dell'organizzazione o creare organizzazioni.
• Le entità servizio non possono creare token, ad esempio token di accesso personale (PAT) o chiavi SSH. Possono generare token ID Microsoft Entra e questi token possono essere usati per chiamare le API REST di Azure DevOps.
• Azure DevOps OAuth non è supportato per le entità servizio.

Domande frequenti

Generali

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

R: Molti clienti cercano un'entità servizio o un'identità gestita per sostituire un token di accesso personale esistente. Tali TOKEN appartengono spesso a un account del servizio (account del team condiviso) che li usa per autenticare un'applicazione con le risorse di Azure DevOps. Le PTE devono essere ruotate laboriosamente ogni tanto (almeno 180 giorni). I PAT archiviati in modo improprio possono cadere nelle mani sbagliate e avere una durata di vita spesso più lunga. I token di Microsoft Entra scadono ogni ora, limitando il fattore di rischio complessivo in caso di perdita. Per gli scenari pat comuni, microsoft condividere alcuni esempi su come è possibile esplorare l'uso di un token Microsoft Entra invece.

Non è possibile usare un'entità servizio per creare un token di accesso personale.

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: Le entità servizio e le identità gestite hanno un prezzo simile a quello degli utenti, in base al livello di accesso. Una modifica rilevante riguarda il modo in cui viene gestita la fatturazione a più organizzazioni per le entità servizio. Gli utenti vengono conteggiati come una sola licenza, indipendentemente dal numero di organizzazioni in cui si trovano. Le entità servizio vengono conteggiate come una licenza per ogni organizzazione in cui si trova l'utente. Questo scenario è simile a quello standard "fatturazione basata sull'assegnazione degli utenti".

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

R: È possibile aggiungere un'identità gestita solo dallo stesso tenant a cui è connessa l'organizzazione. Tuttavia, è disponibile una soluzione alternativa che consente di configurare un'identità gestita nel "tenant delle risorse", dove sono presenti tutte le risorse. È quindi possibile abilitarlo per l'uso da parte di un'entità servizio nel "tenant di destinazione", in cui l'organizzazione è connessa. Seguire questa procedura come soluzione alternativa:

1. Creare un'identità gestita assegnata dall'utente in portale di Azure per il tenant delle risorse.
2. Connetterlo a una macchina virtuale e assegnarvi questa identità gestita.
3. Creare un insieme di credenziali delle chiavi e generare un certificato (non può essere di tipo "PEM"). Quando si genera questo certificato, viene generato anche un segreto con lo stesso nome, che verrà usato in un secondo momento.
4. Concedere l'accesso all'identità gestita in modo che possa leggere la chiave privata dall'insieme di credenziali delle chiavi. Creare un criterio di accesso nell'insieme di credenziali delle chiavi con le autorizzazioni "Get/List" (in "Autorizzazioni segrete" e cercare l'identità gestita in "Seleziona entità".
5. Scaricare il certificato creato in formato "CER", che garantisce che non contenga la parte privata del certificato.
6. Creare una nuova registrazione dell'applicazione nel tenant di destinazione.
7. Caricare il certificato scaricato in questa nuova applicazione nella scheda "Certificati e segreti".
8. Aggiungere l'entità servizio dell'applicazione all'organizzazione Azure DevOps a cui si vuole accedere e ricordare di configurare l'entità servizio con le autorizzazioni necessarie.
9. Ottieni un token di accesso Microsoft Entra da questo principale del servizio che utilizza il certificato di identità gestito con questo esempio di codice:

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);

	var secret = keyVaultSecret.Value;
	return secret.Value;
}

private static async Task<AuthenticationResult> GetAppRegistrationAADAccessToken(string applicationClientID, string appTenantId)
{
	IConfidentialClientApplication app;

	byte[] privateKeyBytes = Convert.FromBase64String(GetSecret(keyVaultName, secretName));
	X509Certificate2 certificateWithPrivateKey = new X509Certificate2(privateKeyBytes, (string)null, X509KeyStorageFlags.MachineKeySet);

	app = ConfidentialClientApplicationBuilder.Create(applicationClientID)
		.WithCertificate(certificateWithPrivateKey)
		.WithAuthority(new Uri(string.Format(CultureInfo.InvariantCulture, "https://login.microsoftonline.com/{0}", appTenantId)))
		.Build();
	app.AddInMemoryTokenCache();

	string AdoAppClientID = "499b84ac-1321-427f-aa17-267ca6975798/.default";
	string[] scopes = new string[] { AdoAppClientID };

	var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();

	return result;
}

Potenziali errori

Il repository Git con nome o identificatore '{repoName}' non esiste o non si dispone delle autorizzazioni per l'operazione che si sta tentando di eseguire.

Assicurarsi che il principale del servizio disponga almeno di una licenza "Basic" per accedere ai repository. Una licenza "Stakeholder" non è sufficiente.

Impossibile creare un'entità servizio con ID oggetto '{provided objectId}'

Non esiste un'entità servizio con provided objectId nel tenant connesso all'organizzazione. Un motivo comune è che si passa l'ID oggetto della registrazione dell'app, anziché l'ID oggetto della relativa entità servizio. Tenere presente che un'entità servizio è un oggetto che rappresenta l'applicazione per un determinato tenant, non è l'applicazione stessa. È service principal object ID disponibile nella pagina "Applicazioni aziendali" del tenant. Cercare il nome dell'applicazione e selezionare il risultato "Applicazione aziendale" restituito. Questo risultato è la pagina dell'applicazione dell'entità servizio o dell'organizzazione ed è possibile usare l'ID oggetto disponibile in questa pagina per creare un'entità servizio in Azure DevOps.

Accesso negato: {ID of the caller identity} richiede le autorizzazioni seguenti per la risorsa Utenti per eseguire questa azione: Aggiungi utenti

Questo errore potrebbe essere dovuto a uno dei motivi seguenti:

• Non si è il proprietario dell'organizzazione, dell'amministratore della raccolta di progetti o di un amministratore del progetto o del team.
• Si è un progetto o un amministratore del team, ma il criterio "Consenti agli amministratori del team e del progetto di invitare nuovi utenti" è disabilitato.
• Si è un amministratore del progetto o del team che può invitare nuovi utenti, ma si sta tentando di assegnare una licenza quando si invita un nuovo utente. Gli amministratori del progetto o del team non possono assegnare una licenza ai nuovi utenti. Qualsiasi nuovo utente invitato viene aggiunto al livello di accesso predefinito per i nuovi utenti. Contattare un PCA per modificare il livello di accesso alle licenze.

L'API Graph List di Azure DevOps restituisce un elenco vuoto, anche se sappiamo che nell'organizzazione sono presenti principali di servizio.

L'API Elenco graph di Azure DevOps potrebbe restituire un elenco vuoto, anche se sono presenti ancora più pagine di utenti da restituire. Usare per continuationToken scorrere gli elenchi ed eventualmente trovare una pagina in cui vengono restituite le entità servizio. Se viene restituito un continuationToken oggetto , significa che sono disponibili più risultati tramite l'API. Anche se in questo momento si prevede di migliorare questa logica, è possibile che i primi risultati X restituisca vuoti.

TF401444: accedere almeno una volta come {tenantId'tenantId\servicePrincipalObjectId'} in un Web browser per abilitare l'accesso al servizio.

Se l'entità servizio non è stata invitata all'organizzazione, potrebbe verificarsi l'errore seguente. Assicurarsi che l'entità servizio venga aggiunta all'organizzazione appropriata e disponga di tutte le autorizzazioni necessarie per accedere alle risorse necessarie.

Articoli correlati

• Collegamento ad app di esempio
• Informazioni di riferimento sulle API entitlement per le entità servizio
• Informazioni di riferimento sulle API Graph dell'entità servizio