Criar suplementos do SharePoint de alta confiança

  • Artigo

Um suplemento de alta confiança é um Suplemento do SharePoint hospedado pelo provedor que usa certificados digitais para estabelecer a confiança entre o aplicativo Web remoto e o SharePoint. "Alta confiança" não é o mesmo que "confiança total". Um suplemento de alta confiança ainda deve solicitar permissões de suplemento. O suplemento é considerado "de alta confiança" porque é confiável usar qualquer identidade de usuário que o suplemento precise, porque o suplemento é responsável por criar a parte do usuário do token de acesso que ele passa para o SharePoint.

Um suplemento de alta confiança do SharePoint destina-se principalmente para uso em um ambiente local. O suplemento de alta confiança não pode ser instalado no Microsoft SharePoint Online, e os componentes remotos geralmente são instalados no local, também, dentro do firewall corporativo. Assim, as instâncias do suplemento do SharePoint são específicas para cada empresa individual.

Um suplemento de alta confiança usa um certificado em vez de um token de contexto para estabelecer confiança. (Um suplemento hospedado pelo provedor criado para usar o ACS (Serviço de Controle de Acesso do Microsoft Azure), pois seu agente de confiança precisa ser modificado para funcionar como um aplicativo de alta confiança.) Os suplementos de alta confiança exigem alguma configuração no farm do SharePoint e no servidor que hospeda o aplicativo Web remoto.

No SharePoint, o serviço de token de segurança (STS) de servidor para servidor fornece tokens de acesso para autenticação de servidor para servidor. O STS de servidor para servidor permite que tokens de acesso temporário acessem outros serviços de aplicativo, como o Exchange, o Lync e os suplementos do SharePoint. Você estabelece uma relação de confiança entre os serviços de aplicativo (por exemplo, estabelecer confiança entre o SharePoint e um suplemento remoto) usando cmdlets do Windows PowerShell e um certificado.

Observação

O STS de servidor para servidor não é destinado à autenticação de usuários. Portanto, você não verá o STS de servidor para servidor listado na página de entrada do usuário, na seção Provedor de Autenticação na Administração Central ou no Seletor de Pessoas no SharePoint.

Este artigo mostra como criar um suplemento de alta confiança e fornece instruções de configuração para executá-lo no Visual Studio selecionando F5. Você aprenderá a:

  • Configurar um suplemento para uso como suplemento de alta confiança.
  • Configurar o SharePoint para usar suplementos de alta confiança.
  • Criar um suplemento de alta confiança básico.

A configuração de um ambiente de teste, preparação ou produção é um pouco diferente e está descrita no tópico Empacotar e publicar suplementos de alta confiança do SharePoint.

Pré-requisitos

Para seguir os procedimentos deste artigo, você deve ter o seguinte:

Obter um certificado ou criar um certificado de teste público e particular

Você precisa de um certificado digital X.509 para o aplicativo da Web remoto do seu complemento de alta confiança. Para testar completamente o seu suplemento do SharePoint, você precisa de um certificado emitido por domínio ou um certificado comercial emitido por uma autoridade de certificação. No entanto, para a fase inicial de depuração, você pode usar um certificado autoassinado.

O procedimento a seguir descreve como criar e exportar um certificado de teste usando o IIS. Você aprenderá a substituir o certificado autoassinado por um certificado comercial ou de domínio na seção Concluir a depuração com um certificado comercial ou emitido por domínio posteriormente.

Alternativamente, você também pode usar o programa de teste MakeCert para gerar um certificado X.509. Para obter mais informações sobre como usar o MakeCert, consulte Assinando e verificando código com Authenticode.

Você criará primeiro um arquivo de certificado .pfx de teste e, em seguida, um arquivo .cer de teste correspondente. O certificado .pfx contém a chave privada usada pelo aplicativo remoto para assinar suas comunicações com o SharePoint. O .cer contém a chave pública que o SharePoint usa para descriptografar as mensagens, verificar se elas são provenientes do aplicativo Web remoto e verificar se o aplicativo remoto da Web tem um token de acesso de um emissor de token no qual o SharePoint confia. Para obter mais informações sobre arquivos .pfx e .cer, consulte Certificado de Fornecedor de Software.

Para criar um arquivo de certificado autoassinado de teste .pfx

  1. Quando você está depurando um suplemento do SharePoint de alta confiança no Visual Studio, o aplicativo remoto da Web é hospedado no IIS Express no computador onde o Visual Studio está instalado. Portanto, o computador do aplicativo da Web remoto não tem um Gerenciador do IIS onde você possa criar o certificado. Por esse motivo, você usa o IIS no servidor de teste do SharePoint para criar o certificado.

