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

Важно!

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

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

Важно!

Служба контроля доступа Azure (ACS), которая входит в состав Azure Active Directory (Azure AD), будет упразднена 7 ноября 2018 г. Это не повлияет на модель надстроек SharePoint, использующую имя узла https://accounts.accesscontrol.windows.net (на который также не влияет это прекращение работы службы). Дополнительные сведения см. в статье Влияние упразднения службы контроля доступа Azure на надстройки SharePoint.

В зависимости от структуры надстройки используются разные потоки, но все они включают по крайней мере следующие два типа маркеров:

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

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

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

Маркеры доступа

В системе авторизации с низким уровнем доверия маркеры доступа создаются в службе Azure ACS и отправляются удаленному компоненту надстройки SharePoint. (На момент написания этой статьи срок действия маркеров доступа для SharePoint, выдаваемых службой ACS, составлял 12 часов, но он может измениться). Код надстройки SharePoint должен выполнять следующие основные действия:

• Запрос маркера доступа из Azure ACS. В зависимости от используемого потока OAuth для отправки запроса надстройка использует код авторизации или сведения, извлеченные из маркера контекста.
• Включение маркера доступа к каждый HTTP-запрос к SharePoint. Маркер добавляется в качестве заголовка Authorization для запроса. Значением заголовка является слово Bearer, за которым следует пробел, а затем — маркер доступа в кодировке Base 64.
• Кэширование маркера доступа для повторного использования в последующих запросах (необязательно, но рекомендовано).
• Пересылка маркера доступа в серверные системы, чтобы они могли получать прямой доступ к SharePoint (необязательно).

Эти задачи должен выполнять код на стороне сервера. Если вы используете управляемый код, то пример кода для некоторых из этих задач содержится в файлах SharePointContext и TokenHelper (с расширением CS или VB), которые входят в состав инструментов разработчика Microsoft Office для Visual Studio. Пример кода PHP, выполняющего некоторые из этих задач, см. в статье MSDN: Знакомство с REST-интерфейсом SharePoint 2013 и его использование.

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

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

• в состоянии сеанса;
• в состоянии приложения;
• в службе кэширования Windows Server AppFabric или ее эквиваленте в операционных системах сторонних разработчиков (не Майкрософт);
• в службе кэширования Microsoft Azure или ее эквиваленте в облачных службах, отличных от облачных служб Майкрософт;
• в базе данных;
• в системе memcached.

Примечание.

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

В большинстве случаев достаточно кэшировать маркер доступа в состоянии сеанса. Если удаленное веб-приложение обращается к другим службам, используюющим OAuth (в дополнение к SharePoint), и кэширование различных маркеров доступа в состоянии сеанса, обязательно используйте для маркеров отдельные ключи кэша. например, вместо "AccessToken" используйте "SharePoint_AccessToken", "Facebook_AccessToken", "SAP_Gateway_AccessToken" и т. д. (Если вы не используете кэширование состояния сеанса или другой способ кэширования с автоматическим разделением кэша разных пользователей, то необходимо связать ключи с пользователями).

Если приложение получает доступ к нескольким фермам или веб-клиентам SharePoint, то вы можете использовать домен SharePoint в составе основного ключа кэширования приложения (SharePoint<mydomain>.sharepoint.com_AccessToken) или область фермы или клиента (SharePoint<realmGUID>_AccessToken). Оба эти значения можно считывать из маркера доступа. (Чтобы считывать маркер, код должен отменить кодировку Base 64. В управляемом коде файл TokenHelper.cs или VB содержит пример кода для этой цели, в котором используются классы из пространств имен Microsoft.IdentityModel.S2S.Token и System.IdentityModel.Token .) Существует еще один вариант, если приложение использует поток маркера контекста, как описано в следующем абзаце.

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

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

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

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

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

Предупреждение

Из соображений безопасности не рекомендуем хранить маркер доступа в файле cookie. Лучше избегать передачи маркера доступа через браузер.

Пересылка маркера доступа во внутренние системы

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

