Se connecter aux API sécurisées avec Azure AD dans les solutions SharePoint Framework

Article
04/08/2023

Quand vous créez des solutions SharePoint Framework, il se peut que vous deviez vous connecter à une API sécurisée avec Azure Active Directory (Azure AD). SharePoint Framework vous permet de spécifier les autorisations et les applications Azure AD requises par votre solution. Un administrateur général ou SharePoint peut accorder les autorisations nécessaires si elles n’ont pas encore été accordées. En utilisant AadHttpClient, vous pouvez facilement vous connecter à des API sécurisées avec Azure AD sans avoir à implémenter vous-même le flux OAuth.

Vue d’ensemble des autorisations d’API web

Azure AD sécurise un certain nombre de ressources, allant d’Office 365 aux applications métier personnalisées créées par l’organisation. Pour se connecter à ces ressources, les applications doivent obtenir un jeton d’accès valide qui leur octroie l’accès à une ressource particulière. Les applications peuvent obtenir un jeton d’accès dans le cadre du flux d’autorisation OAuth.

Les applications côté client qui ne peuvent pas stocker de code secret, telles que les solutions SharePoint Framework, utilisent un type spécifique de flux OAuth nommé flux implicite OAuth.

Les développeurs qui créent des solutions côté client sont chargés d’implémenter l’autorisation avec le flux implicite OAuth dans leur application. Dans les solutions SharePoint Framework, cette opération est déjà effectuée dans le cadre de l’infrastructure via MSGraphClient et AadHttpClient, les deux ayant été introduits dans SharePoint Framework v1.4.1.

Remarque

Si vous créez des solutions sur une version antérieure à SharePoint Framework v1.4.1, vous pouvez toujours vous connecter aux ressources sécurisées avec Azure AD. Dans ce cas, vous devez implémenter le flux implicite OAuth directement à l’aide des bibliothèques d’authentification par platfomr d’identité Microsoft. Pour en savoir plus, consultez l’article Se connecter à l’API sécurisée avec Azure Active Directory.

Dans le cadre de SharePoint Framework, un processus spécifique est défini pour permettre aux développeurs de demander des autorisations et aux administrateurs de gérer les autorisations pour accéder aux ressources sécurisées avec Azure AD. Le schéma suivant illustre ce processus.

Schéma illustrant le flux de demande, d’octroi et d’utilisation d’autorisations dans les applications Azure AD

Les développeurs qui créent une solution SharePoint Framework qui nécessite l’accès à certaines ressources sécurisées avec Azure AD répertorient ces ressources, ainsi que les étendues d’autorisation requises dans le manifeste de la solution. Quand il déploie le package de solution dans le catalogue d’applications, SharePoint crée des demandes d’autorisations et invite l’administrateur à gérer les autorisations demandées. Les administrateurs généraux ou SharePoint peuvent décider d’accorder ou de refuser chaque autorisation demandée.

Toutes les autorisations sont octroyées entièrement au client, et non à une application spécifique les ayant demandées. Quand l’administrateur accorde une autorisation spécifique, celle-ci est ajoutée à l’application Azure AD d’extensibilité client SharePoint Online, qui est fournie par Microsoft dans chaque instance Azure AD et qui est utilisée par SharePoint Framework dans le flux OAuth pour fournir aux solutions des jetons d’accès valides.

Découvrez les autorisations et les applications disponibles.

L’instance Azure AD cible qui sécurise votre client Office 365 détermine les applications auxquelles vous pouvez demander des autorisations dans votre solution. La liste d’applications disponibles peut varier selon la licence Office 365 utilisée par l’organisation et selon les applications métier inscrites dans Azure AD. Si vous disposez des autorisations nécessaires, vous pouvez déterminer de différentes manières quelles sont les applications et les étendues d’autorisation disponibles dans votre locataire.

Utiliser le portail Azure ou le Centre d’administration Azure AD

L’une des manières de déterminer les applications disponibles dans Azure AD consiste à accéder au portail Azure ou au Centre d’administration Azure AD.

Dans le Centre d’administration Azure AD, dans le volet de navigation de gauche, sélectionnez le lien Applications d’entreprise.
Dans le panneau Applications d’entreprise, dans le groupe Gérer, sélectionnez le lien Toutes les applications.
Pour rechercher rapidement l’application à laquelle vous souhaitez vous connecter, vous pouvez filtrer la recherche par type d’application (Applications Microsoft ou Applications d’entreprise), ou la rechercher en entrant son nom ou son ID.

