Dela via

Använda tjänstens huvudnamn och hanterade identiteter i Azure DevOps

  • Artikel

Azure DevOps Services

Kommentar

Azure Active Directory har bytt namn till Microsoft Entra ID. För mer information, se Nytt namn för Azure AD.

Genom att lägga till Microsoft Entra-tjänstens huvudnamn och hanterade identiteter i dina Azure DevOps Services-organisationer får de åtkomst till organisationens resurser. För många team kan den här funktionen vara ett genomförbart och föredraget alternativ till personliga åtkomsttoken (PAT) när du autentiserar program som driver automationsarbetsflöden i ditt företag.

Om tjänstens huvudnamn och hanterade identiteter

Tjänstens huvudnamn är säkerhetsobjekt i ett Microsoft Entra-program som definierar vad ett program kan göra i en viss klientorganisation. De konfigureras i Azure Portal under programregistreringsprocessen och konfigureras för åtkomst till Azure-resurser, till exempel Azure DevOps. Genom att lägga till tjänstens huvudnamn i din organisation och konfigurera behörigheter ovanpå dem kan vi avgöra om tjänstens huvudnamn har behörighet att komma åt organisationens resurser och vilka.

Hanterade identiteter är en annan Microsoft Entra-funktion som fungerar på samma sätt som ett programs tjänsthuvudnamn. Dessa objekt tillhandahåller identiteter för Azure-resurser och gör det enkelt för tjänster som stöder Microsoft Entra-autentisering att dela autentiseringsuppgifter. De är ett tilltalande alternativ eftersom Microsoft Entra ID tar hand om hantering och rotation av autentiseringsuppgifter. Även om konfigurationen för en hanterad identitet kan se annorlunda ut på Azure Portal behandlar Azure DevOps båda säkerhetsobjekten på samma sätt som en ny identitet i en organisation med definierade behörigheter. I resten av den här artikeln refererar vi till hanterade identiteter och tjänstens huvudnamn om inte anges.

Använd följande steg för att autentisera dessa identiteter till Azure DevOps så att de kan utföra åtgärder för sig själva.

Konfigurera hanterade identiteter och tjänstens huvudnamn

Implementeringen kan variera, men på hög nivå hjälper följande steg dig att börja använda tjänstens huvudnamn i arbetsflödet. Överväg att titta på en av våra exempelappar för att följa med.

1. Skapa en ny hanterad identitet eller programtjänstens huvudnamn

Skapa ett huvudnamn för programtjänsten eller en hanterad identitet i Azure Portal.

Skapa ett huvudnamn för programtjänsten

När du skapar en ny programregistrering skapas ett programobjekt i Microsoft Entra-ID. Programtjänstens huvudnamn är en representation av det här programobjektet för en viss klientorganisation. När du registrerar ett program som ett program med flera klienter finns det ett unikt objekt för tjänstens huvudnamn som representerar programobjektet för varje klientorganisation som programmet läggs till i.

Ytterligare information:

Skapa en hanterad identitet

Att skapa hanterade identiteter i Azure Portal skiljer sig avsevärt från att konfigurera program med tjänstens huvudnamn. Innan du börjar skapa processen måste du först överväga vilken typ av hanterad identitet du vill skapa:

  • Systemtilldelad hanterad identitet: Med vissa Azure-tjänster kan du aktivera en hanterad identitet direkt på en tjänstinstans. När du aktiverar en systemtilldelad hanterad identitet skapas en identitet i Microsoft Entra-ID. Identiteten är kopplad till livscykeln för den tjänstinstansen. När resursen tas bort tar Azure automatiskt bort identiteten åt dig. Det är bara den Azure-resursen som kan använda den här identiteten för att begära tokens från Microsoft Entra ID.
  • Användartilldelad hanterad identitet Du kan också skapa en hanterad identitet som en fristående Azure-resurs genom att skapa en användartilldelad hanterad identitet och tilldela den till en eller flera instanser av en Azure-tjänst. För användartilldelade hanterade identiteter hanteras identiteten separat från de resurser som använder den.

Mer information finns i följande artiklar och video:

2. Lägg till ett huvudnamn för tjänsten i en Azure DevOps-organisation

När du har konfigurerat tjänstens huvudnamn i administrationscentret för Microsoft Entra måste du göra samma sak i Azure DevOps genom att lägga till tjänstens huvudnamn i din organisation. Du kan lägga till dem via sidan Användare eller med API:er för ServicePrincipalEntitlements. Eftersom de inte kan logga in interaktivt måste ett användarkonto som kan lägga till användare i en organisation, ett projekt eller ett team lägga till dem. Sådana användare inkluderar projektsamlingsadministratörer (PCA) eller projektadministratörer och teamadministratörer när principen "Tillåt team- och projektadministratörer att bjuda in nya användare" är aktiverad.

