Partilhar via

Gerenciamento de tokens de segurança nos suplementos do SharePoint de baixo nível de confiança hospedados pelo fornecedor

  • Artigo

Importante

Este artigo é inteiramente sobre o uso de tokens de segurança no sistema de autorização de baixa confiabilidade e não no sistema de alta confiança. Para saber mais sobre o uso de tokens no sistema de alta confiança, confira Criar e usar tokens de acesso nos Suplementos do SharePoint de alto nível de confiança e hospedados por um fornecedor.

Os Suplementos do SharePoint que usam o sistema de autorização de baixa confiança para obter acesso aos dados do SharePoint participam de um fluxo OAuth que envolve a transmissão de tokens de segurança (no formato Token Web JSON) entre o SharePoint, o Serviço de Controle de Acesso (ACS) do Microsoft Azure, os componentes remotos do Suplemento do SharePoint e, em alguns casos, o navegador do usuário.

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

Há fluxos diferentes dependendo do design do suplemento, mas todos eles envolvem pelo menos dois tipos de tokens a seguir:

  • Token de Acesso. Incluído em cada solicitação para criar, ler, atualizar ou excluir (CRUD) os componentes remotos do suplemento do SharePoint. O SharePoint valida o token e atende à solicitação.
  • Token de atualização. Usado para obter um token de primeiro acesso no fluxo de Token de Contexto e para substituir os tokens de acesso prestes a expirar tanto no fluxo de Token de Contexto quanto no fluxo de Código de Autorização do sistema de autorização de baixa confiança.

Dependendo de qual fluxo OAuth o suplemento está usando, um ou outro dos seguintes também fará parte do processo:

  • Token de contexto. Usado no fluxo de Token de Contexto para fornecer ao componente remoto um token de atualização e as informações de que ele precisa para solicitar um token de acesso do Azure ACS.
  • Código de Autorização. Não é um token, mas um código de autorização exclusivo para cada par de usuário e aplicativo. Ele é usado no fluxo de Código de Autorização para obter um token de primeiro acesso e um token de atualização.

Tokens de acesso

No sistema de autorização de baixa confiança, os tokens de acesso são criados pelo Azure ACS e enviados ao componente remoto de seu Suplemento do SharePoint. (Quando este artigo foi escrito, os tokens de acesso emitidos pelo ACS para o SharePoint tinham uma duração de 12 horas, mas isso poderia ser alterado.) As principais coisas que o código em seu Suplemento do SharePoint precisa implementar são:

  • Solicitar um token de acesso do Azure ACS. Dependendo de qual fluxo OAuth está sendo usado, o suplemento usa um código de autorização ou as informações que ele extrai de um token de contexto para fazer a solicitação.
  • Incluir o token em cada solicitação 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.
  • Opcionalmente (mas recomendável), armazenar o token de acesso no cache para reutilização em solicitações subsequentes.
  • Opcionalmente, encaminhar o token de acesso a sistemas de back-end para que eles possam acessar diretamente o SharePoint.

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) que fazem parte do Microsoft Office Developer Tools para Visual Studio. Para obter um exemplo de código PHP que executa algumas dessas tarefas, consulte MSDN: SharePoint 2013 - entender e usar a interface REST do SharePoint .

Armazenar o token de acesso em cache

Dependendo da arquitetura e da plataforma de hospedagem do Suplemento do SharePoint, existem várias maneiras de armazenar o token de acesso em cache no servidor:

Observação

Na maioria dos cenários, você não poderá usar termos tão simples como "AccessToken" como a chave de armazenamento em cache já que seu suplemento deve manter os tokens para diferentes usuários e farms/locações distintos do SharePoint. Se seu suplemento usa o fluxo de Token de Contexto, haverá um CacheKey especial fornecido pelo SharePoint que poderá ser usado para distinguir tokens armazenados em cache. Esta seção explica quais são os problemas e o que fazer quando seu aplicativo não está usando o fluxo de Token de Contexto.

