Включение единого входа (SSO) в надстройке Office

Статья
01/22/2024

Пользователи входят в Office, используя личную учетную запись Майкрософт, Microsoft 365 для образования или рабочую учетную запись. Воспользуйтесь этим преимуществом и используйте единый вход (SSO) для проверки подлинности и авторизации пользователя в надстройке, не требуя повторного входа в систему.

Изображение, иллюстрирующее процесс входа в надстройку.

Принцип работы единого входа во время выполнения

На приведенной ниже схеме показано, как работает единый вход. Синие элементы представляют Office или платформу удостоверений Майкрософт. Серые элементы представляют код, который вы пишете, и включают клиентский код (область задач) и серверный код надстройки.

Схема единого входа.

Код JavaScript надстройки вызывает Office.js API getAccessToken. Если пользователь уже вошел в Office, ведущее приложение Office возвращает маркер доступа с утверждениями пользователя, вошедшего в систему.
Если пользователь не вошел в систему, ведущее приложение Office открывает диалоговое окно для входа пользователя. Office перенаправляет на платформу удостоверений Майкрософт для завершения процесса входа.
Если текущий пользователь использует надстройку впервые, ему будет предложено дать согласие.
Ведущее приложение Office запрашивает маркер доступа с платформы удостоверений Майкрософт для текущего пользователя.
Платформа удостоверений Майкрософт возвращает маркер доступа в Office. Office поместит в кэш маркер от вашего имени, чтобы дальнейшие вызовы getAccessToken просто возвращали кэшированный маркер.
Ведущее приложение Office возвращает маркер доступа в надстройку как часть объекта результатов, возвращаемого вызовом getAccessToken.
Маркер — это как маркер доступа, так и маркер удостоверений. Его можно использовать в качестве маркера удостоверений для анализа и проверки утверждений о пользователе, таких как имя пользователя и адрес электронной почты.
Кроме того, надстройка может использовать маркер в качестве маркера доступа для выполнения HTTPS-запросов с проверкой подлинности к API на стороне сервера. Так как маркер доступа содержит утверждения удостоверений, сервер может хранить сведения, связанные с удостоверением пользователя; например, предпочтения пользователя.

Разработка надстройки с единым входом

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

Регистрация надстройки на платформе удостоверений Майкрософт

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

Получить идентификатор приложения (клиента) для идентификации надстройки на платформе удостоверений Майкрософт.
Создать секрет клиента, который будет действовать в качестве пароля для надстройки при запросе маркера.
Указать разрешения, требующиеся для надстройки. Всегда требуются разрешения "профиль" и "openid" Microsoft Graph. В зависимости от задач надстройки могут потребоваться дополнительные разрешения.
Предоставить приложениям Office доверие к надстройке.
Предварительно авторизовать приложения Office в надстройке с областью по умолчанию access_as_user.

Дополнительные сведения об этом процессе см. в разделе Регистрация надстройки Office, использующей единый вход, на платформе удостоверений Майкрософт.

Конфигурация надстройки

Добавьте новую разметку в манифест надстройки:

<WebApplicationInfo> — родительский элемент следующих элементов.
<Id> — идентификатор приложения (клиента), полученный при регистрации надстройки в платформа удостоверений Майкрософт. Дополнительные сведения см. в разделе Регистрация надстройки Office, использующей единый вход, на платформе удостоверений Майкрософт.
<Ресурс> — универсальный код ресурса (URI) надстройки. Это тот же универсальный код ресурса (URI) (включая протокол api:), использованный при регистрации надстройки на платформе удостоверений Майкрософт. Доменная часть этого URI должна соответствовать домену, включая все поддомены, используемые в URL-адресах в <разделе Ресурсы> манифеста надстройки, а URI должен заканчиваться идентификатором клиента, указанным в элементе< Id>.
<Scopes> — родительский элемент одного или нескольких <элементов Scope> .
<Область> — указывает разрешение, необходимое надстройке. Разрешения profile и openID всегда необходимы и могут быть единственными необходимыми разрешениями. Если надстройке требуется доступ к Microsoft Graph или другим ресурсам Microsoft 365, вам потребуются дополнительные <элементы Scope> . Например, для разрешений Microsoft Graph можно запросить области User.Read и Mail.Read. Библиотеки, которые вы используете в коде, чтобы получить доступ к Microsoft Graph, могут потребовать дополнительные разрешения. Дополнительные сведения см. в статье Авторизация в Microsoft Graph для надстройки Office.

Для надстроек Word, Excel и PowerPoint добавьте исправления в конец раздела <VersionOverrides ... xsi:type="VersionOverridesV1_0">. Для надстройки Outlook добавьте исправления в конец раздела <VersionOverrides ... xsi:type="VersionOverridesV1_1">.

