Partager via

Utiliser des principaux de service et des identités managées dans Azure DevOps

  • Article

Azure DevOps Services

Remarque

Azure Active Directory est désormais Microsoft Entra ID. Si vous souhaitez obtenir d’autres informations, consultez Nouveau nom pour Azure AD.

Ajoutez des principes de service Microsoft Entra et des identités gérées en tant qu'identités d'application dans vos organisations Azure DevOps Services pour leur accorder l'accès aux ressources de votre organisation. Pour de nombreuses équipes, cette fonctionnalité peut être une alternative viable et préférée aux jetons d’accès personnels (PAT) lorsque vous authentifiez des applications qui alimentent les flux de travail d’automatisation dans votre entreprise.

À propos des principaux de service et des identités managées

Les principaux de service sont des objets de sécurité au sein d’une application Microsoft Entra qui définissent ce qu’une application peut faire dans un locataire donné. Ils sont configurés dans le Portail Azure pendant le processus d’inscription de l’application et configurés pour accéder aux ressources Azure, telles qu’Azure DevOps. En ajoutant des principaux de service à votre organization et en configurant des autorisations par-dessus eux, nous pouvons déterminer si un principal de service est autorisé à accéder aux ressources de votre organisation et lesquels.

Les identités managées sont une autre fonctionnalité Microsoft Entra qui agit de la même façon que les principaux de service d’une application. Ces objets fournissent des identités pour les ressources Azure et permettent aux services qui prennent en charge l’authentification Microsoft Entra de partager des informations d’identification. Il s’agit d’une option attrayante, car Microsoft Entra ID s’occupe de la gestion et de la rotation des informations d’identification. Bien que la configuration d’une identité managée puisse sembler différente sur le portail Azure, Azure DevOps traite les deux objets de sécurité identiques à une nouvelle identité d’application dans une organisation avec des autorisations définies. Dans le reste de cet article, nous faisons référence indifféremment aux identités managées et aux principaux de service en tant que principal de service, sauf indication contraire.

Utilisez les étapes suivantes pour authentifier ces identités auprès d’Azure DevOps afin de leur permettre d’effectuer des actions en leur nom.

Configurer des identités managées et des principaux de service

Votre implémentation peut varier, mais à un niveau élevé, les étapes suivantes vous aident à commencer à utiliser des principaux de service dans votre flux de travail. Envisagez de consulter l'une de nos applications types pour suivre le mouvement.

1. Créer une identité managée ou un principal de service d’application

Créez un principal de service d’application ou une identité managée dans le Portail Azure.

Option 1 : Créer un principal de service d'application

Lorsque vous créez une inscription d’application, un objet d’application est créé dans l’ID Microsoft Entra. Le principal du service d’application est une représentation de cet objet d’application pour un locataire donné. Lorsque vous inscrivez une application en tant qu’application mutualisée, il existe un objet de principal de service unique qui représente l’objet d’application pour chaque locataire auquel l’application est ajoutée.

Informations supplémentaires :

Option 2 : Créer une identité managée

La création d’identités managées dans le Portail Azure diffère considérablement de la configuration d’applications avec des principaux de service. Avant de commencer le processus de création, vous devez d’abord déterminer le type d’identité managée que vous souhaitez créer :

  • Identité managée affectée par le système : Certains services Azure vous permettent d’activer une identité managée directement sur un instance de service. Lorsque vous activez une identité managée affectée par le système, une identité est créée dans Microsoft Entra ID. L’identité est liée au cycle de vie de cette instance de service. Lorsque la ressource est supprimée, Azure supprime automatiquement l’identité. Par défaut, seule cette ressource Azure peut utiliser cette identité pour demander des jetons à Microsoft Entra ID.
  • Une identité managée affectée par l’utilisateur peut également créer une identité managée en tant que ressource Azure autonome en créant une identité managée affectée par l’utilisateur et en l’affectant à une ou plusieurs instances d’un service Azure. Une identité managée affectée par l’utilisateur est gérée séparément des ressources qui l’utilisent.

Pour plus d’informations, consultez les articles et la vidéo suivants :

2. Ajouter un principal de service à une organisation Azure DevOps

Une fois que vous avez configuré les principaux de service dans le Centre d’administration Microsoft Entra, vous devez faire de même dans Azure DevOps en ajoutant les principaux de service à votre organisation. Vous pouvez les ajouter via la page Utilisateurs ou avec les API ServicePrincipalEntitlements. Comme ils ne peuvent pas se connecter de manière interactive, un compte d’utilisateur qui peut ajouter des utilisateurs à un organization, un projet ou une équipe doit les ajouter. Ces utilisateurs incluent les administrateurs de collection de projets (PCA) ou les administrateurs de projets et les administrateurs d’équipe lorsque la stratégie « Autoriser les administrateurs d’équipe et de projet à inviter de nouveaux utilisateurs » est activée.