Armazenar em cache o token de acesso no estado da sessão é aceitável para a maioria dos cenários. Se o aplicativo Web remoto estiver acessando outros serviços que usam o OAuth (além do SharePoint) e o cache dos vários tokens de acesso no estado da sessão, use chaves de cache distintas para os tokens; por exemplo, em vez de "AccessToken", use "SharePoint_AccessToken", "Facebook_AccessToken", "SAP_Gateway_AccessToken" e assim por diante. (Se você não estiver usando o estado da sessão ou algum outro cache que separe automaticamente o cache de cada usuário, será necessário relativizar suas chaves para os usuários.)

Se o aplicativo acessar mais de um locatário online ou farm do SharePoint, você poderá usar o domínio do SharePoint como parte da chave de cache principal do aplicativo (SharePoint<mydomain>.sharepoint.com_AccessToken) ou usar o realm do farm/locação (SharePoint<realmGUID>_AccessToken), sendo que ambos podem ser lidos a partir do token de acesso. (Seu código precisa reverter a codificação base 64 do token para lê-lo. No código gerenciado, o tokenHelper.cs ou .vb, o arquivo tem código de exemplo para essa finalidade que usa classes dos namespaces Microsoft.IdentityModel.S2S.Tokens e System.IdentityModel.Tokens .) Há outra opção disponível quando o aplicativo está usando o fluxo de Token de Contexto, conforme descrito no próximo parágrafo.

Podem existir cenários em que seu aplicativo precisará armazenar o token de acesso em cache em algum lugar disponível para o aplicativo nas sessões ou após o término de uma sessão. Por exemplo, o aplicativo pode ser projetado para permitir que os usuários planejem ações que ocorram após o usuário ter fechado o aplicativo. Se essas ações incluírem o acesso ao SharePoint, o suplemento precisa recuperar o token de acesso. Nesse tipo de cenário, o aplicativo deve manter tokens de acesso de vários usuários distintos.

Se você estiver usando o fluxo de Token de Contexto, uma cadeia de caracteres de chave de cache será fornecida para essa finalidade no token de contexto que o SharePoint passará para o componente remoto do Suplemento do SharePoint quando o suplemento for iniciado. Para saber mais sobre essa chave de cache especial e como usá-la, confira Entender a chave de cache. Você também pode usar nessa cadeia de caracteres no cenário descrito acima. O sistema de agendamento tem alguns meios de armazenar os dados de configuração necessários, como quando o trabalho agendado é executado e o que ele deve fazer. Use esse armazenamento para armazenar a chave de cache do token de acesso.

Se o cache entre sessões usado também for compartilhado por vários aplicativos, será necessário relativizar as chaves de cache para os aplicativos, os usuários e os realms do SharePoint. A chave de cache fornecida no token de contexto é exclusiva para aplicativos, usuários e realms do SharePoint.

Se seu aplicativo estiver usando o fluxo de Código de Autorização, não haverá token de contexto e, portanto, nenhuma chave de cache especial. Nesse cenário, você precisa criar seu próprio sistema de chaves para dados em cache que são relativizados para uma ou mais das seguintes opções, dependendo dos possíveis conflitos de nomes que podem ocorrer devido aos casos de uso do aplicativo: o usuário, o realm do SharePoint e a aplicativo. Você pode usar as declarações dentro do token de acesso para essa finalidade, por exemplo, o nameId e o aud (veja as tabelas a seguir). Seu código pode simplesmente concatenar as cadeias de caracteres ou usá-las como sementes para criar um hash exclusivo que poderá ser usado como chave de cache.

Por fim, se seu aplicativo fizer tanto chamadas do tipo somente suplemento quanto chamadas do tipo usuário+suplemento para o SharePoint, ele terá dois tokens de acesso diferentes e, portanto, você precisará de chaves de cache distintas. Depois de decidir uma chave de cache básica, basta acrescentar "_add somente" ou "_add-in+user" a ela.

Aviso

Não é uma prática segura armazenar o token de acesso em um cookie. Em geral, é uma boa prática evitar que o token de acesso passe pelo navegador.

Encaminhar o token de acesso a sistemas de back-end