Par exemple, si vous souhaitez demander d’autres autorisations pour Microsoft Graph, recherchez graph dans la zone de recherche.
Une fois l’application trouvée, sélectionnez-la pour obtenir des informations supplémentaires. Dans le panneau de l’application, dans le groupe Gérer, sélectionnez Propriétés pour ouvrir les propriétés de l’application.
Dans la liste des propriétés, copiez la valeur de la propriété ID d’objet dont vous avez besoin pour demander des étendues d’autorisation supplémentaires à Microsoft Graph. Au lieu de cela, vous pouvez plutôt copier le nom de l’application et l’utiliser dans la demande d’autorisation.

Remarque

Tandis que l’ID d’objet est unique pour chaque client, le nom de l’application est identique sur tous les clients. Si vous voulez créer une seule fois votre solution et la déployer sur différents clients, vous devez utiliser le même nom d’application lorsque vous demandez des autorisations supplémentaires dans votre solution.

Utilisation d’Azure PowerShell

Remarque

Avant de procéder aux étapes suivantes, installez Azure PowerShell. Sinon, vous pouvez exécuter les cmdlets mentionnées dans cette section dans Azure Cloud Shell PowerShell.

Connectez-vous à votre abonnement Azure en exécutant PowerShell (cette opération n’est pas nécessaire si vous utilisez Azure Cloud Shell) :
```
Login-AzureRmAccount
```
Saisissez ce qui suit pour répertorier les applications disponibles dans votre client :
```
Get-AzureRmADServicePrincipal | sort DisplayName | ft DisplayName, Id
```
L’exécution de cette cmdlet répertorie toutes les applications disponibles dans votre client. Le nom d’affichage et l’ID d’objet de chaque application s’affichent. Vous pouvez les utiliser dans votre solution SharePoint Framework pour demander des autorisations d’application.

Utilisation d’Azure CLI

Remarque

Avant de procéder aux étapes suivantes, installez l’interface de ligne de commande Azure (Azure CLI). Vous pouvez également exécuter Azure CLI via Azure Cloud Shell ou en tant que conteneur Docker.

Si vous exécutez l’interface de ligne de commande (CLI) sur votre ordinateur ou dans un conteneur Docker, commencez par vous connecter à votre abonnement Azure :
```
azure login
```
Une fois connecté, exécutez la commande suivante pour répertorier toutes les applications Azure AD disponibles :
```
azure ad sp list --query "sort_by([*].{displayName: displayName, objectId: objectId}, &displayName)" -o table
```
L’exécution de cette commande répertorie toutes les applications Azure AD disponibles dans votre client par nom d’affichage. La commande affiche le nom d’affichage (displayName) et l’ID d’objet (objectId) de chaque application. De plus, la sortie est affichée sous forme de tableau.

Obtenir la liste des étendues d’autorisation présentées par l’application

Chaque application Azure AD expose un certain nombre d’étendues d’autorisation. Ces étendues d’autorisation concernent souvent des ressources spécifiques ou des opérations au sein de l’application. Pour obtenir la liste des autorisations disponibles pour l’application à laquelle vous voulez vous connecter, consultez sa documentation. Pour obtenir la liste des étendues d’autorisation disponibles dans Microsoft Graph, consultez l’article Référence des autorisations de Microsoft Graph.

Demander des autorisations pour une application Azure AD

Si votre solution SharePoint Framework nécessite des autorisations pour accéder à certaines ressources sécurisées avec Azure AD, comme Microsoft Graph ou des applications d’entreprise, vous pouvez spécifier ces ressources et les autorisations nécessaires dans la configuration de votre solution.

Dans votre projet SharePoint Framework, ouvrez le fichier config/package-solution.json.
Pour la propriété solution, ajoutez la propriété webApiPermissionRequests qui répertorie toutes les ressources et les autorisations correspondantes requises par votre solution.

