Utilisation d’API d’entreprise sécurisées avec Azure AD dans SharePoint Framework

Cet article explique comment se connecter à partir d’une solution SharePoint Framework à une API d’entreprise sécurisée avec Azure Active Directory. Il décrit la création et la sécurisation de l’API, ainsi que la création de la solution SharePoint Framework.

Créer une API d’entreprise sécurisée avec Azure AD

Commencez par créer une API d’entreprise sécurisée avec Azure Active Directory. S’il n’existe aucune restriction quand à la façon d’implémenter l’API côté SharePoint Framework, dans le cadre de ce didacticiel, vous allez créer l’API à l’aide d’Azure Functions et la sécuriser à l’aide d’une authentification Azure App Service.

Votre organisation a probablement déjà des API spécifiques qui exposent ses applications, et cette section a pour objectif de donner un aperçu complet des étapes d’implémentation et de configuration.

Créer une fonction Azure

Dans le portail Azure, créez une Function App.

Pour plus d’informations sur la création d’applications de fonction dans Azure, consultez l’article d’aide Créer une Function App à l’aide du Portail Azure.

Dans la Function App, vous allez créer une fonction déclenchée via HTTP. Dans cet exemple, vous allez créer la fonction en C#. Toutefois, en règle générale, vous pouvez utiliser le langage de programmation de votre choix.

Dans Function App, appuyez sur le bouton Nouvelle fonction :

Dans la liste des modèles, sélectionnez Déclencheur HTTP :

Dans le panneau Nouvelle fonction, spécifiez le nom de la fonction, définissez Niveau d’autorisation sur Anonyme, puis cliquez sur le bouton Créer :

Les fonctions Azure peuvent être sécurisées de différentes façons. Étant donné que vous souhaitez sécuriser la fonction via Azure AD, au lieu de sécuriser la fonction elle-même, vous allez sécuriser la Function App sous-jacente. C’est pourquoi, à ce stade, vous décidez de ne pas sécuriser la fonction elle-même. Les paramètres d’authentification appliqués à la Function App s’appliquent à toutes les fonctions à l’intérieur de cette application.

Une fois la fonction créée, remplacez son contenu par l’extrait de code suivant :

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    return (ActionResult)new OkObjectResult(new List<object> {
        new {
            Id = 1,
            OrderDate = new DateTime(2016, 1, 6),
            Region = "east",
            Rep = "Jones",
            Item = "Pencil",
            Units = 95,
            UnitCost = 1.99,
            Total = 189.05
        },
        new {
            Id = 2,
            OrderDate = new DateTime(2016, 1, 23),
            Region = "central",
            Rep = "Kivell",
            Item = "Binder",
            Units = 50,
            UnitCost = 19.99,
            Total = 999.50
        },
        new {
            Id = 3,
            OrderDate = new DateTime(2016, 2, 9),
            Region = "central",
            Rep = "Jardine",
            Item = "Pencil",
            Units = 36,
            UnitCost = 4.99,
            Total = 179.64
        },
        new {
            Id = 4,
            OrderDate = new DateTime(2016, 2, 26),
            Region = "central",
            Rep = "Gill",
            Item = "Pen",
            Units = 27,
            UnitCost = 19.99,
            Total = 539.73
        },
        new {
            Id = 5,
            OrderDate = new DateTime(2016, 3, 15),
            Region = "west",
            Rep = "Sorvino",
            Item = "Pencil",
            Units = 56,
            UnitCost = 2.99,
            Total = 167.44
        }
    });
}

Vérifiez que la fonction opère correctement en appuyant sur le bouton Enregistrer et exécuter :

Si la fonction a été exécutée correctement, l’étiquette OK (code d’état HTTP : 200) et la liste de commandes s’affichent dans le volet de test.

Sécuriser la fonction Azure

À présent que la fonction Azure est opérationnelle, l’étape suivante consiste à la sécuriser avec Azure Active Directory de façon à ce que soyez obligé de vous connecter avec le compte de votre organisation pour pouvoir y accéder.

Dans le volet latéral du panneau Function Apps, sélectionnez la Function App :

Dans la section supérieure, accédez à l’onglet Fonctionnalités de la plateforme :

Ensuite, dans le groupe Mise en réseau, sélectionnez le lien Authentification / Autorisation :

Dans le panneau Authentification / Autorisation, activez l’authentification App Service en mettant le bouton bascule Authentification App Service en position Activé :

