Включение единого входа для приложения Teams

Microsoft Teams предоставляет функцию единого входа (SSO) для приложения, чтобы получить маркер пользователя Teams для доступа к Microsoft Graph и другим API. Набор средств Microsoft Teams упрощает процесс, включив определенные Microsoft Entra рабочие процессы и интеграции в простые высокоуровневые API. В результате вы можете легко включить возможности единого входа в приложение Teams. Дополнительные сведения см. в статье Проверка подлинности пользователей в Microsoft Teams.

Конфигурации ключей

Чтобы включить единый вход, настройте приложение Teams следующим образом:

• Microsoft Entra манифесте приложения: обязательно определите URI, включая URI, который определяет приложение проверки подлинности Microsoft Entra и URI перенаправления, возвращающий маркер.

• Манифест приложения Teams. Подключите приложение единого входа к приложению Teams, включив правильную конфигурацию.

• Конфигурация Teams Toolkit и инфра-файлы. Убедитесь, что существуют необходимые конфигурации, чтобы включить единый вход для приложения Teams.

• Сведения о приложении единого входа в файлах конфигурации Teams Toolkit. Убедитесь, что приложение проверки подлинности регистрируется в серверной службе, а набор средств Teams инициирует его во время отладки или предварительного просмотра приложения Teams.

Приложение tab

Создание манифеста приложения Microsoft Entra

1. Скачайте шаблон манифеста приложения Microsoft Entra.

2. Добавьте в файл скачанный код шаблона манифеста ./aad.manifest.json приложения. Это позволяет настраивать различные аспекты регистрации приложения и обновлять манифест по мере необходимости. Дополнительные сведения см. в манифесте приложения.

Обновление манифеста приложения Teams

./appPackages/manifest.json Добавьте в файл следующий код:

"webApplicationInfo": {
  "id": "${{AAD_APP_CLIENT_ID}}",
  "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
}

webApplicationInfoпредоставляет Microsoft Entra идентификатор приложения и сведения о Microsoft Graph, чтобы помочь пользователям войти в приложение.

Примечание.

Можно использовать для {{ENV_NAME}} ссылки на переменные в env/.env.{TEAMSFX_ENV} файле.

Обновление файлов конфигурации набора средств Teams

1. Найдите файлы конфигурации набора средств Teams, например ./teamsapp.yml и ./teamsapp.local.yml. Обновите необходимые конфигурации, связанные с Microsoft Entra в этих файлах.

2. Добавьте действие provision в и ./teamsapp.yml./teamsapp.local.yml, чтобы создать новое приложение Microsoft Entra, используемое для единого aadApp/create входа:

   - uses: aadApp/create
     with:
       name: "YOUR_AAD_APP_NAME"
       generateClientSecret: true
       signInAudience: "AzureADMyOrg"
     writeToEnvironmentFile:
         clientId: AAD_APP_CLIENT_ID
         clientSecret: SECRET_AAD_APP_CLIENT_SECRET
         objectId: AAD_APP_OBJECT_ID
         tenantId: AAD_APP_TENANT_ID
         authority: AAD_APP_OAUTH_AUTHORITY
   

   Примечание.

   Замените name значение нужным именем для приложения Teams.

   Дополнительные сведения см. в разделе aadApp/create.

3. aadApp/update Добавьте действие provision в и ./teamsapp.yml./teamsapp.local.yml, чтобы обновить приложение Microsoft Entra:

   - uses: aadApp/update
     with:
       manifestPath: "./aad.manifest.json"
       outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json"
   

   Примечание.

   • Измените manifestPath значение на относительный путь к шаблону aad.manifest.jsonманифеста приложения Microsoft Entra , если вы изменили путь к файлу.
   • В локальной конфигурации разместите aad/updatefile/createOrUpdateEnvironmentFile после действия . Это необходимо, так как aad/update использует выходные данные из file/createOrUpdateEnvironmentFile.

   Дополнительные сведения см. в разделе aadApp/update

4. Для проекта React обновите cli/runNpmCommand в разделе deploy.

5. Если вы создаете приложение вкладки с помощью платформы React в CLI, найдите cli/runNpmCommand действие с build app в teamsapp.yml файле и добавьте следующие переменные среды:

   env:
     REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
     REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html
   

6. Если вы создаете приложение вкладки с React платформой, найдите file/createOrUpdateEnvironmentFile действие для развертывания в teamsapp.local.yml файле и добавьте следующие переменные среды:

   envs:
     ...
     REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
     REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html
   

