Configurar o ambiente do SharePoint Embedded e o projeto de aplicação Web

Neste exercício, irá criar um projeto que contém um componente do lado do servidor e do lado do cliente. O componente do lado do servidor é uma API REST que se autentica com Microsoft Entra ID e acederá aos Contentores Incorporados do SharePoint com o Microsoft API do Graph. O componente do lado do cliente é uma aplicação React de página única que irá chamar a API REST que expõe os conteúdos do Contentor Do SharePoint Embedded.

No final deste exercício, terá um projeto de modelo que irá utilizar para adicionar mais funcionalidades nas secções seguintes.

Ativar o SharePoint Embedded no seu inquilino do Microsoft 365 SharePoint Online

Para utilizar o SharePoint Embedded para criar e registar Tipos de Contentor, primeiro tem de ativá-lo no seu inquilino do SharePoint Online. Este processo tem de ser feito tanto no fornecedor como nos inquilinos que consomem onde define a sua aplicação e em quaisquer inquilinos que consumam que utilizem a sua aplicação SharePoint Embedded.

Ativar o SharePoint Embedded num inquilino do SharePoint Online é uma operação unidirecional; não pode ser desativada. Isto é para garantir que todas as aplicações que criou no inquilino consumidor continuarão a funcionar.

Depois de ativar o SharePoint Embedded num inquilino do SharePoint Online, poderá criar um Tipo de Contentor no inquilino do fornecedor e registar o Tipo de Contentor num inquilino consumidor.

Para ativar o SharePoint Embedded, navegue para o Centro de administração do Microsoft 365 (https://portal.microsoft.com) e inicie sessão com o Trabalho e Escola da sua conta de administrador do inquilino do Microsoft 365.

Selecione Mostrar Tudo na parte inferior do painel de navegação esquerdo e, em seguida, selecione Administração Centro > do SharePoint.

Em seguida, no centro de administração do SharePoint, selecione Definições no painel de navegação esquerdo. Localize e selecione SharePoint Embedded. Reveja os termos de serviço e selecione Ativar para ativá-lo no seu inquilino do SharePoint Online.

Criar Microsoft Entra ID Aplicação

Comece por criar a Aplicação Microsoft Entra ID. Isto será utilizado 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 para o centro de administração do Microsoft Entra (https://entra.microsoft.com). Entre usando uma Conta Corporativa ou de Estudante que tenha direitos de administrador global para os locatários.

Selecione Gerenciar > 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: O Meu SharePoint Embedded
• Tipos de conta suportados: apenas contas neste diretório organizacional (apenas Andrew Connell Inc. - Inquilino único)

Microsoft Entra ID apresentará 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.

Configurar autenticação

Em seguida, defina as configurações de autenticação do aplicativo. Selecione Gerenciar > autenticação na navegação à esquerda.

Selecione Adicionar uma plataforma e, em seguida, selecione Aplicação de página única.

No painel Configurar aplicação de página única , defina os URIs de Redirecionamento como http://localhost:3000 e selecione Configurar.

Configurar Permissões de API

Em seguida, defina as permissões de que a aplicação precisará para poder criar e aceder a Contentores e Tipos de Contentor.

Na página Gerir > Manifesto , localize a propriedade requiredResourceAccess.

O recurso existente com o resourceAppId conjunto como00000003-0000-0000-c000-000000000000 é o Microsoft Graph. Adicione a seguinte aplicação & permissão delegada para o âmbito FileStorageContainer.Selected . A permissão existente que já está presente destina-se ao âmbito 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"
    }
  ]
}

Em seguida, adicione um novo resourceAppId para o SharePoint cujo ID é 00000003-0000-0ff1-ce00-000000000000e adicione a seguinte aplicação & permissões delegadas para o âmbito 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"
    }
  ]
},

Adicionar uma Permissão Personalizada à Aplicação Microsoft Entra ID

Em seguida, adicione uma permissão personalizada à aplicação para que um administrador possa pedir ao utilizador para permitir que a aplicação faça a gestão dos contentores.

Na página Gerir > Expor uma API , selecione a ligação Definir junto ao URI do ID da Aplicação. Isso definirá o ID do aplicativo padrão a api://<app-id>.

Em seguida, selecione Adicionar um escopo para adicionar uma nova permissão para o aplicativo. Crie um novo escopo usando as seguintes configurações e selecione Adicionar escopo:

