Configuración y configuración de SharePoint Embedded

En este ejercicio, creará una aplicación Microsoft Entra ID, configurará SharePoint Embedded en el inquilino de Microsoft 365 SharePoint y creará su primer contenedor y tipo de contenedor.

Requisitos previos

• Postman instaló el cliente de escritorio que inició sesión en una cuenta gratuita o de pago de Postman.
• Acceso a una cuenta de administrador en un inquilino de Microsoft 365.
• Windows PowerShell mensaje.

Registro de Microsoft Entra ID aplicación

Las aplicaciones de SharePoint Embedded personalizadas usan una aplicación de Microsoft Entra ID personalizada para autenticarse y obtener los permisos necesarios para llamar a las API de Microsoft Graph y Microsoft SharePoint.

Abra un explorador y vaya al Microsoft Entra ID administrador escriba. Inicie sesión con una cuenta profesional o educativa para el inquilino de Microsoft 365 que tenga derechos de administrador global.

Seleccione Aplicaciones > de identidad > Registros de aplicaciones en el panel de navegación izquierdo y, a continuación, seleccione Nuevo registro.

En la página Registrar una aplicación, establezca los valores como se indica a continuación y seleccione Registrar:

• Nombre: aplicación de SharePoint Embedded
• Tipos de cuenta admitidos: cuentas en cualquier directorio organizativo (cualquier inquilino Microsoft Entra ID multiinquilino)

Después de crear la aplicación de SharePoint Embedded, Microsoft Entra ID muestra los detalles de la nueva aplicación. Cree un archivo de texto para realizar un seguimiento de varios valores que necesitará más adelante en este módulo.

Copie el identificador de aplicación (cliente) & id. de directorio (inquilino) de la página de información general de la aplicación en el archivo de texto local.

Configurar la autenticación

Después, configure las opciones de autenticación de la aplicación. Seleccione Administrar > autenticación en el panel de navegación izquierdo y, a continuación, seleccione Agregar una plataforma.

Seleccione la opción Web y, para los URI de redirección, escriba https://oauth.pstmn.io/v1/callback y seleccione Configurar.

A continuación, seleccione Agregar URI para la nueva plataforma https://oauth.pstmn.io/v1/browser-callbackweb y seleccione Configurar.

Estas dos opciones se usarán para autenticar y obtener tokens de acceso mediante el cliente de Postman más adelante en este módulo.

Desplácese hacia abajo hasta la sección Concesión implícita y flujos híbridos , seleccione la opción Tokens de acceso (que se usan para flujos implícitos) y, a continuación, seleccione Guardar.

Para agregar otra plataforma, seleccione Agregar una plataforma, aplicación de página única, establezca el URI de redirección en http://localhosty seleccione Configurar.

Configuración de permisos de API

A continuación, configure la aplicación con más permisos para que pueda crear contenedores y acceder a ellos.

Seleccione Administrar > manifiesto en el panel de navegación izquierdo. Busque la propiedad requiredResourceAccess y edítela para que tenga el siguiente aspecto:

"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"
     }
   ]
 }
],

Agregue los dos nuevos permisos al objeto existente "resourceAppId": "00000003-0000-0000-c000-000000000000" , por lo que ahora tiene tres (3) permisos.

Concesión del consentimiento del administrador a los nuevos permisos

Algunos de los permisos requieren el consentimiento del administrador. Seleccione Permisos de API en el panel de navegación izquierdo, desplácese hasta la parte inferior de la página y seleccione el vínculo Aplicaciones empresariales.

En la página Permisos, seleccione Conceder consentimiento de administrador para Contoso. Si se le pide que inicie sesión, use la misma cuenta profesional y educativa que usó para iniciar sesión en el centro de administración de Microsoft Entra ID. En la página Permisos solicitados , seleccione Aceptar para conceder el consentimiento del administrador a los dos pares de permisos: FileStorageContainer.Selected para Microsoft Graph y Container.Selected para SharePoint. Los dos pares representan la aplicación & opciones delegadas para cada uno de los dos permisos.

Creación de un secreto de cliente

