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

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

  • Статья

Важно!

Эта статья целиком посвящена использованию маркеров доступа в системе авторизации с высоким уровнем доверия, а не системе ACS. Сведения о пользователе маркеров безопасности в системе ACS см. в статье Обработка маркеров безопасности в надстройках SharePoint с низким уровнем доверия, размещаемых у поставщика.

Надстройки SharePoint, использующие систему авторизации с высоким уровнем доверия для доступа к SharePoint, должны передавать маркер доступа (в формате JSON Web Token) среде SharePoint с каждым запросом на создание, чтение, обновление или удаление (CRUD). SharePoint проверяет маркер и обслуживает запрос.

В этой статье представлены сведения о том, как код создает и передает маркер доступа.

В системе авторизации с высоким уровнем доверия удаленный компонент надстройки SharePoint создает маркер доступа. Если удаленный компонент использует управляемый код на стороне сервера, то большая часть работы по созданию кода токенов выполняется автоматически в файлах SharePointContext.cs (или SharePointContext.vb) и TokenHelper.cs (или TokenHelper.vb), входящих в состав Visual Studio Office Developer Tools.

Так как пользователь надстройки SharePoint с высоким уровнем доверия работает в локальной среде SharePoint, скорее всего, он не против использовать ASP.NET, IIS и Windows Server в качестве стека для размещения удаленного компонента. Рекомендуем использовать этот стек, так как два создаваемых файла избавят вас от лишней работы, связанной с написанием кода и тестированием.

Если удаленный компонент должен использовать язык, не поддерживаемый платформой .NET, а удаленный компонент и ферма SharePoint подключены к Интернету, рекомендуем использовать систему авторизации с низким (а не высоким) уровнем доверия. В системе, использующей службу контроля доступа Microsoft Azure (ACS), созданием токенов занимается ACS, что также значительно упрощает вашу работу.

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

Обработка маркеров доступа

Примечание.

Читая эту статью, помните (особенно в том, что касается задач, которые должен выполнять код), что если вы используете управляемый код, то инструменты Microsoft Visual Studio Office Developer Tools добавляют к проекту каждой надстройки SharePoint два файла с кодом — SharePointContext.cs (или SharePointContext.vb) и TokenHelper.cs (или TokenHelper.vb), — автоматически выполняющих большую часть этих задач. Как правило, код для обработки токенов в приложении состоит из всего нескольких вызовов классов из этих файлов.

Сведения в этой статье призваны помочь разработчикам, не использующим управляемый код (и тем, кто занимается устранением проблем с токенами). Ссылки на библиотеки OAuth для множества языков и платформ представлены на странице OAuth 2.0 (прокрутите до раздела Client Libraries). Чтобы узнать больше, выполните поиск на сайте GitHub по запросам "OAuth 2" и "веб-маркер JSON" (без кавычек).

Код должен выполнять указанные ниже задачи.

  1. Создание маркера доступа. Подзадачи для создания токена зависят от того, какие вызовы удаленное веб-приложение отправляет среде SharePoint: "Только для надстроек", "Для пользователей и надстроек" или вызовы обоих типов. Дополнительные сведения см. в статье Типы политик авторизации надстроек в SharePoint.

    • Если надстройка отправляет вызовы "Для пользователей и надстроек", то создание маркера доступа включает указанные ниже подзадачи.

      1. Создание токена субъекта, который идентифицирует надстройку SharePoint и дает среде SharePoint указание делегировать проверку подлинности и авторизацию пользователей надстройке, а также кодирование этого токена в формате Base 64. В таблице 2 представлены подробные сведения об утверждениях и структуре токена субъекта. Подробные сведения о кодировании и подписании токена см. в разделе Кодирование и подписание маркеров.
      2. Подписание токена субъекта с помощью учетных данных из сертификата X.509, указанного в качестве доверенного для SharePoint администратором фермы SharePoint.
      3. Включение токена субъекта в маркер доступа.
      4. Добавление других необходимых утверждений в маркер доступа. В таблице 1 представлены подробные сведения об утверждениях и структуре маркера.

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

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

  2. Включите маркер доступа в каждый HTTP-запрос к SharePoint. Маркер добавляется в качестве заголовка Authorization для запроса. Значением заголовка является слово Bearer, за которым следует пробел, а затем — маркер доступа в кодировке Base 64.

  3. Необязательно: кэширование маркера доступа для повторного использования в последующих запросах.

