Instalar e configurar o SharePoint Embedded

Neste exercício, você criará um aplicativo do Microsoft Entra ID, configurará o SharePoint Embedded em seu locatário do Microsoft 365 SharePoint e criará seu primeiro Tipo de Contêiner e Contêiner.

Pré-requisitos

• O cliente de área de trabalho instalado pelo Postman entrou em uma conta gratuita ou paga do Postman.
• Acesso a uma conta de administrador em um locatário do Microsoft 365.
• Prompt do Windows PowerShell.

Registrar o aplicativo Microsoft Entra ID

Os aplicativos personalizados do SharePoint Embedded usam um aplicativo personalizado do Microsoft Entra ID para autenticar e obter as permissões necessárias para chamar as APIs do Microsoft Graph e do Microsoft SharePoint.

Abra um navegador e navegue até a entrada de administrador do Microsoft Entra ID. Entre usando uma conta corporativa ou de estudante para seu locatário do Microsoft 365 que tenha direitos de administrador global.

Selecione Aplicativos de identidade >> Registros de aplicativo na navegação à esquerda e selecione Novo registro.

Na página Registrar um aplicativo, defina os valores da seguinte forma, e depois selecione Registrar:

• Nome: Aplicativo incorporado do SharePoint
• Tipos de conta com suporte: contas em qualquer diretório organizacional (qualquer locatário do Microsoft Entra ID - multilocatário)

Depois de criar o aplicativo incorporado do SharePoint, o Microsoft Entra ID exibe os detalhes do novo aplicativo. Crie um arquivo de texto para controlar vários valores necessários posteriormente neste módulo.

Copie a ID do aplicativo (cliente) & ID do diretório (locatário) da página de visão geral do aplicativo para o arquivo de texto local.

Configurar autenticação

Em seguida, defina as configurações de autenticação do aplicativo. Selecione Gerenciar > Autenticação na navegação à esquerda e selecione Adicionar uma plataforma.

Selecione a opção Web e, para os URIs de redirecionamento, insira https://oauth.pstmn.io/v1/callback e selecione Configurar.

Em seguida, selecione Adicionar URI para a nova plataforma https://oauth.pstmn.io/v1/browser-callbackWeb e selecione Configurar.

Essas duas opções serão usadas para autenticar e obter tokens de acesso usando o cliente Postman posteriormente neste módulo.

Role para baixo até a seção Concessão implícita e fluxos híbridos , selecione a opção Tokens de acesso (usados para fluxos implícitos) e selecione Salvar.

Adicione outra plataforma selecionando Adicionar uma plataforma, Aplicativo de página única, defina o URI de redirecionamento como http://localhoste selecione Configurar.

Configurar permissões de API

Em seguida, configure o aplicativo com mais permissões para que ele possa criar e acessar Tipos de Contêiner e Contêineres.

Selecione Gerenciar > manifesto na navegação à esquerda. Localize a propriedade requiredResourceAccess e edite-a para que ela se pareça com o seguinte JSON:

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

Adicione as duas novas permissões ao objeto existente "resourceAppId": "00000003-0000-0000-c000-000000000000" para que ele agora tenha três (3) permissões.

Conceder consentimento de administrador para as novas permissões

Algumas das permissões exigem o consentimento do administrador. Selecione Permissões de API na navegação à esquerda, role até a parte inferior da página e selecione o link Aplicativos empresariais.

Na página Permissões, selecione Conceder consentimento de administrador para a Contoso. Se solicitado a entrar, use a mesma conta corporativa e de estudante usada para entrar no centro de administração do Microsoft Entra ID. Na página Permissões solicitadas , selecione Aceitar para conceder consentimento de administrador aos dois pares de permissões: FileStorageContainer.Selected para Microsoft Graph e Container.Selected para SharePoint. Os dois pares representam o aplicativo & opções delegadas para cada uma das duas permissões.

Criar um segredo do cliente