Обновление исходного кода

После реализации указанных выше изменений среда будет подготовлена. Теперь вы можете обновить код, чтобы включить единый вход в приложение Teams.

Vanilla JavaScript

Для приложения tab, которое не использует React, используйте следующий код в качестве базового примера для получения маркера единого входа:

function getSSOToken() {
  return new Promise((resolve, reject) => {
    microsoftTeams.authentication.getAuthToken()
      .then((token) => resolve(token))
      .catch((error) => reject("Error getting token: " + error));
  });
}

function getBasicUserInfo() {
  getSSOToken().then((ssoToken) => {
    const tokenObj = JSON.parse(window.atob(ssoToken.split(".")[1]));
    console.log(`username: ${tokenObj.name}`);
    console.log(`user email: ${tokenObj.preferred_username}`);
  });
}

React

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

• Сведения о проекте JavaScript см. в разделе Пример javaScript вкладки.

• Пример проекта TypeScript см. на вкладке TypeScript.

Чтобы обновить исходный код, выполните следующие действия.

1. auth-start.html Переместите файлы и auth-end.html из auth/public папки в папку public/ . Эти HTML-файлы служат для обработки перенаправлений проверки подлинности.

2. Переместите sso папку в auth/ папку src/sso/.

   1. InitTeamsFx: этот файл выполняет функцию, которая инициализирует пакет SDK TeamsFx. После инициализации пакета SDK открывается GetUserProfile компонент .
   2. GetUserProfile: этот файл выполняет функцию для получения сведений о пользователе путем вызова microsoft API Graph.

3. Импортируйте и добавьте InitTeamsFx в Welcome.*.

Дополнительные сведения см. в разделе Приложение вкладки с поддержкой единого входа.

Приложение расширения bot/message

Создание манифеста приложения Microsoft Entra

1. Скачайте шаблон манифеста приложения Microsoft Entra.

2. Добавьте в файл скачанный код шаблона манифеста ./aad.manifest.json приложения. Это позволяет настраивать различные аспекты регистрации приложения и обновлять манифест по мере необходимости. Дополнительные сведения см. в манифесте приложения.

Обновление манифеста приложения Teams

1. ./appPackages/manifest.json Добавьте в файл следующий код:

   "webApplicationInfo": {
     "id": "${{AAD_APP_CLIENT_ID}}",
     "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
   }
   

   webApplicationInfoпредоставляет Microsoft Entra идентификатор приложения и сведения о Microsoft Graph, чтобы помочь пользователям войти в приложение.

   Примечание.

   Можно использовать для {{ENV_NAME}} ссылки на переменные в env/.env.{TEAMSFX_ENV} файле.

2. Зарегистрируйте одну или несколько команд в commandLists.

   Содержит commandLists команды, которые бот может предложить пользователям. Если вы используете шаблон бота teamsFx , задайте следующие значения:

   {
     "title": "profile",
     "description": "Show user profile using Single Sign On feature"
   }
   

3. Поле validDomains содержит домены для веб-сайтов, которые приложение загружает в клиенте Teams. Обновите следующее значение:

   "validDomains": [
   "${{BOT_DOMAIN}}"
   ]
   

Обновление файлов конфигурации набора средств Teams

1. Найдите файлы конфигурации набора средств Teams, например ./teamsapp.yml и ./teamsapp.local.yml. Обновите необходимые конфигурации, связанные с Microsoft Entra в этих файлах.

2. Добавьте следующий код aadApp/createprovision в и ./teamsapp.yml./teamsapp.local.yml для создания приложений Microsoft Entra, используемых для единого входа:

   - uses: aadApp/create
     with:
       name: "YOUR_AAD_APP_NAME"
       generateClientSecret: true
       signInAudience: "AzureADMyOrg"
     writeToEnvironmentFile:
         clientId: AAD_APP_CLIENT_ID
         clientSecret: SECRET_AAD_APP_CLIENT_SECRET
         objectId: AAD_APP_OBJECT_ID
         tenantId: AAD_APP_TENANT_ID
         authority: AAD_APP_OAUTH_AUTHORITY
         authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST
   

   Примечание.

   Замените name значение нужным именем для приложения Microsoft Teams.

   Дополнительные сведения см. в разделе aadApp/create.

