Использование ACS для авторизации надстроек с низким уровнем доверия на локальном сайте SharePoint

Статья
04/08/2023

Предварительные требования

Убедитесь, что у вас есть все перечисленные ниже компоненты.

Локальная среда разработки SharePoint. См. статью Настройка локальной среды разработки надстроек SharePoint.
Сайт SharePoint Office 365. Если ее еще нет и вы хотите быстро настроить среду разработки, можно настроить среду разработки для надстроек SharePoint на Office 365.
Visual Studio устанавливается удаленно или на компьютере с SharePoint с рабочей нагрузкой для разработки Office или SharePoint. В более ранних версиях Visual Studio требовался компонент Средств разработчика Microsoft Office для Visual Studio . Последняя версия этого компонента доступна здесь для Visual Studio 2013 и здесь для Visual Studio 2015.

Важно!

Упразднение ACS в Azure Active Directory не влияет на эту функцию в SharePoint. Дополнительные сведения см. в статье Влияние упразднения службы контроля доступа Azure на надстройки SharePoint.

Настройка локально установленной версии SharePoint на использование службы контроля доступа

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

Настройка службы контроля доступа на работу с локальной установкой SharePoint с помощью сайта SharePoint в Office 365

Настройка службы контроля доступа на работу с локальной установкой SharePoint при помощи сайта Office 365

Создайте прокси-сервер службы контроля доступа в локальной ферме SharePoint.
Установите сертификат подписи своего локального сервера на правах аренды Office 365.
Добавьте полные доменные имена сайтов на своей ферме SharePoint, на которой нужно запускать надстройки, в коллекцию имен субъектов-служб в аренде Office 365.
Создайте прокси-сервер управления надстройками на своей ферме SharePoint.

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

Настройка локального сайта SharePoint на использование службы контроля доступа

На локальном сервере SharePoint скопируйте код функции Connect-SPFarmToAAD (доступно ниже) в текстовый файл с именем MySharePointFunctions.psm1 и сохраните его в одной или другой из следующих папок (не в обеих). Возможно, потребуется создать некоторые элементы пути, если он включает несуществующие папки. Обратите внимание, что в обоих случаях имя последней папки в пути должно совпадать с именем файла.

Совет

Файл необходимо сохранить в формате ANSI, а не UTF-8. При загрузке файла в формате, отличном от ANSI, в PowerShell могут возникать синтаксические ошибки. "Блокнот" Windows по умолчанию сохраняет файлы в формате ANSI. Если вы сохраняете файл с помощью другого редактора, убедитесь, что используется формат ANSI.
- C:\users\username\documents\windowspowershell\modules\MySharePointFunctions, где username — это имя администратора фермы, который будет запускать файл.
- C:\windows\system32\windowspowershell\V1.0\modules\MySharePointFunctions
Функция Connect-SPFarmToAAD требует, чтобы пакет NuGet MSOnlineExt работал, установите его с помощью приведенного ниже командлета.
```
Install-Module -Name MSOnlineExt
```
Откройте командную консоль SharePoint от имени администратора и выполните приведенный ниже командлет, чтобы убедиться, что модуль MySharePointFunctions добавлен в список.
```
Get-Module -listavailable
```
Запустите приведенный ниже командлет, чтобы импортировать модуль.
```
Import-Module MySharePointFunctions
```
Запустите приведенный ниже командлет, чтобы убедиться, что функция Connect-SPFarmToAAD включена в модуль.
```
Get-Command -module MySharePointFunctions
```
Выполните приведенный ниже командлет, чтобы убедиться, что функция Connect-SPFarmToAAD загружена.
```
ls function:\ | where {$_.Name -eq "Connect-SPFarmToAAD"}
```
Запустите функцию Connect-SPFarmToAAD. Обязательно укажите необходимые параметры и все дополнительные параметры, которые применяются к вашей среде разработки. Подробности и примеры см. в следующем разделе.

Параметры функции Connect-SPFarmToAAD