Dricks

Om du vill lägga till ett huvudnamn för tjänsten i organisationen anger du programmets eller den hanterade identitetens visningsnamn. Om du väljer att lägga till ett huvudnamn för tjänsten programmatiskt via API:etServicePrincipalEntitlementsska du skicka in tjänstens huvudnamns objekt-ID och inte programmets objekt-ID.

Om du är en PCA kan du också bevilja tjänstens huvudnamn åtkomst till specifika projekt och tilldela en licens. Om du inte är en PCA måste du kontakta PCA för att uppdatera eventuella projektmedlemskap eller licensåtkomstnivåer.

Skärmbild av tjänstens huvudnamn och hanterade identiteter i användarhubben.

Kommentar

Du kan bara lägga till en hanterad identitet eller tjänstens huvudnamn för den klientorganisation som din organisation är ansluten till. Information om hur du kommer åt en hanterad identitet i en annan klientorganisation finns i lösningen i Vanliga frågor och svar.

3. Ange behörigheter för tjänstens huvudnamn

När tjänstens huvudnamn har lagts till i organisationen kan du behandla dem på samma sätt som standardanvändarkonton. Du kan tilldela behörigheter direkt på ett huvudnamn för tjänsten, lägga till den i säkerhetsgrupper och team, tilldela den till valfri åtkomstnivå och ta bort den från organisationen. Du kan också använda Service Principal Graph APIs för att utföra CRUD-åtgärder på tjänstens huvudnamn.

Inställningen av dessa behörigheter kan skilja sig från hur du är van vid att konfigurera programbehörigheter i ett Microsoft Entra-program för andra Azure-resurser. Azure DevOps förlitar sig inte på konfigurationen "Programbehörigheter" som är tillgänglig för programregistreringar via Azure Portal. Dessa programbehörigheter tillämpar behörigheter på ett tjänstehuvudnamn i alla organisationer som är knutna till en klient och har ingen information om de organisations-, projekt- eller objektbehörigheter som är tillgängliga i Azure DevOps. För att erbjuda tjänstens huvudnamn mer detaljerade behörigheter förlitar vi oss på vår egen behörighetsmodell i stället för Entra-ID:er.

4. Hantera ett huvudnamn för tjänsten

Hanteringen av tjänstens huvudnamn skiljer sig från användarkonton på följande viktiga sätt:

  • Tjänstens huvudnamn har inga e-postmeddelanden och kan därför inte bjudas in till en organisation via e-post.
  • Gruppregler för licensiering gäller för närvarande inte för tjänstens huvudnamn. Om du vill tilldela en åtkomstnivå till ett huvudnamn för tjänsten är det bäst att göra det direkt.
  • Tjänstens huvudnamn kan läggas till i Microsoft Entra-grupper (i Azure-portalen). Det finns för närvarande en teknisk begränsning som hindrar oss från att visa dem i en lista över Microsoft Entra-gruppmedlemmar. Den här begränsningen gäller inte för Azure DevOps-grupper. Med detta sagt ärver ett tjänsthuvudnamn fortfarande alla gruppbehörigheter som har angetts ovanpå en Microsoft Entra-grupp som de tillhör.
  • Användare i en Microsoft Entra-grupp kommer inte att ingå i en Azure DevOps-organisation omedelbart bara för att en administratör skapar en grupp och lägger till en Microsoft Entra-grupp i den. Vi har en process som kallas "materialisering" som sker när en användare från en Microsoft Entra-grupp loggar in på organisationen för första gången. Med en användare som loggar in i en organisation kan vi avgöra vilka användare som ska beviljas en licens. Eftersom inloggning inte är möjligt för tjänstens huvudnamn måste en administratör uttryckligen lägga till den i en organisation enligt beskrivningen tidigare.
  • Du kan inte ändra ett huvudnamn för tjänstens huvudnamn eller avatar i Azure DevOps.
  • Tjänstens huvudnamn får licenser i varje organisation som de läggs till i, även om fakturering för flera organisationer har valts.

5. Hämta en Microsoft Entra ID-token

(a) Hämta en Microsoft Entra ID-token programmatiskt

Du kan hämta en åtkomsttoken för en hanterad identitet genom att följa dokumentationen om Microsoft Entra-ID. Se exemplen för tjänstehuvudprinciper och hanterade identiteter.

Den returnerade åtkomsttoken är en JSON-webbtoken (JWT) med de definierade rollerna, som kan användas för att komma åt organisationsresurser med hjälp av token som Bearer.

(b) Hämta en Microsoft Entra-ID-token med Azure CLI

För ad hoc-åtgärder kan det vara enklare att hämta en engångstoken för Microsoft Entra-ID via Azure CLI. Den här metoden rekommenderas för åtgärder som inte behöver en beständig token för att roteras regelbundet, till exempel API-anrop eller git-kloningsåtgärder.

