Criação de suplementos do SharePoint que usem autorização de baixo nível de confiança

  • Artigo

Os componentes remotos em um Suplemento do SharePoint (ou aplicativo externo) podem obter autorização para recursos do SharePoint ao passar um token de acesso para o SharePoint com cada solicitação HTTP. Componentes remotos obtêm o token de acesso de uma conta do ACS (Serviço de Controle de Acesso) do Microsoft Azure que está associada ao locatário do Office 365 do cliente. O Azure ACS atua como o servidor de autorização em uma transação do OAuth 2.0, chamada fluxo, com o SharePoint como o servidor de recursos e os componentes remotos como o cliente. Confira as especificações de protocolo relacionadas em Protocolo de autorização da Web (oauth).

Importante

O Controle de Acesso do Azure (ACS), um serviço do Azure Active Directory (Azure AD) será desativado em 7 de novembro de 2018. Essa desativação não afeta o modele do Suplemento do SharePoint que usa o nome de host https://accounts.accesscontrol.windows.net (que não é afetado por ela). Para saber mais, confira Impacto da desativação do Controle de Acesso do Azure para Suplementos do SharePoint.

Os Suplementos do SharePoint hospedados pelo provedor que usam o sistema de autorização de baixa confiabilidade podem ser vendidos na Office Store e instalados no Microsoft SharePoint Online ou em um farm do SharePoint no local que tenha sido configurado para usar o locatário do Office 365 do cliente para estabelecer a confiança com o Azure ACS. O cliente deve ter um locatário do Office 365 para instalar Suplementos do SharePoint que usem o sistema de baixa confiabilidade. No entanto, não é necessário que o cliente use o locatário para qualquer outra finalidade. Veja instruções sobre como vincular um farm local a um locatário do Office 365, em Usar um site do SharePoint do Office 365 para autorizar suplementos hospedados pelo provedor em um site do SharePoint local.

Registro no Azure ACS

Para usar o sistema de baixa confiabilidade, primeiro o Suplemento do SharePoint deve ser registrado no Azure ACS e no Serviço de Gerenciamento de Aplicativos do farm do SharePoint ou do locatário do SharePoint Online. (Este recurso se chama "Serviço de Gerenciamento de Aplicativos" porque os Suplementos do SharePoint eram originalmente chamado de "aplicativos do SharePoint").

Para suplementos vendidos na Office Store, o registro no ACS é executado no Painel do Vendedor e o registro no serviço é executado quando o suplemento for instalado.

Para suplementos distribuídos no catálogo de suplementos da organização, o registro no ACS e no serviço é realizado na página _Layouts\15\AppRegNew.aspx de qualquer locação ou farm do SharePoint em que o suplemento deve ser instalado. Também é necessário registrar aplicativos externos que não sejam do SharePoint mas que acessam o SharePoint. Essa categoria inclui Suplementos do Office, aplicativos da Windows Store, aplicativos Web e de dispositivos como smartphone.

Observação

O registro requer que o aplicativo tenha um domínio na Internet. Qualquer domínio existente pode ser usado para essa finalidade, mas pode ser que você não tenha 100% de certeza de que qualquer domínio que não seja de sua propriedade sempre existirá; portanto, um aplicativo Web precisaria ser parte de um aplicativo de dispositivo nativo, mesmo que o componente de aplicativo Web não tenha nenhuma outra função além da habilitação do registro. Veja um exemplo de código avançado projetado dessa maneira em Provisionar sites em lotes com o modelo de suplemento.

Saiba mais sobre registro em Registrar Suplementos do SharePoint.

Expiração secreta de suplemento

O segredo do suplemento precisa ser substituído a cada 12 meses. Confira os detalhes em Substituir um segredo do cliente prestes a expirar em um Suplemento do SharePoint.

Políticas de autorização

Um suplemento do SharePoint pode ser projetado para usar uma das três políticas de autorização:

  • Política somente usuário. Quando a política somente usuário é usada, o SharePoint verifica apenas as permissões do usuário. O SharePoint usa essa política quando o usuário está acessando recursos diretamente sem usar um suplemento, como quando um usuário abre primeiro a página inicial de um site do SharePoint ou acessa APIs do SharePoint desde o PowerShell.

  • Política somente suplemento. Um suplemento com essa política pode executar qualquer ação que tenha permissão para fazê-lo, mesmo que o usuário não tenha permissão para a ação. O desenvolvedor deve solicitar que essa política seja usada no manifesto do suplemento. A solicitação deve ser aprovada pelo usuário que instala o suplemento. Essa política é permitida apenas para Suplementos do SharePoint hospedados pelo provedor.

  • Política usuário+suplemento. Os suplementos que usam essa política só podem executar ações que tanto o usuário como o suplemento tenham permissão para fazer. Esta é a política padrão usada, a menos que o desenvolvedor tome etapas específicas para usar outra.

Saiba mais sobre políticas de autorização em Tipos de política de autorização de suplemento no SharePoint.

Dois fluxos de tempo de execução do OAuth

Sempre que um Suplemento do SharePoint hospedado na nuvem ou um aplicativo externo que acessa o SharePoint é executado, ocorre um fluxo ou uma série de interações entre o suplemento, o SharePoint, o ACS e, às vezes, o usuário final. O resultado final do fluxo é que o SharePoint recebe um token de acesso que acompanha cada solicitação para criar, ler, atualizar e excluir (CRUD) que o aplicativo faz para o SharePoint.