Параметр	Значение
`-AADDomain` (обязательный)	Домен .onmicrosoft.com, созданный при оформлении подписки на сайт Office 365 (ваш_личный_домен.onmicrosoft.com). Когда скрипт предложит вам пройти проверку подлинности, используйте имя пользователя и пароль, созданные для этого домена: имя_пользователя@ваш_личный_домен*.onmicrosoft.com.
`-SharePointOnlineUrl` (обязательный)	URL-адрес сайта SharePoint Office 365 (`_https://yourcustomdomain_.sharepoint.com`). Обратите внимание на то, что onmicrosoft.com не является родительским доменом.
`-SharePointWeb` (обязательный в некоторых случаях)	Полный URL-адрес (включая протокол) локального веб-приложения SharePoint, в котором запускаются размещаемые у поставщика надстройки. Эта функция добавляет только одно веб-приложение SharePoint из локальной фермы в ACS. Если значение этого параметра не указано, скрипт выбирает первое веб-приложение в ферме. Если вы используете семейство веб-сайтов с именем на основе узла (HNSC), которое можно определить с помощью подстановочного знака (например, http://.contoso.com), то такую строку можно использовать в качестве значения этого параметра. Если у веб-приложения есть альтернативное сопоставление доступа (AAM) для зоны Интернета, то в качестве значения этого параметра необходимо задать его URL-адрес. Если веб-приложение SharePoint не настроено для протокола HTTPS, то необходимо применять протокол HTTP и использовать переключатель -AllowOverHttp (см. далее в этой таблице).* Если вы хотите запускать размещаемые у поставщика надстройки с использованием ACS в большем количестве веб-приложений фермы, то их необходимо добавить в коллекцию имен субъектов служб. Скрипт Windows PowerShell после функции `Connect-SPFarmToAAD` иллюстрирует добавление всех веб-приложений фермы в коллекцию имен субъектов служб.
`-AllowOverHttp` (необязательный)	Используйте этот параметр командной строки, если вы работаете со средой разработки и не хотите использовать SSL для своих надстроек. Его необходимо использовать, если веб-приложение SharePoint не настроено для протокола HTTPS.
`-O365Credentials` (необязательный)	Первый символ — заглавная буква O, а не ноль. Если вам часто приходится запускать скрипт для отладки, то при использовании этого параметра вам не придется каждый раз вручную вводить имя и пароль для Office 365. Чтобы использовать этот параметр, необходимо создать соответствующий объект учетных данных с помощью следующих командлетов: `$User = "username@yourcustomdomain.onmicrosoft.com"$PWord = ConvertTo-SecureString -String "the_password" -AsPlainText -Force$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWord` Используйте `$Credential` в качестве значения `-O365Credentials` параметра.
`-Verbose` (необязательный)	Этот параметр создает более подробный отчет, который может быть полезен, если функция не работает и нужно повторно запустить ее для отладки.
`-RemoveExistingACS` (необязательный)	Используйте этот параметр, если вы заменяете имеющееся подключение к Azure Active Directory. Он удаляет имеющийся прокси-сервер ACS, если он уже есть в ферме.
`-RemoveExistingSTS` (необязательный)	Используйте этот параметр, если вы заменяете имеющееся подключение к Azure Active Directory. Он удаляет имеющегося доверенного поставщика токенов безопасности, оставшегося от предыдущего подключения к ACS.
`-RemoveExistingSPOProxy` (необязательный)	Используйте этот параметр, если вы заменяете имеющееся подключение к Azure Active Directory. Он удаляет имеющийся прокси-сервер для управления надстройками, если он уже есть в ферме.
`-RemoveExistingAADCredentials` (необязательный)	Используйте этот параметр командной строки, если заменяете сайт SharePoint в Office 365.

Ниже представлены примеры.

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb https://fabrikam.com

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb http://northwind.com -AllowOverHttp

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb http://northwind.com -AllowOverHttp -RemoveExistingACS -RemoveExistingSTS -RemoveExistingSPOProxy -RemoveExistingAADCredentials

Содержимое MySharePointFunctions.psm1

function Connect-SPFarmToAAD {
param(
    [Parameter(Mandatory)][String]   $AADDomain,
    [Parameter(Mandatory)][String]   $SharePointOnlineUrl,
    #Specify this parameter if you don't want to use the default SPWeb returned
    [Parameter()][String]            $SharePointWeb,
    [Parameter()][System.Management.Automation.PSCredential] $O365Credentials,
    #Use these switches if you're replacing an existing connection to AAD.
    [Parameter()][Switch]            $RemoveExistingACS,
    [Parameter()][Switch]            $RemoveExistingSTS,
    [Parameter()][Switch]            $RemoveExistingSPOProxy,
    #Use this switch if you're replacing the Office 365 SharePoint site.
    [Parameter()][Switch]            $RemoveExistingAADCredentials,
    #Use this switch if you don't want to use SSL when you launch your app.
    [Parameter()][Switch]            $AllowOverHttp
)
    #Prompt for credentials right away.
    if (-not $O365Credentials) {
        $O365Credentials = Get-Credential -Message "Admin credentials for $AADDomain"
    }
    Add-PSSnapin Microsoft.SharePoint.PowerShell
    #Import the Microsoft Online Services Sign-In Assistant.
    Import-Module -Name MSOnline
    #Import the Microsoft Online Services Module for Windows PowerShell.
    Import-Module MSOnlineExt -force -verbose 
    #Set values for Constants.
    New-Variable -Option Constant -Name SP_APPPRINCIPALID -Value '00000003-0000-0ff1-ce00-000000000000' | Out-Null
    New-Variable -Option Constant -Name ACS_APPPRINCIPALID -Value '00000001-0000-0000-c000-000000000000' | Out-Null
    New-Variable -Option Constant -Name ACS_APPPROXY_NAME -Value ACS
    New-Variable -Option Constant -Name SPO_MANAGEMENT_APPPROXY_NAME -Value 'SPO Add-in Management Proxy'
    New-Variable -Option Constant -Name ACS_STS_NAME -Value ACS-STS
    New-Variable -Option Constant -Name AAD_METADATAEP_FSTRING -Value 'https://accounts.accesscontrol.windows.net/{0}/metadata/json/1'
    New-Variable -Option Constant -Name SP_METADATAEP_FSTRING -Value '{0}/_layouts/15/metadata/json/1'
    #Get the default SPWeb from the on-premises farm if no $SharePointWeb parameter is specified.
    if ([String]::IsNullOrEmpty($SharePointWeb)) {
        $SharePointWeb = Get-SPSite | Select-Object -First 1 | Get-SPWeb | Select-Object -First 1 | % Url
    }

    #Configure the realm ID for local farm so that it matches the AAD realm.
    $ACSMetadataEndpoint = $AAD_METADATAEP_FSTRING -f $AADDomain
    $ACSMetadata = Invoke-RestMethod -Uri $ACSMetadataEndpoint
    $AADRealmId = $ACSMetadata.realm

    Set-SPAuthenticationRealm -ServiceContext $SharePointWeb -Realm $AADRealmId
    
    $LocalSTS = Get-SPSecurityTokenServiceConfig
    $LocalSTS.NameIdentifier = '{0}@{1}' -f $SP_APPPRINCIPALID,$AADRealmId
    $LocalSTS.Update()

    #Allow connections over HTTP if the switch is specified.
    if ($AllowOverHttp.IsPresent -and $AllowOverHttp -eq $True) {
        $serviceConfig = Get-SPSecurityTokenServiceConfig
        $serviceConfig.AllowOAuthOverHttp = $true
        $serviceConfig.AllowMetadataOverHttp = $true
        $serviceConfig.Update()
    }

    #Step 1: Set up the ACS proxy in the on-premises SharePoint farm. Remove the existing ACS proxy
    #if the switch is specified.
    if ($RemoveExistingACS.IsPresent -and $RemoveExistingACS -eq $True) {
        Get-SPServiceApplicationProxy | ? DisplayName -EQ $ACS_APPPROXY_NAME | Remove-SPServiceApplicationProxy -RemoveData -Confirm:$false
    }
    if (-not (Get-SPServiceApplicationProxy | ? DisplayName -EQ $ACS_APPPROXY_NAME)) {
        $AzureACSProxy = New-SPAzureAccessControlServiceApplicationProxy -Name $ACS_APPPROXY_NAME -MetadataServiceEndpointUri $ACSMetadataEndpoint -DefaultProxyGroup
    }

    #Remove the existing security token service if the switch is specified.
    if ($RemoveExistingSTS.IsPresent) {
        Get-SPTrustedSecurityTokenIssuer | ? Name -EQ $ACS_STS_NAME | Remove-SPTrustedSecurityTokenIssuer -Confirm:$false
    }
    if (-not (Get-SPTrustedSecurityTokenIssuer | ? DisplayName -EQ $ACS_STS_NAME)) {
        $AzureACSSTS = New-SPTrustedSecurityTokenIssuer -Name $ACS_STS_NAME -IsTrustBroker -MetadataEndPoint $ACSMetadataEndpoint
    }

    #Update the ACS Proxy for OAuth authentication.
    $ACSProxy = Get-SPServiceApplicationProxy | ? Name -EQ $ACS_APPPROXY_NAME
    $ACSProxy.DiscoveryConfiguration.SecurityTokenServiceName = $ACS_APPPRINCIPALID
    $ACSProxy.Update()

    #Retrieve the local STS signing key from JSON metadata.
    $SPMetadata = Invoke-RestMethod -Uri ($SP_METADATAEP_FSTRING -f $SharePointWeb)
    $SPSigningKey = $SPMetadata.keys | ? usage -EQ "Signing" | % keyValue
    $CertValue = $SPSigningKey.value
    
    #Connect to Office 365.
    Connect-MsolService -Credential $O365Credentials
    #Remove existing connection to an Office 365 SharePoint site if the switch is specified.
    if ($RemoveExistingAADCredentials.IsPresent -and $RemoveExistingAADCredentials -eq $true) {
        $msolserviceprincipal = Get-MsolServicePrincipal -AppPrincipalId $SP_APPPRINCIPALID
        [Guid[]] $ExistingKeyIds = Get-MsolServicePrincipalCredential -ObjectId $msolserviceprincipal.ObjectId -ReturnKeyValues $false | % {if ($_.Type -ne "Other") {$_.KeyId}}
        Remove-MsolServicePrincipalCredential -AppPrincipalId $SP_APPPRINCIPALID -KeyIds $ExistingKeyIds
    }
    #Step 2: Upload the local STS signing certificate
    New-MsolServicePrincipalCredential -AppPrincipalId $SP_APPPRINCIPALID -Type Asymmetric -Value $CertValue -Usage Verify

    #Step 3: Add the service principal name of the local web application, if necessary.
    $indexHostName = $SharePointWeb.IndexOf('://') + 3
    $HostName = $SharePointWeb.Substring($indexHostName)
    $NewSPN = '{0}/{1}' -f $SP_APPPRINCIPALID, $HostName
    $SPAppPrincipal = Get-MsolServicePrincipal -AppPrincipalId $SP_APPPRINCIPALID
    if ($SPAppPrincipal.ServicePrincipalNames -notcontains $NewSPN) {
        $SPAppPrincipal.ServicePrincipalNames.Add($NewSPN)
        Set-MsolServicePrincipal -AppPrincipalId $SPAppPrincipal.AppPrincipalId -ServicePrincipalNames $SPAppPrincipal.ServicePrincipalNames
    }

    #Remove the existing SharePoint Online proxy if the switch is specified.
    if ($RemoveExistingSPOProxy.IsPresent -and $RemoveExistingSPOProxy -eq $True) {
        Get-SPServiceApplicationProxy | ? DisplayName -EQ $SPO_MANAGEMENT_APPPROXY_NAME | Remove-SPServiceApplicationProxy -RemoveData -Confirm:$false
    }
    #Step 4: Add the SharePoint Online proxy
    if (-not (Get-SPServiceApplicationProxy | ? DisplayName -EQ $SPO_MANAGEMENT_APPPROXY_NAME)) {
        $spoproxy = New-SPOnlineApplicationPrincipalManagementServiceApplicationProxy -Name $SPO_MANAGEMENT_APPPROXY_NAME -OnlineTenantUri $SharePointOnlineUrl -DefaultProxyGroup
    }  
}

Конфигурация надстройки и веб-приложения SharePoint для Магазина Office

В рабочей среде администраторам фермы следует выполнить еще одно необязательное действие, если требуется, чтобы пользователи могли устанавливать размещаемые у поставщика надстройки с использованием ACS из Магазина Office. В среде разработки SharePoint это бессмысленно, если вы не планируете устанавливать надстройки с использованием ACS из магазина в этой среде. Это можно сделать с помощью приведенного ниже командлета. Этот код можно добавить к предыдущей функции.

New-SPMarketplaceWebServiceApplicationProxy -Name "ApplicationIdentityDataWebServiceProxy" -ServiceEndpointUri "https://oauth.sellerdashboard.microsoft.com/ApplicationIdentityDataWebService.svc" -DefaultProxyGroup

Кроме того, в рабочих веб-приложениях SharePoint рекомендуется активировать компонент Надстройки, которым требуются подключенные к Интернету конечные точки по завершении настройки. См. приведенные ниже инструкции. Этот компонент на самом деле ничего не делает. Он просто служит в качестве флага, сообщающего Магазину Office, что размещаемые у поставщика надстройки с использованием ACS можно устанавливать на веб-сайтах в веб-приложении SharePoint.

Такая система может повлиять на манифест надстройки SharePoint. Если вы планируете продавать надстройку в магазине, рекомендуем добавить следующий параметр AppPrerequisite в раздел AppPrerequisites манифеста надстройки:

<AppPrerequisite Type="Feature" ID="{7877bbf6-30f5-4f58-99d9-a0cc787c1300}" />

Благодаря этому, когда пользователи просматривают магазин из локальной фермы SharePoint, надстройка не будет доступна для установки, если в родительском веб-приложении SharePoint не включен компонент Надстройки, которым требуются подключенные к Интернету конечные точки. Это гарантирует, что вы не будете получать жалобы от пользователей, у которых надстройка не работает при установке на локальном веб-сайте SharePoint.

Включить этот компонент можно двумя способами. Вы можете запустить следующий командлет PowerShell (который можно добавить в конец предыдущей функции) на любом сервере SharePoint:

Enable-SPFeature -identity "7877bbf6-30f5-4f58-99d9-a0cc787c1300" -Url http://domain_of_the_SharePoint_web_application

Чтобы запустить функцию, вы также можете выполнить указанные ниже действия в Центре администрирования.

В Центре администрирования SharePoint перейдите в раздел Управление приложениями>Управление веб-приложениями.
На странице Управление веб-приложениями выберите веб-приложение, которое нужно изменить.
На ленте выберите Управление компонентами.
В списке компонентов рядом со строкой Надстройки, которым требуются подключенные к Интернету конечные точки нажмите кнопку Активировать.
Нажмите кнопку ОК.

Настройка дополнительных веб-приложений SharePoint в ферме

Если на вашей ферме SharePoint есть дополнительные веб-приложения и вы хотите запускать на них надстройки с размещением у поставщика, использующие доверие службы контроля доступа, с помощью этого сценария Windows PowerShell (в Командная консоль SharePoint) вы можете добавить их в коллекцию имен субъектов службы.

$SPAppPrincipal = Get-MsolServicePrincipal -AppPrincipalId 00000003-0000-0ff1-ce00-000000000000
$id = "00000003-0000-0ff1-ce00-000000000000/"

Get-SPWebApplication | ForEach-Object {
    $hostName = $_.Url.substring($_.Url.indexof("//") + 2)
    $hostName = $hostName.Remove($hostName.Length - 1, 1)

    $NewSPN = $id + $hostName

    Write-Host "Adding SPN for" $NewSPN

    if ($SPAppPrincipal.ServicePrincipalNames -notcontains $NewSPN) {
       $SPAppPrincipal.ServicePrincipalNames.Add($NewSPN)
       Set-MsolServicePrincipal -AppPrincipalId $SPAppPrincipal.AppPrincipalId -ServicePrincipalNames $SPAppPrincipal.ServicePrincipalNames
    }
}