Um Suplemento do SharePoint pode ter servidores de back-end que não estão hospedados no mesmo domínio que o aplicativo Web remoto. Quando um servidor de back-end precisa executar operações CRUD no SharePoint, a execução do suplemento será mais rápida se essas operações puderem ir diretamente do sistema back-end para o SharePoint. Felizmente, o domínio só é importante quando seu aplicativo recebe um token de acesso do ACS. Depois ter o token, ele pode encaminhá-lo aos serviços de back-end e chamar o SharePoint usando-o.

O código nesses sistemas precisa manipular os tokens de acesso expirados e enviar uma solicitação de um novo token para o aplicativo Web pai registrado no ACS (consulte Tratar tokens de acesso expirados). Essa técnica só deve ser usada para os servidores de back-end do aplicativo e não para os serviços Web externos. Além disso, se você estiver usando essa técnica, considere projetar os serviços de back-end para usar somente chamadas de suplemento sempre que possível.

Tratar tokens de acesso expirados

Um token de acesso expira depois de algumas horas (12 horas do momento em que este artigo foi escrito, mas pode ser alterado). Se o aplicativo ainda estiver acessando o SharePoint depois que o token de acesso expirar, a primeira solicitação para o SharePoint após a expiração resultará em um erro 401 - Não Autorizado. Seu código precisa tratar essa resposta.

Como alternativa, o código pode testar o tempo de expiração do token de acesso antes que ele seja usado. O código usa o token de atualização para obter outro token de acesso do ACS. No fluxo de Token de Contexto, o token de atualização é incluído no token de contexto que seu suplemento recebe do SharePoint no início de sua primeira sessão no SharePoint. No fluxo do Código de Autorização, ele é transmitido para o aplicativo, juntamente com o token de primeiro acesso. Seu código deve armazená-lo em cache para que esteja disponível quando necessário. O token de atualização dura alguns meses e pode persistir em um cookie ou em um armazenamento do lado do servidor. Para saber mais, confira Noções básicas sobre a manipulação e o cache de tokens de atualização.

Exemplos de tokens de acesso para o sistema de autorização de baixa confiança

Esta seção descreve tokens de acesso com exemplos e mostra como eles diferem dependendo da política de autorização em uso.

Política de usuário+suplemento

Veja a seguir um exemplo decodificado de um token de acesso de usuário+suplemento gerado pelo ACS que será usado em chamadas para o SharePoint usando a política de usuário+suplemento. Um espaço em branco foi adicionado para facilitar a leitura. O token é compatível com o protocolo Token Web JSON. O objeto JSON (JavaScript Object Notation) no token é chamado de conjunto de declarações (confira a Tabela 1 para obter detalhes sobre as propriedades no conjunto de declarações).

Todos os valores devem estar em letras minúsculas. (Os tokens de acesso de usuário+suplemento são os mesmos no fluxo de Token de Contexto e no fluxo do Código de Autorização.)

{
 "aud": "00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss": "00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf": 1377549246,
 "exp": 1377592446,
 "nameid": "2303000085ff9abc",
 "actor": "964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73",
 "identityprovider": "urn:federation:microsoftonline"
}

Tabela 1: Declarações de token de acesso de usuário+suplemento emitidas pelo ACS

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 é audience principal ID/SharePoint domain@SharePoint realm, onde a ID da entidade de público é uma ID de entidade de segurança permanente do SharePoint (confira Constantes da entidade do aplicativo de Produtos da Microsoft).