Para que um aplicativo se autentique usando o fluxo de credenciais do cliente OAuth2 com o Microsoft Entra ID, ele precisa da ID do cliente e de um segredo do cliente.

Selecione Gerenciar > certificados & segredos na navegação à esquerda.

Na seção Segredo do cliente, selecione Novo segredo do cliente. Adicione uma descrição e selecione uma duração de expiração e, em seguida, selecione Adicionar.

Depois de criar o segredo do cliente, ele será mostrado uma vez, portanto, copie-o como o segredo do cliente em seu arquivo de texto local para usar posteriormente neste módulo. Se você não copiar esse valor, terá que criar um novo segredo, pois nunca será possível visualizar um segredo criado anteriormente.

Criar um certificado

Ao contrário do Microsoft Graph, que permite a autenticação de aplicativo com uma ID e segredo do cliente, o SharePoint exige que o aplicativo se autentique usando a ID e o certificado do cliente. Portanto, agora precisamos criar um certificado.

Abra um prompt do Windows PowerShell como administrador e execute o seguinte script do PowerShell. Quando solicitado, insira o nome do seu certificado, como o 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

O script do PowerShell salvará o certificado (*.cer) e a chave privada (*.key) na pasta onde o script do PowerShell foi executado.

No centro de administração do Microsoft Entra ID, na página Certificados & segredos do aplicativo, selecione Certificados e, em seguida, selecione Carregar certificado.

Carregue o *.cer script gerado pelo PowerShell, forneça uma descrição ao certificado e selecione Adicionar.

Depois que o certificado for carregado, copie toda a impressão digital exibida para o arquivo de texto local.

Criar um novo Tipo de Contêiner para seu aplicativo SharePoint Embedded

A próxima etapa é criar um Tipo de Contêiner para seu aplicativo.

Abra uma solicitação do Windows PowerShell como administrador.

Instale ou atualize o módulo do PowerShell do SharePoint Online

Se você não instalou anteriormente o módulo PowerShell do SharePoint Online , instale-o executando o seguinte comando:

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

Se você o tiver instalado, certifique-se de ter a versão mais recente instalada atualizando-a:

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

Criar o tipo de contêiner

Com o módulo mais recente do PowerShell do SharePoint Online instalado, a próxima etapa é criar um Tipo de Contêiner em seu locatário.

Atualize os seguintes valores no seguinte script do PowerShell e execute o script:

• {{SPO_ADMIN_URL}}: Esta é a URL do seu centro de administração do SharePoint Online. Você pode obter isso entrando com o [https://portal.microsoft.com](https://portal.microsoft.com)Trabalho e a Escola da conta de administrador do seu locatário, selecione Mostrar Tudo na parte inferior da navegação à esquerda e, em seguida, selecione Centros > de Administração do SharePoint. Copie a URL do Centro de administração do SharePoint e use este valor. Por exemplo, se a ID do locatário for Contoso123, a URL de administrador será https://contoso123-admin.sharepoint.com.
• {{CONTAINER_TYPE_NAME}}: Escolha um nome para o seu novo Tipo de Contêiner. Por exemplo, use FirstContainerType.
• {{AZURE_ENTRA_APP_ID}}: defina isso como o valor da ID do aplicativo Microsoft Entra ID, também conhecida como "ID do cliente", que você criou anteriormente. Esse valor deve estar no arquivo 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}}"

O script do PowerShell exibirá os detalhes do seu novo Tipo de Contêiner, por exemplo:

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 o ContainerTypeId e ContainerTypeName para o arquivo de texto local para uso posterior.

Configurar o Postman para autenticar com o Microsoft Entra ID para obter tokens de acesso de delegado e aplicativo para o Microsoft Graph e o SharePoint Online

A última etapa é registrar o novo Tipo de Contêiner que você criou no locatário do Microsoft 365 desenvolvedor/provedor com o locatário consumidor. Isso é feito com a API REST do SharePoint. Para esta etapa, você usará o cliente Postman.