Ниже приведен пример разметки.

<WebApplicationInfo>
    <Id>5661fed9-f33d-4e95-b6cf-624a34a2f51d</Id>
    <Resource>api://addin.contoso.com/5661fed9-f33d-4e95-b6cf-624a34a2f51d</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>files.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

Важно!

Если надстройка развертывается одним или несколькими администраторами в своих организациях, добавление новых областей в манифест потребует от администратора согласия на обновления. Пользователи будут заблокированы в надстройке, пока не будет предоставлено согласие.

Примечание.

Несоблюдение требований к формату в манифесте для единого входа приведет к удалению надстройки из AppSource до тех пор, пока она не будет соответствовать требуемому формату.

Включение набора обязательных элементов API удостоверений

Для использования единого входа надстройке требуется набор обязательных элементов API удостоверений 1.3. Дополнительные сведения см. в разделе identityAPI.

Добавьте код для клиента

Добавьте в надстройку код JavaScript для:

Вызова getAccessToken.
Анализа маркера доступа или передачи его в код надстройки на стороне сервера.

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

Примечание.

В этом примере обрабатывается только один тип ошибки явным образом. Примеры более сложной обработки ошибок см. в статьях Единый вход с использованием NodeJS для надстройки Office и Единый вход с использованием ASP.NET для надстройки Office.

async function getUserData() {
    try {
        let userTokenEncoded = await OfficeRuntime.auth.getAccessToken();
        let userToken = jwt_decode(userTokenEncoded); // Using the https://www.npmjs.com/package/jwt-decode library.
        console.log(userToken.name); // user name
        console.log(userToken.preferred_username); // email
        console.log(userToken.oid); // user id     
    }
    catch (exception) {
        if (exception.code === 13003) {
            // SSO is not supported for domain user accounts, only
            // Microsoft 365 Education or work account, or a Microsoft account.
        } else {
            // Handle error
        }
    }
}

Когда вызывать getAccessToken

Если надстройке требуется пользователь, выполнивший вход, необходимо выполнить вызов getAccessTokenизнутри Office.initialize. Вы также должны пройти allowSignInPrompt: true в параметре optionsgetAccessToken. Например; OfficeRuntime.auth.getAccessToken( { allowSignInPrompt: true }); Это гарантирует, что если пользователь еще не вошел в систему, Office предложит пользователю войти в систему сейчас через пользовательский интерфейс.

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

Важно!

Рекомендация по безопасности: вызывайте getAccessToken тогда, когда вам нужен маркер доступа. Office поместит его в кэш для вас. Не помещайте в кэш и не храните маркер доступа с помощью собственного кода.

Передача маркера доступа серверному коду

Чтобы получить доступ к веб-API на сервере или дополнительным службам, таким как Microsoft Graph, необходимо передать маркер доступа в серверный код. Маркер доступа предоставляет доступ (для пользователя, прошедшего проверку подлинности) к веб-API. Кроме того, серверный код может анализировать маркер на наличие сведений об удостоверении, если это необходимо. (См раздел Использование маркера доступа в качестве маркера удостоверений ниже.). Существует множество библиотек для разных языков и платформ, которые могут упростить написание кода. Дополнительные сведения см. в разделе Обзор библиотеки проверки подлинности Майкрософт (MSAL).

Если необходимо получить доступ к данным Microsoft Graph, серверный код должен выполнить следующие действия:

Проверка маркера доступа (см. статью Проверка маркер доступа ниже).
Инициирование потока On-Behalf-Of OAuth 2.0 с вызовом платформы удостоверений Майкрософт, которая включает маркер доступа, некоторые метаданные о пользователе и учетные данные надстройки (ее идентификатор и секрет). Платформа удостоверений Майкрософт вернет новый маркер доступа, который можно использовать для доступа к Microsoft Graph.
Получение данных из Microsoft Graph с помощью нового маркера.
Если необходимо поместить в кэш новый маркер доступа для нескольких вызовов, рекомендуется использовать сериализацию кэша маркеров в MSAL.NET.

Важно!

Рекомендация по системе безопасности: всегда используйте серверный код для выполнения вызовов Microsoft Graph или других вызовов, требующих передачи маркера доступа. Никогда не возвращайте маркер OBO клиенту, чтобы клиент мог выполнять прямые вызовы в Microsoft Graph. Это помогает защитить маркер от перехвата или утечки. Дополнительные сведения о правильном потоке протокола см. в разделе Схема протокола OAuth 2.0.

