Configurer et configurer l’environnement SharePoint Embedded et le projet d’application web
Dans cet exercice, vous allez créer un projet qui contient un composant côté serveur et côté client. Le composant côté serveur est une API REST qui s’authentifie avec l’ID Microsoft Entra et accède aux conteneurs SharePoint Embedded à l’aide de l’API Microsoft Graph. Le composant côté client est une application React monopage qui appelle l’API REST qui expose le contenu du conteneur Incorporé SharePoint.
À la fin de cet exercice, vous disposerez d’un modèle de projet que vous utiliserez pour ajouter d’autres fonctionnalités dans les sections suivantes.
Activer SharePoint Embedded dans votre client Microsoft 365 SharePoint Online
Pour pouvoir utiliser SharePoint Embedded pour créer et inscrire des types de conteneurs, vous devez d’abord l’activer sur votre locataire SharePoint Online. Ce processus doit être effectué à la fois sur le fournisseur et sur les locataires consommateurs où vous définissez votre application et sur tous les locataires consommateurs qui utiliseront votre application SharePoint Embedded.
Remarque
Vous pouvez utiliser le même locataire SharePoint Online que le fournisseur/développeur et le locataire consommateur.
L’activation de SharePoint Embedded sur un locataire SharePoint Online est une opération unidirectionnelle ; il ne peut pas être désactivé. Cela permet de s’assurer que toutes les applications que vous avez créées sur le locataire consommateur continueront de fonctionner.
Une fois que vous avez activé SharePoint Embedded sur un locataire SharePoint Online, vous pouvez créer un type de conteneur dans votre locataire fournisseur et inscrire le type de conteneur dans un locataire consommateur.
Pour activer SharePoint Embedded, accédez au Centre d’administration Microsoft 365 (https://portal.microsoft.com) et connectez-vous avec le compte d’administrateur de votre client Microsoft 365.
Sélectionnez Afficher tout en bas du volet de navigation gauche, puis sélectionnez Centres > d’administration SharePoint.
Ensuite, dans le Centre d’administration SharePoint, sélectionnez Paramètres dans le volet de navigation gauche. Recherchez et sélectionnez SharePoint Embedded. Passez en revue les conditions d’utilisation du service et sélectionnez Activer pour l’activer sur votre locataire SharePoint Online.
Créer une application d’ID Microsoft Entra
Commencez par créer l’application d’ID Microsoft Entra. Il sera utilisé pour authentifier et obtenir les autorisations nécessaires pour appeler les API Microsoft Graph et Microsoft SharePoint.
Ouvrez un navigateur et accédez au Centre d’administration Microsoft Entra (https://entra.microsoft.com). Connectez-vous à l’aide d’un Compte professionnel ou scolaire possédant des droits d’administrateur général sur l’entreprise.
Sélectionnez Gérer > Inscriptions des applications dans la navigation de gauche, puis sélectionnez Nouvelle Inscription.
Sur la page Inscrire une application, définissez les valeurs comme suit, puis sélectionnez Inscrire :
- Nom : Mon SharePoint Embedded
- Types de comptes pris en charge : Comptes de cet annuaire organisationnel uniquement (Andrew Connell Inc. uniquement - Locataire unique)
L’ID Microsoft Entra affiche ensuite les détails de la nouvelle application. Créez un fichier texte pour effectuer le suivi des valeurs dont vous aurez besoin plus loin dans ce module. Copiez l’ID d’application (client) & RÉPERTOIRE (locataire) de la page de vue d’ensemble de l’application dans le fichier texte.
Configurer l’authentification
Configurez ensuite les paramètres d’authentification de l’application. Sélectionnez Gérer > l'authentification dans la navigation de gauche.
Sélectionnez Ajouter une plateforme , puis application monopage.
Dans le volet Configurer une application monopage , définissez les URIhttp://localhost:3000 de redirection sur et sélectionnez Configurer.
Configurer les autorisations d’API
Ensuite, définissez les autorisations dont l’application aura besoin pour pouvoir créer et accéder aux types de conteneurs et aux conteneurs.
Remarque
Au moment de la publication de ce module, pendant la préversion publique de SharePoint Embedded, les deux autorisations dont l’application a besoin ne sont pas encore visibles dans la liste des autorisations dans l’interface web de l’ID Microsoft Entra à sélectionner. Pour contourner cette limitation, ajoutez-les manuellement au manifeste de l’application.
Dans la page Gérer > le manifeste , recherchez la propriété requiredResourceAccess.
La ressource existante avec la resourceAppId valeur définie00000003-0000-0000-c000-000000000000 sur est Microsoft Graph. Ajoutez l’application suivante & autorisation déléguée pour l’étendue FileStorageContainer.Selected . L’autorisation existante qui est déjà présente concerne l’étendue User.Read .
{
"resourceAppId": "00000003-0000-0000-c000-000000000000",
"resourceAccess": [
{
"id": "085ca537-6565-41c2-aca7-db852babc212",
"type": "Scope"
},
{
"id": "40dc41bc-0f7e-42ff-89bd-d9516947e474",
"type": "Role"
}
]
}
Ensuite, ajoutez un nouveau resourceAppId pour SharePoint dont l’ID est 00000003-0000-0ff1-ce00-000000000000, puis ajoutez l’application suivante & autorisations déléguées pour l’étendue Container.Selected :
{
"resourceAppId": "00000003-0000-0ff1-ce00-000000000000",
"resourceAccess": [
{
"id": "4d114b1a-3649-4764-9dfb-be1e236ff371",
"type": "Scope"
},
{
"id": "19766c1b-905b-43af-8756-06526ab42875",
"type": "Role"
}
]
},
Ajouter une autorisation personnalisée à l’application d’ID Microsoft Entra
Ensuite, ajoutez une autorisation personnalisée à l’application afin qu’un administrateur puisse inviter l’utilisateur à autoriser l’application à gérer les conteneurs.
Dans la page Gérer > exposer une API , sélectionnez le lien Définir en regard de l’URI ID d’application. L’ID de l’application sera par défaut api://<app-id>.
Ensuite, sélectionnez Ajouter une étendue afin d’ajouter une nouvelle autorisation pour l’application. Créez une étendue à l’aide des paramètres suivants, puis sélectionnez Ajouter une étendue :
- Nom de l’étendue : Container.Manage
- Qui peut consentir ? Administrateurs uniquement
- Titre du consentement administrateur (utilisateur &) : Gérer les conteneurs SharePoint Embedded.
- Description du consentement administrateur (utilisateur &) : L’application peut appeler l’API de cette application pour gérer les conteneurs de stockage SharePoint Embedded.
- État : activé
Dans l’API web, vous allez ajouter du code pour vous assurer que cette autorisation a été accordée à l’application.
Accorder le consentement de l’administrateur aux nouvelles autorisations
Certaines autorisations nécessitent le consentement de l’administrateur. Dans la page Autorisations de l’API , faites défiler vers le bas de la page, puis sélectionnez le lien Applications d’entreprise.
Dans la page Autorisations , sélectionnez Accorder le consentement administrateur pour Contoso , puis Accepter l’invite pour accorder le consentement administrateur aux deux paires d’autorisations : FileStorageContainer.Selected pour Microsoft Graph et Container.Selected pour SharePoint. Les deux paires représentent l’application & options déléguées pour chacune des deux autorisations.
Créer une clé secrète client
Pour qu’une application s’authentifie à l’aide du flux d’informations d’identification du client OAuth2 avec l’ID Microsoft Entra, elle a besoin de l’ID client et d’une clé secrète client.
Sélectionnez Gérer > Certificats et secrets de la navigation de gauche.
Dans la page Certificats & secrets , sélectionnez l’onglet Secrets client , puis sélectionnez Nouvelle clé secrète client. Définissez une description et sélectionnez une durée d’expiration, puis sélectionnez Ajouter.
Lorsque le secret est créé, il s’affiche une fois. Veillez donc à le copier en tant que clé secrète client dans votre fichier texte local pour une utilisation ultérieure dans ce module. Si vous ne copiez pas cette valeur, vous devrez créer une autre clé secrète, car vous ne pourrez jamais afficher une clé secrète créée précédemment.
Créer le type de conteneur
La dernière étape consiste à créer un type de conteneur. Cette opération peut être effectuée à l’aide du module PowerShell SharePoint Online. Vérifiez que la dernière version est installée en installant...
Install-Module "Microsoft.Online.SharePoint.PowerShell"
... ou en mettant à niveau celle que vous avez installée précédemment pour vous assurer que vous disposez de la dernière version...
Update-Module "Microsoft.Online.SharePoint.PowerShell"
Une fois que vous disposez de la dernière version, connectez-vous à votre site SharePoint Online et créez un type de conteneur :
Mettez à jour les valeurs suivantes dans le script PowerShell suivant, puis exécutez le script :
-
{{SPO_ADMIN_URL}}: IL s’agit de l’URL de votre centre d’administration SharePoint Online. Pour ce faire, connectez-vous au portail Microsoft 365 (https://portal.microsoft.com) avec le compte d’administrateur professionnel et scolaire de votre locataire, sélectionnez Afficher tout en bas du volet de navigation de gauche, puis sélectionnez Centres > d’administration SharePoint. Copiez l’URL du Centre d’administration SharePoint et utilisez cette valeur. Par exemple, si votre ID de locataire est Contoso123, votre URL d’administrateur esthttps://contoso123-admin.sharepoint.com. -
{{CONTAINER_TYPE_NAME}}: choisissez un nom pour votre nouveau type de conteneur. Par exemple, utilisezMyFirstSpeContainerType. -
{{AZURE_ENTRA_APP_ID}}: définissez cette valeur sur la valeur de l’ID d’application Microsoft Entra, également appelé « ID client » que vous avez créé précédemment. Cette valeur doit se trouver dans votre fichier texte local.
Import-Module "Microsoft.Online.SharePoint.PowerShell"
Connect-SPOService -Url "https://{{SPO_ADMIN_URL}}"
New-SPOContainerType -TrialContainerType
-ContainerTypeName "{{CONTAINER_TYPE_NAME}}"
-OwningApplicationId "{{AZURE_ENTRA_APP_ID}}"
Le script PowerShell affiche les détails de votre nouveau type de conteneur, par exemple :
Container Type ID:
===============================================================================
ContainerTypeId : 1e59a44b-b77e-051e-3cba-dbf83007b520
ContainerTypeName : MyFirstSpeContainerType
OwningApplicationId : 520e6e65-1143-4c87-a7d3-baf242915dbb
Classification : Trial
AzureSubscriptionId : 00000000-0000-0000-0000-000000000000
ResourceGroup :
Region :
Copiez votre ContainerTypeId fichier texte local pour une utilisation ultérieure.
Inscrire le type de conteneur dans le locataire consommateur
Enfin, dans le cadre de la dernière étape, vous devez inscrire le type de conteneur (actuellement défini dans le locataire du fournisseur) dans le ou les locataires du consommateur. Cela est vrai pour les applications monolocataires et multilocataires et garantit que seules les applications spécifiées ont accès aux conteneurs dans leur locataire.
Si cette étape n’est pas terminée, l’application SharePoint Embedded obtient une erreur d’accès refusé lors d’une tentative d’opération avec un conteneur.
Inscrire un type de conteneur auprès de l’API REST SharePoint Online. L’API REST SharePoint Online nécessite qu’une application s’authentifie avec un certificat plutôt qu’une simple clé secrète client.
Créer un certificat auto-signé
Tout d’abord, créez un certificat auto-signé à l’aide de l’applet de commande de New-SelfSignedCertificate PowerShell. Mettez à jour les valeurs suivantes dans le script PowerShell suivant, puis exécutez le script :
-
{{CERT NAME}}: nom du certificat. Ça peut être ce que tu veux. -
{{CERT_PATH}}: chemin d’accès complet à l’emplacement du fichier *.cer , tel que c :\mycert.cer.
$cert = New-SelfSignedCertificate -Subject "CN={{CERT_NAME}}" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "{{CERT_PATH}}" -Force
# Private key to Base64
$privateKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
$privateKeyBytes = $privateKey.Key.Export([System.Security.Cryptography.CngKeyBlobFormat]::Pkcs8PrivateBlob)
$privateKeyBase64 = [System.Convert]::ToBase64String($privateKeyBytes, [System.Base64FormattingOptions]::InsertLineBreaks)
$privateKeyString = @"
-----BEGIN PRIVATE KEY-----
$privateKeyBase64
-----END PRIVATE KEY-----
"@
# Print private key to output
Write-Host $privateKeyString
Enregistrez la valeur de la clé privée au format Base64, également appelé format PEM, dans un nouveau fichier *.key portant le même nom que le fichier *.cer généré.
Importante
Le contenu du fichier doit inclure les -----BEGIN PRIVATE KEY----- chaînes et -----END PRIVATE KEY----- .
Dans la page Gérer les > certificats & secrets , sélectionnez Certificats, puis Charger le certificat. Sélectionnez le fichier *.cer , puis sélectionnez Ajouter.
Après avoir chargé le certificat, copiez l’empreinte numérique affichée dans la page Certificats & Secrets du portail Microsoft Entra ID :
Inscrire le type de conteneur dans le locataire du consommateur
Ensuite, inscrivez le type de conteneur auprès du locataire du consommateur à l’aide du point de terminaison REST /_api/v2.1/storageContainerTypes/{{ContainerTypeId}}/applicationPermissions SharePoint. L’équipe SharePoint Embedded a simplifié cette tâche en fournissant une collection Postman remplie de nombreux exemples d’appel des différents points de terminaison SharePoint Online & Microsoft Graph.
Dans le référentiel Exemples SharePoint Embedded, recherchez la collection Postman, obtenez l’URL brute de celle-ci et importez-la dans Postman en tant que nouvelle collection :
Notez que la vue d’ensemble de la collection contient un ensemble de documentation. Une section importante traite de la création d’un fichier d’environnement Postman pour simplifier la définition des valeurs nécessaires. J’en ai déjà créé un et j’ai juste besoin de remplir les valeurs :
- ClientID : l’ID client ou l’APPLICATION d’ID Microsoft Entra.
- ClientSecret : clé secrète client de l’application d’ID Microsoft Entra.
- ConsumeTenantId : ID du locataire Microsoft 365 du locataire consommateur que vous souhaitez cibler.
- TenantName : nom de votre locataire. Il s’agit de la partie sous-domaine de votre site SharePoint Online.
- RootSiteUrl : URL racine de votre locataire.
- ContainerTypeID : GUID du type de conteneur créé dans le locataire du fournisseur.
- CertThumbprint : empreinte numérique de l’ID Microsoft Entra du certificat affichée après le chargement du certificat dans l’application Microsoft Entra ID.
- CertPrivateKey : clé privée du certificat. Il s’agit de la clé au format PEM.
Une fois la collection et l’environnement Postman configurés, exécutez la requête Register ContainerType dans le dossier Conteneurs d’applications>. Une fois la demande terminée, l’application que vous allez créer dans le reste de ce module sera en mesure de gérer et d’accéder aux conteneurs de stockage dans mon client Microsoft 365.
Créer une application web pour accéder aux conteneurs Incorporés SharePoint
Avec l’installation de SharePoint Embedded dans les locataires fournisseur et consommateur, y compris la création et l’inscription du type de conteneur, l’étape suivante consiste à créer l’application. Cette application se compose de deux projets :
- Un projet web pour générer et afficher l’application SPA React front-end
- UNE API côté serveur pour héberger les méthodes qui nécessitent un client confidentiel qui effectue des opérations qui ne peuvent pas être effectuées à partir de l’application cliente.
Commençons par créer la partie frontale du projet :
Créer une application front-end
À partir d’une ligne de commande, accédez au dossier dans lequel vous souhaitez créer l’application et exécutez la commande suivante :
npx create-react-app my-first-spe-app --template typescript
Ensuite, installez les packages npm qui facilitent l’interface utilisateur spa et l’authentification avec l’ID Microsoft Entra. À partir de la ligne de commande, accédez au dossier my-first-spe-app créé par la commande précédente et exécutez la commande suivante :
npm install @azure/msal-browser @fluentui/react-components @fluentui/react-icons @microsoft/mgt-react @microsoft/mgt-element @microsoft/mgt-msal2-provider -SE
Cette commande installe les packages npm suivants :
- @azure/msal-browser : utilisé pour l’authentification avec l’ID Microsoft Entra.
- @microsoft/mgt-element, @microsoft/mgt-react, & @microsoft/mgt-msal2-provider : le kit de ressources Microsoft Graph qui contient des composants d’interface utilisateur pour React.
- @fluentui/react-components & @fluentui/react-icons : composants d’interface utilisateur de la bibliothèque Fluent UI v9.
Créer une application back-end
Ensuite, créez et ajoutez la structure nécessaire pour le serveur d’API. Commencez par exécuter la commande suivante pour installer d’autres packages npm :
npm install restify @azure/msal-node @microsoft/microsoft-graph-client isomorphic-fetch jsonwebtoken jwks-rsa -SE
npm install @types/restify @types/jsonwebtoken @types/isomorphic-fetch -DE
Cette commande installe les packages npm :
- restify & @types/restify : serveur d’API de base Node.js et déclarations de type associées pour TypeScript.
- @azure/msal-node : utilisé pour l’authentification avec l’ID Microsoft Entra.
- @microsoft/microsoft-graph-client : Kit de développement logiciel (SDK) JavaScript Microsoft Graph.
-
isomorphe-fetch : Polyfill qui ajoute l’API de navigateur
fetchen tant qu’api globale afin que son API soit cohérente entre le client & serveur. - jsonwebtoken : implémentation de jetons web JSON.
- jwks-rsa : bibliothèque pour récupérer des clés de signature à partir d’un point de terminaison JWKS (Json Web Key Set).
Ajoutez une configuration de compilateur TypeScript pour le projet côté serveur :
Créez un fichier, ./server/tsconfig.json projet et ajoutez-y le code suivant. Cette opération configure le compilateur TypeScript pour la partie API côté serveur de ce projet.
{ "$schema": "http://json.schemastore.org/tsconfig", "compilerOptions": { "target": "ES2015", "module": "commonjs", "lib": [ "es5", "es6", "dom", "es2015.collection" ], "esModuleInterop": true, "moduleResolution": "node", "strict": true } }
Ensuite, ajoutez un espace réservé pour l’API côté serveur à ce projet.
Créez un fichier , ./server/index.ts, puis ajoutez-y le code suivant :
import * as restify from "restify"; const server = restify.createServer(); server.use(restify.plugins.bodyParser()); server.listen(process.env.port || process.env.PORT || 3001, () => { console.log(`\nAPI server started, ${server.name} listening to ${server.url}`); }); // add CORS support server.pre((req, res, next) => { res.header('Access-Control-Allow-Origin', req.header('origin')); res.header('Access-Control-Allow-Headers', req.header('Access-Control-Request-Headers')); res.header('Access-Control-Allow-Credentials', 'true'); if (req.method === 'OPTIONS') { return res.send(204); } next(); });
Cela crée un serveur Restify, le configure pour écouter les demandes sur le port 3001 et active CORS sur le serveur.
Ajouter des paramètres globaux et des constantes de projet
Ensuite, ajoutez quelques constantes pour stocker vos paramètres de déploiement
Créez un fichier, ./.env, pour stocker les paramètres de votre serveur d’API. Ajoutez ce qui suit au fichier :
API_ENTRA_APP_CLIENT_ID= API_ENTRA_APP_CLIENT_SECRET= API_ENTRA_APP_AUTHORITY= CONTAINER_TYPE_ID=Créez un fichier ./src/common/constants.ts pour stocker les paramètres de votre application côté client. Ajoutez ce qui suit au fichier :
export const CLIENT_ENTRA_APP_CLIENT_ID = ''; export const CLIENT_ENTRA_APP_AUTHORITY = ''; export const API_SERVER_URL = ''; export const CONTAINER_TYPE_ID = '';
Mettez à jour les valeurs de ces deux fichiers à l’aide des conseils suivants :
- API_ENTRA_APP_CLIENT_ID : il s’agit de l’ID d’application (client) de l’application d’ID Microsoft Entra que vous avez créée précédemment.
- API_ENTRA_APP_CLIENT_SECRET : il s’agit de la clé secrète d’application (client) de l’application d’ID Microsoft Entra que vous avez créée précédemment.
-
API_ENTRA_APP_AUTHORITY : il s’agit de l’autorité de l’application d’ID Microsoft Entra. Utilisez
https://login.microsoftonline.com/{{MS-ENTRA-TENANT-ID}}/. L’ID de locataire est l’ID du locataire d’ID Microsoft Entra où l’application a été créée précédemment. -
API_SERVER_URL : IL s’agit de l’URL du serveur d’API côté serveur. Utilisez
http://localhost:3001. - CLIENT_ENTRA_APP_CLIENT_ID : il s’agit de l’ID d’application (client) de l’application d’ID Microsoft Entra que vous avez créée précédemment.
Enfin, ajoutez un nouveau fichier, ./src/common/scopes.ts, pour stocker une liste d’étendues OAuth2 (autorisations) que nous utiliserons dans l’application côté client :
// microsoft graph scopes
export const GRAPH_USER_READ = 'User.Read';
export const GRAPH_USER_READ_ALL = 'User.Read.All';
export const GRAPH_FILES_READ_WRITE_ALL = 'Files.ReadWrite.All';
export const GRAPH_SITES_READ_ALL = 'Sites.Read.All';
export const GRAPH_OPENID_CONNECT_BASIC = ["openid", "profile", "offline_access"];
// SharePoint Embedded scopes
export const SPEMBEDDED_CONTAINER_MANAGE= 'Container.Manage';
export const SPEMBEDDED_FILESTORAGECONTAINER_SELECTED= 'FileStorageContainer.Selected';
Créez un cop de ce fichier pour le serveur d’API. Enregistrez le fichier copié à l’emplacement suivant dans le projet : ./server/common/scopes.ts.
Configurer la génération de projet
À présent, nous allons apporter des modifications au projet pour simplifier les builds et les tests.
Mettez à jour les scripts pour simplifier la génération des projets :
Ouvrez une invite de commandes, définissez le dossier actif sur la racine de votre projet, puis exécutez la commande suivante pour installer quelques packages npm utilisés dans le développement :
npm install env-cmd npm-run-all -DERecherchez et ouvrez le fichier ./package.json et mettez à jour la
scriptssection comme suit :"scripts": { "build:backend": "tsc -p ./server/tsconfig.json", "start": "run-s build:backend start:apps", "start:apps": "run-p start:frontend start:backend", "start:frontend": "npm run start-cre", "start:backend": "env-cmd --silent -f .env node ./server/index.js", "start-cre": "react-scripts start", "build-cre": "react-scripts build", "test-cre": "react-scripts test", "eject-cre": "react-scripts eject" },
La liste suivante explique ce que font les scripts :
- Tous les scripts create-react-app (CRE) par défaut ont été mis à jour pour inclure le suffixe -cre dans leur nom afin d’indiquer qu’ils sont associés à create-react-app.
- Le script de démarrage utilise la méthode run-s du package npm-run-all pour exécuter deux scripts séquentiellement :
- Il exécute d’abord le script de build pour transpiler l’ensemble du projet de TypeScript en JavaScript.
- Ensuite, il exécute le script start :apps.
- Le script start :apps exécute les scripts start :frontend & start :backend en parallèle à l’aide de la méthode run-p du package npm-run-all npm.
- Le script start :backend utilise le package npm env-cmd pour injecter les variables d’environnement dans le fichier ./.env dans le processus du serveur d’API.
À ce stade, vous disposez d’un projet de modèle que vous allez utiliser pour ajouter d’autres fonctionnalités dans les sections suivantes.
Résumé
Dans cet exercice, vous avez créé un projet qui contient un composant côté serveur et côté client. Le composant côté serveur est une API REST qui s’authentifie avec l’ID Microsoft Entra et accède aux conteneurs SharePoint Embedded à l’aide de l’API Microsoft Graph. Le composant côté client est une application React monopage qui appelle l’API REST qui expose le contenu du conteneur Incorporé SharePoint.