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

  • Статья

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

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

Такие надстройки устанавливают доверие с помощью сертификата, а не токена контекста. (Надстройка, размещенная у поставщика, которая использует службу microsoft Azure контроль доступа (ACS) в качестве брокера доверия, необходимо изменить для работы в качестве приложения с высоким уровнем доверия.) Надстройки с высоким уровнем доверия требуют некоторой настройки на ферме SharePoint и на сервере, на котором размещено удаленное веб-приложение.

В SharePoint межсерверная служба токенов безопасности (STS) предоставляет маркеры доступа для проверки подлинности "сервер-сервер". Межсерверная служба STS предоставляет временные маркеры доступа к службам других приложений, таким как Exchange, Lync и надстройки SharePoint. Чтобы установить отношение доверия между службами приложений (например, между SharePoint и удаленной надстройкой), используются командлеты Windows PowerShell и сертификат.

Примечание.

Межсерверная служба STS не предназначена для проверки подлинности пользователей. Следовательно, эта служба не отображается на странице входа пользователя, в разделе Поставщик проверки подлинности Центра администрирования и в средстве выбора людей SharePoint.

В этой статье показано, как создать надстройку с высоким уровнем доверия и запустить ее в Visual Studio с помощью клавиши F5. В этой статье рассматриваются следующие темы:

  • Конфигурация надстройки для использования в качестве надстройки с высоким уровнем доверия.
  • Настройка SharePoint для использования надстроек с высоким уровнем доверия.
  • Создание простейшей надстройки с высоким уровнем доверия.

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

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

Прежде чем выполнять процедуры, описанные в этой статье, убедитесь, что у вас есть следующее:

Получение сертификата или создание общедоступного и закрытого сертификатов для тестирования

Для удаленного веб-приложения надстройки с высоким уровнем доверия необходим цифровой сертификат X.509. Чтобы полностью протестировать надстройку SharePoint, необходим сертификат, выданный доменом, или коммерческий сертификат от центра сертификации. Однако на начальном этапе отладки можно использовать самозаверяющий сертификат.

Ниже описано, как создать и экспортировать тестовый сертификат с помощью IIS. В разделе Полная отладка с доменным или коммерческим сертификатом далее в этой статье описано, как заменить самозаверяющий сертификат на доменный или коммерческий сертификат.

Кроме того, вы можете использовать тестовую программу MakeCert, чтобы создать сертификат X.509. Дополнительные сведения о том, как использовать MakeCert, см. в статье Подписание и проверка кода с помощью Authenticode.

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

Создание PFX-файла тестового самозаверяющего сертификата

  1. При отладке надстройки SharePoint с высоким уровнем доверия в Visual Studio удаленное веб-приложение размещается в IIS Express на том компьютере, где установлена среда Visual Studio. Таким образом, на компьютере с удаленным веб-приложением нет диспетчера IIS, где можно создать сертификат. По этой причине мы используем службы IIS на тестовом сервере SharePoint для создания сертификата.

В диспетчере IIS выберите узел Имя сервера в представлении в виде дерева слева.

  1. Щелкните значок Сертификаты сервера, как показано на приведенном ниже рисунке.

Элемент

  1. Выберите ссылку Создать самозаверяющий сертификат в списке ссылок справа.

Ссылка

  1. Задайте для сертификата имя HighTrustSampleCert и нажмите кнопку ОК.

  2. Щелкните сертификат правой кнопкой мыши и выберите пункт Экспорт.

Экспорт тестового сертификата

  1. В Windows или в командной строке создайте папку с именем C:\Certs.

  2. В диспетчере IIS экспортируйте файл в папку C:\Certs и задайте для него пароль. В этом примере используется пароль password.

  3. Если тестовая установка SharePoint находится не на том же компьютере, где работает Visual Studio, создайте папку C:\Certs на компьютере Visual Studio и переместите в нее файл HighTrustSampleCert.pfx. На этом компьютере будет работать удаленное веб-приложение при запуске отладки в Visual Studio.

Создание соответствующего CER-файла

  1. На сервере SharePoint убедитесь, что удостоверениям следующих пулов надстроек IIS предоставлены права Read для папки C:\Certs:

  • SecurityTokenServiceApplicationPool.

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

  1. В диспетчере IIS выберите узел Имя сервера в представлении в виде дерева слева.

  2. Дважды щелкните элемент Сертификаты сервера.

  3. В представлении Сертификаты сервера дважды щелкните сертификат HighTrustSampleCert, чтобы просмотреть сведения о нем.

  4. На вкладке Сведения нажмите кнопку Копировать в файл, чтобы запустить мастер экспорта сертификатов, а затем нажмите кнопку Далее.

  5. Оставьте значение по умолчанию (Нет, не экспортировать закрытый ключ) и нажмите кнопку Далее.

  6. Оставьте значения по умолчанию и нажмите кнопку Далее.

  7. Нажмите кнопку Обзор, перейдите к папке C:\Certs, задайте для сертификата имя HighTrustSampleCert и нажмите кнопку Сохранить. Сертификат будет сохранен в виде CER-файла.

  8. Нажмите кнопку Далее.

  9. Нажмите кнопку Готово.

