У більшості сценаріїв ви не зможете використовувати прості терміни, наприклад AccessToken, як ключ кешування, так як надбудові необхідно зберігати унікальні маркери для кожного користувача і ферми або області клієнта SharePoint. Якщо надбудова використовує потік маркера контексту. SharePoint надає спеціальний ключ CacheKey. який можна використовувати, щоб розрізняти кешированниє маркери. У цьому розділі описані проблеми і способи їх вирішення, в разі якщо надбудова не використовує потік маркера контексту.
Кешування маркера доступу в стані сеансу підходить для більшості сценаріїв. Якщо віддалене веб-додаток отримує доступ до інших служб, які використовують протокол OAuth (на додаток до SharePoint), і кешируєт різні маркери доступу в стані сеансу, використовуйте різні ключі кеша для маркерів. Наприклад, замість AccessToken використовуйте SharePoint_AccessToken, Facebook_AccessToken, SAP_Gateway_AccessToken. (Якщо ви не використовуєте стан сеансу або інший спосіб кешування, який автоматично розділяє кеші всіх користувачів, знадобиться також співвіднести ключі з кожним користувачем.)
Додаток може отримувати доступ до кількох ферм або областям клієнта SharePoint. У цьому випадку використовуйте домен SharePoint як частина первинного ключа кешування додатка ( "SharePoint_<мой_домен> .sharepoint.com_AccessToken ") або область ферми або клієнта (" SharePoint_
Якщо межсеансовий кеш, який використовуєте ви, також використовують кілька додатків, ключі кеша потрібно співвіднести з додатками, користувачами і областями SharePoint. Ключ кешу, наданий в маркері контексту, унікальний для кожної програми, користувача і області SharePoint.
Нарешті, якщо ваша надбудова виконує виклики SharePoint як з перевіркою дозволів додатки, так і з перевіркою дозволів користувача і надбудови, у нього буде два різних маркера доступу. Тому знадобляться різні ключі кеша. Визначивши основний ключ кешу, просто додайте до нього "_add-in-only" (тільки надбудова) або "_add-in + user" (надбудова і користувач).
Зберігати маркер доступу в файлі cookie небезпечно. Краще уникати передачі маркера доступу через браузер.
Передача маркера доступу в серверні системи
Обробка маркерів доступу з вичерпаним терміном дії
Приклади маркерів доступу
Політика для користувача і надбудови
Область SharePoint - GUID області клієнта SharePoint Online або локальної ферми SharePoint, для доступу до якого використовується маркер доступу. Цей GUID виконує роль ідентифікатора області для видавця маркера, в цьому випадку - служби Azure ACS.
Скорочення від "issuer" (видавець). Являє суб'єкта, який створив маркер. Формат: GUID видавця @ GUID області SharePoint.
Унікальний ідентифікатор користувача, для якого випущений маркер. Формат залежить від постачальника посвідчень. У цьому прикладі постачальник - Microsoft Online. Якби це була служба Active Directory, ВД виглядав би так: "s-1-5-21-2127521184-1604012920-1887927527-415149".
Суб'єкт, який пробує отримати доступ до ферми або області клієнта SharePoint. Формат: ВД клієнта додатки @ область SharePoint.
Унікальне ім'я постачальника посвідчень, зареєстроване в організації IANA (Internet Assigned Numbers Authority).
Для надбудов, встановлених в SharePoint Online, значення зазвичай відповідає зазначеному в цьому прикладі.
Для надбудов, встановлених на локальній фермі, це звичайно локальний постачальник посвідчень, наприклад "urn: office: idp: activedirectory".
Політика тільки для надбудови
Перевірка маркера контексту за допомогою секрету клієнта надбудови.
Кешування маркера контексту або витяг з нього маркера поновлення або деяких інших елементів і їх окреме кешування.
Використання маркера поновлення та інших даних, щоб запросити маркер доступу у служби контролю доступу, а потім його кешувати.
Кешування ключа CacheKey з маркера контексту.
Перші два завдання важливо виконати, перш ніж користувач перейде на іншу сторінку або оновить поточну, інакше маркер буде втрачено. Наприклад, в додатку веб-форм ASP.NET ці завдання слід виконувати за допомогою методу Page_Load (в коді умови представлений блоком, який виконується, якщо запит не передається назад). У додатку ASP.NET MVC ці завдання слід виконувати за допомогою методу контролера за замовчуванням.
Якщо ви використовуєте керований код, приклад коду для деяких завдань представлений в файлах SharePointContext і TokenHelper (з розширенням CS або VB), які входять в Інструменти розробника Microsoft Office для Visual Studio. Вам потрібно лише виконати прості виклики членів класу TokenHelper. Наприклад, ваш код може впоратися з першим завданням за допомогою такої одного рядка:
Кешування маркера контексту або його частин
Ви можете кешувати весь маркер контексту або тільки його частини в серверному або клієнтському сховище. Скажімо, включені в нього маркер поновлення і деякі інші елементи, за допомогою яких код отримує маркери доступу. Щоб було простіше, в цій статті передбачається, що ви кешіруете весь маркер контексту.
Нагадаємо ще раз, так як це дуже важливо: не використовуйте кешування на стороні клієнта для маркера доступу. Його можна використовувати тільки для маркера контексту.
Варіанти кешування на стороні сервера такі ж, як і перераховані вище для маркера доступу. Варіанти на стороні клієнта також включають файл cookie і приховане поле форми на HTML-сторінці. Крім того, можна зберігати маркер контексту в кеші сеансу, а ключ CacheKey. отриманий з нього, - на стороні клієнта.
Якщо додаток отримує доступ до SharePoint після завершення сеансу, неможливо використовувати ні кешування сеансу, ні кешування на стороні клієнта. Це пояснюється тим, що у додатку повинен бути доступ до маркера поновлення, на випадок якщо закінчиться термін дії вихідного маркера доступу при виконанні роботи після сеансу. У цьому сценарії потрібен стійкий (межсеансовий) кеш, який спільно використовують кілька користувачів, областей SharePoint або додатків. Тому код повинен використовувати ключі кешу, які розрізняють користувачів, області SharePoint і додатки, як описано вище в розділі Кешування маркера доступу. Для цього можна використовувати спеціальний ключ кешу з маркера контексту так само, як і для маркера доступу. (Див. Розділ Поняття про ключі кеша нижче.)
Поняття про ключі кеша
Ключ кешу - непрозора рядок, яка унікальна для комбінації користувача, видавця імені користувача, надбудови і ферми SharePoint або клієнта SharePoint Online. Нижче наведена його форма до шифрування, де область - це GUID локальної ферми SharePoint або області клієнта SharePoint Online.
ІД_імені_пользователя + "," + іздатель_ІД_імені_пользователя + "," + ІД_пріложенія + "," + область
Так як за допомогою одного ключа кеша додаток може кешувати кілька елементів в одному кеші, наприклад маркер доступу і маркер контексту, ключ кешу слід використовувати в якості основи. При необхідності до нього на початку або в кінці можна додавати певну рядок, наприклад AccessToken або ContextToken, щоб сформувати повний ключ кешу. Ще один варіант - створити клас з властивостями для різних елементів, які необхідно кешувати, а потім кешувати об'єкт такого типу. Є і третій варіант. на випадок якщо ви використовуєте базу даних як кеша. Він має на увазі використання таблиці зі стовпцем CacheKey і додатковими стовпцями для кешованих елементів (AccessToken, ContextToken і т. Д.).
Звичайно, додаток не повинно використовувати один кеш для всіх операцій кешування. Зазвичай маркер доступу кешують в кеші сеансу, маркер контексту (або маркер поновлення з нього) - в базі даних, а ключ CacheKey - в файлі cookie.
Отримання маркера доступу за допомогою маркера контексту
Щоб отримати маркер доступу, додаток відправляє запит безпосередньо в службу контролю доступу. Запит включає три частини даних, витягнуті з маркера контексту, а також іншу інформацію:
GUID суб'єкта додатки в SharePoint.
GUID ферми SharePoint або області клієнта SharePoint Online, до яких надбудова хоче отримати доступ.
Додаток може отримати область клієнта або ферми SharePoint в середовищі виконання замість її вилучення з маркера контексту. Якщо ви використовуєте керований код, для отримання області існує метод TokenHelper.GetRealmFromTargetUrl. Значення необхідно кешувати, щоб код не виконував повторний виклик по мережі для його отримання.
Отримання нового маркера контексту
client_id. Ідентифікатор клієнта Надбудова SharePoint.
Приклад маркера контексту
Твердження aud. iss. nbf і exp такі ж, як і в маркері доступу (наведені вище). Твердження appctxsender. appctx. CacheKey. SecurityTokenServiceUri. refreshtoken і isbrowserhostedapp описані в таблиці нижче.
Таблиця 3. Твердження маркера контексту і відомості про них
Обмеження доступу тільки для користувачів SharePoint за допомогою маркера контексту
Маркер поновлення включений в маркер контексту, який служба SharePoint публікує в веб-додатку при його запуску. Маркер поновлення зашифрований, і Надбудова SharePoint не може його розшифрувати. Код використовує його і інші дані для отримання нового маркера доступу після закінчення терміну дії поточного. З його допомогою також можна отримати перший маркер доступу в потоці маркера контексту. (Під час написання цієї статті тривалість існування маркера поновлення, випущеного службою контролю доступу для SharePoint, становила 6 місяців, але це могло змінитися.)
Так як маркер доступу діє тільки кілька годин (зараз - 12) і користувач отримує новий при кожному запуску Надбудова SharePoint в SharePoint, маркер поновлення потрібен тільки в таких сценаріях:
Користувачі відкрили тривалі сеанси надбудови, в яких вона виконує виклики SharePoint протягом декількох годин (більше 12) після запуску.
Дизайн надбудови дозволяє користувачам планувати її доступ до SharePoint після завершення сеансу.