No gerenciador do IIS, selecione o nó ServerName na visualização em árvore à esquerda.

  1. Selecione o ícone Certificados do Servidor, conforme mostrado na figura a seguir.

Opção Certificados do Servidor no IIS

  1. Selecione o link Criar certificado autoassinado no conjunto de links à direita.

Link Criar certificado autoassinado

  1. Nomeie o certificado como HighTrustSampleCert e, em seguida, selecione OK.

  2. Clique com o botão direito do mouse no certificado e selecione Exportar.

Exportando um certificado de teste

  1. No Windows, ou em uma linha de comando, crie uma pasta chamada C:\Certs.

  2. De volta ao Gerenciador do IIS, exporte o arquivo para C:\Certs e forneça uma senha. Neste exemplo, a senha é password.

  3. Se sua instalação de teste do SharePoint não estiver no mesmo computador em que o Visual Studio está sendo executado, crie uma pasta C:\Certs no computador do Visual Studio e mova o arquivo HighTrustSampleCert.pfx para ela. Este é o computador em que o aplicativo da Web remoto é executado quando você está depurando no Visual Studio.

Para criar um arquivo .cer correspondente

  1. No servidor do SharePoint, certifique-se de que a identidade do grupo de suplementos para os seguintes grupos de suplementos do IIS tem direitos de leitura na pasta C:\Certs:

  • SecurityTokenServiceApplicationPool

  • O grupo de suplementos que atende o site do IIS que hospeda o aplicativo Web pai do SharePoint para o seu site de teste do SharePoint. Para o site IIS SharePoint - 80, o grupo é chamado OServerPortalAppPool.

  1. No gerenciador do IIS, selecione o nó ServerName na visualização em árvore à esquerda.

  2. Clique duas vezes em Certificados do servidor.

  3. Na exibição Certificados de Servidor, clique duas vezes em HighTrustSampleCert para exibir os detalhes do certificado.

  4. Na guia Detalhes, selecione Copiar para Arquivo para iniciar o Assistente para Exportação de Certificados e, em seguida, selecione Avançar.

  5. Use o valor padrão Não exportar a chave privada e, em seguida, selecione Avançar.

  6. Use os valores padrão e, em seguida, selecione Avançar.

  7. Selecione Procurar, navegue até C:\Certs, nomeie o certificado como HighTrustSampleCert e, em seguida, selecione Salvar. O certificado é salvo como um arquivo .cer.

  8. Selecione Avançar.

  9. Selecione Concluir.

Configurar o SharePoint para usar certificados e configurar a confiança do suplemento

O script do Windows PowerShell que você cria nesta seção destina-se a ser compatível com o uso da F5 no Visual Studio. Ele não configurará adequadamente uma instalação de preparação ou de produção do SharePoint. Para obter instruções sobre como configurar um SharePoint de produção para usar certificados, consulte Empacotar e publicar suplementos do SharePoint de alta confiança.

Importante

Verifique se você concluiu as etapas em Configurar serviços no SharePoint para uso de suplemento de servidor a servidor (o que é listado como pré-requisito para este artigo). Se não, você deve configurá-lo agora, antes de prosseguir.

Para configurar o SharePoint

  1. Em um editor de texto ou no editor do Windows PowerShell, inicie um novo arquivo e adicione as seguintes linhas a ele para criar um objeto de certificado.
  $publicCertPath = "C:\Certs\HighTrustSampleCert.cer"
  $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)
  1. Adicione a linha a seguir para garantir que o SharePoint trate o certificado como uma autoridade raiz.
  New-SPTrustedRootAuthority -Name "HighTrustSampleCert" -Certificate $certificate
  1. Adicione a linha a seguir para obter a ID do realm de autorização.
  $realm = Get-SPAuthenticationRealm
  1. Seu aplicativo da Web remoto usa um token de acesso para obter acesso aos dados do SharePoint. O token de acesso deve ser emitido por um emissor de token no qual o SharePoint confia. Em um suplemento do SharePoint de alta confiança, o certificado é o emissor do token. Adicione as seguintes linhas para construir uma ID do emissor no formato que o SharePoint exige: _specific_issuer_GUID_@_realm_GUID_.
  $specificIssuerId = "11111111-1111-1111-1111-111111111111"
  $fullIssuerIdentifier = $specificIssuerId + '@' + $realm