Настройка SharePoint на использование сертификатов и настройка доверия для надстройки

Скрипт Windows PowerShell, создаваемый в этом разделе, предназначен для поддержки использования клавиши F5 в Visual Studio. Он не настраивает промежуточную или рабочую среду SharePoint должным образом. Инструкции по настройке рабочей среды SharePoint на использование сертификатов см. в статье Упаковка и публикация надстроек SharePoint с высоким уровнем доверия.

Важно!

Прежде чем продолжать, настройте службы в SharePoint для межсерверного использования надстройки (это одно из предварительных требований для этой статьи). Не продолжайте, пока это не будет сделано.

Настройка SharePoint

  1. В текстовом редакторе или в редакторе Windows PowerShell создайте новый файл и добавьте приведенные ниже строки для создания объекта сертификата.
  $publicCertPath = "C:\Certs\HighTrustSampleCert.cer"
  $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)
  1. Добавьте приведенную ниже строку, чтобы гарантировать, что SharePoint будет рассматривать сертификат как корневой центр.
  New-SPTrustedRootAuthority -Name "HighTrustSampleCert" -Certificate $certificate
  1. Добавьте приведенную ниже строку, чтобы получить идентификатор области авторизации.
  $realm = Get-SPAuthenticationRealm
  1. Удаленное веб-приложение использует маркер доступа для обращения к данным SharePoint. Маркер доступа должен быть выдан поставщиком маркеров, которому доверяет SharePoint. В надстройках SharePoint с высоким уровнем доверия поставщиком маркеров является сертификат. Добавьте следующие строки, чтобы создать идентификатор издателя в формате, необходимом для SharePoint: _specific_issuer_GUID_@_realm_GUID_.
  $specificIssuerId = "11111111-1111-1111-1111-111111111111"
  $fullIssuerIdentifier = $specificIssuerId + '@' + $realm

Примечание.

Значение $specificIssuerId должно быть идентификатором GUID, так как в рабочей среде у каждого сертификата должен быть уникальный издатель. Однако в этом контексте, когда для отладки всех надстроек с высоким уровнем доверия используется один и тот же сертификат, значение можно быть жестко заданным. Если по той или иной причине вы используете не такой GUID, как здесь, убедитесь, что GUID полностью состоит из строчных букв. На данный момент в инфраструктуре SharePoint идентификаторы GUID издателей сертификатов должны писаться в нижнем регистре.

  1. Добавьте приведенные ниже строки, чтобы зарегистрировать сертификат в качестве доверенного поставщика маркеров. Параметр -Name должен быть уникальным, поэтому в рабочей конфигурации GUID часто используется как часть имени (или имя целиком), но в данном контексте можно использовать понятное имя. Переключатель -IsTrustBroker гарантирует, что для всех разрабатываемых надстроек используется один и тот же сертификат. Команда iisreset необходима, чтобы поставщик маркеров был сразу зарегистрирован. Без нее может потребоваться до 24 часов, чтобы зарегистрировать нового поставщика.
  New-SPTrustedSecurityTokenIssuer -Name "High Trust Sample Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
  iisreset
  1. Как правило, SharePoint не принимает самозаверяющие сертификаты. Таким образом, если вы используете для отладки самозаверяющий сертификат, добавьте приведенные ниже строки, чтобы отключить обычное требование SharePoint касательно использования протокола HTTPS в вызовах от удаленных веб-приложений. В противном случае, если удаленное веб-приложение вызовет SharePoint с помощью самозаверяющего сертификата, будет возвращено сообщение 403 (forbidden). Мы отменим это действие в последующей процедуре. Отключение требования HTTPS означает, что запросы от удаленного веб-приложения в SharePoint не шифруются, но сертификат по-прежнему используется в качестве доверенного поставщика маркеров доступа (это его основное назначение в надстройках SharePoint с высоким уровнем доверия).
  $serviceConfig = Get-SPSecurityTokenServiceConfig
  $serviceConfig.AllowOAuthOverHttp = $true
  $serviceConfig.Update()

  1. Сохраните файл под именем HighTrustConfig-ForDebugOnly.ps1.

  2. Откройте командную консоль SharePoint от имени администратора и запустите файл с помощью следующей строки:

  ./HighTrustConfig-ForDebugOnly.ps1

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