Para que una aplicación se autentique mediante el flujo de credenciales de cliente de OAuth2 con Microsoft Entra ID, necesita el identificador de cliente y un secreto de cliente.

Seleccione Administrar > certificados & secretos en el panel de navegación izquierdo.

En la sección Secretos de cliente, seleccione Nuevo secreto de cliente. Agregue una descripción, seleccione una duración de expiración y, después, seleccione Agregar.

Después de crear el secreto de cliente, se mostrará una vez, por lo que asegúrese de copiarlo como secreto de cliente en el archivo de texto local para usarlo más adelante en este módulo. Si no copia este valor, tendrá que crear un nuevo secreto, ya que nunca podrá ver un secreto creado anteriormente.

Crear un certificado

A diferencia de Microsoft Graph, que permite la autenticación de aplicaciones con un identificador de cliente y un secreto, SharePoint requiere que la aplicación se autentique mediante el identificador de cliente y el certificado. Por lo tanto, ahora necesitamos crear un certificado.

Abra un símbolo del sistema de Windows PowerShell como administrador y ejecute el siguiente script de PowerShell. Cuando se le solicite, escriba el nombre del certificado, como 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

El script de PowerShell guardará el certificado (*.cer) y la clave privada (*.key) en la carpeta donde se ejecutó el script de PowerShell.

En el centro de administración de Microsoft Entra ID, en la página Certificados & secretos de la aplicación, seleccione Certificados y, a continuación, seleccione Cargar certificado.

Cargue el *.cer generado por el script de PowerShell, proporcione una descripción al certificado y, a continuación, seleccione Agregar.

Una vez cargado el certificado, copie toda la huella digital mostrada en el archivo de texto local.

Creación de un nuevo tipo de contenedor para la aplicación de SharePoint Embedded

El siguiente paso es crear un tipo de contenedor para la aplicación.

Abra un símbolo del sistema de Windows PowerShell como administrador.

Instalación o actualización del módulo de PowerShell de SharePoint Online

Si no ha instalado previamente el módulo de PowerShell de SharePoint Online , instálelo ejecutando el siguiente comando:

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

Si lo tiene instalado, asegúrese de que tiene la última instalada actualizándola:

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

Creación del tipo de contenedor

Con el módulo de PowerShell de SharePoint Online más reciente instalado, el siguiente paso es crear un tipo de contenedor en el inquilino.

Actualice los siguientes valores en el siguiente script de PowerShell y, a continuación, ejecute el script:

• {{SPO_ADMIN_URL}}: esta es la dirección URL del centro de administración de SharePoint Online. Para obtener esto, inicie sesión en [https://portal.microsoft.com](https://portal.microsoft.com) con la cuenta de administrador profesional y educativa de su inquilino, seleccione Mostrar todo en la parte inferior del panel de navegación izquierdo y, a continuación, seleccione Administración Centros > de SharePoint. Copie la dirección URL del Centro de administración de SharePoint y use este valor. Por ejemplo, si el identificador de inquilino es Contoso123, la dirección URL de administrador sería https://contoso123-admin.sharepoint.com.
• {{CONTAINER_TYPE_NAME}}: elija un nombre para el nuevo tipo de contenedor. Por ejemplo, use FirstContainerType.
• {{AZURE_ENTRA_APP_ID}}: establézcalo en el valor del identificador de aplicación de Microsoft Entra ID, también conocido como "id. de cliente", que creó anteriormente. Este valor debe estar en el archivo de texto 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}}"

El script de PowerShell mostrará los detalles del nuevo tipo de contenedor, por ejemplo:

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              :

Copie y ContainerTypeName en el ContainerTypeId archivo de texto local para su uso posterior.

Configuración de Postman para autenticarse con Microsoft Entra ID para obtener tokens de acceso a aplicaciones y delegados para Microsoft Graph y SharePoint Online

El último paso consiste en registrar el nuevo tipo de contenedor que creó en el inquilino de Microsoft 365 para desarrolladores o proveedores con el inquilino de consumo. Esto se hace con la API REST de SharePoint. Para este paso, usará el cliente de Postman.