Förutsättningar

  • Azure-klient-ID och prenumerations-ID: Kontrollera att prenumerationen är associerad med den klientorganisation som är ansluten till den Azure DevOps-organisation som du försöker komma åt. Om du inte känner till ditt klient- eller prenumerations-ID hittar du det i Azure-portalen.
  • klient-ID och klienthemlighet i Azure-appen
  • Azure CLI-

Dessa instruktioner tillhandahålls av Databricks-dokumenten och mer information finns på deras sida.

  1. Logga in på Azure CLI som tjänstens huvudnamn med hjälp av kommandot az devops login.
  2. Följ anvisningarna på skärmen och slutför inloggningen.
# 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
  1. Ange rätt prenumeration för det inloggade tjänstens huvudkonto genom att ange kommandot:
az account set -s <subscription-id>
  1. Generera en Microsoft Entra ID-åtkomsttoken med az account get-access-token Resurs-ID:t för Azure DevOps: 499b84ac-1321-427f-aa17-267ca6975798.
$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv
  1. Nu kan du använda az cli kommandon per vanligt. Nu ska vi försöka anropa ett Azure DevOps-API genom att skicka med det i huvudena som en Bearer-token:
$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

Kommentar

Använd Program-ID:t för Azure DevOps, inte vår resurs-URI, för att generera token.

6. Använd Microsoft Entra-ID-token för att autentisera till Azure DevOps-resurser

I följande videoexempel går vi från att autentisera med en PAT till att använda en token från ett huvudnamn för tjänsten. Vi börjar med att använda en klienthemlighet för autentisering och sedan övergår vi till att använda ett klientcertifikat.

Ett annat exempel visar hur du ansluter till Azure DevOps med hjälp av en användartilldelad hanterad identitet i en Azure-funktion.

Följ med i de här exemplen genom att hitta appkoden i vår samling med exempelappar.

Några vanliga scenarier för autentisering med tjänstens huvudnamn förutom att göra AZURE DevOps REST API-anrop finns i dessa resurser:

Hur skiljer sig tjänsthuvudkonton från användarna?

  • Du kan inte ändra ett huvudnamn för tjänstens huvudnamn eller avatar i Azure DevOps.
  • Tjänstens huvudnamn räknas som en licens för varje organisation som läggs till, även om fakturering för flera organisationer har valts.
  • Tjänstens huvudnamn kan inte vara organisationsägare eller skapa organisationer.
  • Tjänstens huvudnamn kan inte skapa token, till exempel personliga åtkomsttoken (PAT) eller SSH-nycklar. De kan generera sina egna Microsoft Entra-ID-token och dessa token kan användas för att anropa Azure DevOps REST-API:er.
  • Vi stöder inte Azure DevOps OAuth för tjänstens huvudnamn.

Vanliga frågor och svar

Allmänt

F: Varför ska jag använda tjänstens huvudnamn eller en hanterad identitet i stället för en PAT?

S: Många av våra kunder söker efter tjänstens huvudnamn eller hanterade identitet för att ersätta en befintlig PAT (personlig åtkomsttoken). Sådana PAT:er tillhör ofta ett tjänstkonto (delat teamkonto) som använder dem för att autentisera ett program med Azure DevOps-resurser. PAT måste vara arbetskrävande roteras varje så ofta (minst 180 dagar). Felaktigt lagrade PAT:er kan hamna i fel händer och vara kvar under hela sin ofta långa livslängd. Microsoft Entra-token upphör att gälla varje timme, vilket begränsar den övergripande riskfaktorn vid läckage. För vanliga PAT-scenarier vi dela några exempel på hur du kan utforska med hjälp av en Microsoft Entra-token i stället.

Du kan inte använda tjänstens huvudnamn för att skapa en personlig åtkomsttoken.

F: Vilka är hastighetsbegränsningarna för tjänstens huvudnamn och hanterade identiteter?

S: Tjänstens huvudnamn och hanterade identiteter har samma hastighetsbegränsningar som användare.

F: Kostar det mer att använda den här funktionen?

S: Tjänstens huvudnamn och hanterade identiteter prissätts på samma sätt som användare, baserat på åtkomstnivå. En viktig ändring gäller hur vi behandlar "fakturering för flera organisationer" för tjänstens huvudnamn. Användare räknas bara som en licens, oavsett hur många organisationer de är i. Tjänstens huvudnamn räknas som en licens per organisation som användaren är i. Det här scenariot liknar standard "användartilldelningsbaserad fakturering".

F: Kan jag lägga till en hanterad identitet från en annan klientorganisation i min organisation?

