Partilhar via

Scripts de configuração de alto nível de confiança para o SharePoint

  • Artigo

Os scripts a seguir são usados para designar um ou mais certificados digitais X.509 como emissores confiáveis de tokens de acesso em um farm do Microsoft SharePoint de preparo ou produção. Para um script mais apropriado para um ambiente de desenvolvimento de suplementos do SharePoint, consulte Criar Suplementos do SharePoint de alta confiança. Nenhum único conjunto de scripts pode funcionar para cada farm do SharePoint porque há muitas maneiras diferentes de os certificados serem adquiridos e armazenados. Por esse motivo, observe o seguinte:

  • Os scripts devem ser executados em um Shell de Gerenciamento do SharePoint em qualquer servidor do SharePoint no farm.

  • Esses scripts devem ser considerados como rascunhos que talvez precisem ser personalizados.

  • Eles são usados como parte do processo geral de publicação de um Suplemento do SharePoint de alta confiança. Elas só devem ser usadas por alguém familiarizado com os tópicos Criando Suplementos do SharePoint que usam autorização de alta confiança e Pacote e publicam suplementos do SharePoint de alta confiança e os pré-requisitos listados neles.

  • Eles devem ser revisados e personalizados conforme necessário por alguém familiarizado com as políticas de certificado do cliente de suplemento.

  • Os dois principais scripts que se seguem, HighTrustConfig-ForSharedCertificate.ps1 e HighTrustConfig-ForSingleApp.ps1, assumem que um administrador adquiriu um certificado para o componente de aplicativo Web remoto do suplemento ou suplementos, e que o administrador armazenou temporariamente uma versão .cer do certificado (que não contém a chave privada) em uma pasta à qual as contas do usuário para os seguintes pools de aplicativos IIS nos servidores do SharePoint têm acesso de leitura:

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

      Para localizar a conta de usuário que um pool de aplicativos está usando, abra o IIS Manager em um servidor do SharePoint e clique duas vezes em Pools de Aplicativos no painel Conexões . A coluna Identidade na lista Pools de Aplicativos que é aberta mostra os usuários para os pools de aplicativos.

  • As instruções para os dois principais scripts também pressupõem que os certificados foram instalados no IIS em servidores que hospedam os aplicativos Web remotos. Para obter instruções, consulte Configurar o servidor Web remoto com o certificado.

Confira notas de uso específicas para cada script nas seções a seguir.

AddSPRootAuthority.ps1

O certificado do componente de aplicativo Web remoto do Suplemento do SharePoint de alta confiança é obtido de uma AC (Autoridade de Certificado comercial) ou de uma AC de domínio. Em ambos os casos, o certificado é o link mais baixo em uma cadeia de certificados, cada um confiando no acima dele, que se origina com uma AC raiz (comercial ou domínio). O SharePoint exige que todos os certificados da cadeia sejam adicionados à lista de autoridades raiz confiáveis do SharePoint.

O script a seguir pode ser usado para adicionar cada certificado na cadeia , exceto o mais baixo à lista. O certificado mais baixo da cadeia, o certificado que está diretamente associado ao aplicativo Web remoto, é adicionado às autoridades raiz em um dos principais scripts descritos em seções posteriores.

Os parâmetros para o script são os seguintes:

Parâmetro Valor
-CertPath O caminho completo e o nome do arquivo do certificado (o arquivo .cer).
-CertName O nome do certificado. Para localizar o nome, exiba as propriedades do certificado.

Por exemplo, no cenário comum em que o certificado do aplicativo Web é emitido por um servidor de AC intermediário (também chamado de 'empresa') e seu certificado, por sua vez, é emitido por um servidor de AC raiz (também chamado de 'autônomo'), o script deve ser executado uma vez para cada um dos certificados dos dois servidores de AC. O seguinte mostra o seguinte:

./AddSPRootAuthority.ps1 -CertPath "\\CertStorage\RootCA.cer" -CertName "Contoso Root CA"