3. Добавьте следующий код aadApp/updateprovision в ./teamsapp.yml и./teamsapp.local.yml, чтобы обновить приложение Microsoft Entra:

   - uses: aadApp/update
     with:
       manifestPath: "./aad.manifest.json"
       outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json"
   

   Примечание.

   Измените manifestPath значение на относительный путь к шаблону aad.manifest.jsonманифеста приложения Microsoft Entra , если вы изменили путь к файлу.

   Дополнительные сведения см. в разделе aadApp/update

4. createOrUpdateEnvironmentFile Найдите действие в teamsapp.local.yml файле и добавьте следующие переменные среды:

   envs:
     ...
     M365_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
     M365_CLIENT_SECRET: ${{SECRET_AAD_APP_CLIENT_SECRET}}
     M365_TENANT_ID: ${{AAD_APP_TENANT_ID}}
     INITIATE_LOGIN_ENDPOINT: ${{BOT_ENDPOINT}}/auth-start.html
     M365_AUTHORITY_HOST: ${{AAD_APP_OAUTH_AUTHORITY_HOST}}
     M365_APPLICATION_ID_URI: api://botid-${{BOT_ID}}
   

Обновление инфраструктуры

Обновление конфигураций, связанных с Microsoft Entra, в удаленной службе. В следующем примере показаны параметры конфигурации веб-приложения Azure.

• M365_CLIENT_ID: Microsoft Entra идентификатор клиента приложения
• M365_CLIENT_SECRET: Microsoft Entra секрет клиента приложения
• M365_TENANT_ID: идентификатор клиента приложения Microsoft Entra
• INITIATE_LOGIN_ENDPOINT: начальная страница входа для проверки подлинности
• M365_AUTHORITY_HOST: Microsoft Entra узел центра OAuth приложения
• M365_APPLICATION_ID_URI: URI идентификатора для приложения Microsoft Entra

Чтобы использовать шаблон вкладки teamsFx или бота, выполните следующие действия.

1. infra/azure.parameters.json Откройте файл и добавьте следующий код:

   "m365ClientId": {
     "value": "${{AAD_APP_CLIENT_ID}}"
   },
   "m365ClientSecret": {
     "value": "${{SECRET_AAD_APP_CLIENT_SECRET}}"
   },
   "m365TenantId": {
     "value": "${{AAD_APP_TENANT_ID}}"
   },
   "m365OauthAuthorityHost": {
     "value": "${{AAD_APP_OAUTH_AUTHORITY_HOST}}"
   }
   

2. Откройте infra/azure.bicep файл и добавьте следующий код после param location string = resourceGroup().location:

   param m365ClientId string
   param m365TenantId string
   param m365OauthAuthorityHost string
   param m365ApplicationIdUri string = 'api://botid-${botAadAppClientId}'
   @secure()
   param m365ClientSecret string
   