Эти задачи должен выполнять код на стороне сервера. Если вы используете управляемый код, пример кода для некоторых из этих задач находится в файлах SharePointContext.cs (или .vb) и TokenHelper.cs (или .vb), создаваемых средствами разработчика Microsoft Office для Visual Studio.

Кэширование маркера доступа

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

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

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

В целом, вам могут потребоваться ключи кэша, основанные на ИД пользователя, ИД приложения, домене или области SharePoint либо на нескольких из этих значений. Рекомендуем использовать систему ключей кэша, подобную той, которая применяется в надстройках SharePoint, использующих систему авторизации с низким уровнем доверия. Дополнительные сведения см. в разделе Общие сведения о ключе кэша.

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

Обработка просроченных маркеров доступа

У маркера доступа есть срок действия. Код может задать любое время окончания этого срока. Если надстройка создает новый маркер доступа для каждого запроса, то каждому из них достаточно просуществовать до проверки средой SharePoint, то есть всего несколько секунд, если локальная сеть пользователя не занята. Вы можете задать срок действия в несколько лет, но даже в "полностью локальном" сценарии, на который рассчитаны надстройки с высоким уровнем доверия, существует опасность похищения маркеров доступа. Следовательно, рекомендуем задавать срок действия не дольше нескольких часов. Если вы работаете с управляемым кодом, то пример кода для создания маркера в файле TokenHelper.cs (или TokenHelper.vb) задает срок действия в 12 часов.

Если продолжительность сеанса работы пользователя с надстройкой SharePoint превысит срок действия кэшированного маркера доступа, то при первом запросе к SharePoint по истечении срока действия маркера возникнет ошибка 401 Unauthorized. Код должен реагировать на этот отклик. Кроме того, он может проверять срок действия маркера доступа перед его использованием. Код должен реагировать на просроченные маркеры доступа, создавая новый маркер доступа и повторяя неудачный запрос.

Структура маркеров доступа