Observação

O $specificIssuerId valor deve ser um GUID porque, em um ambiente de produção, cada certificado deve ter um emissor exclusivo. No entanto, neste contexto, em que você usa o mesmo certificado para depurar todos os seus suplementos de alta confiança, você pode embutir o valor. Se, por algum motivo, você usar um GUID diferente daquele usado aqui, certifique-se de que as letras no GUID estejam em minúsculas. Atualmente, a infraestrutura do SharePoint requer minúsculas para os GUIDs de emissor de certificado.

  1. Adicione as seguintes linhas para registrar o certificado como um emissor de token confiável. O parâmetro -Name deve ser exclusivo, portanto, em uma configuração de produção, é comum usar um GUID como parte do nome ou todo o nome, mas, nesse contexto, você pode usar um nome amigável. A opção -IsTrustBroker é necessária para garantir que você possa usar o mesmo certificado para todos os suplementos de alta confiança que você desenvolve. O comando iisreset é necessário para tornar seu emissor de token registrado imediatamente. Sem ele, você pode ter que esperar até 24 horas para o novo emissor ser registrado.
  New-SPTrustedSecurityTokenIssuer -Name "High Trust Sample Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
  iisreset
  1. O SharePoint normalmente não aceita certificados autoassinados. Portanto, quando você estiver usando um certificado autoassinado para depuração, adicione as seguintes linhas para desativar o requisito normal do SharePoint de que o HTTPS seja usado quando os aplicativos da Web remotos acessarem o SharePoint. Caso contrário, você receberá uma mensagem 403 (proibido) quando o aplicativo remoto da Web chamar o SharePoint usando um certificado autoassinado. Você vai reverter este passo em um procedimento posterior. Desativar o requisito HTTPS significa que as solicitações do aplicativo Web remoto para o SharePoint não são criptografadas, mas o certificado ainda é usado como um emissor confiável de tokens de acesso, o que é seu principal objetivo nos suplementos do SharePoint de alta confiança.
  $serviceConfig = Get-SPSecurityTokenServiceConfig
  $serviceConfig.AllowOAuthOverHttp = $true
  $serviceConfig.Update()

  1. Salve o arquivo com o nome HighTrustConfig-ForDebugOnly.ps1.

  2. Abra o Shell de Gerenciamento do SharePoint como administrador e execute o arquivo com a seguinte linha:

  ./HighTrustConfig-ForDebugOnly.ps1

Criar um suplemento do SharePoint de alta confiança

Nesta seção, você cria um suplemento do SharePoint de alta confiança usando o Visual Studio.

Observação

Conforme declarado na seção Pré-requisitos para criar suplementos de alta confiança, este artigo pressupõe que você sabe como criar um suplemento do SharePoint hospedado pelo provedor. Para obter mais informações, consulte Introdução à criação de suplementos do SharePoint hospedados pelo provedor.

Para criar um suplemento do SharePoint de alta confiança

  1. No Visual Studio, selecione Arquivo>Novo>Projeto.

  2. No Novo Assistente de Projeto, expanda o nó Visual C# ou Visual Basic e, em seguida, expanda o nó Office/SharePoint.

  3. Selecione Suplementos e, em seguida, escolha criar um projeto de Suplemento para o SharePoint.

  4. Nomeie o projeto HighTrustSampleApp.

  5. Salve o projeto em um local selecionado e, em seguida, selecione OK.

  6. Especifique a URL completa do site do desenvolvedor do SharePoint. Por exemplo, http://TestServer/sites/devsite/

  7. Selecione a opção Hospedado pelo provedor e, em seguida, selecione Avançar.

  8. Se você for solicitado a especificar o tipo de projeto da Web, selecione Aplicativo Web Forms do ASP.NET para obter o exemplo em continuação neste tópico e, em seguida, selecione Avançar.

  9. A página Definir configurações de autenticação do assistente é aberta. Os valores adicionados a este formulário são adicionados ao arquivo web.config automaticamente. Em Como você deseja que seu suplemento seja autenticado?, selecione Usar um certificado.

  10. Clique em Procurar ao lado da caixa Local do certificado e vá até o local do certificado autoassinado (arquivo.pfx) que você criou (C:\Certs). O valor desse campo deve ser o caminho completo C:\Certs\HighTrustSampleCert.pfx.

  11. Digite a senha desse certificado na caixa Senha. Neste caso, é password.

  12. Digite o ID do emissor (11111111-1111-1111-1111-111111111111) na caixa ID do Emissor.

  13. Selecione Concluir. Grande parte da configuração é feita quando a solução é aberta. Dois projetos são criados na solução do Visual Studio, um para o suplemento do SharePoint e outro para o aplicativo da Web do ASP.NET.