Код в этих системах должен обрабатывать просроченные маркеры доступа и отправлять запрос на получение нового маркера родительскому веб-приложению, зарегистрированному в ACS (см. Обработка просроченных маркеров доступа). Эту методику следует использовать только для собственных внутренних серверов приложения, а не для внешних веб-служб. Кроме того, при ее применении лучше, чтобы при разработке внутренних служб по мере возможности предусматривалось использование ими вызовов только для надстроек.

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

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

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

Примеры маркеров доступа для систем авторизации с низким уровнем доверия

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

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

Ниже приведен раскодированный пример маркера доступа для пользователя и надстройки, созданного службой контроля доступа для отправки вызовов среде SharePoint с помощью политики для пользователей и надстроек. Пробел добавлен для удобочитаемости. Маркер соответствует протоколу JSON Web Token. Объект, представленный нотацией объектов JavaScript (JSON), в маркере называется набором утверждений (в таблице 1 вы найдете подробные сведения о свойствах набора утверждений).

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

{
 "aud": "00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss": "00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf": 1377549246,
 "exp": 1377592446,
 "nameid": "2303000085ff9abc",
 "actor": "964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73",
 "identityprovider": "urn:federation:microsoftonline"
}

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

Утверждение	Описание	Соответствующее значение в примере маркера доступа
aud	Сокращение от "audience" (аудитория, то есть субъект, для которого предназначен маркер). Используется формат audience principal ID/SharePoint domain@SharePoint realm, где ИД субъекта аудитории — это постоянный ИД субъекта безопасности для SharePoint (см. константы субъектов для приложений в продуктах корпорации Майкрософт). Область SharePoint — это GUID клиента SharePoint Online или локальной фермы SharePoint, для доступа к которым используется маркер доступа. Этот GUID служит в качестве ИД области для издателя маркера (в данном случае — Azure ACS).	00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss	Сокращение от слова "issuer" (издатель). Представляет субъекта, создавшего маркер. Используется формат Issuer GUID@SharePoint realm GUID. В системе авторизации с низким уровнем доверия издателем является служба Azure ACS со следующим GUID: 00000001-0000-0000-c000-000000000000.	00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf	Сокращение от "not before" (не ранее). Представляет время, с которого начинается срок действия маркера (в секундах, начиная с 1 января 1970 г). По умолчанию оно соответствует моменту создания маркера (см. раздел Значения времени в формате JWT).	1377549246
exp	Сокращение от "expiration" (истечение срока действия). Представляет время окончания срока действия для маркера. Значение по умолчанию составляет 12 часов после времени nbf (см. раздел Значения времени в формате JWT).	1377592446
nameid	Уникальный идентификатор пользователя, которому выдан маркер. Формат зависит от поставщика удостоверения. В этом примере поставщиком является Microsoft Online, но если бы это была служба Active Directory, ИД выглядел бы так: s-1-5-21-2127521184-1604012920-1887927527-415149.	2303000085ff9abc
actor	Субъект, запрашивающий доступ к ферме или клиенту SharePoint. Представлен в формате Client ID of Application@SharePoint realm.	964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73
identityprovider	Уникальное имя поставщика удостоверений, зарегистрированное в Администрации адресного пространства Интернет (IANA). Как правило, для надстроек, установленных в SharePoint Online, используется такое же значение, как в этом примере. Как правило, для надстроек, установленных на локальной ферме, это локальный поставщик удостоверений, например urn:office:idp:activedirectory.	urn:federation:microsoftonline

Политика только для надстроек

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

{
 "aud":"00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf":1403304705,
 "exp":1403347905,
 "nameid":"c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73",
 "sub":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
 "oid":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
 "trustedfordelegation":"false",
 "identityprovider":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73"
}

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

