API Protection

  • Article

Lorsque vous, en tant que développeur, protégez votre API, votre focus est sur l’autorisation. Pour appeler l’API de votre ressource, les applications doivent acquérir l’autorisation d’application. La ressource elle-même doit appliquer l’autorisation. Dans cet article, vous découvrez les meilleures pratiques pour protéger votre API via l’inscription, la définition d’autorisations et de consentement et l’application de l’accès afin d’atteindre vos objectifs Confiance Zéro.

Inscrire votre API protégée

Pour protéger votre API avec l’ID Microsoft Entra (Microsoft Entra ID), vous devez d’abord inscrire votre API, après quoi vous pouvez gérer vos API inscrites. Dans l’ID Microsoft Entra, une API est une application avec des paramètres d’inscription d’application spécifiques qui le définissent en tant que ressource ou API qu’une autre application peut être autorisée à accéder. Dans le Centre d’administration Microsoft Entra, Microsoft Identity Developer, Les inscriptions d’applications sont des API qui se trouvent dans le locataire en tant qu’API métier ou services provenant de fournisseurs SaaS disposant d’API protégées par protection des ID Microsoft Entra.

Pendant l’inscription, vous définissez la façon dont les applications appelantes font référence à votre API et ses autorisations d’application et déléguées. Une inscription d’application peut représenter une solution qui possède à la fois des applications clientes et des API. Toutefois, dans cet article, nous abordons le scénario dans lequel une ressource autonome expose une API.

Normalement, une API n’effectue pas d’authentification ni demande directement l’autorisation. L’API valide un jeton présenté par l’application appelante. Les API n’ont aucune connexion interactive et vous n’avez donc pas besoin d’enregistrer des paramètres tels que l’URI de redirection ou le type d’application. Les API obtiennent leurs jetons à partir des applications qui appellent ces API, et non en interagissant avec Microsoft Entra ID. Pour les API web, utilisez des jetons d’accès OAuth2 pour l’autorisation. Les API web valident les jetons du porteur pour autoriser les appelants. N’acceptez pas les jetons d’ID comme preuve d’autorisation.

Par défaut, Microsoft Entra ID ajoute User.Read aux autorisations d’API de toute nouvelle inscription d’application. Vous supprimez cette autorisation pour la plupart des API web. Microsoft Entra ID nécessite des autorisations d’API uniquement lorsqu’une API appelle une autre API. Si votre API n’appelle pas une autre API, supprimez l’autorisation User.Read lorsque vous inscrivez votre API.

Vous devez avoir un identificateur unique pour votre API, appelé l’URI d’ID d’application auprès duquel les applications clientes demandent l’autorisation d’appeler votre API afin d’y accéder. L’URI de l’ID d’application doit être unique sur tous les clients Microsoft Entra. Vous pouvez utiliser api://<clientId> (la suggestion par défaut dans le portail), où <clientId> est l’ID d’application de votre API inscrite.

Pour fournir aux développeurs qui appellent votre API avec un nom plus convivial, vous pouvez utiliser l’adresse de votre API comme URI d’ID d’application. Par exemple, vous pouvez utiliser l’emplacement https://API.yourdomain.com où yourdomain.com doit être un domaine d’éditeur configuré dans votre client Microsoft Entra. Microsoft valide que vous possédez le domaine pour pouvoir l’utiliser comme identificateur unique pour votre API. Vous n’avez pas besoin de code à cette adresse. L’API peut être là où vous le souhaitez, mais il est recommandé d’utiliser l’adresse HTTPS de l’API comme URI d’ID d’application.

Définir des autorisations déléguées avec des privilèges minimum

Si votre API va être appelée par des applications qui ont des utilisateurs, vous devez définir au moins une permission déléguée (voir Ajouter une étendue sur l’inscription d’application Exposer une API).

Les API qui fournissent l’accès aux magasins de données d’organisation peuvent attirer l’attention des attaquants qui souhaitent accéder à ces données. Au lieu d’avoir une seule permission déléguée, concevez vos autorisations avec le principe Confiance Zéro du droit d’accès minimal à l’esprit. Il peut être difficile d’accéder à un modèle à privilèges minimum plus tard si toutes les applications clientes commencent par un accès privilégié complet.

Souvent, les développeurs se trouvent dans un modèle d’utilisation d’une autorisation unique comme « accès en tant qu’utilisateur » ou « emprunt d’identité utilisateur » (qui est une expression courante, bien que techniquement inexacte). Les autorisations uniques comme celles-ci autorisent uniquement l’accès complet et privilégié à votre API.