./AddSPRootAuthority.ps1 -CertPath "C:\RegionalCerts\NorthRegion.cer" -CertName "North Region Intermediate CA"

Se todos os certificados dos suplementos do SharePoint de alta confiança do cliente forem provenientes da mesma cadeia de certificados, como normalmente seria o caso, esse script nunca mais será usado.

A seguir está o código do script. Basta cole-o em qualquer editor de texto ou no editor do PowerShell (IPowerShell ISE) e salve-o como AddSPRootAuthority.ps1.

Observação

O arquivo deve ser salvo no formato ANSI, não UTF-8. O PowerShell pode dar erros de sintaxe quando executa um arquivo com um formato não ANSI. NotePad e o editor do PowerShell padrão para salvá-lo como ANSI. Se você usar qualquer outro editor para salvar o arquivo, salve-o como ANSI.

param(
  [Parameter(Mandatory)][String] $CertName = $(throw "Usage: AddSPRootAuthority.ps1 -CertPath <full path to .cer file> -CertName <name of certificate>"),
  [Parameter(Mandatory)][String] $CertPath
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Make the certificate a trusted root authority in SharePoint
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)
New-SPTrustedRootAuthority -Name $CertName -Certificate $cert

HighTrustConfig-ForSharedCertificate.ps1

As principais tarefas deste script são registrar o certificado compartilhado dos componentes remotos do aplicativo Web em vários Suplementos do SharePoint de alta confiança com o SharePoint como uma autoridade raiz e como um emissor de token de acesso confiável. Esse script não será usado se o cliente estiver usando certificados separados com cada Suplemento do SharePoint de alta confiança. Para esse cenário, consulte HighTrustConfig-ForSingleApp.ps1. Se todos os suplementos usarem o mesmo certificado, esse script será executado apenas uma vez. Se alguns conjuntos de suplementos usarem um certificado diferente de outros conjuntos, esse script será executado uma vez para cada conjunto.

A tabela a seguir descreve os parâmetros e as opções para o script. A personalização do script pode exigir alterações nesta tabela.

Parâmetro Valor
-CertPath (necessário) O caminho completo para o arquivo *.cer compartilhado.
-CertName (necessário) O nome do certificado compartilhado. Para localizar o nome, abra o IIS no servidor Web remoto que hospeda o aplicativo Web remoto. Realce o nó nome do servidor e clique duas vezes em Certificados. O certificado é listado pelo nome.
-TokenIssuerFriendlyName
(opcional)		 Um nome amigável exclusivo para o emissor de token, até 50 caracteres. Isso pode ser útil se você estiver depurando problemas com emissores de token.

O nome deve ser exclusivo. Incluir um GUID garantiria que ele seja, mas um GUID usa até 32 dos 50 caracteres, portanto, considere converter um GUID em uma cadeia de caracteres Base 64 que pode ser reduzida para 22 caracteres.

Se esse parâmetro não for usado, o script usará o nome High-Trust Add-ins <base64 version of issuer GUID>.

A seguir está um exemplo de execução deste script.

./HighTrustConfig-ForSharedCertificate.ps1 -CertPath "C:\Certs\MyCert.cer" -CertName "My Cert" -TokenIssuerFriendlyName "SharePoint High-Trust Add-ins Token Issuer"

Importante

O registro do certificado como emissor de token não tem efeito imediato. Pode levar até 24 horas antes que todos os servidores do SharePoint reconheçam o novo emissor de token. Executar um iisreset em todos os servidores do SharePoint faria com que eles reconhecessem imediatamente o emissor, se você puder fazer isso sem incomodar os usuários do SharePoint.

Inicie um novo arquivo em um editor de texto ou no editor do PowerShell e copie o seguinte em um arquivo de texto e salve-o como HighTrustConfig-ForSharedCertificate.ps1. Use o formato ANSI, não UTF-8.