В этом разделе описывается создание надстройки SharePoint с высоким уровнем доверия при помощи Visual Studio.

Примечание.

Как указано в разделе Необходимые условия для создания надстроек с высоким уровнем доверия, в этой статье предполагается, что вы умеете создавать надстройки SharePoint, размещаемые у поставщика. Дополнительные сведения см. в статье Знакомство с созданием надстроек SharePoint, размещаемых у поставщика.

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

  1. В Visual Studio выберите Файл>Создать>Проект.

  2. В мастере создания проекта разверните узел Visual C# или Visual Basic, а затем — узел Office/SharePoint.

  3. Выберите Надстройки, а затем создайте проект надстройки для SharePoint.

  4. Задайте для проекта имя HighTrustSampleApp.

  5. Сохраните проект в любой папке на свой выбор и нажмите кнопку ОК.

  6. Укажите полный URL-адрес сайта разработчика SharePoint. Пример: http://TestServer/sites/devsite/

  7. Выберите вариант Размещено у поставщика, а затем нажмите кнопку Далее.

  8. Если вам будет предложено указать тип веб-проекта, выберите Приложение веб-форм ASP.NET для рассматриваемого в этой статье примера, а затем нажмите кнопку Далее.

  9. В мастере откроется страница Настройка параметров проверки подлинности. Значения, добавляемые в этой форме, автоматически добавляются в файл web.config. В разделе Как требуется выполнять проверку подлинности надстройки? выберите пункт Использовать сертификат.

  10. Нажмите кнопку Обзор рядом с полем Расположение сертификата и перейдите к расположению созданного самозаверяющего сертификата (PFX-файла) — C:\Certs. Значением в этом поле должен быть полный путь C:\Certs\HighTrustSampleCert.pfx.

  11. Введите пароль для этого сертификата в поле Пароль. В данном случае используется пароль password.

  12. Введите ИД поставщика (11111111-1111-1111-1111-111111111111) в поле Идентификатор поставщика.

  13. Нажмите кнопку Готово. Основная часть операций по настройке совершается при открытии решения. В решении Visual Studio создаются два проекта: один для надстройки SharePoint, а другой — для веб-приложения ASP.NET.

Запуск и отладка надстройки

  1. Инструменты разработчика Office для Visual Studio автоматически создают файлы default.aspx и default.aspx.cs при создании проекта ASP.NET. Созданный код получает имя хост-сайта SharePoint и выводит его на странице по умолчанию для удаленного веб-приложения. Точные разметка и код в этих файлах зависят от версии инструментов. В этой статье файлы default.aspx и default.aspx.cs используются без изменений.

  2. Чтобы тестировать надстройку SharePoint и ее удаленное веб-приложение, нажмите клавишу F5 в Visual Studio. Веб-приложение будет развернуто в IIS Express по адресу localhost. Надстройка SharePoint будет установлена на целевом веб-сайте SharePoint. SharePoint предложит вам предоставить разрешения, запрашиваемые надстройкой SharePoint. Некоторые версии инструментов Visual Studio Office Developer Tools автоматически запускают надстройку. В других открывается страница Контент сайта на целевом веб-сайте SharePoint, где вы увидите новую надстройку.

Запустите надстройку, если она не запустилась автоматически. В удаленном веб-приложении откроется страница, заданная в качестве начальной в файле AppManifest.xml, — Default.aspx. Надстройка должна выглядеть примерно так:

Пример приложения, получающего название веб-сайта

Полная отладка с доменным или коммерческим сертификатом

Созданный ранее скрипт Windows PowerShell отключил обычное требование SharePoint о том, что удаленные веб-приложения используют протокол HTTPS для доступа к SharePoint. Работа с отключенным ПРОТОКОЛом HTTPS может привести к тому, что вы, как разработчик, пропустите некоторые проблемы при создании надстройки, которые могут возникнуть во время рабочего развертывания, где требуется ПРОТОКОЛ HTTPS. Соответственно, не следует считать этапы разработки и отладки завершенными, пока не будет заменен тестовый сертификат выданным доменом или коммерческим сертификатом, а затем повторно протестировать надстройку с включенным требованием HTTPS.

Получив новый сертификат, необходимо добавить к нему пароль, если он еще не задан. В рабочей среде следует использовать надежный пароль, но для отладки надстройки SharePoint подойдет любой. Сертификат должен быть представлен в двух форматах: PFX и CER. Если он не был получен в формате PFX, его можно преобразовать с помощью служебной программы. Если у вас есть PFX-файл, вы можете импортировать его в IIS и экспортировать CER-файл, как описано в предыдущей процедуре.

