Поделиться через

Скрипты настройки для SharePoint с высоким уровнем доверия

  • Статья

Приведенные ниже скрипты используются для назначения одного или нескольких цифровых сертификатов X.509 в качестве доверенных поставщиков маркеров доступа в промежуточной или рабочей ферме Microsoft SharePoint. Скрипт, более подходящий для среды разработки надстроек SharePoint, представлен в статье Создание надстроек SharePoint с высоким уровнем доверия. Любой отдельно взятый набор скриптов подойдет не для каждой фермы SharePoint, так как сертификаты можно получать и хранить множеством различных способов. По этой причине следует учитывать следующее:

  • Скрипты предназначены для запуска в командной консоли SharePoint на любом сервере SharePoint в ферме.

  • Они представляют собой черновики, которые можно настраивать.

  • Они используются в ходе публикации надстройки SharePoint с высоким уровнем доверия. Прежде чем запускать их, необходимо ознакомиться со статьями Создание надстроек для SharePoint, которые используют авторизацию с высоким уровнем доверия и Упаковка и публикация надстроек с высоким уровнем доверия для SharePoint, а также описанными в них предварительными требованиями.

  • В случае необходимости эти скрипты должен изучить и настроить специалист, знакомый с политиками сертификатов пользователя надстройки.

  • В двух приведенных ниже основных скриптах, HighTrustConfig-ForSharedCertificate.ps1 и HighTrustConfig-ForSingleApp.ps1, предполагается, что администратор получил сертификаты для компонентов удаленных веб-приложений надстроек и временно сохранил CER-файлы сертификатов (без закрытого ключа) в папке, к которой есть доступ для чтения у учетных записей пользователей для следующих пулов приложений IIS на серверах SharePoint:

    • SecurityTokenServiceApplicationPool.

    • Пул надстроек, обслуживающий веб-сайт IIS, на котором размещается родительское веб-приложение SharePoint для тестового веб-сайта SharePoint. Пул для веб-сайта IIS SharePoint - 80 называется OServerPortalAppPool.

      Чтобы найти учетную запись пользователя, которую применяет пул приложений, откройте диспетчер служб IIS на сервере SharePoint и дважды щелкните элемент Пулы приложений в области Подключения. В столбце Удостоверение в списке Пулы приложений отображаются пользователи пулов приложений.

  • В инструкциях к двум основным скриптам также предполагается, что сертификаты установлены в службах IIS на серверах, где размещаются удаленные веб-приложения. Инструкции см. в разделе Настройка удаленного веб-сервера с помощью сертификата.

В последующих разделах представлены конкретные примечания по использованию каждого скрипта.

AddSPRootAuthority.ps1

Сертификат компонента удаленного веб-приложения для надстройки SharePoint с высоким уровнем доверия получается от коммерческого или доменного центра сертификации (ЦС). В обоих случаях этот сертификат является последним звеном цепочки сертификатов, каждый из которых доверяет предыдущему, начиная с корневого ЦС (коммерческого или доменного). Среде SharePoint необходимо, чтобы все сертификаты в цепочке были добавлены в список доверенных корневых центров сертификации в SharePoint.

С помощью приведенного ниже скрипта можно добавить в список все сертификаты из цепочки, кроме последнего. Последний сертификат в цепочке, который привязан непосредственно к удаленному веб-приложению, добавляется к корневым центрам в одном из основных скриптов, описанных в дальнейших разделах.

Ниже перечислены параметры скрипта.

Параметр Значение
-CertPath Полный путь и имя файла сертификата (CER-файла).
-CertName Имя сертификата. Его можно найти в свойствах сертификата.