Antes de chamar a API REST do SharePoint com o Postman, primeiro você precisa configurar o Postman para obter um token de acesso.

Criar um novo ambiente do Postman

Primeiro, crie um novo ambiente do Postman que armazenará variáveis de ambiente para simplificar as chamadas e centralizar todas as nossas configurações.

No Postman, selecione Ambientes e, em seguida, selecione o ícone de adição para criar um novo ambiente.

Nomeie o ambiente como SharePoint Embedded.

Adicione as variáveis a seguir ao ambiente e defina o valor inicial para os valores do arquivo de texto local. Salve o ambiente depois de adicionar essas variáveis.

Selecione o ambiente selecionando-o no seletor suspenso no canto superior direito do cliente Postman. O menu suspenso está logo abaixo dos ícones de engrenagem e alerta e acima dos botões Salvar e Compartilhar na mesma linha das guias.

Criar uma nova coleção do Postman

Em seguida, crie uma nova coleção do Postman que armazenará as solicitações e obterá os tokens de acesso.

No Postman, selecione Coleções e, em seguida, selecione o ícone de adição para criar uma nova coleção

Nomeie a coleção como SharePoint Embedded.

Na nova coleção, crie conjuntos de pastas usando o contexto da coleção muitos para armazenar solicitações de contêineres; um em uma pasta Delegado e outro em uma pasta de Aplicativo :

Configure a pasta Aplicativo da coleção do Postman

A próxima etapa é atualizar a configuração de autenticação da pasta Aplicativo . Esse requer um pouco mais de trabalho porque precisamos obter um token somente de aplicativo para chamar o Microsoft Graph. Para fazer isso, você configurará a pasta Application para baixar um script e armazená-lo em uma variável global para uso posterior.

Selecione a pasta Aplicativo e, em seguida, selecione a guia Autorização . Defina o tipo como token de portador e o token como {{AppOnlyCertGraphToken}}.

Selecione a guia Script de pré-solicitação e insira o seguinte 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());
      }
    }
  );
}

Salve as alterações na coleção.

Configure a pasta Contêineres de Aplicativos > da coleção do Postman

Em seguida, selecione a pasta Contêineres de Aplicativos > da coleção.

Na guia Autorização , defina o Tipo como Herdar autenticação do pai.

Na guia Script de pré-solicitação , insira o seguinte 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();

Salve as alterações na coleção.

Neste ponto, o Postman agora está configurado para obter um token de acesso somente do aplicativo para chamadas para o Microsoft Graph.

Registrar o Tipo de Contêiner com seu Locatário de Consumo

Com o Postman configurado, agora você pode adicionar uma solicitação para registrar o Tipo de Contêiner com seu locatário consumidor.

No Postman, selecione Coleções na navegação à esquerda e expanda o nó Aplicativo Incorporado > do SharePoint , selecione o menu de contexto ... no nó Contêineres e selecione Adicionar solicitação.

Renomeie a solicitação para Registrar Tipo de Contêiner.

Defina o método HTTP como PUT e o seguinte ponto de extremidade:

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

No Script de Pré-solicitação, adicione o seguinte código para obter um token somente de aplicativo para chamar a API REST do 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();

Na guia Autorização , defina o Tipo como Token de Portador e o Token como {{AppOnlyCertSPOToken}}. Essa variável de token é criada e definida no script de pré-solicitação.

Na guia Corpo , selecione o tipo bruto , defina o tipo de dados como JSON e adicione o seguinte código ao corpo:

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

Selecione o botão Enviar para executar a solicitação Registrar Tipo de Contêiner . O Postman exibirá a resposta abaixo da solicitação:

Resumo

Neste exercício, você criou um aplicativo do Microsoft Entra ID, configurou o SharePoint Embedded em seu locatário do Microsoft 365 SharePoint e criou seu primeiro Tipo de Contêiner usando o PowerShell, uma nova coleção do Postman e ambiente associado para enviar solicitações às APIs REST do Microsoft Graph e do SharePoint.