Delen via

Service-principals en beheerde identiteiten gebruiken in Azure DevOps

  • Artikel

Azure DevOps Services

Notitie

Azure Active Directory heet nu Microsoft Entra ID. Meer informatie leest u in Nieuwe naam voor Azure AD.

Als u Microsoft Entra-service-principals en beheerde identiteiten toevoegt aan uw Azure DevOps Services-organisaties, krijgen ze toegang tot uw organisatiebronnen. Voor veel teams kan deze functie een levensvatbaar en voorkeurs alternatief zijn voor persoonlijke toegangstokens (PAT's) wanneer u toepassingen verifieert die werkstromen voor power automation in uw bedrijf gebruiken.

Over service-principals en beheerde identiteiten

Service-principals zijn beveiligingsobjecten in een Microsoft Entra-toepassing die definiëren wat een toepassing in een bepaalde tenant kan doen. Ze worden ingesteld in Azure Portal tijdens het registratieproces van de toepassing en geconfigureerd voor toegang tot Azure-resources, zoals Azure DevOps. Door service-principals toe te voegen aan uw organisatie en machtigingen in te stellen, kunnen we bepalen of een service-principal is gemachtigd voor toegang tot uw organisatieresources en welke.

Beheerde identiteiten is een andere Microsoft Entra-functie die vergelijkbaar is met de service-principals van een toepassing. Deze objecten bieden identiteiten voor Azure-resources en bieden een eenvoudige manier voor services die Ondersteuning bieden voor Microsoft Entra-verificatie om referenties te delen. Ze zijn een aantrekkelijke optie omdat Microsoft Entra ID zorgt voor referentiebeheer en rotatie. Hoewel de installatie van een beheerde identiteit er anders uitziet in Azure Portal, behandelt Azure DevOps beide beveiligingsobjecten hetzelfde als een nieuwe identiteit in een organisatie met gedefinieerde machtigingen. In de rest van dit artikel verwijzen we naar beheerde identiteiten en service-principals door elkaar als service-principal, tenzij opgegeven.

Gebruik de volgende stappen om deze identiteiten te verifiëren bij Azure DevOps, zodat ze acties namens zichzelf kunnen uitvoeren.

Beheerde identiteiten en service-principals configureren

Uw implementatie kan variëren, maar op hoog niveau helpen de volgende stappen u bij het gebruik van service-principals in uw werkstroom. Bekijk een van onze voorbeeld-apps om mee te doen.

1. Een nieuwe beheerde identiteit of toepassingsservice-principal maken

Maak een toepassingsservice-principal of een beheerde identiteit in Azure Portal.

Een toepassingsservice-principal maken

Wanneer u een nieuwe toepassingsregistratie maakt, wordt er een toepassingsobject gemaakt in Microsoft Entra-id. De service-principal van de toepassing is een weergave van dit toepassingsobject voor een bepaalde tenant. Wanneer u een toepassing registreert als een toepassing met meerdere tenants, is er een uniek service-principalobject dat het toepassingsobject vertegenwoordigt voor elke tenant waaraan de toepassing wordt toegevoegd.

Meer informatie:

Een beheerde identiteit maken

Het maken van beheerde identiteiten in Azure Portal verschilt aanzienlijk van het instellen van toepassingen met service-principals. Voordat u begint met het maken van het proces, moet u eerst rekening houden met het type beheerde identiteit dat u wilt maken:

  • Door het systeem toegewezen beheerde identiteit: met sommige Azure-services kunt u een beheerde identiteit rechtstreeks op een service-exemplaar inschakelen. Wanneer u een door het systeem toegewezen beheerde identiteit inschakelt, wordt er een identiteit gemaakt in Microsoft Entra-id. De identiteit is gekoppeld aan de levenscyclus van dat service-exemplaar. Als de resource wordt verwijderd, wordt de identiteit automatisch verwijderd. Standaard kan alleen die Azure-resource deze identiteit gebruiken voor het aanvragen van tokens van Microsoft Entra ID.
  • Door de gebruiker toegewezen beheerde identiteit U kunt ook een beheerde identiteit maken als een zelfstandige Azure-resource door een door de gebruiker toegewezen beheerde identiteit te maken en deze toe te wijzen aan een of meer exemplaren van een Azure-service. Voor door de gebruiker toegewezen beheerde identiteiten wordt de identiteit afzonderlijk beheerd van de resources die er gebruik van maken.

Zie de volgende artikelen en video voor meer informatie:

2. Een service-principal toevoegen aan een Azure DevOps-organisatie

Zodra u de service-principals in het Microsoft Entra-beheercentrum hebt geconfigureerd, moet u hetzelfde doen in Azure DevOps door de service-principals toe te voegen aan uw organisatie. U kunt ze toevoegen via de pagina Gebruikers of met de ServicePrincipalEntitlements-API's. Omdat ze zich niet interactief kunnen aanmelden, moet een gebruikersaccount dat gebruikers kan toevoegen aan een organisatie, project of team deze toevoegen. Dergelijke gebruikers omvatten beheerders van projectverzamelingen (PCA) of projectbeheerders en teambeheerders wanneer het beleid 'Team- en projectbeheerders toestaan om nieuwe gebruikers uit te nodigen' is ingeschakeld.

Tip

Als u een service-principal wilt toevoegen aan de organisatie, voert u de weergavenaam van de toepassing of beheerde identiteit in. Als u ervoor kiest om programmatisch een service-principal toe te voegen via de ServicePrincipalEntitlements API, moet u ervoor zorgen dat u de object-id van de service-principal doorgeeft en niet de object-id van de toepassing.

Als u een PCA bent, kunt u ook een service-principal toegang verlenen tot specifieke projecten en een licentie toewijzen. Als u geen PCA bent, moet u contact opnemen met de PCA om projectlidmaatschappen of licentietoegangsniveaus bij te werken.

Schermopname van service-principals en beheerde identiteiten in de Users Hub.

Notitie

U kunt alleen een beheerde identiteit of service-principal toevoegen voor de tenant waaraan uw organisatie is gekoppeld. Zie de tijdelijke oplossing in de veelgestelde vragen voor toegang tot een beheerde identiteit in een andere tenant.

3. Machtigingen instellen voor een service-principal

Nadat uw service-principals aan de organisatie zijn toegevoegd, kunt u ze op dezelfde manier behandelen als standaardgebruikersaccounts. U kunt machtigingen rechtstreeks toewijzen aan een service-principal, deze toevoegen aan beveiligingsgroepen en teams, deze toewijzen aan elk toegangsniveau en deze verwijderen uit de organisatie. U kunt ook CRUD-bewerkingen Service Principal Graph APIs uitvoeren op service-principals.

Het instellen van deze machtigingen kan verschillen van de wijze waarop u toepassingsmachtigingen instelt in een Microsoft Entra-toepassing voor andere Azure-resources. Azure DevOps is niet afhankelijk van de installatie van toepassingsmachtigingen die beschikbaar zijn voor toepassingsregistraties via Azure Portal. Met deze toepassingsmachtigingen worden machtigingen toegepast op een service-principal in alle organisaties die zijn gekoppeld aan een tenant en die geen kennis hebben van de organisatie-, project- of objectmachtigingen die beschikbaar zijn in Azure DevOps. Om service-principals gedetailleerdere machtigingen te bieden, vertrouwen we op ons eigen machtigingsmodel in plaats van entra-id's.

4. Een service-principal beheren

Het beheer van service-principals verschilt van gebruikersaccounts op de volgende belangrijke manieren:

  • Service-principals hebben geen e-mailberichten en kunnen daarom niet via e-mail worden uitgenodigd voor een organisatie.
  • Groepsregels voor licenties zijn momenteel niet van toepassing op service-principals. Als u een toegangsniveau wilt toewijzen aan een service-principal, kunt u dit het beste rechtstreeks doen.
  • Service-principals kunnen worden toegevoegd aan Microsoft Entra-groepen (in Azure Portal). Er bestaat momenteel een technische beperking waardoor we deze niet kunnen weergeven in een lijst met Microsoft Entra-groepsleden. Deze beperking geldt niet voor Azure DevOps-groepen. Dat gezegd hebbende, neemt een service-principal nog steeds alle groepsmachtigingen over die zijn ingesteld op een Microsoft Entra-groep waartoe ze behoren.
  • Gebruikers in een Microsoft Entra-groep maken niet direct deel uit van een Azure DevOps-organisatie omdat een beheerder een groep maakt en er een Microsoft Entra-groep aan toevoegt. We hebben een proces met de naam 'materialisatie' dat plaatsvindt zodra een gebruiker van een Microsoft Entra-groep zich voor het eerst bij de organisatie aanmeldt. Een gebruiker die zich aanmeldt bij een organisatie stelt ons in staat om te bepalen welke gebruikers een licentie moeten krijgen. Omdat aanmelden niet mogelijk is voor service-principals, moet een beheerder deze expliciet toevoegen aan een organisatie zoals eerder is beschreven.
  • U kunt de weergavenaam of avatar van een service-principal niet wijzigen in Azure DevOps.
  • Service-principals krijgen licenties in elke organisatie waaraan ze worden toegevoegd, zelfs als facturering voor meerdere organisaties is geselecteerd.

5. Een Microsoft Entra ID-token ophalen

(a) Programmatisch een Microsoft Entra ID-token verkrijgen

Het verkrijgen van een toegangstoken voor een beheerde identiteit kan worden uitgevoerd door de Microsoft Entra ID-documentatie te volgen. Zie de voorbeelden voor service-principals en beheerde identiteiten.

Het geretourneerde toegangstoken is een JSON-webtoken (JWT) met de gedefinieerde rollen, die kunnen worden gebruikt voor toegang tot organisatieresources met behulp van het token als Bearer-.

(b) Een Microsoft Entra ID-token verkrijgen met de Azure CLI

Voor ad-hocbewerkingen is het mogelijk eenvoudiger om een eenmalig Microsoft Entra ID-token te verkrijgen via de Azure CLI. Deze benadering heeft de voorkeur voor bewerkingen die geen permanent token nodig hebben om regelmatig te worden geroteerd, zoals API-aanroepen of git-kloonbewerkingen.

vereisten

  • Azure-tenant-id en abonnements-id: zorg ervoor dat het abonnement is gekoppeld aan de tenant die is verbonden met de Azure DevOps-organisatie waartoe u toegang probeert te krijgen. Als u uw tenant- of abonnements-id niet weet, kunt u deze vinden in de Azure-portal.
  • client-id en clientgeheim van Azure-app
  • Azure CLI

Deze instructies worden verstrekt door de Databricks-documenten en meer informatie vindt u op hun pagina.

  1. Meld u als service-principal aan bij de Azure CLI met behulp van de opdracht az devops login.
  2. Volg de instructies op het scherm en voltooi de aanmelding.
# 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. Stel het juiste abonnement in voor de aangemelde service-principal door de opdracht in te voeren:
az account set -s <subscription-id>
  1. Genereer een Microsoft Entra ID-toegangstoken met de az account get-access-token de Azure DevOps-resource-id: 499b84ac-1321-427f-aa17-267ca6975798.
$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv
  1. U kunt nu opdrachten per gebruikelijke manier gebruiken az cli . We proberen een Azure DevOps-API aan te roepen door deze als een Bearer token door te geven in de headers:
$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

Notitie

Gebruik de Azure DevOps-toepassings-id, niet onze resource-URI, voor het genereren van tokens.

6. Het Microsoft Entra ID-token gebruiken om te verifiëren bij Azure DevOps-resources

In het volgende videovoorbeeld gaan we van verificatie met een PAT naar het gebruik van een token van een service-principal. We beginnen met het gebruik van een clientgeheim voor verificatie en gaan vervolgens over naar het gebruik van een clientcertificaat.

Een ander voorbeeld laat zien hoe u verbinding maakt met Azure DevOps met behulp van een door de gebruiker toegewezen beheerde identiteit binnen een Azure-functie.

Volg deze voorbeelden door de app-code te vinden in onze verzameling voorbeeld-apps.

Enkele veelvoorkomende scenario's voor verificatie met service-principals, naast het maken van Azure DevOps REST API-aanroepen, vindt u in deze resources:

Hoe verschillen service-principals van gebruikers?

  • U kunt de weergavenaam of avatar van een service-principal niet wijzigen in Azure DevOps.
  • Een service-principal telt als een licentie voor elke organisatie waaraan deze wordt toegevoegd, zelfs als facturering voor meerdere organisaties is geselecteerd.
  • Service-principals kunnen geen organisatie-eigenaren zijn of organisaties maken.
  • Service-principals kunnen geen tokens maken, zoals persoonlijke toegangstokens (PAT's) of SSH-sleutels. Ze kunnen hun eigen Microsoft Entra ID-tokens genereren en deze tokens kunnen worden gebruikt om Azure DevOps REST API's aan te roepen.
  • Azure DevOps OAuth wordt niet ondersteund voor service-principals.

Veelgestelde vragen

Algemeen

V: Waarom moet ik een service-principal of een beheerde identiteit gebruiken in plaats van een PAT?

A: Veel van onze klanten zoeken een service-principal of beheerde identiteit om een bestaande PAT (persoonlijk toegangstoken) te vervangen. Dergelijke PAW's behoren vaak tot een serviceaccount (gedeeld teamaccount) dat ze gebruikt om een toepassing te verifiëren met Azure DevOps-resources. PAW's moeten zo vaak (minimaal 180 dagen) arbeidsintensief worden gedraaid. Onjuist opgeslagen PAT's kunnen in verkeerde handen vallen en blijven beschikbaar gedurende hun vaak langere levensduur. Microsoft Entra-tokens verlopen elk uur, waardoor de algehele risicofactor wordt beperkt wanneer deze wordt gelekt. Voor veelvoorkomende PAT-scenario's we enkele voorbeelden delen over hoe u een Microsoft Entra-token kunt verkennen in plaats.

U kunt een service-principal niet gebruiken om een persoonlijk toegangstoken te maken.

V: Wat zijn de frequentielimieten voor service-principals en beheerde identiteiten?

A: Service-principals en beheerde identiteiten hebben dezelfde frequentielimieten als gebruikers.

V: Kost het gebruik van deze functie meer?

A: Service-principals en beheerde identiteiten zijn vergelijkbaar met gebruikers, op basis van het toegangsniveau. Een belangrijke wijziging heeft betrekking op de wijze waarop we facturering voor meerdere organisaties behandelen voor service-principals. Gebruikers worden geteld als slechts één licentie, ongeacht het aantal organisaties waarin ze zich bevinden. Service-principals worden geteld als één licentie per elke organisatie waarin de gebruiker zich bevindt. Dit scenario is vergelijkbaar met de standaard facturering op basis van gebruikerstoewijzingen.

V: Kan ik een beheerde identiteit vanuit een andere tenant toevoegen aan mijn organisatie?

A: U kunt alleen een beheerde identiteit toevoegen vanuit dezelfde tenant waarmee uw organisatie is verbonden. We hebben echter een tijdelijke oplossing waarmee u een beheerde identiteit kunt instellen in de 'resourcetenant', waar zich al uw resources bevinden. Vervolgens kunt u inschakelen dat deze wordt gebruikt door een service-principal in de doeltenant, waar uw organisatie is verbonden. Volg de volgende stappen als tijdelijke oplossing:

  1. Maak een door de gebruiker toegewezen beheerde identiteit in Azure Portal voor uw resourcetenant.
  2. Verbind deze met een virtuele machine en wijs deze beheerde identiteit eraan toe.
  3. Maak een sleutelkluis en genereer een certificaat (kan niet van het type PEM zijn). Wanneer u dit certificaat genereert, wordt er ook een geheim met dezelfde naam gegenereerd, dat we later gebruiken.
  4. Ververleent toegang tot de beheerde identiteit, zodat deze de persoonlijke sleutel uit de sleutelkluis kan lezen. Maak een toegangsbeleid in de sleutelkluis met de machtigingen Ophalen/Lijst (onder 'Geheime machtigingen' en zoek naar de beheerde identiteit onder 'Principal selecteren'.
  5. Download het gemaakte certificaat in cer-indeling, zodat het niet het privégedeelte van uw certificaat bevat.
  6. Maak een nieuwe toepassingsregistratie in de doeltenant.
  7. Upload het gedownloade certificaat naar deze nieuwe toepassing op het tabblad Certificaten en geheimen.
  8. Voeg de service-principal van deze toepassing toe aan de Azure DevOps-organisatie die we willen openen en vergeet niet om de service-principal in te stellen met eventuele vereiste machtigingen.
  9. Haal een Microsoft Entra-toegangstoken op uit deze service-principal die gebruikmaakt van het beheerde identiteitscertificaat met dit codevoorbeeld:

Notitie

Vernieuw uw certificaten altijd regelmatig.

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

Mogelijke fouten

De Git-opslagplaats met de naam of id {repoName} bestaat niet of u beschikt niet over machtigingen voor de bewerking die u probeert uit te voeren.

Zorg ervoor dat de service-principal ten minste een Basislicentie heeft voor toegang tot opslagplaatsen. Een licentie voor belanghebbenden is niet voldoende.

Kan service-principal niet maken met object-id {provided objectId}

Er is geen service-principal met de provided objectId tenant die is verbonden met uw organisatie. Een veelvoorkomende reden is dat u de object-id van de app-registratie doorgeeft in plaats van de object-id van de service-principal. Een service-principal is een object dat de toepassing voor een bepaalde tenant vertegenwoordigt, niet de toepassing zelf. U service principal object ID vindt deze op de pagina Bedrijfstoepassingen van uw tenant. Zoek de naam van de toepassing en selecteer het resultaat 'Bedrijfstoepassing' dat wordt geretourneerd. Dit resultaat is de pagina van de service-principal/bedrijfstoepassing en u kunt de object-id op deze pagina gebruiken om een service-principal te maken in Azure DevOps.

Toegang geweigerd: {ID of the caller identity} heeft de volgende machtigingen nodig voor de resourcegebruikers om deze actie uit te voeren: Gebruikers toevoegen

Deze fout kan een van de volgende oorzaken hebben:

  • U bent niet de eigenaar van de organisatie, beheerder van de projectverzameling of een project- of teambeheerder.
  • U bent een project- of teambeheerder, maar het beleid Team- en projectbeheerders toestaan om nieuwe gebruikers uit te nodigen, is uitgeschakeld.
  • U bent een projectbeheerder of teambeheerder die nieuwe gebruikers kan uitnodigen, maar u probeert een licentie toe te wijzen wanneer u een nieuwe gebruiker uitnodigt. Project- of teambeheerders mogen geen licentie toewijzen aan nieuwe gebruikers. Nieuwe uitgenodigde gebruikers worden toegevoegd op het standaardtoegangsniveau voor nieuwe gebruikers. Neem contact op met een PCA om het licentietoegangsniveau te wijzigen.

Azure DevOps Graph List API retourneert een lege lijst, ook al weten we dat er service-principals in de organisatie zijn

De Azure DevOps Graph List-API kan een lege lijst retourneren, zelfs als er nog steeds meer pagina's van gebruikers worden geretourneerd. Gebruik de continuationToken opdracht om door de lijsten te bladeren en u kunt uiteindelijk een pagina vinden waar de service-principals worden geretourneerd. Als een continuationToken resultaat wordt geretourneerd, betekent dit dat er meer resultaten beschikbaar zijn via de API. Hoewel we van plan zijn om deze logica te verbeteren, is het mogelijk dat de eerste X-resultaten leeg zijn.

TF401444: Meld u ten minste één keer aan als {tenantId'tenantId\servicePrincipalObjectId'} in een webbrowser om toegang tot de service in te schakelen.

Als de service-principal niet is uitgenodigd voor de organisatie, ziet u mogelijk de volgende fout. Zorg ervoor dat de service-principal wordt toegevoegd aan de juiste organisatie en alle machtigingen heeft die nodig zijn om toegang te krijgen tot alle vereiste resources.