Criação de Suplementos do SharePoint que usem a biblioteca de domínio cruzado

  • Artigo

Existem alguns cenários em que nem os sistemas de autorização de baixa confiança, nem os de alta confiança podem ser usados por um Suplemento do SharePoint, ou eles não são uma boa opção como o único meio para que o suplemento obtenha autorização para os recursos do SharePoint.

Exemplos:

  • Os componentes remotos do Suplemento do SharePoint não estão no local, mas um firewall corporativo bloqueia a comunicação de servidor para servidor entre o SharePoint e o ACS, impedindo, assim, o uso do sistema de baixa confiança.

  • O Suplemento do SharePoint foi projetado como um aplicativo Web de página única que depende de JavaScript do lado do cliente para operações de dados com o SharePoint.

  • O Suplemento do SharePoint depende principalmente de chamadas de servidor para servidor para acessar os dados do SharePoint (e está autorizado por sistemas de alta ou baixa confiança), mas precisa ser complementado com algumas chamadas de JavaScript. Por exemplo, uma página com muitos elementos gráficos pode usar o JavaScript para fazer pequenas atualizações nos dados exibidos sem precisar recarregar a página inteira.

No entanto, por segurança, os navegadores não permitem que o JavaScript hospedado em um domínio acesse os recursos em outro domínio, para isso é necessário uma técnica especial para permitir que o JavaScript remoto acesse os recursos do SharePoint. A biblioteca de JavaScript entre domínios do SharePoint facilita o uso dessa técnica pelo aplicativo Web remoto.

Observação

A biblioteca de domínio cruzado também é usada para permitir o acesso aos dados na direção contrária, ou seja, para permitir que o JavaScript em uma página do SharePoint acesse os dados em um domínio remoto. Para saber mais, confira Acessar dados remotos de uma página do SharePoint.

Compreender a arquitetura da biblioteca de domínio cruzado

A biblioteca de domínio cruzado do SharePoint está no arquivo SP.RequestExecutor.js, localizado na pasta virtual /_layouts/15/ de cada site do SharePoint. Os scripts no arquivo encapsulam uma técnica reconhecida segura para superar a restrição do navegador no script entre domínios: um iFrame pode se comunicar com sua página pai por meio da função window.postMessage(), mesmo se a página do iFrame estiver em um domínio diferente. Então as solicitações e respostas de dados são passadas sobre o limite de domínio, usando chamadas para postMessage().

Aviso

A função postMessage() só funciona em navegadores que oferecem suporte a HTML 5, de modo que os Suplementos do SharePoint que usam a biblioteca de domínio cruzado não funcionarão em navegadores mais antigos.

Para o Microsoft Office SharePoint Online, a biblioteca de domínio cruzado é carregada em uma página do aplicativo Web remoto onde ela cria um iFrame oculto que hospeda uma página de proxy especial do domínio do SharePoint. A página proxy já existe em todos os sites do Microsoft Office SharePoint Online.

A biblioteca é usada para criar um objeto JSON (JavaScript Object Notation) que contém todas as informações necessárias para fazer uma chamada CRUD para as APIs de REST do SharePoint. O objeto JSON será passado para a página de proxy usando postMessage(). Na página de proxy, onde a biblioteca também foi carregada, o objeto JSON é analisado e reconstruído como uma chamada de REST do SharePoint. Como a página de proxy está no domínio do SharePoint, o navegador permite a chamada.

É claro que os componentes remotos do Suplemento do SharePoint ainda precisam ter acesso autorizado aos recursos do Microsoft Office SharePoint Online. Há duas maneiras de fazer isso:

  • Definir o tipo de entidade do suplemento como RemoteWebApplication (o padrão para aplicativos hospedados pelo provedor) no manifesto do suplemento. Quando o suplemento estiver registrado com ACS, a inscrição inclui o domínio do aplicativo Web remoto. O SharePoint confia nos domínios registrados no ACS, mesmo que não esteja, nesse cenário, usando qualquer um dos fluxos de passagem de token que fazem parte do sistema de baixa confiança do lado do servidor. Confira informações detalhadas sobre como registrar os suplementos em Registrar suplementos do SharePoint.

  • Em um suplemento hospedado do SharePoint, você pode deixar o tipo de entidade do suplemento definido como padrão, que é Internal. Em seguida, você pode definir o atributo AllowedRemoteHostUrl do elemento Internal para a URL do aplicativo Web remoto, como no exemplo a seguir.

  <AppPrincipal>
    <Internal AllowedRemoteHostUrl="https://example.com/Home.html" />
  </AppPrincipal>

Observação

Se você usar a segunda opção (uma entidade de suplemento Internal), será possível usar apenas o JavaScript e a biblioteca de domínio cruzado para acessar o SharePoint. O modelo de objeto de cliente do SharePoint está bloqueado para Suplementos do SharePoint Internal; portanto, não é possível ter um sistema de autorização dupla que use a biblioteca de domínio cruzado e os sistemas de alta e baixa confiança.

Saiba mais sobre como usar a biblioteca em Acessar dados do SharePoint de suplementos usando a biblioteca de domínio cruzado.

Acessar dados remotos de uma página do SharePoint

A biblioteca de domínio cruzado do SharePoint também pode ser usada em direção inversa; ou seja, o JavaScript na página do SharePoint pode usar a biblioteca para obter dados de componentes remotos do suplemento. Para fazer isso, você inverte a arquitetura entre domínios: você cria uma página de proxy no aplicativo Web remoto. A biblioteca é chamada da página do SharePoint em que cria um iFrame para hospedar a página de proxy.

Saiba mais sobre como usar a biblioteca dessa maneira em Criar uma página de proxy personalizada para a biblioteca de domínio cruzado no SharePoint.

Confira também