Ниже приведен пример маркера доступа, созданного надстройкой SharePoint с высоким уровнем доверия. В частности, этот маркер был создан примером кода из файла TokenHelper.cs (или TokenHelper.vb), входящего в состав шаблона проекта "Надстройка SharePoint", созданного Visual Studio Office Developer Tools. Маркер раскодирован, а для наглядности добавлен пробел. Маркеры доступа, используемые в системе с высоким уровнем доверия, соответствуют протоколу проверки подлинности OAuth 2.0 (MS-SPS2SAUTH, профиль для SharePoint, также называемому протоколом "сервер-сервер", или S2S. Эти сведения призваны помочь разработчикам, использующим управляемый код, в отладке надстроек SharePoint с высоким уровнем доверия. Кроме того, представлены рекомендации по созданию маркеров.

Этот маркер доступа создается, если надстройка вызывает SharePoint с помощью политики "Для пользователей и надстроек". Если надстройка использует политику "Только для надстроек" и отправляет соответствующий вызов SharePoint, токен субъекта (рассматриваемый ниже дочерний токен маркера доступа "Для пользователей и надстроек") становится маркером доступа (без родительского токена).

Примечание.

Обратите внимание, что маркеры доступа с высоким уровнем доверия, создаваемые вашим кодом, отличаются от маркеров, создаваемых службой Azure ACS при использовании системы авторизации с низким уровнем доверия:

  • Для утверждения alg в заголовке задано значение none, так как маркер доступа в вызове "Для пользователей и надстроек" из надстройки с высоким уровнем доверия не подписан.
  • В данном примере в качестве URL-адреса надстройки в значении aud указан локальный сервер. Это нормально для системы с высоким уровнем доверия.
  • Утверждение identityprovider отсутствует, но указано утверждение nii (поставщик имен) с теми же значениями, что и в маркерах доступа из утверждения identityprovider, используемых в системе авторизации с низким уровнем доверия. Сведения об этом значении при использовании поставщика удостоверений на основе SAML см. в записях блога Стива Пешки (Steve Peschka) Безопасность в надстройках SharePoint (часть 8) и Использование надстроек SharePoint с сайтами SAML и FBA в SharePoint 2013.
  • Утверждение actor отсутствует, но есть утверждение actortoken, содержащее внутренний маркер в кодировке Base 64 с 12-часовым сроком действия.

У верхнего колонтитула есть два свойства. typ — это тип маркера. Код удаленного веб-приложения всегда должен задавать для этого параметра значение "JWT". alg — это алгоритм, используемый для подписания маркера. Так как внешний токен в коде вызова "Для пользователей и надстроек", выполняемом надстройкой с высоким уровнем доверия, не подписан, задайте для этого параметра значение none. В таблице 1 представлены сведения о значениях в основном тексте маркера доступа с высоким уровнем доверия.

{"typ":"JWT", "alg":"none"} 
.
{
 "aud":"00000003-0000-0ff1-ce00-000000000000/MarketingServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "iss":"c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "nbf":"1403212820",
 "exp":"1403256020",
 "nameid":"s-1-5-21-2127521184-1604012920-1887927527-2963467",
 "nii":"urn:office:idp:activedirectory",
 "actortoken":"6sMZhbw … [remainder of long base 64 string omitted] … "
}

В приведенной ниже таблице представлены рекомендации касательно того, какие свойства код должен включать в маркер доступа и какие значения для них задавать. Если вы используете управляемый код, то файлы SharePointContext.cs (или SharePointContext.vb) и TokenHelper.cs (или TokenHelper.vb) создают токены автоматически. Допустим, код совершает один вызов метода SharePointContext.CreateUserClientContextForSPHost. Тот, в свою очередь, вызывает методы из класса TokenHelper, которые создают маркер доступа. Этот маркер включается в каждый вызов, отправляемый среде SharePoint объектом контекста клиента SharePoint, который возвращает метод SharePointContext.CreateUserClientContextForSPHost.

Таблица 1. Утверждения с маркерами доступа, выдаваемыми приложением

Утверждение Описание Соответствующее значение в примере маркера доступа
aud Сокращение от "audience" (аудитория, то есть субъект, для которого предназначен маркер).

Используется следующий формат: ИД субъекта аудитории/полное доменное имя SharePoint@область SharePoint.

Субъектом аудитории для надстроек SharePoint всегда является 00000003-0000-0ff1-ce00-000000000000.

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

Определите область SharePoint с помощью командлета PowerShell Get-SPAuthenticationRealm на сервере SharePoint Server, а затем используйте его непосредственно в коде или сохраните в файле конфигурации, где код может его считывать, например в разделе app.Settings файла web.config.

Кроме того, код может динамически определять область SharePoint во время выполнения, отправляя запрос проверки подлинности в SharePoint. Пример того, как реализовать это в управляемом коде, см. в методе GetRealmFromTargetUrl из файла TokenHelper.cs (или TokenHelper.vb).		 00000003-0000-0ff1-ce00-000000000000/MarketingSharePointServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
iss Сокращение от слова "issuer" (поставщик). Представляет субъекта, создавшего маркер.

Используется следующий формат: GUID поставщика@GUID области SharePoint. В системе с высоким уровнем доверия поставщиком является сама надстройка, поэтому идентификатор клиента надстройки SharePoint обычно используется в качестве GUID издателя.

Все буквы в ИД поставщика должны быть строчными.		 c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
nbf Сокращение от "not before" (не ранее). Представляет время, с которого начинается срок действия маркера (в секундах с полуночи 1 января 1970 г). Код должен указывать в качестве значения время создания маркера. 1403212820
exp Сокращение от "expiration" (истечение срока действия). Означает время, когда истекает срок действия маркера, в секундах, после полуночи 1 января 1970 г. 1403256020
nameid Уникальный идентификатор пользователя, которому выдан маркер. Формат зависит от поставщика удостоверения. В данном примере поставщик — Active Directory. s-1-5-21-2127521184-1604012920-1887927527-2963467
nii Сокращение от "name identifier issuer" (издатель идентификатора имени). Уникальное имя поставщика удостоверений, как оно зарегистрировано в IANA. Для надстройки SharePoint с высоким уровнем доверия это обычно локальный поставщик удостоверений, например Active Directory, как в этом примере. urn:office:idp:activedirectory
actortoken Маркер JWT в кодировке Base 64, идентифицирующий надстройку SharePoint и указывающий SharePoint доверять надстройке независимо от того, какой пользователь запускает ее. См. ниже.

Ниже показан раскодированный actortoken. В начале файла находится небольшой объект заголовка, представленный в нотации объектов JavaScript (JSON). Он содержит метаданные маркера, включая его тип и используемый алгоритм подписания. Свойство x5t заголовка — это дайджест, полученный из отпечатка сертификата X.509, являющегося официальным поставщиком маркера. Чтобы составить это значение, код делает следующее:

  1. Получает массив байтов (не строку) с версией отпечатка сертификата. Это дайджест SHA-1 сертификата. В управляемом код это можно сделать с помощью метода GetCertHash(). Вам потребуется его аналог в используемом вами языке.

  2. Кодирует байтовый массив с использованием кодировки Base 64 для URL-адресов.

  3. Задать для закодированного дайджеста значение x5t.

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

{"typ":"JWT","alg":"RS256","x5t":"7MjK99QvkVdwz6UrKldx8AG7ydM"}
.
{
 "aud":"00000003-0000-0ff1-ce00-000000000000/MarketingServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "iss":"11111111-1111-1111-1111-111111111111@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "nbf":"1403212820",
 "exp":"1403256020",
 "nameid":"c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "trustedfordelegation":"true"
}

Примечание.

Если надстройка с высоким уровнем доверия использует политику "Только для надстроек" и совершает вызов SharePoint "Только для надстроек", то приведенный здесь маркер фактически будет маркером доступа. Внешний маркер не используется. Кроме того, отсутствует утверждение trustedfordelegation, так как разрешения пользователя не имеют значения в вызовах "Только для надстроек".

Таблица 2. Утверждения actortoken, выданные сертификатом

Утверждение Описание Соответствующее значение в примере маркера доступа
aud Аналогично родительскому маркеру доступа. 00000003-0000-0ff1-ce00-000000000000/MarketingSharePointServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
iss Такое же значение, как и в родительском маркере доступа, но GUID поставщика не совпадает с идентификатором клиента для веб-приложения. Это GUID сертификата.

Несмотря на то что токен субъекта создается в коде приложения, его поставщиком считается сертификат.

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

Администратор также может использовать разные сертификаты для разных надстроек SharePoint. В этом случае для сертификатов используются различные случайно сгенерированные GUID.

Все буквы в GUID издателя должны быть строчными.		 11111111-1111-1111-1111-111111111111@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
nbf Такое же значение, как и в родительском маркере доступа. Такое же значение, как и в родительском маркере доступа.
exp Такое же значение, как и в родительском маркере доступа. Такое же значение, как и в родительском маркере доступа.
nameid Уникальный идентификатор надстройки SharePoint, являющейся "субъектом" в системе с высоким уровнем доверия. Используется следующий формат: ИД_клиента@область_SharePoint. c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
trustedfordelegation Логическое значение, определяющее, может ли SharePoint доверять надстройке SharePoint авторизацию и аутентификацию пользователя. В системах с высоким уровнем доверия для этого утверждения обычно задается значение true. Не включайте это утверждение в вызовы "Только для надстроек" в системе с высоким уровнем доверия. true

Кодирование и подписание маркеров

После того как код добавит все свойства и значения в заголовок и основной текст объектов JSON, он должен закодировать и объединить их в JSON Web Token (JWT), а затем подписать. Ниже описаны этапы этого процесса.

  1. Закодировать заголовок с помощью кодировки URL-адреса Base 64.
  2. Закодировать полезную нагрузку с помощью кодировки URL-адреса Base 64.
  3. Объединить закодированное тело после закодированного заголовка, указав между ними символ ".". Это JWT.
  4. Создать подпись SHA256, используя JWT и закрытый ключ сертификата.
  5. Закодировать подпись с помощью кодировки URL-адреса Base 64.
  6. Добавить подпись после JWT, разделив их символом ".".

Токен субъекта, используемого в вызове "Только для надстроек", служит в качестве маркера доступа. Внешний маркер не используется. Для маркера доступа при вызове "Для пользователей и надстроек" с помощью вышеописанных действий создается токен субъекта, который затем вставляется в текст маркера доступа как значение свойства actortoken. Затем полный маркер доступа кодируется и создается с помощью трех вышеописанных действий, но не подписывается, поэтому остальные действия не применяются ко внешнему маркеру.

Устранение неполадок, связанных с маркерами доступа

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

См. также