Criar e usar tokens de acesso nos Suplementos do SharePoint de alta confiança e hospedados pelo provedor

Os Suplementos do SharePoint que usam o sistema de autorização de alta confiança para obter acesso ao SharePoint precisam passar um token de acesso (no formato JSON Web Token) para o SharePoint com cada solicitação de criação, leitura, atualização ou exclusão (CRUD). O SharePoint valida o token e atende à solicitação.

Este artigo fornece informações sobre como seu código cria e passa o token de acesso.

No sistema de autorização de alta confiança, o componente remoto do seu Suplemento do SharePoint cria o token de acesso. Se o componente remoto estiver usando código gerenciado para o próprio código do lado do servidor, a maior parte do trabalho de codificação para criação dos tokens será feita para você nos arquivos SharePointContext.cs (ou .vb) e TokenHelper.cs (ou .vb), incluídos no Office Developer Tools para Visual Studio.

Como o cliente de um Suplemento do SharePoint de alta confiança tem SharePoint no local, ele provavelmente não vai se opor ao uso do ASP.NET, IIS e Windows Server como a pilha de hospedagem para o componente remoto. Você deve considerar o uso dessa pilha, pois os dois arquivos gerados poupam muito trabalho de codificação e teste.

Se o componente remoto precisar usar uma linguagem não-.NET, e o componente remoto e o farm do SharePoint estiverem conectados à Internet, considere o uso do sistema de autorização de baixa confiança em vez de alta confiança. No sistema do Microsoft Azure Access Control Service (ACS), toda a criação do token é feita pelo ACS, portanto, você também poupa muito trabalho.

O restante deste artigo destina-se principalmente a fornecer orientação aos desenvolvedores que criam Suplementos do SharePoint com componentes remotos não-.NET e que usam o sistema de autorização de alta confiança. Ele também pode fornecer algumas informações valiosas para depurar Suplementos do SharePoint baseados em .NET que usam o sistema de alta confiança.

Manipulação de tokens de acesso

Os detalhes neste tópico têm a finalidade de ajudar os desenvolvedores que não estão usando código gerenciado (e de ajudar quem está solucionando problemas com tokens). Os links para bibliotecas OAuth para muitas linguagens e plataformas estão em OAuth 2.0 (role até Bibliotecas do cliente). É possível encontrar mais pesquisando "OAuth 2" e "JSON Web Token" (sem as aspas) no GitHub.

Seu código precisa:

1. Criar um token de acesso. As subtarefas de criação desse token variam em função de se o aplicativo da Web remoto faz chamadas apenas de suplemento para o SharePoint, chamadas de usuário e suplemento ou ambas. (Confira mais informações em Tipos de política de autorização de suplemento no SharePoint.)

   • Se o suplemento fizer chamadas de usuário e suplemento, a criação do token de acesso incluirá as seguintes subtarefas:

     1. Criação de um token de ator que identifica o Suplemento do SharePoint e informa ao SharePoint para delegar a autenticação e a autorização do usuário ao seu suplemento e codificá-lo na codificação da base 64. A Tabela 2 contém detalhes sobre as declarações e a estrutura do token de ator. Os detalhes sobre a codificação e a assinatura do token estão em Codificação e assinatura de tokens.
     2. Assine o token de ator com credenciais de um certificado X.509 configurado por um administrador de farm do SharePoint para ser confiável para o SharePoint.
     3. Inclua o token de ator no token de acesso.
     4. Adicione outras declarações necessárias ao token de acesso. A Tabela 1 contém detalhes sobre as declarações e a estrutura do token.

   • Se o suplemento fizer chamadas somente de suplemento, seu código precisará executar apenas as duas primeiras dessas subtarefas. O token de ator serve como token de acesso.

   • Se o suplemento fizer algumas chamadas usuário e suplemento e algumas chamadas apenas de suplemento, ele deverá criar um token de ator simples para as chamadas apenas de suplemento e um maior, o token de acesso aninhado, para as chamadas de usuário e suplemento. Não é possível usar o mesmo token de acesso para ambos.

2. Inclua o token de acesso em todas as solicitações HTTP para o SharePoint. O token é adicionado como um cabeçalho de Autorização à solicitação. O valor do cabeçalho é a palavra "Portador", seguida por um espaço, seguida pelo token de acesso codificado na base 64.

3. Como alternativa, armazene em cache o token de acesso para reutilização em solicitações subsequentes.