Há dois fluxos OAuth principais usados pelo SharePoint. Uma delas é para suplementos do SharePoint hospedados na nuvem. O outro, chamado "em tempo real", é para aplicativos em outras plataformas que acessam dados do SharePoint.

  • Fluxo de token de contexto. O componente remoto do Suplemento do SharePoint usa o CSOM (modelo de objeto do cliente do SharePoint) ou pontos de extremidade REST para fazer chamadas para o SharePoint. O SharePoint solicita um token de contexto do ACS, que pode enviar para o servidor remoto. O servidor remoto usa o token de contexto para solicitar um token de acesso ao ACS. Em seguida, o servidor remoto usa o token de acesso para responder ao SharePoint.

    Confira os detalhes sobre esse fluxo em Fluxo do token de contexto do OAuth para Suplementos do SharePoint.

  • Fluxo do código de autenticação. Um Suplemento do SharePoint recebe as permissões necessárias para os recursos do SharePoint quando é instalado. Mas os aplicativos que não estão instalados no SharePoint precisam solicitar permissões "na hora", ou seja, sempre que forem executados. Não há nenhum token de contexto do SharePoint nesse fluxo. Em vez disso, quando o suplemento é executado e tenta acessar o SharePoint, o SharePoint solicita que o usuário conceda permissões para o aplicativo solicitante. Quando o usuário concede as permissões, o SharePoint obtém um código de autorização do ACS que é passado para o aplicativo. O aplicativo usa o código para obter um token de acesso do ACS que depois pode ser usado para se comunicar com o SharePoint.

    Confira os detalhes sobre esse fluxo em Fluxo de código de autorização do OAuth para Suplementos do SharePoint.

Solução de problemas relativos a Suplementos do SharePoint de baixo nível de confiança

Este artigo fornece algumas diretrizes e informações gerais sobre a solução de problemas relacionados a algumas questões específicas de suplementos do SharePoint que usam o sistema de autorização de confiança baixa.

Usar a ferramenta Fiddler

A ferramenta gratuita Fiddler pode ser usada para capturar as solicitações HTTP enviadas pelo componente remoto do seu suplemento para o SharePoint. Há uma extensão gratuita para a ferramenta que decodifica automaticamente os tokens de acesso nas solicitações.

Desativar o requisito de HTTPS para o OAuth durante o desenvolvimento

O OAuth requer que o SharePoint execute o HTTPS (não apenas o serviço, mas o SharePoint também). Isso pode atrapalhar o desenvolvimento do seu suplemento. Por exemplo, você pode receber uma mensagem 403 (proibido) ao tentar fazer uma chamada para o SharePoint ao depurar o suplemento porque não há suporte a SSL no "localhost" em que o suplemento está em execução.

Você pode desativar o requisito de HTTPS durante o desenvolvimento usando os seguintes cmdlets do Windows PowerShell.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $true
$serviceConfig.Update()

Para reativar o requisito de HTTPS mais tarde, use os seguintes cmdlets do Windows PowerShell.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $false
$serviceConfig.Update()

Uma incompatibilidade de nomes de domínio em arquivos de configuração e formulários de registro pode impedir a autorização. Os quatro valores a seguir devem ser exatamente os mesmos:

  • O Domínio do Suplemento especificado quando o suplemento do SharePoint é registrado no AppRegNew.aspx ou no Painel do Vendedor.

  • O domínio sob o qual o certificado de segurança do aplicativo Web remoto é registrado.

  • A parte de domínio do valor StartPage no arquivo AppManifest.xml.

  • A parte de domínio das URLs de qualquer receptor de evento especificado no AppManifest.xml.

Em relação a esse ponto, observe o seguinte:

  • Se o componente remoto do seu suplemento do SharePoint estiver usando qualquer porta diferente da 443, você deverá incluir explicitamente a porta como parte do domínio em todos os quatro lugares, por exemplo, contoso.com:3333. (Você deve usar o protocolo HTTPS para o qual a porta padrão é 443).

  • Se você criar um alias CNAME DNS para seu aplicativo Web remoto, use o alias CNAME para o valor de domínio em todos os quatro locais. Por exemplo, se seu aplicativo estiver hospedado no contoso.cloudapp.net e você criar um CNAME de contososoftware.com para ele, use contososoftware.com como o domínio.

  • O domínio deve ser codificado no valor StartPage (e nas URLs de destinatário de qualquer evento) do arquivo AppManifest.xml antes que o suplemento seja empacotado. Se você usar o Assistente de Publicação no Visual Studio para empacotar o suplemento, será solicitado o domínio e as Office Developer Tools para Visual Studio as inserem no valor StartPage para você, no lugar do token ~remoteWebUrl usado durante a depuração. Mas se não estiver usando o Assistente de Publicação, ou mesmo se estiver, mas o aplicativo Web remoto estiver implantado no Azure, será necessário substituir manualmente o token pelo domínio (e protocolo); por exemplo, https://contososoftware.com ou https://MyCloudVM:3333.

Erro "A conexão subjacente estava fechada: Não foi possível estabelecer relação de confiança para o canal seguro de SSL/TLS".

Esse erro é um problema de aperto de mão SSL, não um problema de OAuth. Verifique se o certificado que você está usando é confiável pelo SharePoint e se o certificado corresponde ao nome do ponto de extremidade.

Erros ao usar o método HTTP DAV para ler arquivos do SharePoint

O HTTP DAV não funciona com o OAuth. Se você estiver usando o modelo de objeto cliente do SharePoint (CSOM), use o código a seguir para ler um arquivo.

File f = clientContext.Web.GetFileByServerRelativeUrl( url);
ClientResult<Stream> r = f.OpenBinaryStream();
clientContext.ExecuteQuery();

Confira também