Dans le menu déroulant Action à exécuter quand une demande n’est pas authentifiée, sélectionnez Se connecter avec Azure Active Directory. Ce paramétrage garantit que des demandes anonymes adressées à l’API ne seront pas autorisées :

Ensuite, dans la liste des fournisseurs d’authentification, sélectionnez Azure Active Directory :

Dans le panneau Paramètres d’Azure Active Directory, définissez l’option Mode d’administration sur Express. Définissez la deuxième option Mode d’administration sur Créer une application AD :

Importante

Avant de poursuivre, notez la valeur figurant dans le champ Créer une application. Cette valeur est le nom de l’application Azure AD que vous allez utiliser pour sécuriser l’API. Vous en aurez besoin plus tard pour demander des autorisations d’accès à l’API à partir du projet SharePoint Framework.

Confirmez votre choix en appuyant sur le bouton OK.

Dans le panneau Authentification / Autorisation, mettez à jour les paramètres d’authentification et d’autorisation de la Function App en appuyant sur le bouton Enregistrer :

Vérifiez que l’API est correctement sécurisée en ouvrant une nouvelle fenêtre de navigateur en mode privé, puis en accédant à l’API. L’URL de votre Function App figure dans la section Vue d’ensemble du panneau Function App. Si les paramètres d’authentification ont été correctement appliqués, vous devriez être redirigé vers la page de connexion à Azure AD :

Obtenir l’ID d’une application Azure AD

Pour demander un jeton d’accès pour vous connecter à l’API, vous avez besoin de l’ID de l’application Azure AD utilisé pour sécuriser cette API.

Dans la Function App, accédez aux paramètres d’Authentification. Si le lien Authentification n’est pas disponible sous l’en-tête Fonctionnalités configurées, appuyez sur le bouton Actualiser en regard de la Function App dans le volet gauche :

Dans la liste des fournisseurs d’authentification, sélectionnez Azure Active Directory :

Dans le panneau Paramètres Azure Active Directory, appuyez sur le bouton Gérer l’application :

Dans le panneau de l’application Azure AD, copiez la valeur de la propriété ID d’application :

Activation de CORS

La Function App sera appelée du JavaScript exécuté sur une page SharePoint. Étant donné que l’API est hébergée sur un domaine différent du portail SharePoint, des contraintes de sécurité inter-domaines s’appliqueront à l’appel de l’API. Par défaut, les API implémentées à l’aide d’une Function App Azure ne peuvent pas être appelées à partir d’autres domaines. Vous pouvez modifier cela en ajustant les paramètres CORS de la Function App.

Importante

Si vous authentifiez l’API à l’aide d’un cookie SharePoint Online au lieu d’OAuth, vous ne pouvez pas configurer de paramètres CORS via le portail Azure. Pour que l’authentification fonctionne, vous devez effacer tous les paramètres CORS sur le portail Azure et les spécifier dans votre API.

Dans la Function App, accédez à l’onglet Fonctionnalités de la plateforme.

Dans le groupe API, sélectionnez le lien CORS :

Dans la liste des origines autorisées, ajoutez l’URL de votre client SharePoint, par exemple, https://contoso.sharepoint.com :

Confirmez vos changements en appuyant sur le bouton Enregistrer.

Utiliser l’API d’entreprise sécurisée avec Azure AD à partir de SharePoint Framework

Une fois l’API configurée et fonctionnelle, l’étape suivante consiste à créer la solution SharePoint Framework qui l’utilisera.

Avant de continuer, vérifiez que vous avez installé la version 1.4.1 ou une version ultérieure du générateur Yeoman pour SharePoint Framework. Si vous avez installé le générateur de manière globale, vous pouvez vérifier la version installée en l’exécutant dans la ligne de commande : npm ls -g --depth=0.

Créer un projet SharePoint Framework

Ensuite, vous allez créer un projet SharePoint Framework pour utiliser l’API.

Dans la ligne de commande, créez un dossier pour votre projet :

md contoso-api

Modifiez le répertoire de travail :

cd contoso-api

Pour créer un projet, lancez le générateur Yeoman pour SharePoint Framework :

yo @microsoft/sharepoint

Lorsque vous y êtes invité, utilisez les valeurs suivantes :