Para executar e depurar o suplemento

  1. As Ferramentas para Desenvolvedores do Office para o Visual Studio geram automaticamente um arquivo default.aspx e default.aspx.cs quando o projeto ASP.NET é criado. O código gerado busca o título do host da Web do SharePoint e o imprime na página padrão do aplicativo da Web remoto. A marcação e o código exatos nesses arquivos variam dependendo da versão das ferramentas. Para este tópico, você usa os arquivos default.aspx e default.aspx.cs gerados sem modificação.

  2. Para testar o suplemento do SharePoint e seu aplicativo da Web remoto, selecione F5 no Visual Studio. O aplicativo da Web é implantado no IIS Express em localhost. O suplemento do SharePoint é instalado no site do SharePoint de destino. Você é solicitado pelo SharePoint a conceder as permissões que o suplemento do SharePoint solicita. Algumas versões das Ferramentas para Desenvolvedores do Office para Visual Studio iniciam o suplemento imediatamente; outras abrirão a página Conteúdo do Site do seu site de destino do SharePoint e você verá o novo suplemento listado lá.

Inicie o suplemento, se não for iniciado automaticamente. O aplicativo da Web remoto é aberto na página especificada como Página Inicial no arquivo AppManifest.xml, que é Default.aspx. Seu suplemento deve ser semelhante à figura a seguir.

Amostra do aplicativo recuperando o título da Web

Realizar a depuração com um certificado comercial ou emitido pelo domínio

O script do Windows PowerShell que você criou anteriormente desativou o requisito habitual do SharePoint de que os aplicativos da Web remotos usem o protocolo HTTPS para acessar o SharePoint. Trabalhar com o HTTPS desativado pode fazer com que você, como desenvolvedor, ao criar um suplemento não note alguns problemas que ocorreriam durante uma implantação de produção na qual o HTTPS fosse exigido. Da mesma forma, você não deve considerar as fases de desenvolvimento e depuração concluídas até substituir o certificado de teste por um certificado comercial ou emitido por domínio e, em seguida, testar novamente o suplemento com o requisito HTTPS ativado.

Quando você obtiver o novo certificado, precisará adicionar uma senha, caso este ainda não tenha uma. Em um ambiente de produção, você usaria uma senha forte, mas para depurar um suplemento do SharePoint, você pode usar qualquer senha. Você precisa do certificado em dois formatos, pfx e cer. Se não estiver no formato pfx ao obtê-lo, talvez seja necessário convertê-lo em pfx usando um utilitário. Quando você tiver um arquivo pfx, poderá importá-lo para o IIS e exportar o arquivo cer conforme descrito no procedimento a seguir.

Para importar o novo certificado

  1. Coloque o arquivo .pfx em C:\Certs no servidor do SharePoint. Para fins deste artigo, supomos que o arquivo se chama "MyCert.pfx". Você deve substituir "MyCert" em todas essas instruções pelo nome real do seu certificado.

  2. No Gerenciador de IIS, selecione o nó ServerName na exibição em árvore à esquerda.

  3. Clique duas vezes no ícone Certificados do Servidor.

  4. Selecione Importar no painel Ações à direita.

  5. Na caixa de diálogo Importar Certificado, use o botão procurar para navegar até C:\Certs\MyCert.pfx e, em seguida, insira a senha do certificado.

  6. Certifique-se de que Permitir que este certificado seja exportado esteja ativado e, em seguida, selecione OK.

  7. Na lista Certificados do Servidor, clique com o botão direito do mouse no certificado e selecione Exportar.

  8. Exporte o arquivo para C:\Certs e especifique uma senha para este.

  9. Se a instalação do SharePoint de teste não estiver no mesmo computador em que o Visual Studio está em execução, mova o arquivo MyCert.pfx para a pasta C:\Certs no computador do Visual Studio.

  10. Na tela Certificados do Servidor, clique duas vezes em MyCert para exibir os detalhes do certificado.

  11. Na guia Detalhes, selecione Copiar para Arquivo para iniciar o Assistente para Exportação de Certificados e, em seguida, selecione Avançar.

  12. Use o valor padrão Não exportar a chave privada e, em seguida, selecione Avançar.

  13. Use os valores padrão. Selecione Avançar.

  14. Selecione Procurar, navegue até C:\Certs, nomeie o certificado MyCert e, em seguida, selecione Salvar. O certificado é salvo como um arquivo .cer.

  15. Selecione Avançar.

  16. Selecione Concluir.

