Instalar e configurar o ambiente incorporado do SharePoint e o projeto de aplicativo Web

Neste exercício, você 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 o Microsoft Entra ID e acessará os Contêineres Incorporados do SharePoint usando a API do Graph. O componente do lado do cliente é um aplicativo React de página única que chamará a API REST que expõe o conteúdo do Contêiner Incorporado do SharePoint.

No final deste exercício, você terá um projeto de modelo que usará para adicionar mais funcionalidade nas seções a seguir.

Habilitar o SharePoint Embedded em seu locatário do Microsoft 365 SharePoint Online

Para usar o SharePoint Embedded para criar e registrar Tipos de Contêiner, primeiro você deve habilitá-lo em seu locatário do SharePoint Online. Esse processo deve ser feito no provedor e nos locatários de consumo, onde você define seu aplicativo, e em todos os locatários de consumo que usarão seu aplicativo incorporado do SharePoint.

Habilitar o SharePoint Embedded em um locatário do SharePoint Online é uma operação unidirecional; Ele não pode ser desabilitado. Isso é para garantir que todos os aplicativos criados no locatário consumidor continuem funcionando.

Depois de habilitar o SharePoint Embedded em um locatário do SharePoint Online, você poderá criar um Tipo de Contêiner em seu locatário do provedor e registrar o Tipo de Contêiner em um locatário consumidor.