• Quel est le nom de votre solution ? contoso-api
• Quels packages de base voulez-vous cibler pour vos composants ? SharePoint Online uniquement (dernière version)
• Où souhaitez-vous placer les fichiers ? Utilisez le dossier actuel
• Voulez-vous autoriser l’administrateur client à choisir de pouvoir déployer la solution sur tous les sites immédiatement sans exécuter de déploiement de fonctionnalité ni ajouter d’applications sur les sites. Oui
• Les composants de la solution nécessiteront-ils des autorisations pour accéder aux API web qui sont uniques et qui ne sont pas partagées avec d'autres composants du client ? Non
• Quel type de composant côté client créer? Composant WebPart
• Quel est le nom de votre composant WebPart ? Commandes
• Quelle est la description de votre composant WebPart ? Afficher les commandes récentes
• Quelle infrastructure voulez-vous utiliser ? Aucune infrastructure JavaScript

Une fois le projet créé, ouvrez-le dans un éditeur de code. Dans ce didacticiel, vous allez utiliser Visual Studio Code :

Demander des autorisations d’accès à l’API d’entreprise

Par défaut, SharePoint Framework n’a pas accès aux API d’entreprise, même si celles-ci sont inscrites dans le même annuaire Azure Active Directory qu’Office 365. Cette approche permet aux organisations de choisir consciemment les API qui doivent être exposées à des scripts et à des solutions côté client déployés sur SharePoint. Pour accéder à vos API d’entreprise, vous devez émettre une demande d’autorisation à partir du projet SharePoint Framework que vous créez.

Dans l’éditeur de code, ouvrez le fichier config/package-solution.json :

À la propriété solution, ajoutez une nouvelle propriété nommée webApiPermissionRequests avec une référence à l’application Azure AD utilisée pour sécuriser votre API :

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "contoso-api-client-side-solution",
    "id": "8cbc01fb-bab6-48fc-afec-2c2053759771",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "webApiPermissionRequests": [
      {
        "resource": "contoso-api-dp20191109",
        "scope": "user_impersonation"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/contoso-api.sppkg"
  }
}

La valeur de la propriété resource fait référence au nom de l’application Azure AD utilisée pour sécuriser l’API. La valeur de la propriété scope indique l’étendue de l’autorisation nécessaire à votre solution pour communiquer avec l’API. Dans ce didacticiel, Azure AD est utilisé uniquement pour sécuriser l’API, donc user_impersonation est l’étendue que vous utiliserez.

Remarque

Si vous souhaitez vous connecter à une API d’entreprise qui a été créée précédemment, contactez votre administrateur pour obtenir des détails sur l’application Azure AD utilisée pour la sécuriser. Vous aurez besoin d’informations telles que l’ID d’application, les autorisations que l’application expose et l’audience pour laquelle elle est configurée.

Se connecter à l’API d’entreprise

Cette dernière partie a trait à l’implémentation de la connexion réelle à l’API d’entreprise.

Dans l’éditeur de code, ouvrez le fichier src\webparts\orders\OrdersWebPart.ts :

Dans la section supérieure du fichier, référencez les classes AadHttpClient et HttpClientResponse en ajoutant l’extrait de code suivant :

import { AadHttpClient, HttpClientResponse } from '@microsoft/sp-http';

Ajoutez une nouvelle variable de classe nommée ordersClient à la classe OrdersWebPart :

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  // shortened for brevity
}