O realm do SharePoint é o GUID da locação do SharePoint Online, ou o farm do SharePoint local, que o token de acesso é usado para acessar. Este GUID funciona como a ID do realm para o emissor do token, nesse caso, o ACS Azure.		 00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss Abreviação de "emissor". Ele representa a entidade que criou o token. O formato é Issuer GUID@SharePoint realm GUID. No sistema de autorização de confiabilidade baixa o emissor é ACS Azure e seu GUID é 00000001-0000-0000-c000-000000000000. 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
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. Por padrão, é definida no momento em que o token é criado (consulte valores de tempo JWT). 1377549246
exp Abreviação de "expiração". Representa a hora que o token expira. Por padrão, isso é 12 horas após a hora nbf (confira valores de tempo JWT). 1377592446
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 Microsoft Online, mas, se fosse o Active Directory, a ID seria s-1-5-21-2127521184-1604012920-1887927527-415149. 2303000085ff9abc
actor A entidade de segurança que busca acesso ao farm ou à locação do SharePoint. Ela tem o formato Client ID of Application@SharePoint realm. 964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73
identityprovider O nome exclusivo do provedor de identidade registrado na IANA (Internet Assigned Numbers Authority). Para um suplemento instalado no SharePoint Online, o valor é normalmente o mesmo que neste exemplo. Para um suplemento instalado em um farm local, o valor é normalmente um provedor de identidade local, como urn:office:idp:activedirectory. urn:federation:microsoftonline

Política somente suplemento

Veja a seguir um exemplo decodificado de um token de acesso somente suplemento gerado pelo ACS que será usado em chamadas para o SharePoint usando a política somente suplemento. Um espaço em branco foi adicionado para facilitar a leitura. O token é compatível com o protocolo Token Web JSON. Confira a Tabela 2 para ver detalhes sobre as propriedades no conjunto de declarações. (A política somente de suplemento não está disponível para aplicativos que usam o fluxo de Código de Autorização porque eles não têm um arquivo de manifesto de suplemento e, portanto, não podem solicitar permissão para usar chamadas somente para o suplemento.)

{
 "aud":"00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf":1403304705,
 "exp":1403347905,
 "nameid":"c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73",
 "sub":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
 "oid":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
 "trustedfordelegation":"false",
 "identityprovider":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73"
}

Tabela 2: Declarações de token de acesso somente suplemento emitidas pelo ACS

Declaração Descrição Valor correspondente no token de acesso de exemplo
aud Igual ao token de usuário+suplemento na Tabela 1. 00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss Igual ao token de usuário+suplemento na Tabela 1. 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf Igual ao token de usuário+suplemento na Tabela 1. 1403304705
exp Igual ao token de usuário+suplemento na Tabela 1. 1403347905
nameid Um identificador exclusivo para o suplemento, em vez do usuário, já que a identidade do usuário não é importante com a política somente suplemento. O formato é client ID@SharePoint realm. c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73
sub Abreviação de "requerente". é o assunto do token, que é a entidade que está procurando acessar o SharePoint, nesse caso, o aplicativo Web remoto. A ID do objeto é usada para o valor. Confira a declaração oid. 1d47ac31-498b-4988-8aac-85fc9bd2e1ce
oid Abreviada de "ID de objeto". é a ID do objeto do Azure Active Directory para o aplicativo Web remoto. Em um token de acesso do suplemento, o assunto e a ID do objeto têm o mesmo valor. 1d47ac31-498b-4988-8aac-85fc9bd2e1ce
trustedfordelegation Um valor booliano que especifica se o SharePoint deve confiar no Suplemento do SharePoint para autenticar e autorizar o usuário. é falso nas chamadas somente para o suplemento porque a identidade do usuário não importa. false
identityprovider O nome exclusivo do provedor de identidade. Como é o suplemento, em vez de um usuário, cuja identidade está sendo fornecida, o ACS é o provedor de identidade. O formato é ACS GUID@SharePoint realm. 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73

Tokens de contexto

Um token de contexto é usado apenas no fluxo de Token de Contexto do sistema de autorização de baixa confiança. Quando o Suplemento do SharePoint é iniciado no SharePoint, o SharePoint solicita que o Azure ACS crie um token de contexto que o SharePoint passa para o componente remoto do Suplemento do SharePoint. O token é passado como um parâmetro de formulário oculto chamado SPAppToken em uma solicitação do SharePoint para a página inicial do componente remoto. O token é assinado com um segredo de cliente conhecido apenas pelo ACS e pelo Suplemento do SharePoint.