Para configurar o SharePoint para usar o novo certificado

  1. Abra o arquivo HighTrustConfig-ForDebugOnly.ps1 para edição e faça as seguintes alterações:

  • Substitua HighTrustSampleCert nos dois locais onde aparece por MyCert.

  • Substitua o ID do emissor específico, 11111111-1111-1111-1111-111111111111, por 22222222-2222-2222-2222-222222222222.

  • Substitua "High Trust Sample Cert" por "My Cert" ou algum outro nome amigável apropriado.

  • Na linha $serviceConfig.AllowOAuthOverHttp = $true, substitua true por false. Isso reativa o requisito de que HTTPS seja usado.

  1. Salve o arquivo.

  2. Abra o Shell de Gerenciamento do SharePoint como administrador e execute o arquivo com a seguinte linha:

  ./HighTrustConfig-ForDebugOnly.ps1

Para reconfigurar o aplicativo Web remoto

  1. No Visual Studio, abra o arquivo web.config do projeto de aplicativo Web e faça as seguintes alterações:

  • Na chave ClientSigningCertificatePath, substitua C:\Certs\HighTrustSampleCert.pfx por C:\Certs\<MyCert>.pfx.

  • Substitua o valor da chave ClientSigningCertificatePassword pela senha real do certificado.

  • Substitua o valor da chave IssuerId por 22222222-2222-2222-2222-222222222222.

  1. Selecione F5 para depurar o suplemento.

Quando você terminar de desenvolver seu suplemento de alta confiança, verifique Empacotar e publicar Suplementos do SharePoint de alta confiança para obter instruções sobre como empacotar e publicar esse tipo de suplemento do SharePoint.

O que os arquivos TokenHelper e SharePointContext fazem?

As Ferramentas para Desenvolvedores do Office para Visual Studio incluem um arquivo TokenHelper.cs (ou .vb) no aplicativo da Web remoto. Algumas versões das ferramentas também incluem um arquivo SharePointContext.cs (ou .vb).

O código nesses arquivos faz o seguinte:

  • Configura o .NET para confiar em certificados ao fazer chamadas de rede.

  • Recupera um token de acesso de servidor a servidor que é assinado pelo certificado particular do aplicativo Web remoto em nome do objeto WindowsIdentity especificado e que o SharePoint usa para estabelecer confiança.

  • Obtém o certificado do serviço de token de segurança (STS) do SharePoint.

  • Em suplementos que usam o sistema de autorização de baixa confiança e não o de alta confiança, esses arquivos têm tarefas adicionais, como manipular tokens OAuth para o cenário descrito em Fluxo OAuth de Token de Contexto para Suplementos do SharePoint. Esse cenário está fora do escopo deste artigo.

Em um suplemento de alta confiança, não há token de contexto. O token de contexto é específico para configurações que usam autorização de baixa confiabilidade. No entanto, um token de acesso ainda é necessário. Se você estiver usando uma configuração de alta confiabilidade, seu aplicativo da Web precisará autenticar o usuário exatamente como o SharePoint o faz (isto é, o suplemento será responsável por criar o token de acesso, incluindo os IDs do usuário e do provedor de identidade).

Quando você está depurando no Visual Studio com F5, as Ferramentas para Desenvolvedores do Office para Visual Studio usam a autenticação do Windows, e os dois arquivos de código gerados usam a identidade do Windows da pessoa executando o suplemento para criar o token de acesso. Quando o suplemento é publicado, você precisa configurar o aplicativo remoto da Web no Gerenciador do IIS para usar a Autenticação do Windows se quiser usar os dois arquivos gerados sem modificação.

Se o seu suplemento não usar a Autenticação do Windows no ambiente de produção, você precisará personalizar os arquivos de código gerados, TokenHelper e/ou SharePointContext, para usar um sistema de autenticação diferente. Você também personalizaria esses arquivos se o seu aplicativo da Web remoto acessasse o SharePoint em uma identidade diferente do usuário que está executando o Suplemento do SharePoint. Finalmente, se o aplicativo da Web remoto estiver em PHP, node.js, Java ou alguma outra plataforma que não ASP.NET, seu código precisará obter a ID do usuário de qualquer sistema de autenticação que estiver sendo usado e, em seguida, incluir essa ID no token de acesso que ele constrói.

Confira também