Conseil

Pour ajouter un principal de service au organization, entrez le nom d’affichage de l’application ou de l’identité managée. Si vous choisissez d’ajouter un principal de service par programmation via l’APIServicePrincipalEntitlements, veillez à transmettre l’ID d’objet du principal de service et non l’ID d’objet de l’application.

Si vous êtes un PCA, vous pouvez également accorder à un principal de service l’accès à des projets spécifiques et attribuer une licence. Si vous n’êtes pas un CPA, vous devez contacter l’ACP pour mettre à jour les appartenances au projet ou les niveaux d’accès aux licences.

Capture d’écran des principaux de service et des identités managées dans le hub utilisateurs.

Remarque

Vous ne pouvez ajouter qu’une identité managée ou un principal de service pour le locataire auquel votre organisation est connectée. Les mandants de service peuvent être rendus multi-tenants pour accéder à plusieurs locataires à la fois. Les identités managées ne peuvent appartenir qu’à un seul locataire. Pour accéder à une identité managée dans un autre locataire, consultez la solution de contournement dans le FAQ.

3. Définition des autorisations sur un principal de service

Une fois vos principaux de service ajoutés au organization, vous pouvez les traiter de la même manière que les comptes d’utilisateur standard. Vous pouvez attribuer des autorisations directement sur un principal de service, l’ajouter à des groupes de sécurité et des équipes, l’affecter à n’importe quel niveau d’accès et le supprimer du organization. Vous pouvez également utiliser pour effectuer des Service Principal Graph APIs opérations CRUD sur les principaux de service.

La définition de ces autorisations peut différer de la façon dont vous êtes utilisé pour configurer des autorisations d’application dans une application Microsoft Entra pour d’autres ressources Azure. Azure DevOps ne s’appuie pas sur le programme d’installation « Autorisations d’application » disponible pour les inscriptions d’applications via le Portail Azure. Ces autorisations d’application appliquent des autorisations à un principal de service dans toutes les organisations liées à un locataire et n’ont aucune connaissance de l’organisation, du projet ou des autorisations d’objet disponibles dans Azure DevOps. Pour offrir des autorisations plus granulaires aux principaux de service, nous nous appuyons sur notre propre modèle d’autorisations au lieu de l’ID Entra.

4. Gestion d’un principal de service

La gestion des principaux de service diffère des comptes d’utilisateur des manières clés suivantes :

  • Les principaux de service n’ont pas d’e-mails et, par conséquent, ils ne peuvent pas être invités à un organization par e-mail.
  • Les règles de groupe pour les licences ne s’appliquent actuellement pas aux principaux de service. Si vous souhaitez affecter un niveau d’accès à un principal de service, il est préférable de le faire directement.
  • Les principaux de service peuvent être ajoutés aux groupes Microsoft Entra (dans le portail Azure). Il existe actuellement une limitation technique nous empêchant d’être en mesure de les afficher dans une liste des membres du groupe Microsoft Entra. Cette limitation n’est pas vraie pour les groupes Azure DevOps. Cela dit, un principal de service hérite toujours des autorisations de groupe définies sur un groupe Microsoft Entra auquel ils appartiennent.
  • Les utilisateurs d’un groupe Microsoft Entra ne font pas partie immédiatement d’une organisation Azure DevOps, car un administrateur crée un groupe et y ajoute un groupe Microsoft Entra. Nous avons un processus appelé « matérialisation » qui se produit une fois qu’un utilisateur d’un groupe Microsoft Entra se connecte à l’organisation pour la première fois. Un utilisateur qui se connecte à un organization nous permet de déterminer quels utilisateurs doivent recevoir une licence. Étant donné que la connexion n’est pas possible pour les principaux de service, un administrateur doit l’ajouter explicitement à un organization comme décrit précédemment.
  • Vous ne pouvez pas modifier le nom d’affichage ou l’avatar d’un principal de service sur Azure DevOps.
  • Les directeurs de service obtiennent des licences dans chaque organisation à laquelle ils sont ajoutés, même si la facturation multi-organisations est sélectionnée.

5. Obtenir un jeton d’ID Microsoft Entra

(a) Acquérir un jeton d’ID Microsoft Entra par programmation

L’acquisition d’un jeton d’accès pour une identité managée peut être effectuée en suivant la documentation microsoft Entra ID. Voir les exemples de mandants de service et d'identités gérées.

Le jeton d’accès retourné est un jeton web JSON (JWT) avec les rôles définis, qui peut être utilisé pour accéder aux ressources de l'organisation en utilisant le jeton comme Bearer.