3. Добавьте в файл следующий код:outputinfra/azure.bicep

   resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = {
     name: '${webAppName}/appsettings'
     properties: {
       M365_CLIENT_ID: m365ClientId
       M365_CLIENT_SECRET: m365ClientSecret
       INITIATE_LOGIN_ENDPOINT: uri('https://${webApp.properties.defaultHostName}', 'auth-start.html')
       M365_AUTHORITY_HOST: m365OauthAuthorityHost
       M365_TENANT_ID: m365TenantId
       M365_APPLICATION_ID_URI: m365ApplicationIdUri
       BOT_ID: botAadAppClientId
       BOT_PASSWORD: botAadAppClientSecret
       RUNNING_ON_AZURE: '1'
     }
   }
   

   Примечание.

   • Чтобы добавить дополнительные конфигурации в веб-приложение Azure, добавьте конфигурации в webAppSettings.
   • Вам также может потребоваться определить версию узла по умолчанию, добавив следующую конфигурацию: bash WEBSITE_NODE_DEFAULT_VERSION: '14.20.0'

   Обновление исходного кода

   Бот

   1. Переместите файлы, расположенные в папке, auth/sso в src. Класс ProfileSsoCommandHandler служит обработчиком команд единого входа, предназначенным для получения сведений о пользователе с помощью маркера единого входа. Этот метод можно использовать для разработки собственного обработчика команд единого входа.

   2. Переместите папку в auth/publicsrc/public. Эта папка содержит HTML-страницы для приложения бота. При инициации потоков единого входа с Microsoft Entra пользователь перенаправляется на эти страницы.

   3. Выполните следующую команду в папке ./ :

      npm install copyfiles --save-dev
      

   4. Обновите следующую команду в package.json файле:

      "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/",
      

      HTML-страницы, используемые для перенаправления проверки подлинности, копируются при создании этого проекта бота.

   5. В src/index файле добавьте следующую команду для импорта isomorphic-fetch:

       require("isomorphic-fetch");
      

   6. Добавьте следующую команду для перенаправления на страницы проверки подлинности:

      server.get(
          "/auth-:name(start|end).html",
          restify.plugins.serveStatic({
            directory: path.join(__dirname, "public"),
          })
      );
      

   7. Обновите commandApp.requestHandler , чтобы убедиться, что проверка подлинности работает со следующим кодом:

      await commandApp.requestHandler(req, res).catch((err) => {
          // Error message including "412" means it is waiting for user's consent, which is a normal process of SSO, sholdn't throw this error.
          if (!err.message.includes("412")) {
          throw err;
          }
      });
      

   8. Добавьте ssoConfig и ssoCommands в src/internal/initializeConversationBot :

      import { ProfileSsoCommandHandler } from "../profileSsoCommandHandler";
      
      export const commandBot = new ConversationBot({
          ...
          // To learn more about ssoConfig, please refer teamsfx sdk document: https://docs.microsoft.com/microsoftteams/platform/toolkit/teamsfx-sdk
          ssoConfig: {
          aad :{
            scopes:["User.Read"],
          },
          },
          command: {
          enabled: true,
          commands: [new HelloWorldCommandHandler() ],
          ssoCommands: [new ProfileSsoCommandHandler()],
          },
      });
      

   Расширение для обмена сообщениями

   1. Реализуйте ключ handleMessageExtensionQueryWithSSO API в TeamsActivityHandler.handleTeamsMessagingExtensionQuery. Дополнительные сведения см. в статье Единый вход для расширений сообщений.

   2. Переместите папку в auth/publicsrc/public. Эта папка содержит HTML-страницы для приложения бота. При инициации потоков единого входа с Microsoft Entra пользователь перенаправляется на эти страницы.

   3. Обновите src/index файл, чтобы добавить соответствующий restify:

      const path = require("path");
      
      // Listen for incoming requests.
      server.post("/api/messages", async (req, res) => {
          await adapter.process(req, res, async (context) => {
          await bot.run(context);
          }).catch((err) => {
          // Error message including "412" means it is waiting for user's consent, which is a normal process of SSO, sholdn't throw this error.
          if(!err.message.includes("412")) {
                throw err;
            }
          })
      });
      
      server.get(
          "/auth-:name(start|end).html",
          restify.plugins.serveStatic({
          directory: path.join(__dirname, "public"),
          })
      );
      

   4. Выполните следующие команды в ./ папке:

      npm install @microsoft/teamsfx
      

      npm install isomorphic-fetch
      

   5. Реализуйте ключ handleMessageExtensionQueryWithSSO API в TeamsActivityHandler.handleTeamsMessagingExtensionQuery.

   6. Установите copyfiles пакеты npm в проекте бота TypeScript и обновите build скрипт в src/package.json файле следующим образом:

      "build": "tsc --build && copyfiles ./public/*.html lib/",
      

      HTML-страницы, используемые для перенаправления проверки подлинности, копируются при создании этого проекта бота.

   7. Обновите templates/appPackage/aad.template.json файл с областями, используемыми в handleMessageExtensionQueryWithSSO функции:

      "requiredResourceAccess": [
            {
            "resourceAppId": "Microsoft Graph",
            "resourceAccess": [
                    {
                        "id": "User.Read",
                        "type": "Scope"
                    }
            ]
            }
        ]
      

---

Отладка приложения

Чтобы отладить приложение, выберите клавишу F5 . Teams Toolkit использует манифест Microsoft Entra для регистрации приложения с поддержкой единого входа. Дополнительные сведения см. в статье Отладка приложения Teams локально.

Настройка приложений Microsoft Entra

Манифест приложения Teams позволяет настраивать различные аспекты регистрации приложения. Манифест можно обновить по мере необходимости.

Дополнительные разрешения API для доступа к нужным API см. в статье Изменение манифеста Microsoft Entra.

Сведения о просмотре приложения Microsoft Entra в портал Azure см. в статье Изменение манифеста Microsoft Entra.

Следующее действие

Добавление функциональности единого входа в приложение Teams