Configurer et configurer SharePoint Embedded

Dans cet exercice, vous allez créer une application Microsoft Entra ID, configurer SharePoint Embedded sur votre client Microsoft 365 SharePoint et créer votre premier type de conteneur et conteneur.

Configuration requise

• Postman a installé le client de bureau connecté à un compte Postman gratuit ou payant.
• Accès à un compte administrateur dans un locataire Microsoft 365.
• Windows PowerShell invite.

Inscrire Microsoft Entra ID application

Les applications SharePoint Embedded personnalisées utilisent une application Microsoft Entra ID personnalisée pour s’authentifier et obtenir les autorisations nécessaires pour appeler les API Microsoft Graph et Microsoft SharePoint.

Ouvrez un navigateur et accédez à l’entrée Microsoft Entra ID administrateur. Connectez-vous à l’aide d’un compte professionnel ou scolaire pour votre locataire Microsoft 365 disposant de droits d’administrateur général.

Sélectionnez Applications > d’identité > inscriptions d'applications dans le volet de navigation gauche, puis sélectionnez Nouvelle inscription.

Sur la page Inscrire une application, définissez les valeurs comme suit, puis sélectionnez Inscrire :

• Nom : Application SharePoint Embedded
• Types de comptes pris en charge : Comptes dans n’importe quel annuaire organisationnel (tout locataire Microsoft Entra ID - Multilocataire)

Après avoir créé l’application SharePoint Embedded, Microsoft Entra ID affiche 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)&'ID du répertoire (locataire) de la page de vue d’ensemble de l’application dans votre fichier texte local.

Configurer l’authentification

Configurez ensuite les paramètres d’authentification de l’application. Sélectionnez Gérer > l’authentification dans le volet de navigation de gauche, puis sélectionnez Ajouter une plateforme.

Sélectionnez l’option Web et, pour les URI de redirection, entrez https://oauth.pstmn.io/v1/callback et sélectionnez Configurer.

Ensuite, sélectionnez Ajouter un URI pour la nouvelle plateforme web , https://oauth.pstmn.io/v1/browser-callback puis sélectionnez Configurer.

Ces deux options seront utilisées pour authentifier et obtenir des jetons d’accès à l’aide du client Postman plus loin dans ce module.

Faites défiler jusqu’à la section Octroi implicite et flux hybrides , sélectionnez l’option Jetons d’accès (utilisés pour les flux implicites), puis sélectionnez Enregistrer.

Ajoutez une autre plateforme en sélectionnant Ajouter une plateforme, Application monopage, définissez l’URI de redirection sur http://localhost, puis sélectionnez Configurer.

Configurer les autorisations d’API

Ensuite, configurez l’application avec davantage d’autorisations afin qu’elle puisse créer et accéder aux types de conteneurs et aux conteneurs.

Sélectionnez Gérer > le manifeste dans le volet de navigation gauche. Recherchez la propriété requiredResourceAccess et modifiez-la afin qu’elle ressemble au code JSON suivant :

"requiredResourceAccess": [
  {
    "resourceAppId": "00000003-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
      {
        "id": "4d114b1a-3649-4764-9dfb-be1e236ff371",
        "type": "Scope"
      },
      {
        "id": "19766c1b-905b-43af-8756-06526ab42875",
        "type": "Role"
      }
    ]
  },
  {
    "resourceAppId": "00000003-0000-0000-c000-000000000000",
    "resourceAccess": [
      {
        "id": "085ca537-6565-41c2-aca7-db852babc212",
        "type": "Scope"
      },
      {
        "id": "40dc41bc-0f7e-42ff-89bd-d9516947e474",
        "type": "Role"
      }
    ]
  }
],

"requiredResourceAccess": [
 {
   "resourceAppId": "00000003-0000-0000-c000-000000000000",
   "resourceAccess": [
     {
       "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",
       "type": "Scope"
     }
   ]
 }
],

Ajoutez les deux nouvelles autorisations à l’objet existant "resourceAppId": "00000003-0000-0000-c000-000000000000" afin qu’il dispose désormais de trois (3) autorisations.

Accorder le consentement de l’administrateur aux nouvelles autorisations

