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

Cet article présente la façon dont vous vous connecteriez à une API d’entreprise mutualisée sécurisée avec Azure Active Directory à partir d’une solution SharePoint Framework. Il décrit la création et la sécurisation de l’API ainsi que la création de la solution SharePoint Framework.

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

Commencez par créer une API d’entreprise mutualisée sécurisée avec Azure Active Directory. Bien qu’il n’existe aucune restriction sur la façon dont l’API doit être implémentée du point de vue SharePoint Framework, dans ce didacticiel, vous allez créer l’API à l’aide des fonctions Azure et la sécuriser à l’aide de l’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 application de fonction.

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, créez une fonction déclenchée par HTTP. Dans cet exemple, vous allez la créer à l’aide de C#, mais il n’existe aucune restriction quant au langage de programmation que vous pouvez utiliser.

Dans la Function App, sélectionnez le bouton Ajouter et, dans la liste des types de fonctions disponibles, choisissez déclencheur HTTP.

Lien « DÉCLENCHEUR HTTP » mis en évidence dans le portail Azure

Dans les paramètres de la fonction, spécifiez le nom de la fonction et définissez le niveau d’autorisation sur Anonyme.

Paramètres pour la nouvelle fonction Azure sur le portail Azure

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éfinissez 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.

Pour confirmer vos paramètres et créer la fonction, sélectionnez le bouton Créer une fonction.

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

