Partilhar via

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

  • Artigo

Importante

Este artigo trata inteiramente do uso de tokens de acesso no sistema de autorização de alta confiança, não no sistema ACS. Confira informações sobre o usuário dos tokens de segurança no sistema ACS em Manipular tokens de segurança em Suplementos do SharePoint de baixo nível de 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

Observação

Tenha em mente ao ler este artigo, particularmente com relação às tarefas que seu código deverá executar, que se você estiver usando código gerenciado, o Microsoft Office Developer Tools para Visual Studio adiciona a todos os projetos de Suplementos do SharePoint dois arquivos de código gerados, SharePointContext.cs (ou .vb) e TokenHelper.cs (ou .vb), que fazem a maioria dessas tarefas por você. O código de manipulação de token do seu aplicativo geralmente consiste em apenas algumas chamadas para as classes nesses arquivos.

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:

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).

Observação

Observe que os tokens de acesso de alta confiança que seu código cria são diferentes dos criados pelo Azure ACS quando o sistema de autorização de baixa confiança está sendo usado:

  • A declaração alg no cabeçalho é "nenhum", pois o token de acesso em uma chamada de usuário e suplemento de um suplemento de alta confiança não é assinado.
  • A URL do complemento no valor aud neste exemplo é um servidor local, o que é normal para o sistema de alta confiança.
  • Não há nenhuma declaração identityprovider, mas há um nii (emissor de identidade de nome) com o mesmo tipo de valores que os tokens de acesso de declaração identityprovider usados no sistema de autorização de baixa confiança. (Veja informações sobre esse valor quando o provedor de identidade é baseado em SAML consultando as postagens do blog de Steve Peschka: Segurança em suplementos do SharePoint – Parte 8 e Usar suplementos do SharePoint com sites SAML e FBA no SharePoint 2013.
  • Não há nenhuma declaração actor, mas há uma declaração actortoken que contém um token interno codificado na base 64 com uma vida útil de 12 horas.

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

Declaração Descrição Valor correspondente no token de acesso de exemplo
aud Abreviação de "público", ou seja, a entidade para a qual o token se destina.

O formato é ID da entidade do público-alvo/domínio totalmente qualificado do SharePoint @Realm do SharePoint.

A entidade do público-alvo de um Suplemento do SharePoint é sempre 00000003-0000-0ff1-ce00-000000000000.

Como os Suplementos do SharePoint de alta confiança normalmente são usados em um cenário totalmente local, o nome de domínio totalmente qualificado do SharePoint em geral é apenas um nome de servidor. O domínio do SharePoint é o GUID do farm local do SharePoint que o token de acesso é usado para acessar , (ou o GUID do locatário, se o farm tiver sido configurado para locatários).

Encontre o realm do SharePoint executando o cmdlet Get-SPAuthenticationRealm do PowerShell no servidor do SharePoint e use-o diretamente em seu código ou armazene-o em um arquivo de configuração em que seu código possa lê-lo, como a seção app.Settings de um arquivo web.config.

Como alternativa, seu código pode descobrir dinamicamente o realm do SharePoint em tempo de execução enviando um desafio de autenticação para o SharePoint. Confira um exemplo de como isso é feito no código gerenciado no método GetRealmFromTargetUrl no arquivo TokenHelper.cs (ou .vb).		 00000003-0000-0ff1-ce00-000000000000/MarketingSharePointServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
iss Abreviação de "emissor". Ele representa a entidade que criou o token.

O formato é Issuer GUID@SharePoint realm GUID. No sistema de alta confiança, o suplemento em si é o emissor; portanto, a ID do cliente do suplemento do SharePoint é normalmente usada para o GUID do emissor.

Todas as letras na ID do emissor devem estar em minúsculas.		 c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
nbf Abreviação de "não antes". Representa a hora que o token começa a ser válido, em segundos a partir da meia-noite de 1º de janeiro de 1970. Seu código deve definir isso no momento em que o token é criado. 1403212820
exp Abreviação de "expiração". Representa o tempo que o token expira, em segundos, desde a meia-noite de 1º de janeiro de 1970. 1403256020
nameid Um identificador exclusivo do Exchange Server para quem o token é emitido. O formato varia de acordo com o provedor de identidade. Neste exemplo, o provedor é o Active Directory. s-1-5-21-2127521184-1604012920-1887927527-2963467
nii Abreviação de "emissor de identificador de nome". O nome exclusivo do provedor de identidade registrado com a IANA (Autoridade de Números Atribuídos à Internet). Para um suplemento do SharePoint de alta confiança, normalmente é um provedor de identidade local, como o Active Directory, como neste exemplo. urn:office:idp:activedirectory
actortoken Um token JWT codificado em base 64 que identifica o suplemento do SharePoint e instrui o SharePoint a confiar no suplemento, independentemente do usuário que está executando o suplemento. Confira a seguir.

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"
}

Observação

Se o suplemento de alta confiança estiver usando a política somente de suplemento e fizer uma chamada somente de suplemento para o SharePoint, o token mostrado aqui será, na verdade, o token de acesso. Não há token externo. Além disso, não há nenhuma declaração trustedfordelegation, pois as permissões do usuário são irrelevantes para uma chamada somente de suplemento.

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

Declaração Descrição Valor correspondente no token de acesso de exemplo
aud Igual ao do token de acesso pai. 00000003-0000-0ff1-ce00-000000000000/MarketingSharePointServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
iss O mesmo significado do token de acesso pai, mas o GUID do emissor não é a ID do cliente do aplicativo da Web. É o GUID do certificado.

Embora o código no aplicativo construa o token de ator, o certificado é considerado o emissor do token de ator.

Observe que o GUID do emissor neste exemplo é uma sequência de GUID fácil de lembrar que o administrador do farm usou quando registrou o certificado X.509 como um emissor de token confiável no SharePoint. Isso é comum quando o mesmo certificado é usado como o emissor do token de ator para todos os suplementos do SharePoint de alta confiança no farm.

Um administrador também pode optar por ter certificados distintos para cada Suplemento do SharePoint. Nesse caso, ele usaria diferentes GUIDs gerados aleatoriamente para os certificados.

Todas as letras no GUID do emissor devem estar em minúsculas.		 11111111-1111-1111-1111-111111111111@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
nbf Mesmo significado que no token de acesso pai. Mesmo valor que no token de acesso pai.
exp Mesmo significado que no token de acesso pai. Mesmo valor que no token de acesso pai.
nameid Um identificador exclusivo para o Suplemento do SharePoint, porque é o "ator" no sistema de alta confiança. O formato é client_ID@SharePoint_realm. c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
trustedfordelegation Um valor booliano que especifica se o SharePoint deve confiar no Suplemento do SharePoint para autenticar e autorizar o usuário. Isso é normalmente verdade no sistema de alta confiança. Não inclua essa declaração em uma chamada somente de suplemento no sistema de alta confiança. true

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