Configurar e configurar o SharePoint Embedded

• 15 minutos

Neste exercício, irá criar uma aplicação Microsoft Entra ID, configurar o SharePoint Embedded no seu inquilino do Microsoft 365 SharePoint e criar o seu primeiro Tipo de Contentor e Contentor.

Pré-requisitos

• O Postman instalou o cliente de ambiente de trabalho com sessão iniciada numa conta gratuita ou paga do Postman.
• Acesso a uma conta de administrador num inquilino do Microsoft 365.
• Pedido do Windows PowerShell.

Registar a aplicação Microsoft Entra ID

As aplicações personalizadas do SharePoint Embedded utilizam uma aplicação Microsoft Entra ID personalizada para autenticar e obter as permissões necessárias para chamar as APIs do Microsoft Graph e do Microsoft SharePoint.

Abra um browser e navegue até à introdução de administrador do Microsoft Entra ID. Inicie sessão com uma Conta Escolar ou Profissional para o seu inquilino do Microsoft 365 que tenha direitos de administrador global.

Selecione Identity > Applications Registos de aplicações > no painel de navegação esquerdo e, em seguida, selecione Novo Registo.

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

• Nome: aplicação SharePoint Embedded
• Tipos de conta suportados: contas em qualquer diretório organizacional (qualquer inquilino do Microsoft Entra ID - Multi-inquilino)

Depois de criar a aplicação SharePoint Embedded, o Microsoft Entra ID apresenta os detalhes da nova aplicação. Crie um ficheiro de texto para controlar múltiplos valores de que irá precisar mais adiante neste módulo.

Copie o ID da Aplicação (Cliente) & O ID do Diretório (inquilino) da página de descrição geral da aplicação para o ficheiro de texto local.

Configurar autenticação

Em seguida, defina as configurações de autenticação do aplicativo. Selecione Gerir > Autenticação no painel de navegação esquerdo e, em seguida, selecione Adicionar uma plataforma.

Selecione a opção Web e, para os URIs de Redirecionamento, introduza 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.

Estas duas opções serão utilizadas para autenticar e obter tokens de acesso com o cliente Postman mais à frente neste módulo.

Desloque-se para baixo até à secção Concessão implícita e fluxos híbridos , selecione a opção Tokens de acesso (utilizados para fluxos implícitos) e, em seguida, selecione Guardar.

Adicione outra plataforma ao selecionar Adicionar uma plataforma, aplicação de página única, defina o URI de Redirecionamento como http://localhoste selecione Configurar.

Configurar Permissões de API

Em seguida, configure a aplicação com mais permissões para que possa criar e aceder a Contentores e Tipos de Contentor.

Selecione Gerir > Manifesto no painel de navegação esquerdo. Localize a propriedade requiredResourceAccess e edite-a para que 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" , pelo que tem agora três (3) permissões.

Conceder consentimento do administrador às novas permissões

Algumas das permissões requerem o consentimento do administrador. Selecione Permissões de API no painel de navegação esquerdo, desloque-se para a parte inferior da página e selecione a ligação Aplicações empresariais.

Na página Permissões, selecione Conceder consentimento do administrador para a Contoso. Se lhe for pedido para iniciar sessão, utilize a mesma conta Escolar e Profissional que utilizou para iniciar sessão no centro de administração do Microsoft Entra ID. Na página Permissões pedidas , selecione Aceitar para conceder consentimento do administrador aos dois pares de permissões: FileStorageContainer.Selected para o Microsoft Graph e Container.Selected para o SharePoint. Os dois pares representam a aplicação & opções delegadas para cada uma das duas permissões.

Criar um segredo do cliente

Para que uma aplicação se autentique com o fluxo de credenciais do cliente OAuth2 com o Microsoft Entra ID, precisa do ID de cliente e de um segredo do cliente.

Selecione Gerir > Certificados & segredos no painel de navegação esquerdo.

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, este será apresentado uma vez, por isso, certifique-se de que o copia como o segredo do cliente no ficheiro de texto local para utilização numa versão posterior deste 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 aplicações com um ID de cliente e segredo, o SharePoint requer que a aplicação se autentique com o ID de cliente e o certificado. Por isso, precisamos agora de criar um certificado.

Abra uma linha de comandos do Windows PowerShell como administrador e execute o seguinte script do PowerShell. Quando lhe for pedido, introduza o nome do 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

O script do PowerShell irá guardar 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 da aplicação, selecione Certificados e, em seguida, selecione Carregar certificado.

Carregue o *.cer gerado pelo script do PowerShell, dê uma descrição ao certificado e, em seguida, selecione Adicionar.

Assim que o certificado tiver sido carregado, copie todo o Thumbprint apresentado para o ficheiro de texto local.

Criar um novo Tipo de Contentor para a sua aplicação SharePoint Embedded

O próximo passo é criar um Tipo de Contentor para a sua aplicação.

Abra uma linha de comandos do Windows PowerShell como administrador.

Instalar ou atualizar o módulo do PowerShell do SharePoint Online

Se ainda não instalou o módulo do PowerShell do SharePoint Online , instale-o ao executar o seguinte comando:

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