using System.Net;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)
{
    log.Info("C# HTTP trigger function processed a request.");

    return req.CreateResponse(HttpStatusCode.OK, 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 fonctionne correctement, en sélectionnant le bouton Tester et exécuter, puis en cliquant sur Exécuter.

Bouton « Tester et exécuter » mis en évidence dans le portail Azure

Si la fonction est exécutée correctement, OK (code d’état HTTP : 200) s’affiche ainsi que les commandes de liste dans le volet de test.

Bouton « Ok » mis en évidence dans le portail Azure

Secure Azure Function

Maintenant que la fonction Azure fonctionne, l’étape suivante consiste à la sécuriser avec Azure Active Directory afin que pour y accéder, vous devrez vous connectez avec votre compte d’organisation.

Dans le panneau Function App, dans le panneau latéral, sélectionnez le lien Authentification/Autorisation.

Lien « Authentification / Autorisation » mis en évidence sur le panneau Function App dans le portail Azure

Sur le panneau Authentification/Autorisation, activez l’authentification App Service en faisant passer le bouton bascule Authentification App Service sur Activé.

In the Action to take when request not authenticated drop-down, change the value to Log in with Azure Active Directory.

Ce paramètre garantit que les demandes anonymes à l’API ne sont pas autorisées.

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

« Azure Active Directory » est mis en évidence dans la liste des fournisseurs d’authentification pour une Function App

Sur le panneau Paramètres Azure Active Directory, pour la première option Mode d’administration, sélectionnez Express. Pour la deuxième option Mode d’administration, sélectionnez Créer une application AD.

Panneau Paramètres Azure Active Directory ouvert pour une Function App dans le portail Azure

Confirmez votre choix en sélectionnant le bouton OK.

Important

Avant de poursuivre, notez la valeur figurant dans le champ Créer une application. Cette valeur représente le nom de l’application Azure AD que vous utiliserez pour sécuriser l’API et dont vous aurez besoin ultérieurement pour demander des autorisations d’accès à l’API à partir du projet SharePoint Framework.

Mettez à jour les paramètres d’authentification et d’autorisation Function App en sélectionnant le bouton Enregistrer.

Bouton « Enregistrer » mis en évidence sur le panneau « Authentification / Autorisation » pour une Function App dans le portail Azure

Vérifiez que l’API est sécurisée correctement en ouvrant une nouvelle fenêtre de navigateur en mode privé et en accédant à l’API. Si les paramètres d’authentification ont été appliqués correctement, vous êtes redirigé vers la page de connexion Azure AD.

Page de connexion Azure AD

Modification d’une application Azure AD en application mutualisée

Par défaut, lorsque vous sécurisez une fonction Azure à l’aide d’une application Azure AD, cette fonction Azure peut être utilisée uniquement par les utilisateurs du même répertoire Azure AD que celui où se trouve l’application. Si vous souhaitez utiliser l’API dans différents clients, vous devez modifier l’application Azure AD pour qu’elle soit mutualisée.

Modification de l’application pour qu’elle soit mutualisée

Go to the home page of the Azure portal and search for Azure Active Directory

Azure AD

Dans le bord gauche, sélectionnez Inscriptions d’application et sélectionnez l’application qui a été créée automatiquement lors de la création de l’application de fonction.

Bouton « Inscriptions d’applications » mis en évidence dans le portail Azure

Dans l’api Exposer, mettez à jour le champ URI ID de l’application, modifiez l’ID de votre application Azure AD, afin qu’elle commence par, par https://yourtenant.onmicrosoft.com exemple, https://contoso.onmicrosoft.com/contoso-api . Cette modification est requise, car votre application Azure AD sera utilisée par d’autres clients, et il sera nécessaire de garantir son unicité dans tous les répertoires Azure Active Directory.

URI de l’ID d’application dans le portail Azure

Dans la vue d’ensemble, cliquez sur le lien Types de comptes pris en charge, qui sera Mon organisation uniquement. Nous devons le modifier afin de rendre l’application multi-tension.

Bouton « Types de comptes pris en charge » mis en évidence dans le portail Azure

Basculez la valeur du champ multi-locataires sur Oui:

Bouton « Enregistrer » mis en évidence dans l’authentification

Pour finir, confirmez vos changements en sélectionnant le bouton Enregistrer dans la barre d’outils.

Autorisation donnée aux utilisateurs d’autres répertoires Azure AD d’utiliser vos applications

Étant donné que vous avez sécurisé votre API à l’aide des paramètres express d’Azure AD, seuls des utilisateurs du même répertoire Azure AD que celui où se trouve l’application, sont autorisés à l’utiliser. Étant donné que vous souhaitez que l’API soit utilisée par les utilisateurs d’autres clients également, vous devez ajuster les paramètres de sécurité.

Fermez tous les palettes ouvertes jusqu’à ce que vous retentiez sur le blade Authentication/Authorization de l’application Function. Dans la liste des fournisseurs d’authentification, choisissez Azure Active Directory.

« Azure Active Directory » mis en évidence dans la liste des fournisseurs d’authentification Function App

Sur le panneau Paramètres Azure Active Directory, modifiez la valeur de l’option Mode d’administration et définissez-la sur Avancé.

Valeur « Avancé » pour le « Mode d’administration » mise en évidence dans les paramètres Azure Active Directory de la Function App

Ensuite, effacez la valeur dans le champ URL de l’émetteur. Cela permet aux utilisateurs d’autres répertoires Azure Active Directory de s’authentifier auprès de votre API.

Avant de confirmer vos changements, copiez la valeur du champ ID client. Vous en aurez besoin lors de la création de votre partie Web, pour demander un jeton d’accès pour l’API.

Confirmez vos modifications à l’aide du bouton OK et confirmez vos modifications à l’aide du bouton Enregistrer.

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’Azure Function Apps ne peuvent pas être appelées à partir d’autres domaines. Vous pouvez modifier cela en ajustant les paramètres CORS de la Function App.

Dans la Function App, cliquez sur le lien CORS.

Lien « CORS » mis en évidence sous l’onglet Fonctionnalités de la plateforme de la Function App

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

URL du client SharePoint ajouté à la liste des origines autorisés dans les paramètres CORS de la Function App

Confirmez vos changements à l’aide du bouton Enregistrer.

Pour que les utilisateurs de votre client peuvent utiliser l’API à partir d’un autre client, l’API doit être approuvée. L’approbation, également connue sous le nom de consentement, peut être effectuée à deux niveaux : utilisateur et administrateur (organisation). Dans ce scénario, vous utiliserez le consentement de l’administrateur pour approuver l’API à utiliser par l’ensemble de l’organisation.

Notes

En règle générale, le site qui expose l’API vous guide dans le processus de consentement de l’API dans votre client. Dans cet exemple, vous allez effectuer manuellement les étapes nécessaires pour mieux comprendre le fonctionnement du processus.

Dans le panneau Function App, sélectionnez votre fonction.

Pour obtenir l’URL de la fonction, dans la barre d’outils, sélectionnez l’option Obtenir l’URL de la fonction.

Option « Obtenir l’URL de la fonction » mise en évidence dans la barre d’outils du panneau Function App

Dans la boîte de dialogue Obtenir l’URL de la fonction, copiez l’URL de la fonction en utilisant le bouton Copier.

Bouton « Copier » mis en évidence dans la boîte de dialogue Obtenir l’URL de la fonction

Dans une nouvelle fenêtre de navigateur, accédez à l’URL de fonction que vous avez copiée. Lorsque vous êtes invité à vous connecter, utilisez le compte d’administrateur du client Office 365, dans lequel vous souhaitez utiliser l’API.

Une fois la connexion ouverte, vous êtes invité à consentir à l’utilisation de cette API.

Invitation de consentement pour l’API d’entreprise

Il s’agit toutefois du consentement de l’utilisateur. Pour basculer vers le consentement de l’administrateur et approuver l’API à utiliser par l’ensemble de l’organisation,&l’URL prompt=admin_consent. Une fois encore, une boîte de dialogue de consentement s’invite, mais notez que cette fois, la boîte de dialogue indique que l’application aura accès aux ressources spécifiées pour tous les utilisateurs de votre organisation et que personne d’autre ne sera invité.

Confirmez que vous souhaitez que les utilisateurs dans votre organisation utilisent l’API, en sélectionnant le bouton Accepter.

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

Une fois que l’API est configurée et qu’elle fonctionne, l’étape suivante consiste à créer la solution SharePoint Framework qui utilisera cette API.

Avant de continuer, assurez-vous 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 globalement, vous pouvez vérifier la version installée en l’exécutant dans la ligne de commande : npm ls -g --depth=0.

Création d’un projet SharePoint Framework

Commencez par créer un projet SharePoint Framework. Créez un dossier pour votre projet dans la ligne de commande :

md contoso-api

Modifiez le répertoire de travail en exécutant la ligne de commande :

cd contoso-api

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

yo @microsoft/sharepoint

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

  • contoso-api comme nom de solution
  • SharePoint Online uniquement (dernière version) comme packages de référence
  • Utiliser le dossier actuel comme emplacement pour les fichiers
  • Y comme choix pour l’activation du déploiement à l’échelle du client
  • WebPart comme type de composant à créer
  • Commandes comme nom du composant WebPart à créer
  • Affiche les commandes récentes comme description du composant WebPart
  • Aucune infrastructure JavaScript comme infrastructure à utiliser

Générateur Yeoman pour SharePoint Framework dans une fenêtre de terminal

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

Projet SharePoint Framework ouvert dans 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 elles sont inscrites dans la même Azure Active Directory que 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.

Fichier package-solution ouvert dans Visual Studio Code

Ajoutez une nouvelle section nommée webApiPermissionRequests à la propriété solution, 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,
    "webApiPermissionRequests": [
      {
        "resource": "contoso-api",
        "scope": "user_impersonation"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/contoso-api.sppkg"
  }
}

La valeur de la propriété ressource fait référence au nom ou à l’ID de l’application Azure AD utilisée pour sécuriser l’API. L’utilisation du nom est plus lisible et plus facile à gérer au fil du temps. La valeur de la propriété d’étendue spécifie l’étendue d’autorisation dont votre solution a besoin 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.

Notes

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 exposées par l’application et l’audience à qui 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.

Fichier OrdersWebPart.ts ouvert dans Visual Studio Code

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('https://contoso-api.azurewebsites.net')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  // shortened for brevity
}

L’URI transmis dans la méthode est getClient() l’URI d’ID d’application 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('https://contoso-api.azurewebsites.net')
        .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.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 dans SharePoint catalogue d’applications

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

Tout d’abord, créez et créez un package du projet en exécutant dans la ligne de commande :

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

Ensuite, dans l’Explorateur, ouvrez le dossier du projet et accédez au dossier sharepoint/solution.

Dossier du projet « sharepoint/solution » ouvert dans macOS Finder

Dans votre navigateur web, accédez au catalogue d’applications client dans votre Office 365 client.

Catalogue d’applications client affiché dans le navigateur web

Ajoutez le fichier .sppkg** nouvellement généré en le faisant glisser et en le faisant glisser de l’explorateur vers le catalogue d’applications client.

Fenêtre de recherche macOS affichée sur le navigateur web affichant le catalogue d’applications client

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

Octroi de 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.

Option « Administrateur » mise en évidence dans le menu du lanceur d’applications Office 365

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

Option « SharePoint » mise en évidence dans le menu du centre d’administration Office 365

Dans le centre d’administration SharePoint, naviguez vers le nouvel aperçu du centre d’administration SharePoint à l’aide du lien permettant d’essayer le nouvel aperçu du centre d’administration SharePoint.

Lien « Try the new SharePoint admin center » (Essayer le nouveau centre d’administration SharePoint) mis en évidence dans le centre d’administration SharePoint

Dans le nouveau centre d’administration, dans le menu, sélectionnez l’option Gestion des API.

Option « Gestion des API » mise en évidence dans le menu du nouveau centre d’administration SharePoint

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.

Bouton Sélectionner en regard d’une demande d’autorisation mis en évidence sur la page de gestion des API dans le nouveau centre d’administration SharePoint

Ensuite, dans la barre d’outils, sélectionnez l’option Approuver ou rejeter.

Option « Approuver ou rejeter » mise en évidence dans la barre d’outils de la page de gestion des API dans le nouveau centre d’administration SharePoint

Dans le volet latéral, accordez l’accès à l’API en sélectionnant le bouton Approuver.

Bouton « Approuver » mis en évidence dans le panneau latéral pour la gestion d’une demande d’API dans le nouveau Centre d’administration SharePoint

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 client. Dans la barre d’outils, sélectionnez l’option Modifier.

Bouton « Modifier » mis en évidence sur la barre d’outils dans un site d’équipe moderne

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

Section de page mise en évidence dans le navigateur web

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

« Commandes » tapé dans la boîte à outils. Composant WebPart Commandes affiché dans la boîte à outils

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

Liste des commandes récentes récupérée d’une API d’entreprise affichée dans une page SharePoint