Essas tarefas devem ser feitas com o código do servidor. Se você estiver usando o código gerenciado, o código de exemplo para algumas dessas tarefas está nos arquivos SharePointContext.cs (ou .vb) e TokenHelper.cs (ou .vb) gerado pelo Microsoft Office Developer Tools para Visual Studio.

Armazenar o token de acesso em cache

Depois que um token é criado, ele pode ser reutilizado em chamadas posteriores para o SharePoint até expirar. Dependendo da arquitetura do componente remoto e da plataforma de hospedagem, existem várias maneiras de armazenar em cache o token de acesso no servidor:

• No estado da sessão
• No estado do aplicativo
• No Serviço de Cache do AppFabric no Windows Server.
• Em um banco de dados
• Em um sistema memcached

Se o armazenamento em cache for compartilhado por diferentes sessões do usuário, como o cache do aplicativo, use uma chave de cache exclusiva da sessão.

Se o cache for compartilhado por vários aplicativos, seu código também deverá relativizar a chave de cache para essa variável. Também é possível que o seu suplemento acesse diferentes farms do SharePoint. São necessários tokens de acesso distintos para cada um deles, então, nesse cenário, sua chave de cache precisaria relativizar para o farm.

Ao todo, você pode precisar de chaves de cache baseadas em uma ou mais ID do usuário, ID do aplicativo e domínio ou realm do SharePoint. Considere o uso de um sistema de chave de cache semelhante ao usado pelos suplementos do SharePoint que usam o sistema de autorização de baixa confiança. Confira mais informações em Entender a chave do cache.

Essencialmente, você iria concatenar umas ou mais dessas três IDs (e, opcionalmente, transformar o resultado em uma cadeia de caracteres mais curta) para servir como uma chave de cache.

Lidar com tokens de acesso expirados

O token de acesso tem um tempo de expiração que pode ser definido pelo seu código para qualquer valor desejado. Se o seu suplemento criar um novo token de acesso para cada solicitação, cada token terá que funcionar o tempo suficiente para ser validado pelo SharePoint, não mais do que alguns segundos, a menos que a LAN do cliente fique geralmente obstruída. Você pode definir a expiração para anos no futuro, mas mesmo no cenário "todos os locais" para o qual os suplementos de alta confiança foram criados, há certo risco de roubo de tokens de acesso. Portanto, convém definir a expiração para algumas poucas horas. (Se você estiver trabalhando com código gerenciado, o código de criação de token de amostra no arquivo TokenHelper.cs [ou .vb] definirá a expiração para 12 horas.)

Se a sessão de um usuário com o Suplemento do SharePoint durar mais do que a duração do token de acesso em cache, a primeira solicitação para o SharePoint após a expiração do token resultará em um erro 401 Não Autorizado. Seu código precisa tratar essa resposta. Como alternativa, ele pode testar o tempo de expiração do token de acesso antes de ser usado. Seu código deve responder a um token de acesso expirado, criando um novo token de acesso e repetindo a solicitação que falhou.

Estrutura de tokens de acesso

A seguir, um exemplo de um token de acesso gerado por um Suplemento do SharePoint de alta confiança; especificamente, esse token foi gerado pelo código de exemplo no arquivo TokenHelper.cs (ou .vb) que faz parte do modelo de projeto do Suplemento do SharePoint criado pelo Office Developer Tools para Visual Studio. O token foi decodificado e o espaço em branco foi adicionado para facilitar a leitura. Os tokens de acesso usados no sistema de alta confiança estão em conformidade com o MS-SPS2SAUTH: Protocolo de autenticação do OAuth 2.0: perfil do SharePoint, também chamado de protocolo servidor-a-servidor ou S2S. Essas informações são fornecidas para ajudar os desenvolvedores que usam o código gerenciado a depurar os suplementos do SharePoint de alta confiança e fornecer algumas orientações para os desenvolvedores que usam outras linguagens sobre como construir os tokens.

Esse token de acesso é gerado se o suplemento estiver fazendo uma chamada para o SharePoint usando a política de usuário e suplemento. Se o suplemento estiver usando a política de apenas suplemento e fizer uma chamada de apenas suplemento para o SharePoint, o token de ator (que é um token filho no token de acesso do usuário e suplemento e será descrito posteriormente) se tornará o token de acesso (e não há token pai).

O cabeçalho tem duas propriedades. O "typ" é o tipo de token. O código no aplicativo da Web remoto deve sempre definir esse valor como "JWT". O "alg" é o algoritmo usado para assinar o token. Como o token externo em uma chamada de usuário e suplemento de um suplemento de alta confiança não é assinado, defina esse valor como "nenhum". Confira informações na Tabela 1 sobre os valores na parte do corpo do token de acesso de alta confiabilidade.