Certaines autorisations nécessitent le consentement de l’administrateur. Sélectionnez Autorisations d’API dans le volet de navigation de gauche, 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. Si vous êtes invité à vous connecter, utilisez le même compte professionnel et scolaire que celui que vous avez utilisé pour vous connecter au centre d’administration Microsoft Entra ID. Dans la page Autorisations demandées , sélectionnez Accepter 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 Microsoft Entra ID, elle a besoin de l’ID client et d’une clé secrète client.

Sélectionnez Gérer les > certificats & secrets dans le volet de navigation gauche.

Dans la section Clés secrètes client, sélectionnez Nouvelle clé secrète client. Ajoutez une description et sélectionnez une durée d’expiration, puis Ajouter.

Après avoir créé la clé secrète client, elle s’affiche une seule fois. Veillez donc à la copier en tant que clé secrète client dans votre fichier texte local pour l’utiliser plus loin 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éez un certificat

Contrairement à Microsoft Graph qui autorise l’authentification de l’application avec un ID client et un secret, SharePoint exige que l’application s’authentifie à l’aide de l’ID client et du certificat. Nous devons donc maintenant créer un certificat.

Ouvrez une invite Windows PowerShell en tant qu’administrateur et exécutez le script PowerShell suivant. Lorsque vous y êtes invité, entrez le nom de votre certificat, par exemple SharePoint Embedded :

$name = Read-Host -Prompt "Certificate name: "
$cert = New-SelfSignedCertificate -Subject "CN=$name" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "$name.cer"

# 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)

# Private key file contents
$privateKeyFileContent = @"
-----BEGIN PRIVATE KEY-----
$privateKeyBase64
-----END PRIVATE KEY-----
"@

# Output to file
$privateKeyFileContent | Out-File -FilePath "$name.key" -Encoding Ascii

Le script PowerShell enregistre le certificat (*.cer) et la clé privée (*.key) dans le dossier où le script PowerShell a été exécuté.

Dans le centre d’administration Microsoft Entra ID, dans la page Certificats & secrets de l’application, sélectionnez Certificats, puis Charger le certificat.

Chargez le *.cer généré par le script PowerShell, donnez une description au certificat, puis sélectionnez Ajouter.

Une fois le certificat chargé, copiez l’intégralité de l’empreinte numérique affichée dans votre fichier texte local.

Créer un type de conteneur pour votre application SharePoint Embedded

L’étape suivante consiste à créer un type de conteneur pour votre application.

Ouvrez une invite de Windows PowerShell en tant qu’administrateur.

Installer ou mettre à niveau le module PowerShell SharePoint Online

Si vous n’avez pas encore installé le module PowerShell SharePoint Online , installez-le en exécutant la commande suivante :

Install-Module "Microsoft.Online.SharePoint.PowerShell"

Si vous l’avez installé, vérifiez que la dernière version est installée en la mettant à niveau :

Upgrade-Module "Microsoft.Online.SharePoint.PowerShell"

Créer le type de conteneur

