Token de contexto de fluxo de OAuth para Suplementos do SharePoint
No SharePoint, o fluxo de autorização e autenticação OAuth para um suplemento hospedado em provedor e de baixa confiabilidade envolve uma série de interações entre o seu suplemento, o SharePoint, o servidor de autorização e o navegador no tempo de execução. O servidor de autorização neste cenário é o Serviço de Controle de Acesso (ACS) do Microsoft Azure.
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.
Com um suplemento hospedado pelo provedor, temos um aplicativo ou serviço remoto da Web separado do SharePoint e que não faz parte do farm do SharePoint nem da locação do SharePoint Online. Ele pode ser hospedado na nuvem ou em um servidor físico. Neste artigo, o componente remoto é chamado de Contoso.com.
Observação
O componente remoto também pode hospedar receptores de eventos que respondem a eventos que ocorrem em itens do SharePoint, como listas ou itens de listas. Os exemplos de eventos remotos que o Contoso.com pode desejar atender são listas de eventos, como adicionar ou remover um item de lista; ou eventos de rede, como adicionar ou deletar um site. Confira mais informações sobre como criar receptores remotos de evento em Criar um receptor de eventos remoto nos Suplementos do SharePoint.
O Contoso.com usa o modelo de objeto de cliente do SharePoint (CSOM) ou as REST APIs do SharePoint para fazer chamadas para o SharePoint. O aplicativo Contoso.com usa um fluxo de passagem de token OAuth para autenticar com o SharePoint. SharePoint e o Contoso.com não confiam um no outro, mas ambos confiam no ACS e aceitam tokens emitidos pelo ACS.
Há três tokens envolvidos: o SharePoint faz o ACS criar um token de contexto que o SharePoint repassa para o Constoso.com. O Contoso.com valida que o token de contexto foi emitido pelo ACS, então confia nele. O Contoso.com então extra um novo token do contexto do token e o usa para conseguir um token de acesso diretamente com o ACS. Isso inclui o token de acesso em todos os requisitos ao SharePoint. O SharePoint valida que o token de acesso foi emitido pelo ACS, então responde à solicitação do Contoso.com.
Você fornece o código de tratamento de token no componente remoto (mas se o componente remoto estiver hospedado no .NET, as Ferramentas do Microsoft Office Developer para Visual Studio fornecerão código de exemplo que faz boa parte do trabalho por você). Confira mais informações sobre o código de tratamento de token em Manipular tokens de segurança em suplementos do SharePoint de baixa confiança hospedados pelo provedor.
Pré-requisitos
Os passos preliminares a seguir devem ser concluídos antes de o Suplemento do SharePoint poder usar o fluxo de token de contexto:
Os requisitos a seguir se aplicam apenas se você estiver instalando o suplemento do SharePoint localmente, além do SharePoint Online; esses requisitos não se aplicam se você estiver instalando apenas o suplemento do SharePoint para o SharePoint Online
- O farm deve ser configurado para suportar suplementos. Esse é um requisito para instalar quaisquer Suplementos do SharePoint no farm, mesmo se eles não usarem o fluxo de Token de Contexto. Confira mais informações em Ferramentas e ambientes para desenvolver suplementos do SharePoint.
- O cliente que estiver instalando o suplemento deverá ter uma conta do Office 365. Isso é necessário para ter acesso ao ACS. O cliente não precisa usar sua conta para nenhuma outra finalidade.
- O farm deve ser configurado para compartilhar a relação de confiança que o Office 365 tem com o ACS. Isso é facilmente realizado com os scripts do Windows PowerShell. Confira mais informações em Usar um site do Office 365 SharePoint para autorizar suplementos hospedados pelo provedor em um site do SharePoint local.
Independentemente de o suplemento estar instalado no SharePoint Online ou em um farm do SharePoint local, o Suplemento do SharePoint deve ser registrado com o ACS. Confira detalhes sobre esse procedimento em Registrar suplementos de SharePoint. Entre outras coisas, o suplemento fornece ao ACS seu ID de cliente e o segredo do cliente como parte do registro.
Etapas de fluxo do token de contexto
O fluxo de autenticação e autorização OAuth para um suplemento do SharePoint hospedado pelo provedor é mostrado na figura a seguir.
Fluxo do token de contexto do OAuth
Estas são as etapas que correspondem aos números na figura:
Um usuário lança o Suplemento do SharePoint do SharePoint. O desenho do suplemento determina como ele é feito:
- Se o suplemento tiver sido projetado para exibir o aplicativo da Web remoto (em Contoso.com) em uma parte do suplemento (que é essencialmente um wrapper em torno de um IFRAME ), iniciar o suplemento simplesmente significa navegar para uma página do SharePoint que contém a parte do suplemento. Se o usuário ainda não estiver conectado, o SharePoint solicitará que ele entre. O SharePoint processa a página e detecta que há um componente do aplicativo Contoso.com na página. Confira mais informações sobre partes do suplemento em Criar partes suplementares para instalar com o seu Suplemento do SharePoint.
- Se o suplemento tiver sido projetado para ser usado como uma página inteira no navegador, o usuário o iniciará selecionando seu bloco de suplemento na página Conteúdo do site do site do SharePoint. Uma variação disso é quando o suplemento inclui um menu personalizado ou item da faixa de opções que inicia o componente remoto.
Independentemente de como o suplemento seja lançado, o SharePoint precisa obter um token de contexto que consiga enviar para o aplicativo Contoso.com e, por isso, solicita ao ACS que crie um token de contexto que contenha informações sobre o contexto do SharePoint, incluindo o usuário atual, a URL do aplicativo remoto e outras informações. O token de contexto também contém um token de atualização criptografado.
O ACS sinaliza o token de contexto usando um algoritmo que usa o segredo do suplemento Contoso.com e o retorna ao SharePoint. Apenas o ACS e o suplemento Contoso.com conhecem o segredo.
Se o aplicativo Contoso.com for exibido em uma parte do suplemento, o SharePoint renderizará a página que hospeda a parte do suplemento e adicionará o token de contexto à URL que o IFRAME na parte do suplemento chama para obter o conteúdo dele. Se o aplicativo Contoso.com for uma página completa, o SharePoint redirecionará o navegador para Contoso.com e incluirá o token de contexto como parte da resposta de redirecionamento.
O token de contexto é incluído na solicitação do navegador, que é enviada ao servidor Contoso.com.
O servidor Contoso.com obtém o token de contexto e valida a assinatura, algo possível visto que ele conhece o segredo do cliente. Isso garante ao Contoso.com que o token foi emitido pelo ACS e não por um impostor que tenta se passar pelo SharePoint. Contoso.com extrai o token de atualização do token de contexto e o envia, junto com outras informações, incluindo sua identidade e o segredo de cliente, para o ACS em uma solicitação de um token de acesso que o permite acessar o SharePoint.
O ACS valida o token de atualização para garantir a emissão do token e, em seguida, retorna um token de acesso para Contoso.com. Opcionalmente, Contoso.com pode armazenar em cache esse token de acesso para não precisar solicitar um token de acesso sempre que acessar o SharePoint. Por padrão, tokens de acesso são válidos por algumas horas a cada vez. Quando este artigo foi escrito, a expiração padrão dos tokens de acesso emitidos pelo ACS para o SharePoint era de 12 horas, mas isso pode mudar.
Cada token de acesso é específico para a conta de usuário especificada na solicitação original de autorização e concede acesso apenas ao serviço (neste caso, o SharePoint) especificado nessa solicitação. Os tokens de atualização são mais duradouros (seis meses quando este artigo foi escrito) e também podem ser armazenados em cache. Assim, o mesmo token de atualização pode ser resgatado para um novo token de acesso do ACS até que o próprio token de atualização expire. Confira mais informações sobre tokens de armazenamento em cache em Manipular tokens de segurança em suplementos do SharePoint de baixa confiança hospedados pelo provedor.
Quando o token de atualização expira, Contoso.com pode conseguir um novo, obtendo um novo token de contexto. Confira mais informações em Obter um novo token de contexto.
- Contoso.com usa o token de acesso para fazer uma chamada da API REST do SharePoint ou uma solicitação CSOM para spnv. Isso é feito passando-se o token de acesso OAuth no cabeçalho HTTP Autorização. O código de amostra para criar o cabeçalho será fornecido pelo Office Developer Tools for Visual Studio se o componente remoto estiver hospedado em uma plataforma .NET.
- O SharePoint valida o token de acesso para garantir que o token foi emitido pelo ACS. Em seguida, ele envia os dados que Contoso.com solicitou para a Contoso.com ou executa a operação de criação, leitura, atualização ou exclusão (CRUD) solicitada pela Contoso.com.
- A página do aplicativo Contoso.com é renderizada no navegador (ou no IFRAM da parte do suplemento).