В следующем коде показан пример передачи маркера доступа на сервер. Маркер передается в Authorizationзаголовке при отправке запроса в серверный веб-API. В этом примере представлена отправка данных JSON, поэтому в нем используется метод POST, но GET достаточно для отправки маркера доступа, когда запись не осуществляется на сервере.

$.ajax({
    type: "POST",
    url: "/api/DoSomething",
    headers: {
        "Authorization": "Bearer " + accessToken
    },
    data: { /* some JSON payload */ },
    contentType: "application/json; charset=utf-8"
}).done(function (data) {
    // Handle success
}).fail(function (error) {
    // Handle error
}).always(function () {
    // Cleanup
});

Дополнительные сведения о получении авторизованного доступа к данным Microsoft Graph пользователя см. в статье Авторизация в Microsoft Graph для надстройки Office.

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

Веб-API на сервере должны проверять маркер доступа, если он отправлен от клиента. Это маркер JSON Web Token (JWT), то есть его проверка выполняется так же, как и в большинстве стандартных потоков OAuth. Доступно множество библиотек, которые могут выполнять проверку JWT, основные их действия:

проверяют правильность формата маркера;
проверяют, выдан ли маркер нужным центром сертификации;
проверяют, предназначен ли маркер для веб-API.

При проверке маркера учитывайте приведенные ниже рекомендации.

Действительные маркеры единого входа выдает центр сертификации Azure, https://login.microsoftonline.com. Утверждение iss в маркере должно начинаться с этого значения.
Параметру aud маркера будет присвоено значение идентификатора приложения с портала регистрации приложения Azure надстройки.
Для параметра scp маркера будет задано значение access_as_user.

Дополнительные сведения о проверке маркеров см. в разделе Маркеры доступа платформы удостоверений Майкрософт.

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

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

name — Отображаемое имя пользователя.
preferred_username — Электронный адрес пользователя.
oid — GUID, представляющий идентификатор пользователя в системе удостоверений Майкрософт.
tid — GUID, представляющий клиента, в который вошел пользователь.

Дополнительные сведения об этих и других утверждениях см. в разделе Маркеры удостоверений платформы удостоверений Майкрософт. Если необходимо создать уникальный идентификатор для представления пользователя в системе, см. дополнительные сведения в разделе Использование утверждений для надежной идентификации пользователя.

Пример маркера доступа

Ниже приведен типичная раскодированная нагрузка маркера доступа. Сведения о свойствах см. в разделе Маркеры доступа платформы удостоверений Майкрософт.

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

С использованием единого входа с надстройкой Outlook

Существует ряд небольшие, но важных различий при использовании единого входа в надстройке Outlook и его использования в надстройках Excel, PowerPoint или Word. Обязательно ознакомьтесь с содержанием статей Выполнение проверки подлинности пользователя с маркером единого входа в надстройке Outlook и Сценарий: Реализация единого входа для вашей службы в надстройке Outlook.

Google Chrome постепенно удаляет сторонние файлы cookie в 2024 году и представляет функцию под названием Предотвращение отслеживания. Если в браузере Chrome включена защита от отслеживания, надстройка не сможет использовать сторонние файлы cookie. Надстройка может столкнуться с проблемами при проверке подлинности пользователя, например с несколькими запросами на вход или ошибками.

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

Дополнительные сведения о выпуске Google Chrome см. в следующих ресурсах:

Включение единого входа (SSO) в надстройке Office

Принцип работы единого входа во время выполнения

Рекомендации и требования

Не помещать в кэш маркер доступа

Включение современной проверки подлинности для Outlook

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

Разработка надстройки с единым входом

Регистрация надстройки на платформе удостоверений Майкрософт

Конфигурация надстройки

Включение набора обязательных элементов API удостоверений

Добавьте код для клиента

Когда вызывать getAccessToken

Передача маркера доступа серверному коду

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

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

Пример маркера доступа

С использованием единого входа с надстройкой Outlook

См. также

Обратная связь

Дополнительные ресурсы

Включение единого входа (SSO) в надстройке Office

Принцип работы единого входа во время выполнения

Рекомендации и требования

Не помещать в кэш маркер доступа

Включение современной проверки подлинности для Outlook

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

Разработка надстройки с единым входом

Регистрация надстройки на платформе удостоверений Майкрософт

Конфигурация надстройки

Включение набора обязательных элементов API удостоверений

Добавьте код для клиента

Когда вызывать getAccessToken

Передача маркера доступа серверному коду

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

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

Пример маркера доступа

С использованием единого входа с надстройкой Outlook

Поддержка сторонних файлов cookie в Google Chrome

См. также

Обратная связь

Дополнительные ресурсы