param(
  [Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSharedCertificate.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-TokenIssuerFriendlyName <friendly name>]"),
  [Parameter(Mandatory)][String] $CertName,
  [Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
  throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}

# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)

# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate

# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm

# Generate a unique specific issuer ID
$specificIssuerId = [System.Guid]::NewGuid().ToString()

# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm

# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
  $tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
  $tokenIssuerName = "High-Trust Add-ins " + [System.Convert]::ToBase64String($specificIssuerId.ToByteArray()).TrimEnd('=')
}

# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker

# Output the specific issuer ID to a file in the same folder as this script. The file should be given to the developer of the high-trust SharePoint Add-in.
$specificIssuerId  | Out-File -FilePath "SecureTokenIssuerID.txt"

Dica

Se o script gerar um erro após a execução New-SPTrustedRootAuthority da linha com êxito, o script não poderá ser executado novamente até que esse objeto tenha sido removido. Use o seguinte cmdlet, em que o valor do -Identity parâmetro é o mesmo usado para o -CertName parâmetro no script: Remove-SPTrustedRootAuthority -Identity <certificate name>

Se o emissor de token precisar ser removido por qualquer motivo, use o seguinte cmdlet: Remove-SPTrustedSecurityTokenIssuer -Identity <issuer name>

Se o -TokenIssuerFriendlyName parâmetro foi usado, use o mesmo valor para -Identity.

Se o -TokenIssuerFriendlyName parâmetro não foi usado, um GUID aleatório faz parte do nome do emissor. Para obter o valor necessário para -Identity, execute o cmdlet a seguir. Abra o arquivo TokenIssuers.txt produzido e localize o emissor cujo nome é High-Trust Add-ins <base64 version of issuer GUID>. Use esse nome inteiro para -Identity.

Get-SPTrustedSecurityTokenIssuer | Out-File -FilePath "TokenIssuers.txt"

HighTrustConfig-ForSingleApp.ps1

As principais tarefas deste script são registrar o certificado do aplicativo Web remoto em um Suplemento do SharePoint de alta confiança com o SharePoint como uma autoridade raiz e como um emissor de token de acesso confiável. Esse script não será usado se o cliente estiver usando um único certificado para vários Suplementos do SharePoint. Para esse cenário, consulte HighTrustConfig-ForSharedCertificate.ps1. Esse script é executado para cada Suplemento do SharePoint de alta confiança.

A tabela a seguir descreve os parâmetros e as opções para o script. A personalização do script pode exigir alterações nesta tabela.

Parâmetro Valor
-CertPath (necessário) O caminho completo para o arquivo *.cer compartilhado.
-CertName (necessário) O nome do certificado compartilhado. Para localizar o nome, abra o IIS no servidor Web remoto que hospeda o aplicativo Web remoto. Realce o nó nome do servidor e clique duas vezes em Certificados. O certificado é listado pelo nome.
-SPAppClientID (necessário) A ID do cliente (um GUID) usada quando o Suplemento do SharePoint foi registrado em appregnew.aspx.
Isso é usado como a ID do emissor para o emissor do token. O script garante que ele seja minúscula, o que é um requisito para IDs do emissor.
-TokenIssuerFriendlyName
(opcional)		 Um nome amigável exclusivo para o emissor de token, até 50 caracteres. Isso pode ser útil se você estiver depurando problemas com emissores de token.
O nome deve ser exclusivo. Considere usar o nome do Suplemento do SharePoint. Se esse parâmetro não for usado, o script usará o valor de -SPAppClientID como o nome.

Veja a seguir um exemplo de como chamar o script:

./HighTrustConfig-ForSingleApp.ps1 -CertPath "\\MyServer\Certs\MyCert.cer" -CertName "My Cert" -SPAppClientID "afe332f4-1f87-4c31-89b8-9c343ad7f24e" -TokenIssuerFriendlyName "Payroll add-in"

Importante

O registro do certificado como emissor de token não tem efeito imediato. Pode levar até 24 horas antes que todos os servidores do SharePoint reconheçam o novo emissor de token. Executar um iisreset em todos os servidores do SharePoint faria com que eles reconhecessem imediatamente o emissor, se você puder fazer isso sem incomodar os usuários do SharePoint.