Утверждение	Описание	Соответствующее значение в примере маркера доступа
aud	См. маркер для пользователя и надстройки в таблице 1.	00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss	См. маркер для пользователя и надстройки в таблице 1.	00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf	См. маркер для пользователя и надстройки в таблице 1.	1403304705
exp	См. маркер для пользователя и надстройки в таблице 1.	1403347905
nameid	Уникальный идентификатор надстройки, а не пользователя, так как идентификатор пользователя не имеет значения в политике только для надстройки. Представлен в формате client ID@SharePoint realm.	c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73
sub	Сокращение от "subject" (субъект). Это субъект маркера, запрашивающий доступ к SharePoint. В данном случае это удаленное веб-приложение. В качестве значения используется ИД объекта. См. утверждение oid.	1d47ac31-498b-4988-8aac-85fc9bd2e1ce
oid	Сокращение выражения "ИД объекта". Это ИД объекта в службе Azure Active Directory для удаленного веб-приложения. В маркере доступа только для надстроек значение ИД субъекта и объекта совпадают.	1d47ac31-498b-4988-8aac-85fc9bd2e1ce
trustedfordelegation	Логическое значение, определяющее, может ли SharePoint доверять надстройке SharePoint аутентификацию и авторизацию пользователя. В вызовах только для надстроек это значение равно "false", так как личность пользователя не имеет значения.	false
identityprovider	Уникальное имя поставщика удостоверений. Так как предоставляется идентификатор надстройки, а не пользователя, поставщиком удостоверений является ACS. Представлено в формате ACS GUID@SharePoint realm.	00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73

Токены контекста

Токен контекста используется только в потоке токена контекста для систем авторизации с низким уровнем доверия. При запуске надстройки SharePoint отправляет службе контроля доступа Azure запрос на создание токена контекста, который SharePoint затем передает удаленному компоненту надстройки SharePoint. Токен передается в виде скрытого параметра формы SPAppToken в запросе от SharePoint на получение начальной страницы удаленного компонента. Токен подписывается секретом клиента, известным только службе контроля доступа и надстройке SharePoint.

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

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

• Проверка маркера контекста с помощью секрета клиента надстройки.
• Кэширование маркера контекста или извлечение и отдельное кэширование маркера обновления и некоторых других элементов из него.
• Использование маркера обновления и других сведений для запроса маркера доступа в службе контроля доступа и последующего его кэширования.
• Кэширование CacheKey на основе маркера контекста.

Важно!

Первые две задачи должны выполняться до того, как пользователь перейдет на другую страницу или обновит текущую. В противном случае токен будет потерян. Например, в приложении веб-форм ASP.NET рекомендуем выполнять эти задачи в методе Page_Load (в условном блоке кода, выполняемом только в том случае, если запрос не отправлен обратно). В приложении ASP.NET MVC рекомендуем выполнять эти задачи в методе контроллера по умолчанию.

Если вы используете управляемый код, то пример кода для некоторых из этих задач представлен в файлах SharePointContext и TokenHelper (с расширением CS или VB), которые входят в состав инструментов разработчика Microsoft Office для Visual Studio. Вам нужно только выполнить простые вызовы членов класса TokenHelper. Например, ваш код может справиться с первой задачей с помощью такой одной строки:

SharePointContextToken contextToken =
    TokenHelper.ReadAndValidateContextToken(contextTokenString,
    Request.Url.Authority);

Кэширование маркера контекста или его частей

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

Важно!

Напомним еще раз, так как это очень важно: не используйте кэширование на стороне клиента для маркера доступа. Его можно безопасно использовать только для маркера контекста.

Вам доступны те же варианты кэширования на стороне сервера, которые были перечислены ранее для маркера доступа. На стороне клиента это может быть cookie-файл или скрытое поле формы на HTML-странице. Еще один вариант — хранить токен контекста в кэше сеанса, а полученный из него CacheKey — в клиенте.

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

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

Общие сведения о ключе кэша

Ключ кэша — это непрозрачная строка, уникальная для определенного сочетания пользователя, поставщика имен, надстройки и фермы SharePoint или клиента SharePoint Online. Перед шифрованием он представлен в приведенном ниже формате, где Realm — это GUID локальной фермы SharePoint или клиента SharePoint Online.

UserNameId + "," + UserNameIdIssuer + "," + ApplicationId + "," + Realm

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

KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=

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

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

