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

Использование единого входа для получения удостоверения пользователя, выполнившего вход

  • Статья

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

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

Примечание.

Единый вход в Office и getAccessToken API работает не во всех сценариях. Всегда реализуйте резервное диалоговое окно для входа пользователя, когда единый вход недоступен. Дополнительные сведения см. в статье Проверка подлинности и авторизация с помощью API диалогового окна Office.

Создание регистрации приложения

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

  1. Чтобы зарегистрировать приложение, перейдите на страницу портал Azure — Регистрация приложений.

  2. Войдите с учетными данными администратора в клиент Microsoft 365. Например, MyName@contoso.onmicrosoft.com.

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

    • Введите имяOffice-Add-in-SSO.
    • Для параметра Поддерживаемые типы учетных записей укажите вариант Учетные записи в любом каталоге организации и личные учетные записи Майкрософт (например, Skype, Xbox, Outlook.com).
    • Задайте для типа приложения значение Web , а затем задайте для параметра URI перенаправления значение https://localhost:[port]/dialog.html. Замените [port] правильным номером порта для веб-приложения. Если вы создали надстройку с помощью Yo Office, номер порта обычно равен 3000 и находится в файле package.json. Если вы создали надстройку в Visual Studio 2019, порт будет найден в свойстве URL-адреса SSL веб-проекта.
    • Нажмите кнопку Зарегистрировать.

  4. На странице Office-Add-in-SSO скопируйте и сохраните значения идентификатора приложения (клиента) и идентификатора каталога (клиента). Они понадобятся вам позже.

    Примечание.

    Этот идентификатор приложения (клиента) является значением "аудитории", когда другие приложения, такие как клиентское приложение Office (например, PowerPoint, Word, Excel), ищут авторизованный доступ к приложению. Это также "идентификатор клиента" приложения, когда оно, в свою очередь, ищет авторизованный доступ к Microsoft Graph.

  5. Выберите пункт Проверка подлинности в разделе Управление. В разделе Неявное предоставление установите флажки для маркера доступа и маркера идентификатора.

  6. Щелкните Сохранить в верхней части формы.

  7. Выберите пункт Предоставление API в разделе Управление. Щелкните ссылку Задать . При этом будет создан универсальный код ресурса (URI) идентификатора приложения в формате api://[app-id-guid], где [app-id-guid] — идентификатор приложения (клиента).

  8. В созданном идентификаторе вставьте localhost:[port]/ (обратите внимание на косую черту "/", добавленную в конец) между двойными косыми чертами и GUID. Замените [port] правильным номером порта для веб-приложения. Если вы создали надстройку с помощью Yo Office, номер порта обычно равен 3000 и находится в файле package.json. Если вы создали надстройку в Visual Studio 2019, порт будет найден в свойстве URL-адреса SSL веб-проекта.

    По завершении весь идентификатор должен иметь форму api://localhost:[port]/[app-id-guid], например api://localhost:44355/c6c1f32b-5e55-4997-881a-753cc1d563b7.

  9. Нажмите кнопку Добавить область. На открывающейся панели введите access_as_user имя <области> .

  10. Для параметра Кто может давать согласие? установите вариант Администраторы и пользователи.

  11. Заполните поля для настройки запросов согласия администратора и пользователя значениями, соответствующими access_as_user область, что позволяет клиентскому приложению Office использовать веб-API надстройки с теми же правами, что и у текущего пользователя. Предложения:

    • Администратор отображаемое имя согласия: Office может выступать в качестве пользователя.
    • Описание согласия администратора. Позволяет Office вызывать веб-API надстройки с такими же правами, как у текущего пользователя.
    • Отображаемое имя согласия пользователя. Office может действовать как вы.
    • Описание согласия пользователя. Включите Office для вызова веб-API надстройки с теми же правами, что и у вас.

  12. Убедитесь, что параметру Состояние присвоено значение Включено.

  13. Нажмите кнопку Добавить область.

    Примечание.

    Доменная часть <имени области>, отображаемая сразу под текстовым полем, api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_userдолжна автоматически соответствовать URI идентификатора приложения, заданному ранее, с /access_as_user добавлением в конец, например .

  14. В разделе Авторизованные клиентские приложения введите следующий идентификатор, чтобы предварительно авторизовать все конечные точки приложений Microsoft Office.

    • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (Все конечные точки приложений Microsoft Office)

    Примечание.

    Идентификатор ea5a67f6-b6f3-4338-b240-c655ddc3cc8e предварительно авторизует Office на всех следующих платформах. Кроме того, можно ввести соответствующее подмножество следующих идентификаторов, если по какой-либо причине вы хотите запретить авторизацию Office на некоторых платформах. Просто оставьте идентификаторы платформ, с которых вы хотите удержать авторизацию. Пользователи надстройки на этих платформах не смогут вызывать веб-API, но другие функции надстройки по-прежнему будут работать.

    • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office).
    • 93d53678-613d-4013-afc1-62e9e444a0a5 (Office в Интернете).
    • bc59ab01-8403-45c6-8796-ac3ef710b3e3 (Outlook в Интернете).

  15. Нажмите кнопку Добавить клиентское приложение, а затем на открывающейся панели задайте [app-id-guid] для идентификатора приложения (клиента) и проверка поле для api://localhost:44355/[app-id-guid]/access_as_userпараметра .

  16. Нажмите кнопку Добавить приложение.

  17. Выберите пункт Разрешения API в разделе Управление и нажмите кнопку Добавить разрешение. В открывшейся панели выберите Microsoft Graph и щелкните Делегированные разрешения.

  18. Используйте поле поиска Выбрать разрешения, чтобы найти нужные разрешения для надстройки. Найдите и выберите разрешение профиля . Разрешение profile требуется приложению Office для получения маркера веб-приложения надстройки.

    • profile

    Примечание.

    Разрешение User.Read может быть уже указано по умолчанию. Рекомендуется не запрашивать разрешения, которые не требуются, поэтому рекомендуется снять флажок для этого разрешения, если надстройка не нуждается в нем.

  19. Нажмите кнопку Добавить разрешения в нижней части панели.

  20. На той же странице нажмите кнопку Предоставить согласие администратора для <имени> клиента, а затем нажмите кнопку Да, чтобы появилось подтверждение.