• Nome do âmbito: Container.Manage
• Quem pode consentir? Apenas administradores
• Administração (& User) consent title: Manage SharePoint Embedded Containers (Gerir Contentores Do SharePoint Embedded).
• Administração (& Utilizador): a aplicação pode chamar a API desta aplicação para gerir Contentores de Armazenamento Incorporados do SharePoint.
• Estado: Habilitado

Na API Web, irá adicionar código para garantir que esta permissão foi concedida à aplicação.

Conceder consentimento do administrador às novas permissões

Algumas das permissões requerem o consentimento do administrador. Na página Permissões da API , 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 de administrador para a Contoso e, em seguida, Aceite o pedido para conceder consentimento do administrador aos dois pares de permissões: FileStorageContainer.Selected para 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 Microsoft Entra ID, precisa do ID de cliente e de um segredo do cliente.

Selecione Gerenciar > Certificados e segredos na navegação à esquerda.

Na página Certificados & Segredos , selecione o separador Segredos do Cliente e, em seguida, selecione Novo segredo do cliente. Defina uma descrição e selecione uma duração de expiração e, em seguida, selecione Adicionar.

Quando o segredo for criado, 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 posterior 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 o Tipo de Contentor

O último passo é criar um novo Tipo de Contentor. Isto pode ser feito com o módulo do PowerShell do SharePoint Online. Certifique-se de que tem a versão mais recente instalada ao instalar...

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

... ou ao atualizar o que instalou anteriormente para garantir que tem a versão mais recente...

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

Assim que tiver a versão mais recente, ligue-se ao seu site do SharePoint Online e crie um novo Tipo de Contentor:

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 no Portal do Microsoft 365 (https://portal.microsoft.com) com o Trabalho e a Escola da conta de administrador do seu inquilino, selecione Mostrar Tudo na parte inferior da navegação esquerda e, em seguida, selecione Administração Centro > de 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 MyFirstSpeContainerType.
• {{AZURE_ENTRA_APP_ID}}: defina este valor para o valor do ID da aplicação Microsoft Entra ID, também conhecido como o "ID de cliente" que criou anteriormente. Este valor deve estar no ficheiro de texto 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}}"

O script do PowerShell apresentará os detalhes do novo Tipo de Contentor, por exemplo:

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              :

Copie o ContainerTypeId ficheiro de texto local para utilização posterior.

Registar o Tipo de Contentor no inquilino que consome

Por fim, como parte do último passo, tem de registar o Tipo de Contentor (atualmente definido no inquilino do fornecedor), nos inquilinos do consumidor. Isto aplica-se tanto para o inquilino único como para as aplicações multi-inquilino e garante que apenas as aplicações especificadas têm acesso aos Contentores no respetivo inquilino.

Se este passo não estiver concluído, a aplicação SharePoint Embedded obterá um erro de acesso negado ao tentar qualquer operação com um contentor.

Registe um Tipo de Contentor com a API REST do SharePoint Online. A API REST do SharePoint Online requer que uma aplicação se autentique com um certificado em vez de apenas um segredo do cliente.

Criar certificado autoassinado

Primeiro, crie um novo certificado autoassinado com o cmdlet do New-SelfSignedCertificate PowerShell. Atualize os seguintes valores no seguinte script do PowerShell e, em seguida, execute o script:

• {{CERT NAME}}: o nome do certificado. Isto pode ser o que quiser.
• {{CERT_PATH}}: o caminho completamente qualificado para a localização do ficheiro *.cer , como 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

Guarde o valor da chave privada no formato Base64, também conhecido como formato PEM, num novo ficheiro *.key com o mesmo nome que o ficheiro *.cer gerado.

Na página Gerir > Certificados & segredos , selecione Certificados e, em seguida, selecione Carregar certificado. Selecione o ficheiro *.cer e selecione Adicionar.

Depois de carregar o certificado, copie o Thumbprint apresentado na página Certificados & Segredos no portal do Microsoft Entra ID:

Registar o Tipo de Contentor no inquilino do consumidor

Em seguida, registe o Tipo de Contentor no inquilino do consumidor com o ponto final REST /_api/v2.1/storageContainerTypes/{{ContainerTypeId}}/applicationPermissions do SharePoint. A equipa do SharePoint Embedded facilitou este processo ao fornecer uma coleção do Postman repleta de vários exemplos ao chamar os diferentes pontos finais do SharePoint Online & Microsoft Graph.