O token de contexto inclui um token de atualização que o suplemento usa, juntamente com outras informações do token de contexto, para solicitar um token de acesso do ACS. (Quando este artigo foi escrito, os tokens de contexto emitidos pelo ACS para o SharePoint tinham uma duração de 12 horas, mas isso pode ter mudado.)

As principais tarefas que o código em seu Suplemento do SharePoint precisa fazer são:

  • Usar o segredo do cliente do suplemento para validar o token de contexto.
  • Armazenar em cache o token de contexto ou extrair, e armazenar em cache separadamente, o token de atualização e alguns outros itens dentro dele.
  • Usar o token de atualização e outras informações para solicitar um token de acesso do ACS (que é então armazenado em cache).
  • Armazenar em cache a CacheKey do token de contexto.

Importante

As primeiras duas tarefas devem ser realizadas antes que o usuário passe para outra página ou atualize a página ou o token será perdido. Por exemplo, em um aplicativo Web Forms do ASP.NET, considere realizar essas tarefas no método Page_Load (em um bloco de código condicional que é executado somente quando a solicitação não é um postback). Em um aplicativo ASP.NET MVC, considere realizar essas tarefas no método do controlador padrão.

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) que fazem parte do Microsoft Office Developer Tools para Visual Studio. Você só precisa fazer chamadas simples aos membros da classe TokenHelper. Por exemplo, seu código pode fazer a primeira tarefa com a seguinte linha de código:

SharePointContextToken contextToken =
    TokenHelper.ReadAndValidateContextToken(contextTokenString,
    Request.Url.Authority);

Armazenar o token de contexto ou partes dele no cache

Você pode armazenar todo o token de contexto em cache, ou apenas o token de atualização e alguns outros dentro dele que o seu código utiliza para obter tokens de acesso, em um armazenamento no lado do servidor ou do cliente. Por questões de simplicidade, este artigo pressupõe que você armazene o token de contexto no cache como uma unidade.

Importante

Lembramos mais uma vez porque é muito importante: não use o cache no lado do cliente para o token de acesso. é seguro usá-lo apenas para o token de contexto.

você tem as mesmas opções de cache do lado do servidor conforme listadas anteriormente para o token de acesso. As opções do lado do cliente incluem um cookie e um campo de formulário oculto em uma página HTML. Outra opção é armazenar o token de contexto no cache de sessão, mas armazenar o CacheKey obtido de dentro dele no cliente.

Se seu aplicativo acessa o SharePoint após o encerramento de uma sessão, o cache de sessão ou o cache do cliente é uma opção já que o token de atualização deve estar disponível para o aplicativo caso o token de acesso original tenha expirado durante a execução do trabalho pós-sessão. Nesse cenário, você precisa de um cache durável (entre sessões) compartilhado por vários usuários e/ou realms do SharePoint e/ou aplicativos. Portanto, seu código precisa usar as chaves de cache que distinguem o usuário, realm do SharePoint e/ou aplicativo, conforme explicado anteriormente em Armazenar o token de acesso em cache.

Você pode usar a chave de cache especial que está dentro do token de contexto para essa finalidade, da mesma forma que a usou no token de acesso (confira a próxima seção Noções básicas sobre a chave de cache).

Noções básicas sobre a chave de cache

A chave de cache é uma cadeia de caracteres opaca exclusiva para a combinação de usuário, emissor de nome de usuário, suplemento e farm do SharePoint ou locação do SharePoint Online. Antes de ser criptografada, ela tem o seguinte formato, em que Realm é o GUID do farm do SharePoint local ou o locatário do SharePoint Online.

UserNameId + "," + UserNameIdIssuer + "," + ApplicationId + "," + Realm

A chave de cache não contém informações de URL do site. Cada locação do SharePoint Online (ou farm do SharePoint local) tem um realm exclusivo, portanto, a chave de cache é exclusiva para cada combinação de nome de usuário, emissor de nome de usuário, aplicativo e farm. No exemplo de token de contexto abaixo, o valor da chave de cache criptografada é:

KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=