Déclarez les étendues de privilège minimum afin que vos applications ne soient pas vulnérables à la compromission ou utilisées pour effectuer une tâche que vous n’avez jamais prévue. Définissez vos plusieurs étendues dans les autorisations d’API. Par exemple, séparez les étendues de la lecture et de la mise à jour des données et envisagez d’offrir des autorisations en lecture seule. Un « accès en écriture » inclut des privilèges pour les opérations de création, de mise à jour et de suppression. Un client ne devrait jamais exiger d’accès en écriture seulement pour lire des données.

Lorsque votre API travaille avec des données sensibles, prenez en compte les autorisations d’accès « standard » et « complet ». Limitez les propriétés sensibles afin qu’une autorisation standard n’autorise pas l’accès (par exemple). Resource.Read Implémentez ensuite une autorisation d’accès « complet » (par exemple, Resource.ReadFull) qui renvoie les propriétés et les informations sensibles.

Évaluez toujours les autorisations que vous demandez afin de vous assurer que vous recherchez l'ensemble de privilèges le moins élevé possible pour effectuer le travail. Évitez de demander des autorisations de privilège plus élevées. Au lieu de cela, créez une autorisation individuelle pour chaque scénario principal. Reportez-vous à la référence des autorisations Microsoft Graph pour obtenir de bons exemples de cette approche. Recherchez et utilisez uniquement le bon nombre d’autorisations pour répondre à vos besoins.

Dans le cadre de vos définitions d’étendue, déterminez si la plage d’opérations pouvant être effectuée avec une étendue particulière nécessite le consentement de l’administrateur.

En tant que concepteur d’API, vous pouvez fournir des conseils sur les étendues qui peuvent nécessiter en toute sécurité uniquement le consentement de l’utilisateur. Toutefois, les admins client peuvent configurer un locataire afin que toutes les autorisations nécessitent le consentement administrateur. Si vous définissez une étendue nécessitant le consentement administrateur, l’autorisation exige toujours le consentement administrateur.

Lorsque vous décidez du consentement de l’utilisateur ou de l’administrateur, vous avez deux considérations principales :

  1. Indique si la plage d’opérations derrière l’autorisation affecte plus d’un seul utilisateur. Si l’autorisation permet à l’utilisateur de choisir l’application qui peut accéder uniquement à ses informations, il est possible que le consentement de l’utilisateur soit approprié. Par exemple, l’utilisateur peut donner son consentement pour choisir son application préférée pour l’email. Toutefois, si les opérations derrière l’autorisation impliquent plus d’un seul utilisateur (par exemple, l’affichage de profils utilisateur complets d’autres utilisateurs), définissez cette autorisation comme nécessitant le consentement de l’administrateur.

  2. Indique si la plage d’opérations derrière l’autorisation a une étendue. Par exemple, une étendue est lorsqu’une autorisation permet à une application de modifier tout dans un locataire ou de faire quelque chose qui peut être irréversible. Une étendue indique que vous avez besoin du consentement administrateur plutôt que du consentement de l’utilisateur.

Errez du côté conservateur et demandez le consentement de l’administrateur si vous êtes en doute. Décrivez clairement et concis les conséquences du consentement dans vos chaînes d’autorisation. Supposons que la personne qui lit vos chaînes de description n’a aucune connaissance de vos API ou de votre produit.

Évitez d'ajouter vos API aux autorisations existantes d'une manière qui modifie la sémantique de l'autorisation. La surcharge des autorisations existantes dilue le raisonnement sur lequel les clients ont précédemment accordé leur consentement.

Définir les autorisations d’application

Lorsque vous générez des applications non-utilisateur, vous ne disposez pas d’un utilisateur à qui vous pouvez demander d’entrer un nom d’utilisateur et un mot de passe ou de soumettre une authentification multifacteur (MFA). Si des applications sans utilisateur (telles que des charges de travail, des services et des démons) appellent votre API, vous devez définir des autorisations d’application pour votre API. Lorsque vous définissez une autorisation d’application, vous utilisez un rôle d’application au lieu des étendues.