Se o tiver instalado, certifique-se de que tem o mais recente instalado ao atualizá-lo:

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

Criar o Tipo de Contentor

Com o módulo mais recente do PowerShell do SharePoint Online instalado, o passo seguinte é criar um Tipo de Contentor no seu inquilino.

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

• {{SPO_ADMIN_URL}}: este é o URL do seu centro de administração do SharePoint Online. Pode obtê-lo iniciando sessão [https://portal.microsoft.com](https://portal.microsoft.com) no com o Trabalho e Escola da conta de administrador do seu inquilino, selecione Mostrar Tudo na parte inferior da navegação esquerda e, em seguida, selecione Centro > de Administração sharePoint. Copie o URL do centro de administração do SharePoint e utilize este valor. Por exemplo, se o seu ID de inquilino for Contoso123, o url de administrador será https://contoso123-admin.sharepoint.com.
• {{CONTAINER_TYPE_NAME}}: escolha um nome para o novo Tipo de Contentor. Por exemplo, utilize FirstContainerType.
• {{AZURE_ENTRA_APP_ID}}: defina este valor para o valor do ID da aplicação Microsoft Entra ID, também conhecido como "ID de cliente", que criou anteriormente. Este valor deve estar no ficheiro 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 apresentará os detalhes do novo Tipo de Contentor, 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 e para o ContainerTypeIdContainerTypeName ficheiro de texto local para utilização posterior.

Configurar o Postman para autenticar com o Microsoft Entra ID para obter tokens de acesso de delegados e aplicações para o Microsoft Graph e o SharePoint Online

O último passo consiste em registar o novo Tipo de Contentor que criou no inquilino do Microsoft 365 do programador/fornecedor com o inquilino que está a consumir. Isto é feito com a API REST do SharePoint. Neste passo, irá utilizar o cliente Postman.

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

Criar um novo ambiente do Postman

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

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

Atribua o nome SharePoint Embedded ao ambiente.

Adicione as seguintes variáveis ao ambiente e defina o valor Inicial para vales a partir do ficheiro de texto local. Guarde o ambiente depois de adicionar estas variáveis.

Selecione o ambiente ao selecioná-lo no seletor pendente no canto superior direito do cliente Postman. O menu pendente encontra-se imediatamente abaixo dos ícones de engrenagem e alerta e acima dos botões Guardar e Partilhar na mesma linha que os separadores.

Criar uma nova coleção do Postman

Em seguida, crie uma nova coleção do Postman que irá armazenar os pedidos 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

Atribua o nome SharePoint Embedded à coleção.

Na nova coleção, crie para conjuntos de pastas com o contexto muitos da coleção para armazenar pedidos de Contentores; uma numa pasta Delegada e outra numa pasta Aplicação :

Configurar a pasta Aplicação da coleção do Postman

O passo seguinte é atualizar a definição de autenticação da pasta Aplicação. Este requer um pouco mais de trabalho porque precisamos de obter um token apenas de aplicação para chamar o Microsoft Graph. Para tal, irá configurar a pasta Aplicação para transferir um script e armazená-lo numa variável global para utilização posterior.

Selecione a pasta Aplicação e, em seguida, selecione o separador Autorização . Defina o Tipo como Token de Portador e o Token como {{AppOnlyCertGraphToken}}.

Selecione o separador Script de pré-pedido e introduza 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());
      }
    }
  );
}

Guarde as alterações à coleção.

Configurar a pasta Contentores de Aplicações > da coleção do Postman

Em seguida, selecione a pasta Contentores de Aplicações > da coleção.

No separador Autorização , defina o Tipo como Herdar autenticação do elemento principal.

No separador Script de Pré-pedido e introduza 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();

Guarde as alterações à coleção.

Neste momento, o Postman está agora configurado para obter um token de acesso apenas à aplicação para chamadas para o Microsoft Graph.

Registar o Tipo de Contentor com o Seu Inquilino Consumidor

Com o Postman configurado, agora pode adicionar um pedido para registar o Tipo de Contentor com o seu inquilino consumidor.

No Postman, selecione Coleções no painel de navegação esquerdo e expanda o nó Aplicação Incorporada > do SharePoint , selecione o menu de contexto ... no nó Contentores e selecione Adicionar pedido.

Mude o nome do pedido para Registar Tipo de Contentor.

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

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

No Script de Pré-pedido, adicione o seguinte código para obter um token apenas de aplicação 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();

No separador Autorização , defina o Tipo como Token de Portador e o Token como {{AppOnlyCertSPOToken}}. Esta variável de token é criada e definida no script de pré-pedido.

No separador Corpo , selecione o tipo não processado , 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 o pedido Registar Tipo de Contentor . O Postman apresentará a resposta abaixo do pedido:

Resumo

Neste exercício, criou uma aplicação Microsoft Entra ID, configurou o SharePoint Embedded no seu inquilino do SharePoint do Microsoft 365 e criou o seu primeiro Tipo de Contentor com o PowerShell, uma nova coleção do Postman e um ambiente associado para submeter pedidos às APIs REST do Microsoft Graph e do SharePoint.

Verifique seu conhecimento