Como seu aplicativo pode estar armazenando vários itens em cache, como o token de acesso e o token de contexto no mesmo cache com a mesma chave de cache, considere usar a chave de cache como um tronco e acrescentar a ela uma cadeia de caracteres específica no início ou no fim, como "AccessToken" ou "ContextToken", conforme necessário, para formar uma chave de cache completa.

Outra opção é criar uma classe com propriedades para as várias coisas que você deseja no cache e, em seguida, armazenar em cache um objeto desse tipo.

Uma terceira opção, se você estiver usando um banco de dados como cache, é usar uma tabela com uma coluna CacheKey e colunas adicionais para os itens armazenados em cache (AccessToken, ContextToken, etc.).

O aplicativo não precisa usar o mesmo cache para todo o seu cache. Um padrão comum é armazenar em cache o token de acesso no cache da sessão, o token de contexto (ou o token de atualização dentro dele) em um banco de dados e a CacheKey em um cookie.

Usar o token de contexto para obter um token de acesso

Para obter um token de acesso, seu aplicativo envia uma solicitação diretamente ao ACS. A solicitação inclui três informações extraídas do token de contexto (e outras informações):

  • O token de atualização.
  • O GUID da entidade de segurança do aplicativo do SharePoint
  • O GUID do realm do farm do SharePoint ou da locação do SharePoint Online ao qual o suplemento está tentando obter acesso

O arquivo TokenHelper.cs (ou .vb) tem código que cria essa solicitação. Para obter um exemplo de código PHP que faz isso, consulte SharePoint: executar operações na Biblioteca de Documentos do SharePoint no site PHP.

O aplicativo pode obter o realm da locação ou farm do SharePoint no tempo de execução como uma alternativa para analisá-lo a partir do token de contexto. Se você estiver usando o código gerenciado, existe um TokenHelper.GetRealmFromTargetUrl método para obter o realm. Certifique-se de armazenar o valor em cache para que seu código não faça outra chamada de rede para obtê-lo novamente.

Obter um novo token de contexto

Se você precisa de um novo token de contexto, normalmente porque o token de atualização (que está contido no token de contexto) expirou, seu código pode obter um novo redirecionando o navegador para uma página especial em cada site do SharePoint: AppRedirect.aspx. Dois parâmetros de consulta precisam ser anexados à URL desta página:

  • client_id: a ID de cliente do seu Suplemento do SharePoint.
  • redirect_uri: o URI para o qual você deseja que o navegador seja redirecionado depois que o novo token de contexto for obtido. O SharePoint postará o token de contexto neste URI. Normalmente, essa é a mesma página, método do controlador ou método de serviço Web que solicitou o novo token de contexto. O valor deve ser codificado por URL.

Veja a seguir a estrutura da URL:

https://<SharePointDomain> /_layouts/15/appredirect.aspx?client_id=<app_client_GUID> &amp;redirect_uri=<URL-encoded_redirect_URI>

Veja a seguir um exemplo de como fazer a solicitação no ASP.NET que usa o arquivo TokenHelper:

Response.Redirect(TokenHelper.GetAppContextTokenRequestUrl(sharePointUrl, Server.UrlEncode(Request.Url.ToString())));

Exemplo de um token de contexto

Veja a seguir um exemplo de token de contexto. O pequeno objeto JSON (JavaScript Object Notation) na parte superior contém metadados sobre o token. Essas propriedades são iguais aos tokens de acesso (veja anteriormente). O valor da propriedade alg é o nome do algoritmo usado para gerar a assinatura que o ACS anexa ao token. Confira a Tabela 3 para ver detalhes sobre as propriedades no conteúdo do token. Todos os valores devem estar em letras minúsculas. (Um espaço em branco foi adicionado para facilitar a leitura.)