Para poder llamar a la API REST de SharePoint con Postman, primero debe configurar Postman para obtener un token de acceso.

Creación de un nuevo entorno de Postman

En primer lugar, cree un nuevo entorno de Postman que almacene variables de entorno para simplificar las llamadas y centralizar toda nuestra configuración.

En Postman, seleccione Entornos y, a continuación, seleccione el icono más para crear un nuevo entorno.

Asigne al entorno el nombre SharePoint Embedded.

Agregue las siguientes variables al entorno y establezca el valor Inicial en las vales del archivo de texto local. Guarde el entorno una vez que haya agregado estas variables.

Seleccione el entorno seleccionándolo en el selector desplegable de la esquina superior derecha del cliente de Postman. La lista desplegable está justo debajo de los iconos de engranaje y alerta y encima de los botones Guardar y Compartir de la misma fila que las pestañas.

Creación de una nueva colección de Postman

A continuación, cree una nueva colección de Postman que almacenará las solicitudes y obtendrá los tokens de acceso.

En Postman, seleccione Colecciones y, a continuación, seleccione el icono más para crear una nueva colección.

Asigne a la colección el nombre SharePoint Embedded.

En la nueva colección, cree en conjuntos de carpetas mediante el contexto de la colección muchos para almacenar solicitudes de contenedores; uno en una carpeta delegada y otro en una carpeta Application :

Configuración de la carpeta Application de la colección Postman

El siguiente paso es actualizar la configuración de autenticación de la carpeta Application . Esto requiere un poco más de trabajo porque necesitamos obtener un token de solo aplicación para llamar a Microsoft Graph. Para ello, configurará la carpeta Application para descargar un script y almacenarlo en una variable global para usarlo más adelante.

Seleccione la carpeta Aplicación y, a continuación, seleccione la pestaña Autorización . Establezca Type enBearer Token (Token de portador ) y token (Token) en {{AppOnlyCertGraphToken}}.

Seleccione la pestaña Script de solicitud previa y escriba el siguiente script:

// 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());
      }
    }
  );
}

Guarde los cambios en la colección.

Configuración de la carpeta Contenedores> de aplicaciones de la colección Postman

A continuación, seleccione la carpeta Application > Containers de la colección.

En la pestaña Autorización , establezca tipo en Heredar autenticación del elemento primario.

En la pestaña Script de solicitud previa y escriba el siguiente script:

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();

Guarde los cambios en la colección.

En este momento, Postman ahora está configurado para obtener un token de acceso de solo aplicación para las llamadas a Microsoft Graph.

Registro del tipo de contenedor con el inquilino de consumo

Con Postman configurado, ahora puede agregar una solicitud para registrar el tipo de contenedor con el inquilino de consumo.

En Postman, seleccione Colecciones en el panel de navegación izquierdo y expanda el nodo Aplicación incrustada > de SharePoint , seleccione el menú contextual ... en el nodo Contenedores y seleccione Agregar solicitud.

Cambie el nombre de la solicitud a Registrar tipo de contenedor.

Establezca el método HTTP en PUT y el siguiente punto de conexión:

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

En el script de solicitud previa, agregue el código siguiente para obtener un token de solo aplicación para llamar a la API REST de 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();

En la pestaña Autorización , establezca Tipo en Token de portador y Token en {{AppOnlyCertSPOToken}}. Esta variable de token se crea y establece en el script de solicitud previa.

En la pestaña Cuerpo , seleccione el tipo sin procesar , establezca el tipo de datos en JSON y agregue el código siguiente al cuerpo:

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

Seleccione el botón Enviar para ejecutar la solicitud Registrar tipo de contenedor . Postman mostrará la respuesta debajo de la solicitud:

Resumen

En este ejercicio, ha creado una aplicación de Microsoft Entra ID, ha configurado SharePoint Embedded en el inquilino de Microsoft 365 SharePoint y ha creado su primer tipo de contenedor mediante PowerShell, una nueva colección postman y un entorno asociado para enviar solicitudes a las API REST de Microsoft Graph y SharePoint.