(b) Acquérir un jeton d’ID Microsoft Entra avec Azure CLI

Pour les opérations ad hoc, il peut être plus facile d’acquérir un jeton d’ID Microsoft Entra unique via Azure CLI. Cette approche est recommandée pour les opérations qui n’ont pas besoin d’un jeton persistant pour être régulièrement pivotées, comme les appels d’API ou les opérations de clone Git.

conditions préalables requises

  • id de locataire Azure et id d’abonnement: vérifiez que l’abonnement est associé au locataire connecté à l’organisation Azure DevOps que vous essayez d’accéder. Si vous ne connaissez pas votre locataire ou votre ID d’abonnement, vous pouvez le trouver dans le portail Azure .
  • ID client d’application Azure et secret client
  • Azure CLI

Ces instructions sont fournies par la documentation Databricks et des informations supplémentaires sont disponibles sur leur page .

  1. Connectez-vous à Azure CLI en tant que principal de service à l’aide de la commande az devops login.
  2. Suivez les instructions à l’écran et terminez la connexion.
# 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. Définissez le bon abonnement correct pour le principal de service connecté en entrant la commande :
az account set -s <subscription-id>
  1. Générez un jeton d’accès Microsoft Entra ID avec le az account get-access-token l’ID de ressource Azure DevOps : 499b84ac-1321-427f-aa17-267ca6975798.
$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv
  1. Maintenant, vous pouvez utiliser az cli des commandes par habitude. Essayons d'appeler une API Azure DevOps en la passant dans les en-têtes sous la forme d'un jeton 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

Remarque

Utilisez l’ID d’application Azure DevOps, et non notre URI de ressource, pour générer des jetons.

6. Utiliser le jeton d’ID Microsoft Entra pour s’authentifier auprès des ressources Azure DevOps

Dans l’exemple vidéo suivant, nous passons de l’authentification avec un PAT à l’utilisation d’un jeton d’un principal de service. Nous commençons par utiliser une clé secrète client pour l’authentification, puis nous passons à l’aide d’un certificat client.

Un autre exemple montre comment se connecter à Azure DevOps à l’aide d’une identité managée affectée par l’utilisateur au sein d’une fonction Azure.

Suivez ces exemples en recherchant le code d’application dans notre collection d’exemples d’applications.

Certains scénarios courants d’authentification avec des principaux de service en plus d’effectuer des appels d’API REST Azure DevOps se trouvent dans ces documents :

Comment les principaux de service diffèrent-ils des utilisateurs ?

  • Vous ne pouvez pas modifier le nom d’affichage ou l’avatar d’un principal de service sur Azure DevOps.
  • Un principal de service compte comme licence pour chaque organisation à laquelle il est ajouté, même si la facturation multi-organisation est sélectionnée.
  • Les principaux de service ne peuvent pas être propriétaire d’organisation ou créer des organisations.
  • Les principaux de service ne peuvent pas créer de jetons, tels que des jetons d’accès personnels (PAT) ou desclés SSH. Ils peuvent générer leurs propres jetons d’ID Microsoft Entra et ces jetons peuvent être utilisés pour appeler des API REST Azure DevOps.
  • Nous ne prenons pas en charge OAuth Azure DevOps pour les principaux de service.

FAQ

Général

Q : Pourquoi utiliser un principal de service ou une identité managée au lieu d’un PAT ?

R : La plupart de nos clients recherchent un principal de service ou une identité managée pour remplacer un jeton d’accès personnel (PAT) existant. Ces PAT appartiennent souvent à un compte de service (compte d’équipe partagé) qui les utilise pour authentifier une application avec des ressources Azure DevOps. Les PAT doivent faire l’objet d’une rotation laborieuse de temps en temps (minimum 180 jours). Les PAT mal stockés peuvent tomber entre de mauvaises mains et durer le temps de leur durée de vie, souvent plus longue. Les jetons Microsoft Entra expirent toutes les heures, ce qui limite le facteur de risque global lors de la fuite. Pour les scénarios PAT courants, nous partageons des exemples sur la façon d'explorer l’utilisation d’un jeton Microsoft Entra à la place.

Vous ne pouvez pas utiliser un principal de service pour créer un jeton d’accès personnel.

Q : Quelles sont les limites de débit sur les principaux de service et les identités managées ?

R : Les mandants de service et les identités gérées ont les mêmes limites de débit que les utilisateurs.

Q : L’utilisation de cette fonctionnalité coûtera-t-elle plus cher ?