{"typ":"JWT","alg":"HS256"}
.
{
 "aud":"a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf":"1335822895",
 "exp":"1335866095",
 "appctxsender":"00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "appctx":"{
            \"CacheKey\":\"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\",
            \"SecurityTokenServiceUri\":\"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
           }",
 "refreshtoken":"IAAAAC1Lv5w0OrcFAmJx0xk6aaBdhgsw3VPnPzNEDAWypTHtCYytZ2/dBBUKj+HLK8YB3IUCUfDxYpAque
NHKtgs4rYJJ5AegQpNMOJR1yYK8ngivQx0oetj7aSPuGVb+k6at6G0Kx5LZ5vhxkAq8iUSwu8p4L2cvNMzDF1mDKfMivqxgrIZkr2nbf9as0SJFL6VG5hZnDE4HKq
xJnejSW3umatKM4fsfY1MClVCxrkXb2EQ8H/TmwaJc388YW063GEVUS/3BTSgSIRBKQUmXJuJ6BZY7WTm84LaGrx3mIjnUTM/jnqPoPG55JbCC9sS/MeGNPtzPPCDg
6Vv7dVhQ1Dq5Y3fQ65e9LpJ580jCgzYYvpIFT+Wx5V+17mjY2T8wug04K2ts87Znsr+GfFCorf7NS/lj5HjoxRAQ2tva/8dwguSLwxcUwi/Q9MbpR0NNtlpwVazqi9O
hJ4Df7gVhUDdJ0Dtc6aFCPbl5ZLDDRs42xK2",
 "isbrowserhostedapp": "true"
}

As declarações aud, iss, nbf e exp são exatamente as mesmas de um token de acesso descrito na Tabela 1.

As declarações appctxsender, appctx, CacheKey, SecurityTokenServiceUri, refreshtoken e isbrowserhostedapp são descritas na tabela a seguir.

Tabela 3. Declarações e informações de token de contexto

Solicitação Descrição Valor correspondente no token de contexto de exemplo
aud a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf 1335822895
exp 1335866095
appctxsender Abreviação de "remetente de contexto do aplicativo". Ele representa o aplicativo que enviou o token de contexto ao Suplemento do SharePoint. Ele tem o formato GUID of principal@SharePoint realm, em que o GUID da entidade é a ID constante da entidade do aplicativo, ou seja, o SharePoint, Exchange, Lync ou Workflow. 00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
appctx Abreviação de "contexto do suplemento". é um objeto JSON que contém a CacheKey e o SecurityTokenServiceURI. CacheKey:"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\", SecurityTokenServiceUri:"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
CacheKey Um valor exclusivo que pode ser usado como a chave em qualquer cache estruturado de chave/valor para armazenar e recuperar o token de contexto. Ele também pode ser usado como o valor de uma coluna de chave em uma linha de um banco de dados. KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=
SecurityTokenServiceURI O URI do serviço de emissão de tokens. https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2
refreshtoken O token de atualização do suplemento. IAAAAC1Lv5w0OrcFAmJx0xk6???
isbrowserhostedapp Um campo Booliano que especifica se a solicitação para o suplemento que contém o token de contexto está vindo de um navegador (true) ou de um receptor de eventos remotos (false). true

Use o token de contexto para limitar acesso somente a usuários do SharePoint

Se você quiser limitar o acesso ao seu componente remoto, como um serviço WCF, aos usuários do SharePoint, seu código pode simplesmente validar o token de contexto na Solicitação HTTP. (Se estiver usando código gerenciado, basta ligar TokenHelper.ReadAndValidateContextToken()).

Seu código pode verificar se a declaração de ator do token começa com 00000003-0000-0ff1-ce00-000000000000, caso você queira garantir que é o SharePoint (e não, por exemplo, o Exchange, o Lync ou o Workflow). Se você quiser fazer uma validação adicional que requeira uma chamada de retorno para o SharePoint, como limitar o acesso a usuários com uma determinada função no SharePoint, é possível armazenar em cache o fato de ter feito essa validação para um usuário específico (usando o token de contexto doCacheKey) para que seja possível fazer isso apenas uma vez.

Tokens de atualização