S: Du kan bara lägga till en hanterad identitet från samma klientorganisation som din organisation är ansluten till. Vi har dock en lösning som gör att du kan konfigurera en hanterad identitet i "resursklientorganisationen", där alla dina resurser finns. Sedan kan du aktivera det så att det används av ett huvudnamn för tjänsten i "målklientorganisationen", där din organisation är ansluten. Gör följande som en lösning:

  1. Skapa en användartilldelad hanterad identitet i Azure Portal för resursklientorganisationen.
  2. Anslut den till en virtuell dator och tilldela den här hanterade identiteten till den.
  3. Skapa ett nyckelvalv och generera ett certifikat (kan inte vara av typen "PEM"). När du genererar det här certifikatet genereras också en hemlighet med samma namn, som vi använder senare.
  4. Bevilja åtkomst till den hanterade identiteten så att den kan läsa den privata nyckeln från nyckelvalvet. Skapa en åtkomstprincip i nyckelvalvet med behörigheterna "Hämta/lista" (under "Hemliga behörigheter" och sök efter den hanterade identiteten under "Välj huvudnamn".
  5. Ladda ned det skapade certifikatet i CER-format, vilket säkerställer att det inte innehåller den privata delen av certifikatet.
  6. Skapa en ny programregistrering i målklientorganisationen.
  7. Ladda upp det nedladdade certifikatet till det nya programmet på fliken "Certifikat och hemligheter".
  8. Lägg till det här programmets tjänsthuvudnamn i Azure DevOps-organisationen som vi vill att det ska komma åt och kom ihåg att konfigurera tjänstens huvudnamn med nödvändiga behörigheter.
  9. Hämta en Microsoft Entra-åtkomsttoken från tjänstens huvudnamn som använder det hanterade identitetscertifikatet med det här kodexemplet:

Kommentar

Rotera alltid dina certifikat regelbundet.

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

Potentiella fel

Git-lagringsplatsen med namnet eller identifieraren {repoName} finns inte eller så har du inte behörighet för den åtgärd som du försöker utföra.

Kontrollera att tjänstens huvudnamn har minst en "Basic"-licens för åtkomst till lagringsplatser. En "intressentlicens" räcker inte.

Det gick inte att skapa tjänstens huvudnamn med objekt-ID {provided objectId}

Det finns inget huvudnamn för tjänsten med provided objectId i klientorganisationen som är ansluten till din organisation. En vanlig orsak är att du skickar in objekt-ID:t för appregistreringen i stället för objekt-ID:t för tjänstens huvudnamn. Kom ihåg att ett huvudnamn för tjänsten är ett objekt som representerar programmet för en viss klientorganisation, det är inte själva programmet. Finns service principal object ID på klientorganisationens sida "Företagsprogram". Sök efter programmets namn och välj det "Företagsprogram"-resultat som returneras. Det här resultatet är sidan för tjänstens huvudnamn/företagsprogram och du kan använda objekt-ID:t som finns på den här sidan för att skapa ett huvudnamn för tjänsten i Azure DevOps.

Åtkomst nekad: {ID of the caller identity} behöver följande behörigheter för resursen Användare för att utföra den här åtgärden: Lägg till användare

Det här felet kan bero på någon av följande orsaker:

  • Du är inte ägare till organisationen, projektsamlingsadministratören eller projekt- eller teamadministratören.
  • Du är projekt- eller teamadministratör, men principen "Tillåt team- och projektadministratörer att bjuda in nya användare" är inaktiverad.
  • Du är ett projekt eller en gruppadministratör som kan bjuda in nya användare, men du försöker tilldela en licens när du bjuder in en ny användare. Projekt- eller teamadministratörer får inte tilldela en licens till nya användare. Alla nya inbjudna användare läggs till på standardåtkomstnivån för nya användare. Kontakta ett PCA för att ändra licensåtkomstnivån.

Azure DevOps Graph List API returnerar en tom lista, även om vi vet att det finns tjänsthuvudnamn i organisationen

Api:et för Azure DevOps Graph List kan returnera en tom lista, även om det fortfarande finns fler sidor med användare att returnera. continuationToken Använd för att iterera genom listorna och du kan så småningom hitta en sida där tjänstens huvudnamn returneras. Om en continuationToken returneras innebär det att det finns fler tillgängliga resultat via API:et. Vi har planer på att förbättra den här logiken, men just nu är det möjligt att de första X-resultaten returnerar tomma.

TF401444: Logga in minst en gång som {tenantId'tenantId\servicePrincipalObjectId'} i en webbläsare för att aktivera åtkomst till tjänsten.

Om tjänstens huvudnamn inte har bjudits in till organisationen kan du stöta på följande fel. Kontrollera att tjänstens huvudnamn har lagts till i rätt organisation och har alla behörigheter som krävs för att få åtkomst till nödvändiga resurser.