No repositório Exemplos Incorporados do SharePoint, localize a coleção do Postman, obtenha o URL não processado da mesma e importe-o para o Postman como uma nova coleção:

Repare que a descrição geral da coleção contém uma grande quantidade de documentação. Uma secção importante abrange a criação de um ficheiro de ambiente do Postman para simplificar a definição dos valores necessários. Já criei um e só preciso de preencher os valores:

• ClientID: o Microsoft Entra ID ID de cliente ou aplicação da aplicação.
• ClientSecret: o Microsoft Entra ID segredo do cliente da aplicação.
• ConsumingTenantId: o ID do inquilino do Microsoft 365 do inquilino de consumidor que pretende direcionar.
• TenantName: o nome do seu inquilino. Esta é a parte do subdomínio do seu site do SharePoint Online.
• RootSiteUrl: o URL de raiz do seu inquilino.
• ContainerTypeID: o GUID do Tipo de Contentor criado no inquilino do fornecedor.
• CertThumbprint: o thumbprint do certificado Microsoft Entra ID apresentado após o carregamento com êxito do certificado para a aplicação Microsoft Entra ID.
• CertPrivateKey: a chave privada do certificado. Esta é a chave no formato PEM.

Assim que a coleção e o ambiente do Postman estiverem configurados, execute o pedido Register ContainerType na pasta Application > Containers . Após a conclusão do pedido, a aplicação que irá criar no resto deste módulo poderá gerir e aceder a contentores de armazenamento no meu inquilino do Microsoft 365.

Criar uma aplicação Web para aceder aos Contentores Do SharePoint Embedded

Com a configuração do SharePoint Embedded nos inquilinos do fornecedor e do consumidor, incluindo criar e registar o Tipo de Contentor, o passo seguinte é criar a aplicação. Esta aplicação será composta por dois projetos:

• Um projeto Web para criar e compor a aplicação de front-end React SPA
• Uma API do lado do servidor para alojar os métodos que requerem um cliente confidencial que executará operações que não podem ser feitas a partir da aplicação cliente.

Vamos começar por criar a parte de front-end do projeto:

Criar aplicação de front-end

A partir de uma linha de comandos, navegue para a pasta onde pretende criar a aplicação e execute o seguinte comando:

npx create-react-app my-first-spe-app --template typescript

Em seguida, instale pacotes npm que irão facilitar a interface de utilizador e a autenticação de SPA com Microsoft Entra ID. Na linha de comandos, mova-se para a pasta my-first-spe-app criada pelo comando anterior e execute o seguinte comando:

npm install @azure/msal-browser @fluentui/react-components @fluentui/react-icons @microsoft/mgt-react @microsoft/mgt-element @microsoft/mgt-msal2-provider -SE

Este comando irá instalar os seguintes pacotes npm:

• @azure/msal-browser: utilizado para autenticar com Microsoft Entra ID.
• @microsoft/mgt-element, @microsoft/mgt-react, & @microsoft/mgt-msal2-provider: o Toolkit do Microsoft Graph que contém componentes de IU para React.
• @fluentui/react-components & @fluentui/react-icons: componentes de IU da biblioteca Fluent UI v9.

Criar aplicação de back-end

Em seguida, crie e adicione os andaimes necessários para o servidor de API. Comece por executar o seguinte comando para instalar mais pacotes 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

Este comando irá instalar os pacotes npm:

• restify & @types/restify: um servidor de API de base de Node.js e declarações de tipo associadas para TypeScript.
• @azure/msal-node: utilizado para autenticar com Microsoft Entra ID.
• @microsoft/microsoft-graph-client: SDK JavaScript do Microsoft Graph.
• isomorphic-fetch: Polyfill que adiciona a API do browser fetch como global para que a sua API seja consistente entre o cliente & servidor.
• jsonwebtoken: Implementação de Tokens Web JSON.
• jwks-rsa: biblioteca para obter chaves de assinatura a partir de um ponto final JSON Web Key Set (JWKS).

Adicione uma configuração do compilador TypeScript para o projeto do lado do servidor:

• Crie um novo ficheiro, ./server/tsconfig.json projeto e adicione o seguinte código ao mesmo. Esta ação irá configurar o compilador TypeScript para a parte da API do lado do servidor deste projeto.

  {
    "$schema": "http://json.schemastore.org/tsconfig",
    "compilerOptions": {
      "target": "ES2015",
      "module": "commonjs",
      "lib": [
        "es5",
        "es6",
        "dom",
        "es2015.collection"
      ],
      "esModuleInterop": true,
      "moduleResolution": "node",
      "strict": true
    }
  }
  

