Web Parts isoladas

Ao usar essa funcionalidade, você poderá criar web parts que se comunicam com segurança com APIs protegidas pelo Azure AD sem expor o token de acesso a outros componentes na página ou até mesmo scripts no locatário.

Por que web parts isoladas

Para permitir que suas soluções da Estrutura do SharePoint acessem com segurança APIs protegidas com o Azure AD, você pode usar o gerenciamento de API para especificar quais APIs podem ser acessadas por scripts no seu locatário e com quais permissões. Em seguida, usando a Estrutura do SharePoint, você pode facilmente recuperar um token de acesso para a API específica. Embora isso simplifique significativamente a comunicação com APIs protegidas com o Azure AD, isso permite que todos os scripts, não apenas soluções da Estrutura do SharePoint específicas, obtenham um token de acesso para qualquer uma das APIs aprovadas. Se um dos scripts usados no seu locatário foi explorado, ele pode acessar qualquer uma das APIs aprovadas em nome do usuário atual.

As web parts isoladas apresentam uma nova maneira de isolar o acesso às APIs protegidas com o Azure AD e garantir que apenas web parts da Estrutura do SharePoint específicas tenham permissão para obter um token de acesso para a API específica.

Como as web parts isoladas funcionam

Importante

A funcionalidade de Web Parts isoladas está disponível apenas na Estrutura do SharePoint v1.8 ou posterior. Web Parts isoladas só têm suporte em páginas modernas. Embora você possa adicionar Web Parts isoladas a páginas clássicas, após a publicação, a Web Part não renderizará e gerará um erro. As Web Parts isoladas só podem ser instaladas no catálogo de aplicativos do locatário. Eles não funcionarão de um catálogo de aplicativos do Conjunto de Sites.

As soluções que usam o recurso de web parts isoladas têm um sinalizador específico definido nos metadados do projeto no arquivo *.sppkg . Ao implantar essas soluções no catálogo de aplicativos, todas as solicitações de permissão da API são especificadas como isoladas.

Depois de aprovar uma solicitação de permissão de API isolada, o SharePoint criará um aplicativo separado do Azure AD no Azure AD vinculado ao locatário Microsoft 365 cliente. Esse aplicativo do Azure AD é específico para a solução da Estrutura do SharePoint que solicitou as permissões da API e terá permissões OAuth definidas conforme solicitado por essa solução. A URL de retorno desse aplicativo do Azure AD, que é usada pelo fluxo implícito do OAuth, será definida para um domínio exclusivo vinculado a esse aplicativo da Estrutura do SharePoint específico.

Todas as web parts de soluções que usam permissões isoladas, quando adicionadas a uma página, serão exibidas usando um iframe apontando para um domínio exclusivo vinculado à solução específica da Estrutura do SharePoint. Dessa forma, a Estrutura do SharePoint pode impor permissões exclusivas de API e garantir que nenhuma outra solução ou script no locatário possa obter um token de acesso para essas APIs.

Scaffolding de um projeto que usa permissões isoladas

Quando você estrutura um novo projeto da Estrutura do SharePoint direcionado ao SharePoint Online, o gerador Yeoman da Estrutura do SharePoint exibirá o seguinte prompt:

Os componentes da solução exigem permissões para acessar as APIs da Web que são exclusivas e não são compartilhadas com outros componentes no locatário?:

Se você responder Sim, o gerador adicionará um sinalizador à configuração do seu projeto no arquivo config/package-solution.json, definindo a isDomainIsolated propriedade como true. Como a funcionalidade de web parts isoladas se aplica apenas a web parts, o gerador permitirá apenas que você crie web parts no seu projeto.

Importante

Teoricamente, você pode criar manualmente uma extensão da Estrutura do SharePoint em um projeto que usa permissões isoladas. No entanto, isso é uma má ideia, algo que você nunca deve fazer e não tem suporte.

Se a extensão adicionada tiver se comunicado com APIs protegidas com o Azure AD, ela não poderá recuperar o token de acesso de uma maneira isolada e falhará no tempo de execução.

Comunicação com APIs

Apesar da Web Part usar permissões isoladas, não há nada específico sobre como obter um token de acesso para uma API protegida com o Azure AD em seu código. Além disso, embora no tempo de execução as web parts isoladas sejam carregadas dentro de um iframe apontando para um domínio único, você pode se comunicar com a API REST do SharePoint da mesma forma que faria em web parts não isoladas.

Implantando soluções com web parts isoladas

As soluções com web parts isoladas são implantadas da mesma forma que as soluções da Estrutura do SharePoint regulares. A única diferença é que as solicitações de permissão da API são implantadas como isoladas. Isso é claramente visível na página de gerenciamento de API, em que as solicitações de permissão da API são agrupadas por solução à qual se aplicam.

As permissões de API concedidas no nível do locatário podem ser usadas por qualquer solução da Estrutura do SharePoint ou parte do script no locatário. Por outro lado, as permissões isoladas podem ser usadas apenas pela solução que as solicitou.

Usando web parts isoladas

Quando adicionadas à página, as web parts isoladas são exibidas usando um iframe. Este iframe aponta para um domínio exclusivo atribuído à solução da Estrutura do SharePoint em que a web part está localizada. Também há referência a esse domínio na URL de retorno do aplicativo do Azure AD criado para hospedar as permissões isoladas para a solução específica da Estrutura do SharePoint. Usar o domínio exclusivo permite garantir que somente web parts da solução específica da Estrutura do SharePoint possam obter um token de acesso para o conjunto isolado de permissões.

Painel de propriedades de Web parts isoladas

O painel de propriedades de Web parts isoladas é renderizado como um iframe separado com uma instância adicional da mesma Web part. Ele traz alguns detalhes que os desenvolvedores devem estar cientes:

• Os eventos do ciclo de vida da Web part isolada, como render, serão chamados duas vezes: uma vez para a própria Web part e uma vez para o painel de propriedades.
• O tamanho do iframe do painel de propriedades está limitado às dimensões do painel. Leve isso em consideração se você planeja usar modais ou quaisquer controles amplos no seu painel de propriedades.

Descarte de Web parts isoladas

O método onDispose para Web parts isoladas não pode ser chamado de , pois a remoção do iframe do DOM limpa automaticamente todos os recursos, incluindo conexões de soquete, associados ao documento do iframe.

Atualizando um projeto existente para usar permissões isoladas

Se você estiver atualizando um projeto existente da Estrutura do SharePoint para v1.8.0 e quiser usar a funcionalidade de permissões isoladas, poderá fazer isso definindo no arquivo config/package-solution.json config/package-solution.json, a isDomainIsolated propriedade para true. Você deve assegurar que seu projeto contenha apenas web parts.

Depois de alterar o projeto para usar permissões isoladas, você deve reimplantá-lo. Isso emitirá novas solicitações de permissão de API, isoladas para sua solução, que precisam ser aprovadas por um administrador do locatário.

Removendo soluções com permissões isoladas

Ao aprovar permissões de API isoladas, o SharePoint cria um aplicativo do Azure AD dedicado para a solução da Estrutura do SharePoint que as solicitou. Quando a solução da Estrutura do SharePoint é removida do catálogo de aplicativos, as permissões de API e o aplicativo do Azure AD não são removidos.