Para habilitar o SharePoint Embedded, navegue até o Centro de administração do Microsoft 365 (https://portal.microsoft.com) e entre com o Trabalho e a Escola da conta de administrador do seu locatário do Microsoft 365.

Selecione Mostrar Tudo na parte inferior da navegação à esquerda e, em seguida, selecione Centros > de Administração do SharePoint.

Em seguida, no Centro de administração do SharePoint, selecione Configurações na navegação à esquerda. Localize e selecione o SharePoint Embedded. Examine os termos de serviço e selecione Habilitar para habilitá-lo em seu locatário do SharePoint Online.

Criar aplicativo do Microsoft Entra ID

Comece criando o aplicativo Microsoft Entra ID. Isso será usado 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é 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: Meu SharePoint Embedded
• Tipos de conta com suporte: somente contas neste diretório organizacional (somente Andrew Connell Inc. - locatário único)

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

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 Aplicativo de página única.

No painel Configure single-page application (Configure single-page application) e defina os URIs de redirecionamento e http://localhost:3000 selecione Configurar.

Configurar permissões de API

Em seguida, defina as permissões que o aplicativo precisará para criar e acessar Tipos de Contêiner e Contêineres.

Na página Gerenciar > manifesto , localize a propriedade requiredResourceAccess.

O recurso existente com o definido00000003-0000-0000-c000-000000000000 como é o resourceAppId Microsoft Graph. Adicione o seguinte aplicativo & permissão delegada para o escopo FileStorageContainer.Selected . A permissão existente que já está presente é para o escopo 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 cuja ID seja 00000003-0000-0ff1-ce00-000000000000e adicione o seguinte aplicativo & permissões delegadas para o escopo 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 ao aplicativo Microsoft Entra ID

Em seguida, adicione uma permissão personalizada ao aplicativo para que um administrador possa solicitar ao usuário que permita que o aplicativo gerencie contêineres.

Na página Manage > Expose an API , selecione o link Set ao lado do URI da ID do aplicativo. 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 escopo: Container.Manage
• Quem pode consentir? Somente administradores
• Administração (& usuário) título de consentimento: Gerenciar Contêineres Incorporados do SharePoint.
• Administração (& User) Descrição do consentimento: O aplicativo pode chamar a API desse aplicativo para gerenciar Contêineres de Armazenamento Incorporados do SharePoint.
• Estado: Habilitado

Na API Web, você adicionará código para garantir que essa permissão tenha sido concedida ao aplicativo.

Conceder consentimento de administrador para as novas permissões

Algumas das permissões exigem o consentimento do administrador. Na página Permissões da API , 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 e Aceite a solicitação para conceder consentimento de administrador para os 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 e segredos na navegação à esquerda.

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

Quando o segredo for criado, 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 o tipo de contêiner

A última etapa é criar um novo Tipo de Contêiner. Isso pode ser feito usando o módulo do PowerShell do SharePoint Online. Certifique-se de ter a versão mais recente instalada instalando...

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

... ou atualizando o que você instalou anteriormente para garantir que você tenha a versão mais recente...

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

Depois de ter a versão mais recente, conecte-se ao site do SharePoint Online e crie um novo Tipo de Contêiner:

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 no Portal do Microsoft 365 (https://portal.microsoft.com)com o Trabalho e a Escola da conta de administrador do 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 MyFirstSpeContainerType.
• {{AZURE_ENTRA_APP_ID}}: Defina isso como o valor da ID do aplicativo Microsoft Entra ID, também conhecida como a "ID do cliente" criada anteriormente. Esse valor deve estar no arquivo 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 exibirá os detalhes do seu novo Tipo de Contêiner, 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 arquivo de texto local para uso posterior.

Registrar Tipo de Contêiner no locatário consumidor

Por fim, como parte da última etapa, você precisa registrar o Tipo de Contêiner (que está definido no momento no locatário do provedor) no(s) locatário(s) consumidor(es). Isso é verdadeiro para aplicativos de locatário único e multilocatário e garante que apenas aplicativos especificados tenham acesso aos contêineres em seu locatário.

Se esta etapa não for concluída, o aplicativo SharePoint Embedded receberá um erro de acesso negado ao tentar qualquer operação com um contêiner.

Registrar um tipo de contêiner com a API REST do SharePoint Online. A API REST do SharePoint Online requer que um aplicativo seja autenticado com um certificado, em vez de apenas um segredo do cliente.

Criar certificado autoassinado

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

• {{CERT NAME}}: o nome do certificado. Pode ser o que você quiser.
• {{CERT_PATH}}: o caminho totalmente qualificado para o local do arquivo *.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

Salve o valor da chave privada no formato Base64, também conhecido como formato PEM, em um novo arquivo *.key com o mesmo nome do arquivo *.cer gerado.

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

Depois de carregar o certificado, copie a Impressão digital exibida na página Certificados & Segredos no portal Microsoft Entra ID:

Registrar Tipo de Contêiner no locatário consumidor

Em seguida, registre o Tipo de Contêiner com o locatário do consumidor usando o ponto de extremidade REST /_api/v2.1/storageContainerTypes/{{ContainerTypeId}}/applicationPermissions do SharePoint. A equipe do SharePoint Embedded facilitou isso fornecendo uma coleção do Postman repleta de muitos exemplos ao chamar os diferentes pontos de extremidade do SharePoint Online & do Microsoft Graph.

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

Observe que a visão geral da coleção contém um monte de documentação. Uma seção importante aborda a criação de um arquivo de ambiente do Postman para simplificar a configuração dos valores necessários. Já criei um e só preciso preencher os valores:

• ClientID: o aplicativo do aplicativo do Microsoft Entra ID ou a ID do cliente.
• ClientSecret: o segredo do cliente do aplicativo do Microsoft Entra ID.
• ConsumingTenantId: a ID do locatário do Microsoft 365 do locatário consumidor que você deseja direcionar.
• TenantName: o nome do seu locatário. Essa é a parte do subdomínio do seu site do SharePoint Online.
• RootSiteUrl: a URL raiz do seu locatário.
• ContainerTypeID: O GUID do Tipo de Contêiner criado no locatário do provedor.
• CertThumbprint: a impressão digital do certificado que o Microsoft Entra ID exibiu após o upload bem-sucedido do certificado para o aplicativo do Microsoft Entra ID.
• CertPrivateKey: a chave privada do certificado. Esta é a chave no formato PEM.

Depois que a coleção e o ambiente do Postman estiverem configurados, execute a solicitação Register ContainerType na pasta Contêineres de Aplicativos>. Após a conclusão da solicitação, o aplicativo que você criará no restante deste módulo poderá gerenciar e acessar contêineres de armazenamento em meu locatário do Microsoft 365.

Criar um aplicativo Web para acessar os Contêineres Incorporados do SharePoint

Com a configuração do SharePoint Embedded nos locatários do provedor e do consumidor, incluindo a criação e o registro do Tipo de Contêiner, a próxima etapa é criar o aplicativo. Esta candidatura será composta por dois projetos:

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

Vamos começar criando a parte front-end do projeto:

Criar aplicativo front-end

Em uma linha de comando, navegue até a pasta onde deseja criar o aplicativo e execute o seguinte comando:

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

Em seguida, instale pacotes npm que facilitarão a interface do usuário do SPA e a autenticação com o Microsoft Entra ID. Na linha de comando, vá 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

Esse comando instalará os seguintes pacotes npm:

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

Criar aplicativo back-end

Em seguida, crie e adicione o scaffolding necessário para o servidor de API. Comece executando 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 instalará os pacotes npm:

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

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

• Crie um novo arquivo, ./server/tsconfig.json projeto e adicione o seguinte código a ele. Isso configurará o compilador TypeScript para a parte da API do lado do servidor desse 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 espaço reservado para a API do lado do servidor a esse projeto.

• Crie um novo arquivo, ./server/index.ts, e adicione o seguinte código a ele:

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

Isso cria um novo servidor Restify, configura-o para escutar solicitações na porta 3001 e habilita o CORS no servidor.

Adicionar configurações e constantes globais do projeto

Em seguida, adicione algumas constantes para armazenar as configurações de implantação

• Crie um novo arquivo, ./.env, para armazenar configurações para seu 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 arquivo ./src/common/constants.ts para armazenar configurações para seu aplicativo 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 nesses dois arquivos usando as seguintes orientações:

• API_ENTRA_APP_CLIENT_ID: Essa é a ID do aplicativo (cliente) do aplicativo Microsoft Entra ID criado anteriormente.
• API_ENTRA_APP_CLIENT_SECRET: Este é o segredo do aplicativo (cliente) do aplicativo Microsoft Entra ID que você criou anteriormente.
• API_ENTRA_APP_AUTHORITY: Esta é a autoridade do aplicativo Microsoft Entra ID. Use https://login.microsoftonline.com/{{MS-ENTRA-TENANT-ID}}/. A ID do locatário é a ID do locatário do Microsoft Entra ID onde o aplicativo foi criado anteriormente.
• API_SERVER_URL: Esta é a URL do servidor de API do lado do servidor. Use http://localhost:3001.
• CLIENT_ENTRA_APP_CLIENT_ID: essa é a ID do aplicativo (cliente) do aplicativo Microsoft Entra ID que você criou anteriormente.

Por fim, adicione um novo arquivo, ./src/common/scopes.ts, para armazenar uma lista de escopos (permissões) OAuth2 que usaremos no aplicativo 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 arquivo deste tipo para o servidor de API. Salve o arquivo copiado no seguinte local do projeto: ./server/common/scopes.ts.

Configurar a compilação do projeto

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

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

• Abra um prompt de comando, defina a pasta atual como a raiz do seu projeto e execute o seguinte comando para instalar alguns pacotes npm usados no desenvolvimento:

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

• Localize e abra o arquivo ./package.json e atualize a scripts seçã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 a seguir explica o que os scripts fazem:

• Todos os scripts padrão create-react-app (CRE) foram atualizados para incluir o sufixo -cre em seu nome para indicar que estão associados ao create-react-app.
• O script start usa o método run-s do pacote npm-run-all npm para executar dois scripts sequencialmente:
  1. Primeiro, ele executa o script de construção para transpilar 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 usando o método run-p do pacote npm-run-all npm .
• O script start:backend usa o pacote env-cmd npm para injetar as variáveis de ambiente no arquivo ./.env no processo do servidor de API.

Neste ponto, você tem um projeto de modelo que usará para adicionar mais funcionalidade nas seções a seguir.

Resumo

Neste exercício, você 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 o Microsoft Entra ID e acessará os Contêineres Incorporados do SharePoint usando a API do Graph. O componente do lado do cliente é um aplicativo React de página única que chamará a API REST que expõe o conteúdo do Contêiner Incorporado do SharePoint.