Ensuite, dans la classe OrdersWebPart, remplacez la méthode onInit() pour créer une instance de la classe AadHttpClient :

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  protected onInit(): Promise<void> {
    return new Promise<void>((resolve: () => void, reject: (error: any) => void): void => {
      this.context.aadHttpClientFactory
        .getClient('6bc8bca8-5866-405d-b236-9200bdbb73c0')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  // shortened for brevity
}

Le GUID transmis en tant que deuxième paramètre du constructeur AadHttpClient est l’ID de l’application Azure AD utilisée pour sécuriser l’API d’entreprise.

Pour finir, étendez la méthode render() pour charger et afficher les commandes récupérées de l’API d’entreprise :

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  protected onInit(): Promise<void> {
    return new Promise<void>((resolve: () => void, reject: (error: any) => void): void => {
      this.context.aadHttpClientFactory
        .getClient('6bc8bca8-5866-405d-b236-9200bdbb73c0')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  public render(): void {
    this.context.statusRenderer.displayLoadingIndicator(this.domElement, 'orders');

    this.ordersClient
      .get('https://contoso-api-dp20191109.azurewebsites.net/api/Orders', AadHttpClient.configurations.v1)
      .then((res: HttpClientResponse): Promise<any> => {
        return res.json();
      })
      .then((orders: any): void => {
        this.context.statusRenderer.clearLoadingIndicator(this.domElement);
        this.domElement.innerHTML = `
          <div class="${ styles.orders}">
            <div class="${ styles.container}">
              <div class="${ styles.row}">
                <div class="${ styles.column}">
                  <span class="${ styles.title}">Orders</span>
                  <p class="${ styles.description}">
                    <ul>
                      ${orders.map(o => `<li>${o.rep} $${o.total}</li>`).join('')}
                    </ul>
                  </p>
                  <a href="https://aka.ms/spfx" class="${ styles.button}">
                    <span class="${ styles.label}">Learn more</span>
                  </a>
                </div>
              </div>
            </div>
          </div>`;
      }, (err: any): void => {
        this.context.statusRenderer.renderError(this.domElement, err);
      });
  }

  // shortened for brevity
}

Déployer la solution vers le catalogue d’applications SharePoint

Une fois la solution SharePoint Framework implémentée, il s’agit de la déployer vers SharePoint.

Commencez par créer le projet et générer un package en exécutant la ligne de commande suivante :

gulp bundle --ship && gulp package-solution --ship

Ensuite, dans l’Explorateur de fichiers, ouvrez le dossier du projet, puis accédez au dossier sharepoint/solution :

À l’aide de votre navigateur web, accédez au catalogue d’applications client dans votre locataire Office 365 :

Ajoutez le fichier .sppkg généré en le glissant-déplaçant de l’Explorateur vers le catalogue d’applications client :

Lorsque vous y êtes invité, activez la case à cocher Rendre cette solution disponible pour tous les sites dans l’organisation. Notez également la remarque indiquant que vous devez accéder à la page de gestion des autorisations du principal du service pour approuver les demandes d’autorisation en attente. Confirmez le déploiement en sélectionnant le bouton Déployer.

Octroyer l’accès à l’API d’entreprise

Dans le navigateur web, accédez au site administrateur du client en sélectionnant l’option Administrateur dans le lanceur d’applications Office 365 :

Dans le menu, dans le groupe Centres d’administration, sélectionnez SharePoint :

Dans le Centre d’administration SharePoint, accédez au nouvel aperçu du Centre d’administration SharePoint en suivant le lien permettant d’essayer le nouvel aperçu du Centre d’administration SharePoint :

Dans le menu du nouveau Centre d’administration, sélectionnez l’option Gestion des API :

Dans la page de gestion des API, dans le groupe Approbation en attente, sélectionnez la demande d’autorisation nouvellement ajoutée pour accéder à l’API contoso-api (le nom de votre API s’affiche) :

Ensuite, dans la barre d’outils, appuyez sur le bouton Approve or reject (Approuver ou rejeter) :

Dans le panneau latéral, accordez l’accès à l’API en appuyant sur le bouton Approuver :

Remarque

Il est possible de créer un composant WebPart isolé du domaine qui se connecte à l’API sécurisée avec AAD. Dans ce cas, le CORS de l’API doit être reconfiguré de façon appropriée, car chaque instance de composant WebPart isolé du domaine s’exécute dans une application web dédiée avec un domaine unique.

Ajouter le composant WebPart Commandes à la page

Pour vérifier que tout fonctionne comme prévu, ajoutez à la page le composant WebPart Commandes créé précédemment.

Dans le navigateur web, accédez à un site dans votre locataire. Dans la barre d’outils, sélectionnez l’option Modifier :

Dans le canevas, sélectionnez une section à laquelle ajouter le composant WebPart :

Activez l’option + pour ouvrir la boîte à outils. Dans la zone de recherche, tapez Commandes pour rechercher rapidement le composant WebPart Commandes :

Sélectionnez le composant WebPart Commandes pour l’ajouter à la page. Vous devriez voir la liste des commandes récupérées à partir de l’API d’entreprise :

Si vous voyez s’afficher le message d’erreur « Failed to open pop-up window » (Échec de l’ouverture de la fenêtre contextuelle), cela signifie qu’un bloqueur de fenêtres publicitaires est activé. Pour afficher la page correctement, vous devez désactiver le bloqueur de fenêtres publicitaires du navigateur pour votre site.