Третий вариант (если вы используете в качестве кэша базу данных) — использовать таблицу со столбцом CacheKey и дополнительными столбцами для кэшированных элементов (AccessToken, ContextToken и т. д.).

Конечно, приложение не обязано использовать один кэш для всех операций кэширования. Обычно маркер доступа кэшируют в кэше сеанса, маркер контекста (или маркер обновления из него) — в базе данных, а ключ CacheKey — в файле cookie.

Получение маркера доступа с помощью маркера контекста

Чтобы получить маркер доступа, приложение отправляет запрос напрямую в службу контроля доступа. Запрос включает три части данных, извлеченные из маркера контекста, а также другую информацию:

• маркер обновления;
• GUID субъекта приложения в SharePoint;
• GUID области фермы SharePoint или клиента SharePoint Online, доступ к которым запрашивает надстройка.

Файл TokenHelper (с расширением CS или VB) содержит код, который создает этот запрос. Пример кода PHP, который делает это, см. в статье SharePoint: выполнение операций с библиотекой документов SharePoint с сайта PHP.

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

Получение нового токена контекста

Если вам нужен новый токен контекста (как правило, это вызвано тем, что истек срок действия включенного в него маркера обновления), код может получить его, перенаправив браузер на специальную страницу (AppRedirect.aspx) любого веб-сайта SharePoint. К URL-адресу этой страницы необходимо добавить два параметра запроса:

• client_id. Идентификатор клиента надстройки SharePoint.
• redirect_uri: универсальный код ресурса (URI), к которому требуется перенаправить браузер после получения нового маркера контекста. SharePoint будет ОТПРАВЛЯТЬ маркер контекста в этот URI. Как правило, это та же страница, метод контроллера или метод веб-службы, которые запрашивали новый маркер контекста. Значение должно быть закодировано по URL-адресу.

Структура URL-адреса:

https://<SharePointDomain> /_layouts/15/appredirect.aspx?client_id=<app_client_GUID> &amp;redirect_uri=<URL-encoded_redirect_URI>

Пример запроса в ASP.NET с использованием файла TokenHelper:

Response.Redirect(TokenHelper.GetAppContextTokenRequestUrl(sharePointUrl, Server.UrlEncode(Request.Url.ToString())));

Пример токена контекста

Далее приводится пример токена контекста. Небольшой объект в нотации JavaScript (JSON) в начале файла содержит метаданные токена. Эти свойства аналогичны свойствам маркеров доступа (см. выше). Значение свойства alg — это название алгоритма, используемого для создания подписи, которую ACS добавляет к токену. В таблице 3 вы найдете подробные сведения о свойствах полезных данных токена. Все значения должны быть представлены в нижнем регистре. Пробел добавлен для удобочитаемости.

{"typ":"JWT","alg":"HS256"}
.
{
 "aud":"a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf":"1335822895",
 "exp":"1335866095",
 "appctxsender":"00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "appctx":"{
            \"CacheKey\":\"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\",
            \"SecurityTokenServiceUri\":\"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
           }",
 "refreshtoken":"IAAAAC1Lv5w0OrcFAmJx0xk6aaBdhgsw3VPnPzNEDAWypTHtCYytZ2/dBBUKj+HLK8YB3IUCUfDxYpAque
NHKtgs4rYJJ5AegQpNMOJR1yYK8ngivQx0oetj7aSPuGVb+k6at6G0Kx5LZ5vhxkAq8iUSwu8p4L2cvNMzDF1mDKfMivqxgrIZkr2nbf9as0SJFL6VG5hZnDE4HKq
xJnejSW3umatKM4fsfY1MClVCxrkXb2EQ8H/TmwaJc388YW063GEVUS/3BTSgSIRBKQUmXJuJ6BZY7WTm84LaGrx3mIjnUTM/jnqPoPG55JbCC9sS/MeGNPtzPPCDg
6Vv7dVhQ1Dq5Y3fQ65e9LpJ580jCgzYYvpIFT+Wx5V+17mjY2T8wug04K2ts87Znsr+GfFCorf7NS/lj5HjoxRAQ2tva/8dwguSLwxcUwi/Q9MbpR0NNtlpwVazqi9O
hJ4Df7gVhUDdJ0Dtc6aFCPbl5ZLDDRs42xK2",
 "isbrowserhostedapp": "true"
}