{"typ":"JWT", "alg":"none"} 
.
{
 "aud":"00000003-0000-0ff1-ce00-000000000000/MarketingServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "iss":"c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "nbf":"1403212820",
 "exp":"1403256020",
 "nameid":"s-1-5-21-2127521184-1604012920-1887927527-2963467",
 "nii":"urn:office:idp:activedirectory",
 "actortoken":"6sMZhbw … [remainder of long base 64 string omitted] … "
}

A tabela a seguir fornece algumas orientações para as propriedades que seu código deve incluir no token de acesso e os valores a ser definidos para elas. Se você estiver usando código gerenciado, os arquivos SharePointContext.cs (ou .vb) e TokenHelper.cs (ou .vb) criarão os tokens por você. Por exemplo, seu código faz uma única chamada para o método SharePointContext.CreateUserClientContextForSPHost. Ele, por sua vez, chama métodos na classe TokenHelper que constroem o token de acesso, que é incluído em todas as chamadas feitas ao SharePoint pelo objeto de contexto de cliente do SharePoint retornado por SharePointContext.CreateUserClientContextForSPHost.

Tabela 1: declarações de token de acesso emitidas pelo aplicativo

O actortoken decodificado é exibido. O pequeno objeto de cabeçalho JavaScript Object Notation (JSON) na parte superior contém metadados sobre o token, incluindo o tipo de token e o algoritmo usado para assiná-lo. A propriedade x5t do cabeçalho é um resumo feito da impressão digital do certificado X.509 que é oficialmente o emissor do token. Para chegar a esse valor, seu código faz o seguinte:

1. Obtém a versão da matriz de bytes (não cadeia de caracteres) da impressão digital do certificado. Este é um resumo SHA-1 do certificado. (No código gerenciado, isso pode ser feito com o método GetCertHash(). Você precisa de algo equivalente na linguagem que estiver usando.)

2. Codifica a matriz de bytes com codificação de URL em Base 64.

3. Define o valor da propriedade x5t para o resumo codificado.

A Tabela 2 descreve as declarações que seu código deve incluir no corpo do token e os valores a ser definidos para elas.

{"typ":"JWT","alg":"RS256","x5t":"7MjK99QvkVdwz6UrKldx8AG7ydM"}
.
{
 "aud":"00000003-0000-0ff1-ce00-000000000000/MarketingServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "iss":"11111111-1111-1111-1111-111111111111@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "nbf":"1403212820",
 "exp":"1403256020",
 "nameid":"c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "trustedfordelegation":"true"
}

Tabela 2: Declarações de actortoken emitidas por certificado

Codificação e assinatura de tokens

Depois que seu código tiver adicionado todas as propriedades e valores aos objetos JSON do cabeçalho e do corpo, ele precisará codificá-los, integrá-los a um JSON Web Token (JWT) e assiná-los. A seguir estão as etapas.

1. Codifique o cabeçalho com codificação de URL em Base 64.
2. Codifique o conteúdo com codificação de URL em Base 64.
3. Concatene o corpo codificado após o cabeçalho codificado com um caractere "." entre eles. Este é o JWT.
4. Crie uma assinatura SHA256 usando o JWT e a chave privada do certificado.
5. Codifique a assinatura com codificação de URL em Base 64.
6. Acrescente a assinatura ao final do JWT, com um caractere "." entre eles.

Para um token de ator usado com uma chamada somente de suplemento, o token de ator serve como o token de acesso. Não há token externo. Para um token de acesso usado com uma chamada de usuário e suplemento, as etapas anteriores são usadas para construir um token de ator, que é inserido no corpo de um token de acesso como o valor da propriedade actortoken. O token de acesso completo é então codificado e construído com as três primeiras etapas acima, mas não é assinado; portanto, as etapas restantes não são usadas para o token externo.

Solução de problemas de tokens de acesso

A ferramenta Fiddler gratuita 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 nas solicitações.

Confira também

• Segurança em suplementos do SharePoint, parte 7 de Steve Peschka.
• Suplementos de alta confiança do SharePoint em plataformas que não são Microsoft de Kirk Evan
• OAuth 2.0
• Tipos de política de autorização dos suplementos no SharePoint
• Criação de suplementos do SharePoint com autorização de alto nível de confiança
• Autorização e autenticação de Suplementos do SharePoint