Um token de atualização é incluído no token de contexto que o SharePoint publica em seu aplicativo Web quando ele é iniciado. O token de atualização é um token criptografado que seu Suplemento do SharePoint não pode descriptografar. Seu código usa o usa, juntamente com outras informações, para obter um novo token de acesso quando o token de acesso atual expirar. ele também é usado para obter o primeiro token de acesso no fluxo do Token de Contexto. (Quando este artigo foi escrito, os tokens de atualização emitidos pelo ACS para o SharePoint tinham um tempo de vida de seis meses, mas isso pode ser alterado.)

Como um token de acesso dura horas (atualmente 12), e um usuário final obtém um novo cada vez que ele inicia seu Suplemento do SharePoint no SharePoint, você só precisa do token de atualização em um destes cenários:

  • Os usuários têm sessões de longa execução com o seu suplemento, nas quais o suplemento faz chamadas para o SharePoint muitas horas (atualmente mais de 12) depois de ser iniciado.

  • O design do suplemento permite que os usuários o agendem para acessar o SharePoint em algum momento após o término da sessão.

Ambos os cenários exigem que o suplemento armazene o token de atualização em cache e o segundo cenário exige um cache do lado do servidor que seja durável entre as sessões. Suas opções de cache são iguais àquelas usadas no token de acesso e, no fluxo de Token de Contexto, você pode usar a chave de cache do token contexto. (No fluxo de Token de Contexto, você apenas armazena em cache o token de contexto. Ele contém o token de atualização e outras informações que você precisa para obter um novo token de acesso. No fluxo código de autorização, não há nenhum token de contexto, portanto, você armazena em cache o token de atualização em si.)

Se você estiver armazenando em cache o token de atualização em um armazenamento que persiste entre as sessões de um usuário específico com o suplemento, certifique-se de substituí-lo pelo token de atualização mais recente. Em ambos os fluxos de Código de Autorização e de hospedagem na nuvem, o usuário recebe um novo token de atualização sempre que inicia o suplemento.

Se o token de atualização expirar, uma solicitação ao ACS para um novo token de acesso resultará em um erro 401 - Não Autorizado. Seu suplemento deve responder a esse erro obtendo um novo token de atualização e usando-o para obter um novo token de acesso. (Como o token de atualização é criptografado, seu código não pode verificar sua expiração antes de usá-lo.)

No fluxo de Token de Contexto, seu suplemento obtém um novo token de atualização ao obter um novo token de contexto. No fluxo do Código de Autorização, seu complemento recebe um novo token de atualização ao reiniciar o fluxo. Especificamente, seu código deve responder ao erro redirecionando o usuário para a página OAuthAuthorize.aspx do SharePoint, conforme explicado em Compreender o fluxo de OAuth para suplementos que solicitam permissões em tempo real.

Códigos de autorização

No fluxo do Código de Autorização, o processo de autorização começa com um código de autorização que o ACS emite, a pedido do SharePoint, e que o SharePoint passa para o aplicativo remoto como um parâmetro de consulta. O código de autorização é exclusivo para cada par de usuário e aplicativo remoto. (Quando este artigo foi escrito, os códigos de autorização emitidos pelo ACS para o SharePoint tinham uma duração de 5 minutos, mas isso pode ter mudado.)

A lógica em seu aplicativo deve obter o código de autorização do parâmetro de consulta e usá-lo em uma solicitação ao ACS por um token de acesso. Se você estiver usando um código gerenciado, o código de exemplo para criar o token estará no arquivo TokenHelper.cs (e .vb). O código de exemplo para leitura do parâmetro de consulta está em Obtenha o code-behind de exemplo para uma página que acessa o SharePoint. O ACS invalida o código de autorização imediatamente após a emissão do token de acesso, para que ele só possa ser usado uma vez e não faz sentido armazená-lo em cache.

Valores de tempo JWT

As declarações nbf e exp estão no formato especificado pela especificação JWT. Elas foram escritas como o número de segundos desde 1º de janeiro de 1970. Em C#, você pode traduzir esses valores com o código a seguir, onde jWTTimeStamp é o valor do token, como 1335822895.

DateTime exp = new DateTime(1970,1,1).AddSeconds(jWTTimeStamp);

Solucionar problemas de manipulação de token

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 nas solicitações.

Confira também