Импорт нового сертификата

  1. Поместите PFX-файл в папку C:\Certs на сервере SharePoint. Для целей этой статьи предполагается, что файл называется MyCert.pfx. Замените "MyCert" во всех этих инструкциях на фактическое имя сертификата.

  2. В диспетчере IIS выберите узел Имя сервера в представлении в виде дерева слева.

  3. Дважды щелкните значок Сертификаты сервера.

  4. Выберите пункт Импорт в области Действия справа.

  5. В диалоговом окне Импорт сертификата нажмите кнопку "Обзор" и откройте файл C:\Certs\ MyCert.pfx, а затем введите пароль сертификата.

  6. Убедитесь, что параметр Разрешить экспорт этого сертификата включен, и нажмите кнопку ОК.

  7. В списке Сертификаты сервера щелкните сертификат правой кнопкой мыши и выберите пункт Экспорт.

  8. Экспортируйте файл в папку C:\Certs и укажите пароль для него.

  9. Если тестовая установка SharePoint не находится на том же компьютере, где работает Visual Studio, переместите файл MyCert.pfx в папку C:\Certs на компьютере Visual Studio.

  10. В представлении Сертификаты сервера дважды щелкните MyCert, чтобы увидеть сведения о сертификате.

  11. На вкладке Сведения нажмите кнопку Копировать в файл, чтобы запустить мастер экспорта сертификатов, а затем нажмите кнопку Далее.

  12. Оставьте значение по умолчанию (Нет, не экспортировать закрытый ключ) и нажмите кнопку Далее.

  13. Используйте значения по умолчанию. Нажмите кнопку Далее.

  14. Нажмите кнопку Обзор, перейдите к папке C:\Certs, задайте для сертификата имя MyCert и нажмите кнопку Сохранить. Сертификат будет сохранен в виде CER-файла.

  15. Нажмите кнопку Далее.

  16. Нажмите кнопку Готово.

Настройка SharePoint на использование нового сертификата

  1. Откройте файл HighTrustConfig-ForDebugOnly.ps1 для редактирования и внесите следующие изменения:

  • Замените оба вхождения имени HighTrustSampleCert на MyCert.

  • Замените идентификатор конкретного поставщика — 11111111-1111-1111-1111-111111111111 — на 22222222-2222-2222-2222-222222222222.

  • Замените имя High Trust Sample Cert на My Cert или другое, более понятное имя.

  • В строке $serviceConfig.AllowOAuthOverHttp = $true замените true на false. При этом использование HTTPS снова станет обязательным.

  1. Сохраните файл.

  2. Откройте командную консоль SharePoint от имени администратора и запустите файл с помощью следующей строки:

  ./HighTrustConfig-ForDebugOnly.ps1

Изменение конфигурации удаленного веб-приложения

  1. В Visual Studio откройте файл web.config из проекта веб-приложения и внесите следующие изменения:

  • В ключе ClientSigningCertificatePath замените C:\Certs\HighTrustSampleCert.pfx на C:\Certs\<MyCert>.pfx.

  • Замените значение ключа ClientSigningCertificatePassword на фактический пароль сертификата.

  • Замените значение ключа IssuerId на 22222222-2222-2222-2222-222222222222.

  1. Нажмите клавишу F5 для отладки надстройки.

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

Каково назначение файлов TokenHelper и SharePointContext?

Инструменты разработчика Office для Visual Studio включают файл TokenHelper.cs (или TokenHelper.vb) в удаленное веб-приложение. Некоторые версии этих инструментов также включают файл SharePointContext.cs (или SharePointContext.vb).

Код в этих файлах делает следующее:

  • Настраивает .NET на доверие сертификатам при выполнении сетевых вызовов.

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

  • Получает сертификат службы токенов безопасности SharePoint (STS).

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

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

При отладке Visual Studio с помощью клавиши F5 инструменты Microsoft Visual Studio Office Developer Tools используют проверку подлинности Windows, а два созданных файла используют удостоверение Windows пользователя, запускающего надстройку для создания маркера доступа. Если вы хотите использовать два созданных файла без изменений, то после публикации надстройки необходимо настроить удаленное веб-приложение в диспетчере IIS на использование проверки подлинности Windows.

Если надстройка не будет использовать проверку подлинности Windows в рабочей среде, то необходимо изменить созданные файлы кода, TokenHelper и/или SharePointContext, чтобы использовалась другая система проверки подлинности. Эти файлы также следует изменить, если удаленное веб-приложение получает доступ к SharePoint в удостоверении, отличном от пользователя, запустившего надстройку SharePoint. Наконец, если удаленное веб-приложение создано на PHP, node.js, Java или другой платформе, отличной от ASP.NET, то код должен получить ИД пользователя от используемой системы проверки подлинности, а затем добавить этот идентификатор в создаваемый маркер доступа.

См. также