Создание надстройки Office

  1. Запустите Visual Studio 2019 и выберите Создать новый проект.
  2. Найдите и выберите шаблон проекта веб-надстройки Excel . Затем нажмите кнопку Далее. Примечание. Единый вход работает с любым приложением Office, но Excel — это приложение, используемое в этой статье.
  3. Введите имя проекта, например sso-display-user-info, и нажмите кнопку Создать. Другие поля можно оставить со значениями по умолчанию.
  4. В диалоговом окне Выбор типа надстройки выберите Добавить новые функции в Excel и нажмите кнопку Готово.

Проект будет создан и будет содержать два проекта в решении.

  • sso-display-user-info: содержит манифест и сведения для загрузки надстройки в Excel.
  • sso-display-user-infoWeb: проект ASP.NET, в котором размещаются веб-страницы надстройки.

Настройка манифеста

В Обозреватель решений откройте sso-display-user-info>sso-display-user-infoManifest>sso-display-user-info.xml.

  1. В нижней части манифеста находится закрывающий </Resources> элемент. Вставьте следующий XML-код сразу под элементом </Resources> , но перед закрывающим </VersionOverrides> элементом. Для приложений Office, отличных от Outlook, добавьте разметку в конец <VersionOverrides ... xsi:type="VersionOverridesV1_0"> раздела. Для Outlook добавьте разметку в конец раздела <VersionOverrides ... xsi:type="VersionOverridesV1_1">.

    <WebApplicationInfo>
    <Id>[application-id]</Id>
    <Resource>api://localhost:[port]/[application-id]</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

  2. Замените [port] правильным номером порта для проекта. Если вы создали надстройку с помощью Yo Office, номер порта обычно равен 3000 и находится в файле package.json. Если вы создали надстройку в Visual Studio 2019, порт будет найден в свойстве URL-адреса SSL веб-проекта.

  3. Замените оба [application-id] заполнителя фактическим идентификатором приложения из регистрации приложения.

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

Вставленный XML-код содержит следующие элементы и сведения.

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

Добавление пакета jwt-decode

Вы можете вызвать API, getAccessToken чтобы получить маркер идентификатора из Office. Сначала добавим пакет jwt-decode, чтобы упростить декодирование и просмотр маркера идентификатора.

  1. Откройте решение Visual Studio.

  2. В меню выберите Инструменты>Консоль диспетчера>пакетов NuGet.

  3. Введите следующую команду в консоли диспетчера пакетов.

    Install-Package jwt-decode -Projectname sso-display-user-infoWeb

Добавление пользовательского интерфейса в область задач

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

  1. Откройте файл Home.html.

  2. Добавьте следующий тег скрипта в <head> раздел страницы. Это будет включать пакет jwt-decode, добавленный ранее.

    <script src="Scripts/jwt-decode-2.2.0.js" type="text/javascript"></script>

  3. Замените <body> раздел следующим HTML-кодом.

    <body>
  <h1>Welcome</h1>
  <p>
    Sign in to Office, then choose the <b>Get ID Token</b> button to see your
    ID token information.
  </p>
  <button id="getIDToken">Get ID Token</button>
  <div>
    <span id="userInfo"></span>
  </div>
</body>

Вызов API getAccessToken

Последним шагом является получение маркера идентификатора путем вызова getAccessToken.

  1. Откройте файлHome.js .

  2. Замените все содержимое файла указанным ниже кодом.

    (function () {
  "use strict";

  // The initialize function must be run each time a new page is loaded.
  Office.initialize = function (reason) {
    $(document).ready(function () {
      $("#getIDToken").on("click", getIDToken);
    });
  };

  async function getIDToken() {
    try {
      let userTokenEncoded = await OfficeRuntime.auth.getAccessToken({
        allowSignInPrompt: true,
      });
      let userToken = jwt_decode(userTokenEncoded);
      document.getElementById("userInfo").innerHTML =
        "name: " +
        userToken.name +
        "<br>email: " +
        userToken.preferred_username +
        "<br>id: " +
        userToken.oid;
      console.log(userToken);
    } catch (error) {
      document.getElementById("userInfo").innerHTML =
        "An error occurred. <br>Name: " +
        error.name +
        "<br>Code: " +
        error.code +
        "<br>Message: " +
        error.message;
      console.log(error);
    }
  }
})();

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

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

Выберите Отладка>Начать отладку или нажмите клавишу F5.

  1. При запуске Excel войдите в Office с той же учетной записью клиента, которая использовалась для создания регистрации приложения.
  2. На ленте Главная выберите Показать область задач , чтобы открыть надстройку.
  3. В области задач надстройки выберите Получить маркер идентификатора.

Надстройка отобразит имя, адрес электронной почты и идентификатор учетной записи, с помощью этой учетной записи.

Примечание.

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

Остановка надстройки

Выберите Остановить отладку или нажмите клавиши SHIFT+F5.

См. также

Использование утверждений для надежной идентификации пользователя (идентификатор субъекта и объекта)