Например, в распространенном сценарии, когда сертификат веб-приложения выдан промежуточным сервером ЦС (который также называют "корпоративным), сертификат которого, в свою очередь, выдан корневым сервером ЦС (который также называют "автономным"), скрипт следует выполнить один раз для каждого сертификата двух серверов ЦС. Далее показан пример:

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

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

Если все сертификаты используемых пользователем надстроек SharePoint с высоким уровнем доверия получены из одной цепочки сертификатов (что встречается довольно часто), то этот скрипт больше не используется.

Ниже приведен код скрипта. Просто вставьте его в любом текстовом редакторе или редакторе PowerShell (IPowerShell ISE) и сохраните под именем AddSPRootAuthority.ps1.

Примечание.

Файл необходимо сохранить в формате ANSI, а не UTF-8. При запуске файла в формате, отличном от ANSI, в PowerShell могут возникать синтаксические ошибки. По умолчанию приложение "Блокнот" и редактор PowerShell сохраняют файлы в формате ANSI. Если вы сохраняете файл с помощью другого редактора, убедитесь, что используется формат 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

Основная задача этого скрипта — регистрация общего сертификата компонентов удаленных веб-приложений в нескольких надстройках SharePoint с высоким уровнем доверия. При этом SharePoint является как корневым центром сертификации, так и доверенным поставщиком маркеров доступа. Этот скрипт не используется, если пользователь применяет отдельные сертификаты для каждой надстройки SharePoint с высоким уровнем доверия. Для этого сценария см .HighTrustConfig-ForSingleApp.ps1. Если все надстройки используют один и тот же сертификат, то скрипт выполняется только один раз. Если некоторые наборы надстроек используют другой сертификат, то этот скрипт выполняется по одному разу для каждого набора.

В следующей таблице представлены параметры и переключатели для скрипта. Если скрипт настраивается, эту таблицу может потребоваться изменить.

Параметр Значение
-CertPath (обязательно) Полный путь к общему CER-файлу.
-CertName (обязательно) Имя общего сертификата. Чтобы определить имя, откройте службы IIS на удаленном веб-сервере, где размещено удаленное веб-приложение. Выделите узел Имя сервера и дважды щелкните Сертификаты. В списке вы найдете имя сертификата.
-TokenIssuerFriendlyName
(необязательный)		 Уникальное понятное имя поставщика маркеров (до 50 символов). Это может быть полезно при устранении неполадок, связанных с поставщиками маркеров.

Имя должно быть уникальным. Указав GUID, вы обеспечите это, но GUID занимает 32 из 50 символов, поэтому рекомендуем преобразовать GUID в строку с кодировкой Base 64, которую можно сократить до 22 символов.

Если этот параметр не используется, скрипт задает имя High-Trust Add-ins <base64 version of issuer GUID>.

Ниже приведен пример выполнения этого скрипта.

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

Важно!

Регистрация сертификата в качестве поставщика маркера не вступает в силу немедленно. Может потребоваться до 24 часов, чтобы все серверы SharePoint признали нового поставщика маркеров. Запуск iisreset на всех серверах SharePoint приведет к немедленному распознаванию издателя, если вы можете сделать это, не беспокоя пользователей SharePoint.

Создайте файл в текстовом редакторе или редакторе PowerShell, скопируйте в него приведенный ниже код и сохраните файл как HighTrustConfig-ForSharedCertificate.ps1. Используйте формат ANSI, а не 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"

Совет

Если скрипт вернет ошибку после успешного выполнения строки New-SPTrustedRootAuthority, то его невозможно будет перезапустить, пока этот объект не будет удален. Используйте следующий командлет, указав то же значение параметра -Identity, что и для параметра -CertName в скрипте: Remove-SPTrustedRootAuthority -Identity <certificate name>.

Если по той или иной причине потребуется удалить поставщика маркеров, выполните следующий командлет: Remove-SPTrustedSecurityTokenIssuer -Identity <issuer name>.

Если использовался параметр -TokenIssuerFriendlyName, укажите такое же значение в параметре -Identity.

Если параметр -TokenIssuerFriendlyName не использовался, то в состав имени поставщика будет входить случайный GUID. Чтобы получить необходимое значение параметра -Identity, выполните приведенный ниже командлет. Откройте созданный файл TokenIssuers.txt и найдите поставщика с именем High-Trust Add-ins <base64 version of issuer GUID>. Используйте это имя целиком для параметра -Identity.

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

HighTrustConfig-ForSingleApp.ps1

Основная задача этого скрипта — регистрация сертификата компонентов удаленного веб-приложения в надстройке SharePoint с высоким уровнем доверия. При этом SharePoint является как корневым центром сертификации, так и доверенным поставщиком маркеров доступа. Этот скрипт не используется, если пользователь применяет один и тот же сертификат для нескольких надстроек SharePoint. Этот случай предусмотрен в скрипте HighTrustConfig-ForSharedCertificate.ps1. Этот скрипт выполняется для каждой надстройки SharePoint с высоким уровнем доверия.

В следующей таблице представлены параметры и переключатели для скрипта. Если скрипт настраивается, эту таблицу может потребоваться изменить.

Параметр Значение
-CertPath (обязательно) Полный путь к общему CER-файлу.
-CertName (обязательно) Имя общего сертификата. Чтобы определить имя, откройте службы IIS на удаленном веб-сервере, где размещено удаленное веб-приложение. Выделите узел Имя сервера и дважды щелкните Сертификаты. В списке вы найдете имя сертификата.
-SPAppClientID (обязательно) Идентификатор клиента (GUID), который использовался при регистрации надстройки SharePoint на странице appregnew.aspx.
Он используется в качестве ИД поставщика маркеров. Этот скрипт гарантирует, что ИД будет написан строчными буквами (это обязательно).
-TokenIssuerFriendlyName
(необязательный)		 Уникальное понятное имя поставщика маркеров (до 50 символов). Это может быть полезно при устранении неполадок, связанных с поставщиками маркеров.
Имя должно быть уникальным. Рекомендуем использовать название надстройки SharePoint. Если этот параметр не используется, скрипт задает в качестве имени значение -SPAppClientID.

Ниже приведен пример вызова скрипта.

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

Важно!

Регистрация сертификата в качестве поставщика маркера не вступает в силу немедленно. Может потребоваться до 24 часов, пока все серверы SharePoint не получат сведения о новом поставщике. Если выполнить команду iisreset на всех серверах SharePoint, поставщик будет зарегистрирован немедленно (используйте этот метод, если вы уверены, что работа пользователей SharePoint не будет нарушена).

Создайте файл в текстовом редакторе или редакторе PowerShell, скопируйте в него приведенный ниже код и сохраните файл под именем HighTrustConfig-ForSingleApp.ps1. Используйте формат ANSI, а не 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

Совет

Советы, указанные в конце предыдущего раздела, применимы и здесь, но в качестве значения параметра -Identity командлета Remove-SPTrustedSecurityTokenIssuer используйте идентификатор клиента, если параметр -TokenIssuerFriendlyName не применялся для сценария HighTrustConfig-ForSingleApp.ps1.

Изменения, которые необходимо внести в подписки на сайт

Подписка на сайт, иногда называемая областью клиентов, — это подмножество семейств веб-сайтов в ферме SharePoint. Подписки на сайты обычно создаются в размещаемых фермах SharePoint. Если пользователь надстройки SharePoint с высоким уровнем доверия хочет установить надстройку в ферме, настроенной для подписок на сайты, то необходимо изменить используемый скрипт HighTrustConfig-*.ps1.

У каждой подписки на сайт есть собственный ИД области, но строка $realm = Get-SPAuthenticationRealm в скриптах всегда возвращает область фермы. SharePoint считает маркеры доступа, выданные поставщиком маркеров, действительными только для области, указанной после символа "@" в полном ИД поставщика.

Чтобы получить правильную область для веб-сайта, на котором планируется установить надстройку, скрипт должен использовать параметр -ServiceContext в вызове метода Get-SPAuthenticationRealm. В свою очередь, объект контекста службы создается из родительского семейства веб-сайтов целевого веб-сайта.

Ниже представлен пример, где $WebURL — это строковая переменная с полным URL-адресом веб-сайта SharePoint, например http://marketing.contoso.com/sites/northteam/july. Этот код делает возможным запуск надстройки с высоким уровнем доверия не только на указанном веб-сайте, но и на каждом веб-сайте в той же подписке на сайт.

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

Чтобы завершить изменение сертификата, добавьте обязательный параметр $WebURL в список параметров в начале файла следующим образом:

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

Обязательно добавьте запятую после параметра, предшествующего новому параметру. Дополните пример Usage в верхней строке, чтобы учитывался новый параметр. Пример:

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

Чтобы надстройке SharePoint доверяла каждая подписка на сайт, получите ссылку на ферму с помощью командлета Get-SPFarm, а затем выполните перебор по свойству SiteSubscriptions. Передавайте каждый объект SPSiteSubscription в командлет Get-SPServiceContext в качестве значения параметра -SiteSubscription. Ниже приведен пример.

$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

См. также