Tout comme les autorisations déléguées, vous fournissez des autorisations d’application granulaires afin que les charges de travail appelant votre API puissent suivre l’accès aux privilèges minimum et s’aligner sur les principes de Confiance Zéro. Évitez de publier un seul rôle d’application (autorisation d’application) et une seule étendue (permission déléguée) ou exposer toutes les opérations à chaque client.

Les charges de travail s’authentifient avec les informations d’identification du client et demandent un jeton à l’aide de l’étendue.default, comme illustré dans l’exemple de code suivant.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

Les autorisations nécessitent le consentement de l’administrateur lorsqu’il n’existe aucun utilisateur devant l’application et lorsque l’autorisation d’application active un large éventail d’opérations.

Appliquer l’accès

Vérifiez que vos API appliquent l’accès en validant et interprétant les jetons d’accès fournis comme jetons du porteur par l’application appelante dans l’en-tête d’autorisation de requête HTTPS. Vous pouvez appliquer l’accès en validant les jetons, en gérant l’actualisation des métadonnées et en appliquant des étendues et des rôles, comme décrit dans les sections suivantes.

Valider les jetons

Une fois que votre API reçoit un jeton, elle doit valider le jeton. La validation garantit que le jeton provient de l’émetteur approprié comme non modifié et non modifié. Vérifiez la signature, car vous n’obtenez pas le jeton directement à partir de Microsoft Entra ID, comme vous le faites avec les jetons d’ID. Validez la signature une fois que votre API reçoit un jeton d’une source non approuvée sur le réseau.

Étant donné qu’il existe des vulnérabilités connues autour de la vérification de la signature de jeton Web JSON, utilisez une bibliothèque de validation de jeton standard bien gérée et établie. Les bibliothèques d’authentification (telles que Microsoft-Identity.Web) utilisent les étapes appropriées et atténuent les vulnérabilités connues.

Si vous le souhaitez, étendez la validation des jetons. Utilisez la revendication ID de client (tid) pour restreindre les locataires dans lesquels votre API peut obtenir un jeton. Utiliser les revendications azp et appid pour filtrer les applications qui peuvent appeler votre API. Utilisez la revendication ID d’objet (oid) pour affiner davantage l’accès à des utilisateurs individuels.

Gérer l’actualisation de métadonnées

Veillez toujours à ce que votre bibliothèque de validation de jeton gère efficacement les métadonnées requises. Dans ce cas, les métadonnées sont les clés publiques, la paire de clés privées que Microsoft utilise pour signer des jetons Microsoft Entra. Lorsque vos bibliothèques valident ces jetons, elles obtiennent notre liste publiée de clés de signature publiques d’une adresse Internet bien connue. Assurez-vous que l’environnement d’hébergement a le bon minutage pour obtenir ces clés.

Par exemple, les bibliothèques plus anciennes étaient parfois codées en dur pour mettre à jour ces clés de signature publiques toutes les 24 heures. Envisagez quand Microsoft Entra ID doit faire pivoter rapidement ces clés et les clés que vous avez téléchargées n’ont pas inclus les nouvelles clés pivotées. Votre API peut être hors connexion pendant un jour pendant qu’elle attend son cycle d’actualisation des métadonnées. Référencez des conseils d’actualisation des métadonnées spécifiques pour vous assurer que vous obtenez correctement les métadonnées. Si vous utilisez une bibliothèque, assurez-vous qu’elle traite ces métadonnées dans un délai raisonnable.

Appliquer des étendues et des rôles

Une fois votre jeton validé, votre API examine les revendications dans le jeton pour déterminer s’il doit fonctionner.

Pour les jetons de permission déléguée, votre API inspecte la revendication d’étendue (scp) pour voir ce que l’application a le consentement à faire. Inspectez les revendications de l’ID d’objet (oid) ou de la clé d’objet (sub) pour voir l’utilisateur au nom duquel l’application fonctionne.

Votre API case activée ensuite pour vous assurer que l’utilisateur a également accès à l’opération demandée. Si votre API définit des rôles à attribuer à des utilisateurs et des groupes, faites vérifier les revendications de rôles dans le jeton par votre API afin qu’elle se comporte en conséquence. Les jetons d’autorisation d’application n’ont aucune revendication d’étendue (scp). Faites plutôt inspecter la revendication de rôles par votre API pour déterminer les autorisations d’application reçues par la charge de travail.

Après validation par votre API du jeton et des étendues et traitement de l’ID d’objet (oid), de la clé d’objet (sub) et des revendications de rôles, votre API peut retourner les résultats.

Étapes suivantes