R : Les principaux de service et les identités managées sont facturés de la même façon que les utilisateurs, en fonction du niveau d’accès. Un changement notable concerne la façon dont nous traitons la « facturation multi-organisation » pour les principaux de service. Les utilisateurs sont comptés comme une seule licence, quel que soit le nombre d’organisations dans lesquelles ils sont. Les principaux de service sont comptés comme une licence par organization l’utilisateur. Ce scénario est similaire à la « facturation basée sur l’affectation d’utilisateur » standard.

Q : Puis-je ajouter une identité managée à partir d’un autre locataire à mon organization ?

R : Vous pouvez uniquement ajouter une identité managée à partir du même locataire auquel votre organization est connecté. Toutefois, nous avons une solution de contournement qui vous permet de configurer une identité managée dans le « locataire de ressources », où sont toutes vos ressources. Ensuite, vous pouvez l’activer pour être utilisé par un principal de service dans le « locataire cible », où votre organisation est connectée. Effectuez les étapes suivantes comme solution de contournement :

  1. Créez une identité managée affectée par l’utilisateur dans Portail Azure pour votre locataire de ressource.
  2. Connectez-le à une machine virtuelle et attribuez-lui cette identité managée .
  3. Créez un coffre de clés et générez un certificat (ne peut pas être de type « PEM »). Lorsque vous générez ce certificat, un secret portant le même nom est également généré, que nous utiliserons ultérieurement.
  4. Accordez l’accès à l’identité managée afin qu’elle puisse lire la clé privée à partir du coffre de clés. Créez une stratégie d’accès dans le coffre de clés avec les autorisations « Obtenir/Répertorier » (sous « Autorisations secrètes » et recherchez l’identité managée sous « Sélectionner le principal ».
  5. Téléchargez le certificat créé au format « CER », ce qui garantit qu’il ne contient pas la partie privée de votre certificat.
  6. Créez une inscription d’application dans le locataire cible.
  7. Chargez le certificat téléchargé dans cette nouvelle application sous l’onglet « Certificats & secrets ».
  8. Ajoutez le principal de service de cette application à l’organisation Azure DevOps que nous voulons y accéder et n’oubliez pas de configurer le principal de service avec toutes les autorisations requises.
  9. Obtenez un jeton d’accès Microsoft Entra à partir de ce principal de service qui utilise le certificat d’identité managée avec cet exemple de code :

Remarque

Renouvelez toujours régulièrement vos certificats.

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

Erreurs potentielles

Le référentiel Git portant le nom ou l’identificateur « {repoName} » n’existe pas ou vous n’avez pas d’autorisations pour l’opération que vous tentez.

Vérifiez que le principal de service dispose au moins d’une licence « De base » pour accéder aux référentiels. Une licence « Partie prenante » n’est pas suffisante.

Échec de la création du principal de service avec l’ID d’objet « {provided objectId} »

Il n’existe aucun principal de service avec le provided objectId dans le locataire connecté à votre organization. Une raison courante est que vous transmettez l’ID d’objet de l’inscription de l’application, au lieu de l’ID d’objet de son principal de service. N’oubliez pas qu’un principal de service est un objet qui représente l’application pour un locataire donné, ce n’est pas l’application elle-même. Le service principal object ID se trouve dans la page « Applications d’entreprise » de votre locataire. Recherchez le nom de l’application et sélectionnez le résultat « Application d’entreprise » qui retourne. Ce résultat correspond à la page du principal de service/application d’entreprise et vous pouvez utiliser l’ID d’objet trouvé sur cette page pour créer un principal de service dans Azure DevOps.

Accès refusé : {ID of the caller identity} a besoin des autorisations suivantes sur les utilisateurs de la ressource pour effectuer cette action : Ajouter des utilisateurs

Cette erreur peut être due à l’une des raisons suivantes :

L'API Graph List d'Azure DevOps renvoie une liste vide, alors que nous savons qu'il existe des entités de service dans l'organisation.

L’API Liste Graph Azure DevOps peut renvoyer une liste vide, même s’il existe encore plus de pages d’utilisateurs à retourner. Utilisez le continuationToken pour itérer dans les listes et vous pouvez éventuellement trouver une page dans laquelle les principaux de service sont retournés. Si un continuationToken est retourné, cela signifie qu’il y a plus de résultats disponibles via l’API. Bien que nous ayons des plans pour améliorer cette logique, à ce stade, il est possible que les premiers résultats X retournent vides.

TF401444 : connectez-vous au moins une fois en tant que {tenantId'tenantId\servicePrincipalObjectId'} dans un navigateur web pour activer l’accès au service.

Si le principal de service n’a pas été invité à l’organisation, vous pouvez rencontrer l’erreur suivante. Vérifiez que le principal de service est ajouté à l’organisation appropriée et dispose de toutes les autorisations nécessaires pour accéder aux ressources requises.