Утверждения aud, iss, nbf и exp полностью идентичны соответствующим утверждениям в маркере доступа, описанным в таблице 1.

Утверждения appctxsender, appctx, CacheKey, SecurityTokenServiceUri, refreshtoken и isbrowserhostedapp описываются в приведенной ниже таблице.

Табл. 3. Утверждения маркера контекста и сведения о них

Утверждение	Описание	Соответствующее значение в примере токена контекста
aud		a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss		00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf		1335822895
exp		1335866095
appctxsender	Сокращение от "application context sender" (отправитель контекста приложения). Представляет приложение, которое отправило токен контекста надстройке SharePoint. Представлено в формате GUID of principal@SharePoint realm, где GUID of principal — это постоянный ИД субъекта приложения (SharePoint, Exchange, Lync или Workflow).	00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
appctx	Сокращение выражения "контекст надстройки" Это объект JSON, который содержит элементы CacheKey и SecurityTokenServiceURI.	CacheKey:"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\", SecurityTokenServiceUri:"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
CacheKey	Уникальное значение, которое можно использовать в качестве ключа в кэше со структурой "ключ-значение" для хранения и получения маркера контекста. Его также можно использовать как значение столбца ключа в строке базы данных.	KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=
SecurityTokenServiceURI	URI службы, издавшей маркер.	https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2
refreshtoken	Маркер обновления для надстройки.	IAAAAC1Lv5w0OrcFAmJx0xk6???
isbrowserhostedapp	Поле Boolean, которое определяет, откуда поступил запрос в надстройку с маркером контекста: из браузера (true) или из удаленного приемника событий (false).	true

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

Если вы хотите ограничить доступ к удаленному компоненту, например службе WCF, пользователям SharePoint, код может просто проверить маркер контекста в HTTP-запросе. (Если вы используете управляемый код, можете просто вызвать метод TokenHelper.ReadAndValidateContextToken()).

Если требуется убедиться, что субъектом является SharePoint (а не Exchange, Lync или Workflow), то в коде можно проверить, начинается ли соответствующее утверждение в маркере с 00000003-0000-0ff1-ce00-000000000000. Если вы хотите выполнять дополнительные проверки, требующие обратного вызова SharePoint, например разрешать доступ только пользователям с определенной ролью в SharePoint, вы можете кэшировать значение, указывающее, что определенный пользователь уже прошел такую проверку (с помощью ключа CacheKey маркера контекста), чтобы не делать это несколько раз.

Маркеры обновления

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

Так как маркер доступа действует только несколько часов (на данный момент — 12), а пользователь получает новый при каждом запуске надстройки SharePoint, маркер обновления нужен только в следующих случаях:

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

• Структура надстройки дает пользователям возможность планировать доступ надстройки к SharePoint после окончания сеанса.

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

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

Если срок действия маркера обновления истек, то запрос к ACS на получение нового маркера доступа приведет к ошибке 401 Unauthorized. Надстройка должна реагировать на эту ошибку, получая новый маркер обновления и используя его для получения нового маркера доступа. (Так как маркер обновления шифруется, код не может проверять срок его действия перед использованием маркера).

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

Коды авторизации

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

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

Значения времени в формате JWT

Утверждения nbf и exp представлены в формате, определенном спецификацией JWT. Эти значения представляют собой количество секунд с 1 января 1970 г. На C# эти значения можно преобразовать с помощью приведенного ниже кода, где jWTTimeStamp — это значение из токена, например 1335822895.

DateTime exp = new DateTime(1970,1,1).AddSeconds(jWTTimeStamp);

Устранение неполадок при обработке маркеров

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

См. также

• Образец кода SharePoint: удаленная надстройка Hello World с использованием CSOM
• Пример пакета надстроек SharePoint
• Создание надстроек SharePoint, использующих авторизацию с низким уровнем доверия
• Авторизация и аутентификация надстроек SharePoint