Em seguida, adicione um marcador de posição para a API do lado do servidor a este projeto.

• Crie um novo ficheiro, ./server/index.ts, e adicione o seguinte código ao mesmo:

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

Esta ação cria um novo servidor Restify, configura-o para escutar pedidos na porta 3001 e ativa o CORS no servidor.

Adicionar definições e constantes globais do projeto

Em seguida, adicione algumas constantes para armazenar as definições de implementação

• Crie um novo ficheiro, ./.env, para armazenar as definições do servidor de API. Adicione o seguinte ao arquivo:

  API_ENTRA_APP_CLIENT_ID=
  API_ENTRA_APP_CLIENT_SECRET=
  API_ENTRA_APP_AUTHORITY=
  
  CONTAINER_TYPE_ID=
  

• Crie um novo ficheiro ./src/common/constants.ts para armazenar as definições da sua aplicação do lado do cliente. Adicione o seguinte ao arquivo:

  export const CLIENT_ENTRA_APP_CLIENT_ID = '';
  export const CLIENT_ENTRA_APP_AUTHORITY = '';
  
  export const API_SERVER_URL = '';
  
  export const CONTAINER_TYPE_ID = '';
  

Atualize os valores nestes dois ficheiros com a seguinte documentação de orientação:

• API_ENTRA_APP_CLIENT_ID: este é o ID da aplicação (cliente) da aplicação Microsoft Entra ID que criou anteriormente.
• API_ENTRA_APP_CLIENT_SECRET: este é o segredo da aplicação (cliente) da aplicação Microsoft Entra ID que criou anteriormente.
• API_ENTRA_APP_AUTHORITY: esta é a autoridade da aplicação Microsoft Entra ID. Utilize https://login.microsoftonline.com/{{MS-ENTRA-TENANT-ID}}/. O ID do inquilino é o ID do inquilino Microsoft Entra ID onde a aplicação foi criada anteriormente.
• API_SERVER_URL: este é o URL do servidor de API do lado do servidor. Utilize http://localhost:3001.
• CLIENT_ENTRA_APP_CLIENT_ID: este é o ID da aplicação (cliente) da aplicação Microsoft Entra ID que criou anteriormente.

Por fim, adicione um novo ficheiro, ./src/common/scopes.ts, para armazenar uma lista de âmbitos OAuth2 (permissões) que iremos utilizar na aplicação do lado do cliente:

// 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';

Crie um cop deste ficheiro para o servidor de API. Guarde o ficheiro copiado na seguinte localização no projeto: ./server/common/scopes.ts.

Configurar a compilação do projeto

Agora, vamos fazer algumas alterações ao projeto para simplificar as compilações e os testes.

Atualize os scripts para simplificar a criação dos projetos:

• Abra uma linha de comandos, defina a pasta atual para a raiz do projeto e execute o seguinte comando para instalar alguns pacotes npm utilizados no desenvolvimento:

  npm install env-cmd npm-run-all -DE
  

• Localize e abra o ficheiro ./package.json e atualize a scripts secção para o seguinte:

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

A lista seguinte explica o que os scripts fazem:

• Todos os scripts predefinidos create-react-app (CRE) foram atualizados para incluir o sufixo -cre no respetivo nome para indicar que estão associados à create-react-app.
• O script de início utiliza o método run-s do pacote npm-run-all npm para executar dois scripts sequencialmente:
  1. Primeiro, executa o script de compilação para transpor todo o projeto de TypeScript para JavaScript.
  2. Em seguida, executa o script start:apps.
• O script start:apps executa os scripts start:frontend & start:backend em paralelo com o método run-p do pacote npm-run-all npm.
• O script start:backend utiliza o pacote npm env-cmd para injetar as variáveis de ambiente no ficheiro ./.env no processo do servidor de API.

Neste momento, tem um projeto de modelo que irá utilizar para adicionar mais funcionalidades nas secções seguintes.

Resumo

Neste exercício, criou um projeto que contém um componente do lado do servidor e do lado do cliente. O componente do lado do servidor é uma API REST que se autentica com Microsoft Entra ID e acederá aos Contentores Incorporados do SharePoint com o Microsoft API do Graph. O componente do lado do cliente é uma aplicação React de página única que irá chamar a API REST que expõe os conteúdos do Contentor Do SharePoint Embedded.