Vous trouverez ci-dessous un exemple de solution SharePoint Framework qui demande l’accès en lecture aux calendriers de l’utilisateur à l’aide de Microsoft Graph :
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}
```
Remarque

Pour la valeur de la propriété resource, vous devez spécifier le nom d’affichage (displayName) de l’application pour laquelle vous souhaitez demander des autorisations d’accès. Si vous spécifiez la ressource à l’aide de son objectId, vous obtiendrez une erreur lorsque vous tenterez d’approuver la demande d’autorisation.

Si vous souhaitez demander plusieurs étendues d’autorisation pour la ressource donnée, spécifiez chaque étendue dans une entrée distincte, par exemple :

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "User.ReadBasic.All"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}

Quand cette solution est déployée sur le catalogue d’applications SharePoint, l’administrateur est invité à vérifier les autorisations demandées, puis à les accorder ou les refuser.

Remarque

La solution peut être déployée et utilisée sur les sites, peu importe que l’administrateur refuse ou approuve les autorisations demandées. Lorsque vous créez des solutions qui nécessitent des autorisations supplémentaires, vous ne devez jamais partir du principe que les autorisations demandées ont été accordées.

Gérer les demandes d’autorisation

Lorsque vous déployez de solutions SharePoint Framework qui demandent des autorisations aux applications Azure AD, les administrateurs sont invités à gérer la demande d’autorisation fournie avec la solution. Les demandes d’autorisations peuvent être gérées de plusieurs façons.

Gérer les autorisations dans le nouveau Centre d’administration SharePoint

Pour découvrir comment utiliser la page Accès aux API dans le nouveau Centre d’administration SharePoint, ConsultezGérer l’accès aux API Azure AD sécurisées.

Gérer les autorisations avec PowerShell

Les administrateurs généraux et SharePoint peuvent utiliser SharePoint Online Management Shell pour gérer les autorisations et les demandes d’autorisations dans SharePoint Online.

Pour afficher toutes les demandes d’autorisations en attente, utilisez la cmdlet Get-SPOTenantServicePrincipalPermissionRequests. Pour chaque demande d’autorisation, la cmdlet répertorie son ID (requis pour approuver ou refuser la demande), la ressource pour laquelle les autorisations ont été demandées et les autorisations demandées.

Remarque

SharePoint ne vérifie pas si les autorisations demandées ont déjà été octroyées ou pas. Par conséquent, avant d’approuver ou de refuser une demande d’autorisation, vérifiez quelles autorisations ont déjà été accordées dans votre client.
Pour approuver la demande d’autorisation spécifique, utilisez l’applet de commande Approve-SPOTenantServicePrincipalPermissionRequest -RequestId <GUID> , en spécifiant l’ID de la demande d’autorisation que vous souhaitez approuver.

Remarque

Si vous essayez d’approuver une demande pour une autorisation qui a déjà été octroyée, vous obtenez une erreur.
Pour refuser une demande d’autorisation (si l’autorisation demandée a déjà été accordée ou si la demande est contraire aux stratégies de votre organisation), utilisez l’applet de commande Deny-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid> , en spécifiant l’ID de la demande d’autorisation que vous souhaitez refuser.

Remarque

Le refus d’une demande d’autorisation émise par une application SharePoint Framework n’empêche pas cette application d’être déployée dans le catalogue d’applications et d’être installée sur des sites.
Pour afficher les autorisations qui ont été accordées sur votre client, utilisez la cmdlet Get-SPOTenantServicePrincipalPermissionGrants. Pour chaque autorisation accordée, la cmdlet affiche les informations suivantes :
- ClientId : ID d’objet du principal de service auquel le consentement a été accordé pour emprunter l’identité de l’utilisateur quand il accède à la ressource (représentée par l’ID de ressource).
- ConsentType : détermine si le consentement a été donné par l’administrateur pour l’organisation ou s’il a été donné par un individu. Les valeurs possibles sont « AllPrincipals » ou « Principal ».
- ObjectId : identificateur unique pour l’octroi de l’autorisation.
- Resource : ressource pour laquelle le droit d’accès a été accordé.
- ResourceId : ID d’objet du principal de service de la ressource pour laquelle le droit d’accès a été accordé.
- Scope : valeur de la revendication d’étendue attendue par l’application de ressource dans le jeton d’accès OAuth 2.0.
Pour révoquer une autorisation précédemment accordée, utilisez l’applet de commande Revoke-SPOTenantServicePrincipalPermission -ObjectId <String> . Dans le paramètre ObjectId, spécifiez l’élément objectId de l’autorisation accordée à révoquer, que vous pouvez obtenir à l’aide de la cmdlet Get-SPOTenantServicePrincipalPermissionGrants.

Remarque

Révoquer une autorisation ne déclenche pas de modification du catalogue d’applications ni d’aucune autre application déployée. La seule conséquence d’une révocation d’autorisation est qu’aucune application utilisée dans le client ne sera en mesure de se connecter aux ressources pour lesquelles l’autorisation a été révoquée.

Gérer les autorisations à l’aide de l’interface CLI pour Microsoft 365

Les administrateurs généraux ou SharePoint peuvent utiliser l’interface de ligne de commande CLI pour Microsoft 365 pour gérer les autorisations et les demandes d’autorisations dans SharePoint Online.

Remarque

L’interface CLI pour Microsoft 365 est une solution open source pour laquelle un support est assuré par la communauté active. Il n’existe pas de contrat SLA Microsoft pour le support technique relatif à cet outil open source.

Pour afficher toutes les demandes d’autorisations en attente, utilisez la commande spo serviceprincipal permissionrequest list. Pour chaque demande d’autorisation, la commande répertorie son ID (requis pour approuver ou refuser la demande), la ressource pour laquelle les autorisations ont été demandées et les autorisations demandées.

Remarque

SharePoint ne vérifie pas si les autorisations demandées ont déjà été octroyées ou pas. Par conséquent, avant d’approuver ou de refuser une demande d’autorisation, vérifiez quelles autorisations ont déjà été accordées dans votre client.
Pour approuver une demande d’autorisation spécifique, utilisez la commande spo serviceprincipal permissionrequest approve en indiquant l’ID de la demande d’autorisation à approuver.

Remarque

Si vous essayez d’approuver une demande pour une autorisation qui a déjà été octroyée, vous obtenez une erreur.
Pour refuser une demande d’autorisation (si l’autorisation demandée a déjà été accordée ou ne respecte pas les politiques de votre organisation), utilisez la commande spo serviceprincipal permissionrequest deny en indiquant l’ID de la demande d’autorisation à refuser.

Remarque

Le refus d’une demande d’autorisation émise par une application SharePoint Framework n’empêche pas cette application d’être déployée dans le catalogue d’applications et d’être installée sur des sites.
Pour afficher les autorisations qui ont été accordées dans votre client, utilisez la commande spo serviceprincipal grant list. Pour chaque autorisation accordée, la commande affiche les informations suivantes :
- ObjectId : identificateur unique pour l’octroi de l’autorisation.
- Resource : ressource pour laquelle le droit d’accès a été accordé.
- ResourceId : ID d’objet du principal de service de la ressource pour laquelle le droit d’accès a été accordé.
- Scope : valeur de la revendication d’étendue attendue par l’application de ressource dans le jeton d’accès OAuth 2.0.
Pour révoquer une autorisation accordée précédemment, utilisez la commande spo serviceprincipal grant revoke. Dans le paramètre grantId, spécifiez l’élément objectId de l’autorisation accordée à révoquer, que vous pouvez obtenir à l’aide de la commande spo serviceprincipal grant list.

Remarque

Révoquer une autorisation ne déclenche pas de modification du catalogue d’applications ni d’aucune autre application déployée. La seule conséquence d’une révocation d’autorisation est qu’aucune application utilisée dans le client ne sera en mesure de se connecter aux ressources pour lesquelles l’autorisation a été révoquée.

Se connecter à des applications Azure AD en utilisant AadHttpClient

Introduit dans v1.4.1, SharePoint Framework simplifie la connexion aux API sécurisées avec Azure AD. Avec le nouveau client AadHttpClient, vous pouvez facilement vous connecter à des API sécurisées avec Azure AD sans avoir à implémenter l’authentification et l’autorisation.

En interne, AadHttpClient implémente le flux OAuth Azure AD en tirant parti des bibliothèques d’authentification Plateforme d'identités Microsoft à l’aide du principal du service d’extensibilité du client SharePoint Online pour obtenir un jeton d’accès valide. Le principal de service d’extensibilité client SharePoint Online est mis en service par Microsoft et disponible dans Azure AD sur tous les clients Office 365.

Pour utiliser AadHttpClient dans votre solution SharePoint Framework, ajoutez la clause import suivante dans votre fichier de composant WebPart principal :
```
import { AadHttpClient, HttpClientResponse } from '@microsoft/sp-http';
```
Obtenez une nouvelle instance d’AadHttpClient en transférant la ressource à laquelle vous souhaitez vous connecter sous la forme de paramètres :
```
export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        // connect to the API
      });
  }

  // ...
}
```
Remarque

Chaque instance d’AadHttpClient est associée à une ressource spécifique. C’est pourquoi nous vous recommandons de créer une instance du client pour chaque ressource à laquelle vous souhaitez vous connecter.

Après avoir instancié AadHttpClient pour votre ressource, vous pouvez émettre une demande web pour communiquer avec votre API. Dans cet exemple, l’API renvoie une liste de commandes représentée par l’interface Commande personnalisée qui est définie ailleurs dans le projet :

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        client
          .get('https://contoso.azurewebsites.net/api/orders', AadHttpClient.configurations.v1)
          .then((response: HttpClientResponse): Promise<Order[]> => {
            return response.json();
          })
          .then((orders: Order[]): void => {
            // process data
          });
      });
  }

  // ...
}

Considérations

Vous trouverez par la suite quelques considérations à prendre en compte lorsque vous utilisez les autorisations d’API web.

Demander des autorisations via les solutions SharePoint Framework

Actuellement, vous pouvez demander des autorisations supplémentaires uniquement via une solution SharePoint Framework. La demande est émise quand le package de solution (.sppkg) contenant la demande d’autorisations est déployé dans le catalogue d’applications. Une fois la demande émise, elle peut être approuvée ou refusée par l’administrateur général ou SharePoint.

Les autorisations accordées s’appliquent à toutes les solutions.

Même si les autorisations liées aux ressources Azure AD sont demandées par une solution SharePoint Framework, une fois accordées, elles s’appliquent à l’ensemble du client et peuvent être exploitées par toute solution présente sur ce client.

Supprimer une solution ne révoque pas les autorisations

La suppression de la solution qui a demandé à l’origine une autorisation spécifique n’entraîne pas la révocation de l’autorisation accordée. Les administrateurs doivent révoquer manuellement les autorisations accordées via les demandes d’application SharePoint Framework.

Révoquer les autorisations accordées n’invalide pas les jetons d’accès qui ont été émis

La révocation des autorisations accordées n’invalide pas les jetons d’accès qui ont été émis pour les utilisateurs. Au contraire, ces jetons d’accès restent valides jusqu’à leur expiration.

Les demandes d’autorisations n’ont pas d’impact sur le déploiement de solution

La solution peut être déployée et utilisée sur les sites, peu importe que l’administrateur refuse ou approuve les autorisations demandées par la solution. Lorsque vous créez des solutions qui nécessitent des autorisations supplémentaires, vous ne devez jamais partir du principe que les autorisations demandées ont été accordées.

Contrôler le principal de service client SharePoint Online

Toutes les autorisations accordées via des demandes d’API web sont stockées avec l’application Azure AD d’extensibilité client SharePoint Online. Si les administrateurs refusent que les développeurs utilisent le modèle de demande d’API web, ainsi que MSGraphClient et AadHttpClient dans leurs solutions, ils peuvent désactiver le principal de service d’extensibilité client SharePoint Online via PowerShell en utilisant la cmdlet Disable-SPOTenantServicePrincipal.

Le principal de service peut être réactivé à l’aide de la cmdlet Enable-SPOTenantServicePrincipal. Au lieu de cela, vous pouvez activer et désactiver le principal de service d’extensibilité client SharePoint Online via l’interface de ligne de commande CLI pour Microsoft 365 à l’aide de la commande spo serviceprincipal set.

Se connecter aux API sécurisées avec Azure AD dans les solutions SharePoint Framework

Vue d’ensemble des autorisations d’API web

Découvrez les autorisations et les applications disponibles.

Utiliser le portail Azure ou le Centre d’administration Azure AD

Utilisation d’Azure PowerShell

Utilisation d’Azure CLI

Obtenir la liste des étendues d’autorisation présentées par l’application

Demander des autorisations pour une application Azure AD

Gérer les demandes d’autorisation

Gérer les autorisations dans le nouveau Centre d’administration SharePoint

Gérer les autorisations avec PowerShell

Gérer les autorisations à l’aide de l’interface CLI pour Microsoft 365

Se connecter à des applications Azure AD en utilisant AadHttpClient

Considérations

Demander des autorisations via les solutions SharePoint Framework

Les autorisations accordées s’appliquent à toutes les solutions.

Supprimer une solution ne révoque pas les autorisations

Révoquer les autorisations accordées n’invalide pas les jetons d’accès qui ont été émis

Les demandes d’autorisations n’ont pas d’impact sur le déploiement de solution

Contrôler le principal de service client SharePoint Online

Ressources supplémentaires