Inicie um novo arquivo em um editor de texto ou no editor do PowerShell e copie o seguinte em um arquivo de texto e salve-o como HighTrustConfig-ForSingleApp.ps1. Use o formato ANSI, não UTF-8.

param(
  [Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSingleApp.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-SPAppClientID <client ID of SharePoint add-in>] [-TokenIssuerFriendlyName <friendly name>]"),
  [Parameter(Mandatory)][String] $CertName,
  [Parameter(Mandatory)][String] $SPAppClientID,
  [Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
  throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}

# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)

# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate

# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm

# Must use the client ID as the specific issuer ID. Must be lower-case!
$specificIssuerId = New-Object System.String($SPAppClientID).ToLower()

# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm

# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
  $tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
  $tokenIssuerName = $specificIssuerId
}

# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier

Dica

As dicas no final da seção anterior também se aplicam aqui, mas para o -Identity parâmetro do Remove-SPTrustedSecurityTokenIssuer cmdlet, use a ID do cliente se o -TokenIssuerFriendlyName parâmetro não for usado com HighTrustConfig-ForSingleApp.ps1.

Modificações necessárias para assinaturas de site

Uma assinatura de site, às vezes chamada de locação, é um subconjunto das coleções de sites em um farm do SharePoint. As assinaturas do site normalmente são criadas em fazendas hospedadas do SharePoint. Se o cliente do Suplemento do SharePoint de alta confiança quiser instalar o suplemento em um farm que foi configurado para assinaturas de site, qualquer um dos dois scripts highTrustConfig-*.ps1 precisa ser modificado.

Cada assinatura do site tem sua própria ID de domínio, mas a linha $realm = Get-SPAuthenticationRealm nos scripts sempre retorna o reino do farm. Os tokens de acesso emitidos por um emissor de token só são considerados válidos pelo SharePoint para o reino especificado após o caractere "@" na ID do emissor completo.

Para obter o realm correto para o site em que o suplemento será instalado, o script precisa usar o -ServiceContext parâmetro na chamada para Get-SPAuthenticationRealm. O objeto de contexto de serviço, por sua vez, é criado a partir da coleção de sites pai do site de destino.

A seguir está um exemplo, em que $WebURL é uma variável de cadeia de caracteres com a URL completa de um site do SharePoint, como http://marketing.contoso.com/sites/northteam/july. Esse código permite que o suplemento de alta confiança seja executado, não apenas no site especificado, mas em todos os sites dentro da mesma assinatura do site.

$Web = Get-SPWeb $WebURL
$sc = Get-SPServiceContext -Site $Web.Site
$realm = Get-SPAuthenticationRealm -ServiceContext $sc

Para concluir a modificação do script, adicione um parâmetro $WebURL adicional necessário à lista de param na parte superior do arquivo, assim:

param (
  # other parameters omitted
  [Parameter()][String] $WebURL
)

Certifique-se de adicionar uma vírgula após o parâmetro que precede o novo. E expanda o exemplo "Uso" na linha superior para levar em conta o novo parâmetro com algo assim:

-WebURL <full URL where SP add-in will be installed>

Para tornar o Suplemento do SharePoint confiável em cada assinatura do site, obtenha uma referência ao farm com o Get-SPFarm cmdlet e, em seguida, itere por meio de sua propriedade SiteSubscriptions . Passe cada objeto SPSiteSubscription para o Get-SPServiceContext cmdlet como o valor do -SiteSubscription parâmetro. Apresentamos um exemplo a seguir.

$Farm = Get-SPFarm
foreach ($ss in $Farm.SiteSubscriptions)
{
  $sc = Get-SPServiceContext -SiteSubscription $ss
  $realm = Get-SPAuthenticationRealm -ServiceContext $sc

  # All of the lines from the draft script below the call to
  # Get-SPAuthenticationRealm are inserted here inside the loop.
}
# end of script

Confira também