Une fois le dernier module PowerShell SharePoint Online installé, l’étape suivante consiste à créer un type de conteneur dans votre locataire.

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 à l’aide [https://portal.microsoft.com](https://portal.microsoft.com)du compte d’administrateur de votre locataire, sélectionnez Afficher tout en bas du volet de navigation gauche, puis sélectionnez Administration Centres > 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 est https://contoso123-admin.sharepoint.com.
• {{CONTAINER_TYPE_NAME}}: choisissez un nom pour votre nouveau type de conteneur. Par exemple, utilisez FirstContainerType.
• {{AZURE_ENTRA_APP_ID}}: définissez cette valeur sur la valeur de l’ID d’application Microsoft Entra ID, é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 "{{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     : 3a6b1fc4-0bd9-04b3-3a2a-4843fbb60914
ContainerTypeName   : FirstContainerType
OwningApplicationId : 763cd5ea-ade4-4d2a-a143-29498920e18f
Classification      : Standard
AzureSubscriptionId : 00000000-0000-0000-0000-000000000000
ResourceGroup       :
Region              :

Copiez et dans ContainerTypeIdContainerTypeName votre fichier texte local pour une utilisation ultérieure.

Configurer Postman pour qu’il s’authentifie auprès de Microsoft Entra ID afin d’obtenir des jetons d’accès délégué et d’application pour Microsoft Graph et SharePoint Online

La dernière étape consiste à inscrire le nouveau type de conteneur que vous avez créé dans le client développeur/fournisseur Microsoft 365 auprès du locataire consommateur. Cette opération est effectuée avec l’API REST SharePoint. Pour cette étape, vous allez utiliser le client Postman.

Avant de pouvoir appeler l’API REST SharePoint avec Postman, vous devez d’abord configurer Postman pour obtenir un jeton d’accès.

Créer un environnement Postman

Tout d’abord, créez un environnement Postman qui stockera les variables d’environnement pour simplifier les appels et centraliser tous nos paramètres.

Dans Postman, sélectionnez Environnements, puis sélectionnez l’icône plus pour créer un environnement.

Nommez l’environnement SharePoint Embedded.

Ajoutez les variables suivantes à l’environnement et définissez la valeur Initial sur les valeurs de votre fichier texte local. Enregistrez l’environnement une fois que vous avez ajouté ces variables.

Sélectionnez l’environnement en le sélectionnant dans le sélecteur de liste déroulante en haut à droite du client Postman. La liste déroulante se trouve juste sous les icônes d’engrenage et d’alerte et au-dessus des boutons Enregistrer et Partager sur la même ligne que les onglets.

Créer une collection Postman

Ensuite, créez une collection Postman qui stockera les demandes et obtiendra les jetons d’accès.

Dans Postman, sélectionnez Collections, puis sélectionnez l’icône plus pour créer une collection.

Nommez la collection SharePoint Embedded.

Dans la nouvelle collection, créez dans des ensembles de dossiers à l’aide du contexte de la collection plusieurs pour stocker les demandes pour les conteneurs ; un dans un dossier Délégué et un autre dans un dossier Application :

Configurer le dossier Application de la collection Postman

L’étape suivante consiste à mettre à jour le paramètre d’authentification du dossier Application . Celui-ci nécessite un peu plus de travail, car nous devons obtenir un jeton d’application uniquement pour appeler Microsoft Graph. Pour ce faire, vous allez configurer le dossier Application pour télécharger un script et le stocker dans une variable globale pour une utilisation ultérieure.

Sélectionnez le dossier Application , puis sélectionnez l’onglet Autorisation . Définissez le type sur Jeton du porteur et le jeton sur {{AppOnlyCertGraphToken}}.

Sélectionnez l’onglet Script de pré-demande et entrez le script suivant :

// download jsrsasign library and save it to a global variable
if (!pm.globals.has('jsrsasign-js')) {
  pm.sendRequest(
    'https://kjur.github.io/jsrsasign/jsrsasign-all-min.js',
    function (err, res) {
      if (err) {
        throw new Error(err);
      } else {
        console.log('Downloaded RSA library');
        pm.globals.set('jsrsasign-js', res.text());
      }
    }
  );
}

Enregistrez les modifications apportées à la collection.

Configurer le dossier Conteneurs d’applications > de la collection Postman

Ensuite, sélectionnez le dossier Conteneurs d’applications > de la collection.

Sous l’onglet Autorisation , définissez le Type sur Hériter de l’authentification du parent.

Sous l’onglet Script de pré-demande , entrez le script suivant :

async function ensureAccessToken () {
  var validToken = false;
  var token = pm.environment.get('AppOnlyCertGraphToken');
  if (token) {
    console.log('checking stored token');
    try {
      var tokenObj = KJUR.jws.JWS.parse(token);
      var nbf = tokenObj.payloadObj.nbf;
      var exp = tokenObj.payloadObj.exp;
      var now = getTimeInSec();
      if (nbf <= now && now < exp) {
        validToken = true;
      } else {
        console.log("Stored access token is expired");
      }
    } catch (e) {
      console.log("Unable to parse stored access token");
    }
  } else {
    console.log("No access token found");
  }
  if (!validToken) {
    acquireAccessToken();
  }
}

function acquireAccessToken() {
  console.log("Acquiring a new access token");
  var jwt = getRequestJwt();
  console.log(jwt);
  var tid = pm.environment.get('ConsumingTenantId');

  const tokenRequest = {
    url: `https://login.microsoftonline.com/${tid}/oauth2/v2.0/token`,
    method: 'POST',
    header: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: {
      mode: 'urlencoded',
      urlencoded: [
        { key: 'client_assertion_type', value: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' },
        { key: 'client_assertion', value: jwt },
        { key: 'client_id', value: pm.environment.get('ClientID') },
        { key: 'scope', value: 'https://graph.microsoft.com/.default' },
        { key: 'grant_type', value: 'client_credentials' }
      ]
    }
  };
  pm.sendRequest(tokenRequest, (error, response) => {
    if (error) {
      console.log('Unable to acquire token: ' + error);
    } else {
      var responseJson = response.json();
      var token = responseJson.access_token;
      if (!token)
        throw Error("Invalid or no access token received");
      pm.environment.set('AppOnlyCertGraphToken', token);
    }
  });
}

function getRequestJwt () {
  var header = {
    'alg': 'RS256',
    'typ': 'JWT',
    'x5t': safeBase64EncodedThumbprint(pm.environment.get('CertThumbprint'))
  };

  var now = getTimeInSec();
  var tid = pm.environment.get('ConsumingTenantId');
  var payload = {
    'aud': `https://login.microsoftonline.com/${tid}/oauth2/v2.0/token`,
    'exp': now + 60 * 60,
    'iss': pm.environment.get('ClientID'),
    'jti': pm.variables.replaceIn('{{$guid}}'),
    'nbf': now,
    'sub': pm.environment.get('ClientID'),
    'iat': now
  };

  var encryptedPk = pm.environment.get('CertPrivateKey');
  var decryptedPk = encryptedPk;
  if (pm.environment.has('CertPassword') && pm.environment.get('CertPassword') !== '') {
    decryptedPk = KEYUTIL.getKey(encryptedPk, pm.environment.get('CertPassword'));
  }
  var sHeader = JSON.stringify(header);
  var sPayload = JSON.stringify(payload);
  return KJUR.jws.JWS.sign(header.alg, sHeader, sPayload, decryptedPk);
}

function getTimeInSec() {
  return Math.floor(Date.now() / 1000);
}

function safeBase64EncodedThumbprint (thumbprint) {
  var numCharIn128BitHexString = 128/8*2;
  var numCharIn160BitHexString = 160/8*2;
  var thumbprintSizes  = {};
  thumbprintSizes[numCharIn128BitHexString] = true;
  thumbprintSizes[numCharIn160BitHexString] = true;
  var thumbprintRegExp = /^[a-f\d]*$/;

  var hexString = thumbprint.toLowerCase().replace(/:/g, '').replace(/ /g, '');

  if (!thumbprintSizes[hexString.length] || !thumbprintRegExp.test(hexString)) {
    throw 'The thumbprint does not match a known format';
  }

  var base64 = (Buffer.from(hexString, 'hex')).toString('base64');
  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
}

var navigator = {}; // fake a navigator object for the lib
var window = {}; // fake a window object for the lib
eval(pm.globals.get('jsrsasign-js'));
ensureAccessToken();

Enregistrez les modifications apportées à la collection.

À ce stade, Postman est maintenant configuré pour obtenir un jeton d’accès d’application uniquement pour les appels à Microsoft Graph.

Inscrire le type de conteneur auprès de votre locataire consommateur

Une fois Postman configuré, vous pouvez maintenant ajouter une demande d’inscription du type de conteneur auprès de votre locataire consommateur.

Dans Postman, sélectionnez Collections dans le volet de navigation de gauche et développez le nœud Application incorporée > SharePoint , sélectionnez le menu contextuel ... sur le nœud Conteneurs , puis sélectionnez Ajouter une demande.

Renommez la requête en Register Container Type.

Définissez la méthode HTTP sur PUT et le point de terminaison suivant :

{{RootSiteURL}}/_api/v2.1/storageContainerTypes/{{ContainerTypeId}}/applicationPermissions

Dans le script de pré-demande, ajoutez le code suivant pour obtenir un jeton d’application uniquement pour appeler l’API REST SharePoint :

async function ensureAccessToken () {
  var validToken = false;
  var token = pm.environment.get('AppOnlyCertSPOToken');
  if (token) {
    console.log('checking stored token');
    try {
      var tokenObj = KJUR.jws.JWS.parse(token);
      var nbf = tokenObj.payloadObj.nbf;
      var exp = tokenObj.payloadObj.exp;
      var now = getTimeInSec();
      if (nbf <= now && now < exp) {
        validToken = true;
      } else {
        console.log("Stored access token is expired");
      }
    } catch (e) {
      console.log("Unable to parse stored access token");
    }
  } else {
    console.log("No access token found");
  }
  if (!validToken) {
    acquireAccessToken();
  }
}

function acquireAccessToken() {
  console.log("Acquiring a new access token");
  var jwt = getRequestJwt();
  console.log(jwt);
  var tid = pm.environment.get('ConsumingTenantId');

  const tokenRequest = {
    url: `https://login.microsoftonline.com/${tid}/oauth2/v2.0/token`,
    method: 'POST',
    header: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: {
      mode: 'urlencoded',
      urlencoded: [
        { key: 'client_assertion_type', value: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' },
        { key: 'client_assertion', value: jwt },
        { key: 'client_id', value: pm.environment.get('ClientID') },
        { key: 'scope', value: pm.environment.get('RootSiteURL') + '/.default' },
        { key: 'grant_type', value: 'client_credentials' }
      ]
    }
  };
  pm.sendRequest(tokenRequest, (error, response) => {
    if (error) {
      console.log('Unable to acquire token: ' + error);
    } else {
      var responseJson = response.json();
      var token = responseJson.access_token;
      pm.environment.set('AppOnlyCertSPOToken', token);
    }
  });
}

function getRequestJwt () {
  var header = {
    'alg': 'RS256',
    'typ': 'JWT',
    'x5t': safeBase64EncodedThumbprint(pm.environment.get('CertThumbprint'))
  };

  var now = getTimeInSec();
  var tid = pm.environment.get('ConsumingTenantId');
  var payload = {
    'aud': `https://login.microsoftonline.com/${tid}/oauth2/v2.0/token`,
    'exp': now + 60 * 60,
    'iss': pm.environment.get('ClientID'),
    'jti': pm.variables.replaceIn('{{$guid}}'),
    'nbf': now,
    'sub': pm.environment.get('ClientID'),
    'iat': now
  };

  var encryptedPk = pm.environment.get('CertPrivateKey');
  var decryptedPk = encryptedPk;
  if (pm.environment.has('CertPassword') && pm.environment.get('CertPassword') !== '') {
    decryptedPk = KEYUTIL.getKey(encryptedPk, pm.environment.get('CertPassword'));
  }
  var sHeader = JSON.stringify(header);
  var sPayload = JSON.stringify(payload);
  return KJUR.jws.JWS.sign(header.alg, sHeader, sPayload, decryptedPk);
}

function getTimeInSec() {
  return Math.floor(Date.now() / 1000);
}

function safeBase64EncodedThumbprint (thumbprint) {
  var numCharIn128BitHexString = 128/8*2;
  var numCharIn160BitHexString = 160/8*2;
  var thumbprintSizes  = {};
  thumbprintSizes[numCharIn128BitHexString] = true;
  thumbprintSizes[numCharIn160BitHexString] = true;
  var thumbprintRegExp = /^[a-f\d]*$/;

  var hexString = thumbprint.toLowerCase().replace(/:/g, '').replace(/ /g, '');

  if (!thumbprintSizes[hexString.length] || !thumbprintRegExp.test(hexString)) {
    throw 'The thumbprint does not match a known format';
  }

  var base64 = (Buffer.from(hexString, 'hex')).toString('base64');
  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
}

var navigator = {}; // fake a navigator object for the lib
var window = {}; // fake a window object for the lib
eval(pm.globals.get('jsrsasign-js'));
ensureAccessToken();

Sous l’onglet Autorisation , définissez le Type sur Jeton du porteur et le Jeton sur {{AppOnlyCertSPOToken}}. Cette variable de jeton est créée et définie dans le script de pré-requête.

Sous l’onglet Corps , sélectionnez le type brut , définissez le type de données sur JSON et ajoutez le code suivant au corps :

{
  "value": [
    {
      "appId": "{{ClientID}}",
      "delegated": ["full"],
      "appOnly": ["full"]
    }
  ]
}

Sélectionnez le bouton Envoyer pour exécuter la requête Inscrire le type de conteneur . Postman affiche la réponse sous la demande :

Résumé

Dans cet exercice, vous avez créé une application Microsoft Entra ID, vous avez configuré SharePoint Embedded sur votre client Microsoft 365 SharePoint et vous créez votre premier type de conteneur à l’aide de PowerShell, d’une nouvelle collection Postman et de l’environnement associé pour envoyer des demandes aux API REST Microsoft Graph et SharePoint.