Упражнение. Интеграция подключаемого модуля API с API, защищенным с помощью OAuth

11 мин

Подключаемые модули API для Microsoft 365 Copilot позволяют интегрироваться с API, защищенными С помощью OAuth. Вы храните идентификатор клиента и секрет приложения, которое защищает ВАШ API, безопасно регистрируя их в хранилище Teams. Во время выполнения Microsoft 365 Copilot выполняет подключаемый модуль, извлекает сведения из хранилища и использует их для получения маркера доступа и вызова API. Следуя этому процессу, идентификатор и секрет клиента остаются в безопасности и никогда не предоставляются клиенту.

Открытие примера проекта

Начните с скачивания примера проекта:

В веб-браузере перейдите по адресу https://aka.ms/learn-da-api-ts-repairs. Вы получите запрос на скачивание ZIP-файла с примером проекта.
Сохраните ZIP-файл на компьютере.
Извлеките содержимое ZIP-файла.
Откройте папку в Visual Studio Code.

Пример проекта представляет собой проект Microsoft 365 Agents Toolkit, включающий декларативный агент, подключаемый модуль API и API, защищенный с помощью Microsoft Entra ID. API работает на Функции Azure и реализует безопасность с помощью встроенных возможностей проверки подлинности и авторизации Функции Azure, которые иногда называются простой проверкой подлинности.

Изучение конфигурации авторизации OAuth2

Прежде чем продолжить, изучите конфигурацию авторизации OAuth2 в примере проекта.

Изучение определения API

Сначала ознакомьтесь с конфигурацией безопасности определения API, включенного в проект.

В Visual Studio Code:

Откройте файл appPackage/apiSpecificationFile/repair.yml .
В разделе components.securitySchemes обратите внимание на свойство oAuth2AuthCode :
```
components:
  securitySchemes:
    oAuth2AuthCode:
      type: oauth2
      description: OAuth configuration for the repair service
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/${{AAD_APP_TENANT_ID}}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/${{AAD_APP_TENANT_ID}}/oauth2/v2.0/token
          scopes:
            api://${{AAD_APP_CLIENT_ID}}/repairs_read: Read repair records 
```
Свойство определяет схему безопасности OAuth2 и содержит сведения о URL-адресах для вызова маркера доступа и области, которую использует API.

Важно!

Обратите внимание, что область полностью соответствует URI идентификатора приложения (api://...). При работе с Microsoft Entra необходимо полностью определить настраиваемые области. Когда Microsoft Entra видит неквалифицированный область, он предполагает, что он принадлежит Microsoft Graph, что приводит к ошибкам потока авторизации.
Найдите свойство paths./repairs.get.security . Обратите внимание, что он ссылается на схему безопасности oAuth2AuthCode и область, что клиент должен выполнить операцию.
```
[...]
paths:
  /repairs:
    get:
      operationId: listRepairs
      [...]
      security:
        - oAuth2AuthCode:
          - api://${{AAD_APP_CLIENT_ID}}/repairs_read
[...]
```
Важно!

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

Изучение реализации API

Затем ознакомьтесь с реализацией API.

В Visual Studio Code:

Откройте файл src/functions/repairs.ts .
В функции обработчика исправлений найдите следующую строку, которая проверяет, содержит ли запрос маркер доступа с необходимыми областями:
```
if (!hasRequiredScopes(req, 'repairs_read')) {
  return {
    status: 403,
    body: "Insufficient permissions",
  };
}
```
Функция hasRequiredScopes реализована далее в файле repairs.ts :
```
function hasRequiredScopes(req: HttpRequest, requiredScopes: string[] | string): boolean {
  if (typeof requiredScopes === 'string') {
    requiredScopes = [requiredScopes];
  }

  const token = req.headers.get("Authorization")?.split(" ");
  if (!token || token[0] !== "Bearer") {
    return false;
  }

  try {
    const decodedToken = jwtDecode<JwtPayload & { scp?: string }>(token[1]);
    const scopes = decodedToken.scp?.split(" ") ?? [];
    return requiredScopes.every(scope => scopes.includes(scope));
  }
  catch (error) {
    return false;
  }
}
```
Функция начинается с извлечения маркера носителя из заголовка запроса авторизации. Затем он использует пакет jwt-decode для декодирования маркера и получения списка областей из утверждения scp . Наконец, он проверяет, содержит ли утверждение scp все необходимые области.

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

Изучение конфигурации задачи хранилища

В этом проекте вы используете Microsoft 365 Agents Toolkit для добавления сведений OAuth в хранилище. Microsoft 365 Agents Toolkit регистрирует сведения OAuth в хранилище с помощью специальной задачи в конфигурации проекта.

В Visual Studio Code:

Откройте файл ./teampsapp.local.yml .
В разделе подготовка найдите задачу oauth/register .
```
- uses: oauth/register
  with:
    name: oAuth2AuthCode
    flow: authorizationCode
    appId: ${{TEAMS_APP_ID}}
    clientId: ${{AAD_APP_CLIENT_ID}}
    clientSecret: ${{SECRET_AAD_APP_CLIENT_SECRET}}
    isPKCEEnabled: true
    # Path to OpenAPI description document
    apiSpecPath: ./appPackage/apiSpecificationFile/repair.yml
  writeToEnvironmentFile:
    configurationId: OAUTH2AUTHCODE_CONFIGURATION_ID
```
Задача принимает значения переменных проекта TEAMS_APP_ID, AAD_APP_CLIENT_ID и SECRET_AAD_APP_CLIENT_SECRET переменных проекта, хранящихся в файлах env/.env.local и env/.env.local.user , и регистрирует их в хранилище. Он также включает ключ проверки для Code Exchange (PKCE) в качестве дополнительной меры безопасности. Затем он принимает идентификатор записи хранилища и записывает его в файл среды env/.env.local. Результатом этой задачи является переменная среды с именем OAUTH2AUTHCODE_CONFIGURATION_ID. Microsoft 365 Agents Toolkit записывает значение этой переменной в файл appPackages/ai-plugin.json , содержащий определение подключаемого модуля. Во время выполнения декларативный агент, загружающий подключаемый модуль API, использует этот идентификатор для получения сведений OAuth из хранилища и запуска потока проверки подлинности для получения маркера доступа.

Важно!

Задача oauth/register отвечает только за регистрацию сведений OAuth в хранилище, если она еще не существует. Если эти сведения уже существуют, microsoft 365 Agents Toolkit пропустит выполнение этой задачи.
Затем найдите задачу oauth/update .
```
- uses: oauth/update
  with:
    name: oAuth2AuthCode
    appId: ${{TEAMS_APP_ID}}
    apiSpecPath: ./appPackage/apiSpecificationFile/repair.yml
    configurationId: ${{OAUTH2AUTHCODE_CONFIGURATION_ID}}
    isPKCEEnabled: true
```
Задача сохраняет сведения OAuth в хранилище, синхронизированные с проектом. Это необходимо для правильной работы проекта. Одним из ключевых свойств является URL-адрес, по которому доступен подключаемый модуль API. При каждом запуске проекта microsoft 365 Agents Toolkit открывает туннель разработчика по новому URL-адресу. Сведения OAuth в хранилище должны ссылаться на этот URL-адрес для Copilot, чтобы получить доступ к API.

Изучение конфигурации проверки подлинности и авторизации

Далее следует изучить параметры проверки подлинности и авторизации Функции Azure. API в этом упражнении использует встроенные возможности проверки подлинности и авторизации Функции Azure. Microsoft 365 Agents Toolkit настраивает эти возможности при подготовке Функции Azure в Azure.

В Visual Studio Code:

Откройте файл infra/azure.bicep .
Найдите ресурс authSettings :
```
resource authSettings 'Microsoft.Web/sites/config@2021-02-01' = {
  parent: functionApp
  name: 'authsettingsV2'
  properties: {
    globalValidation: {
      requireAuthentication: true
      unauthenticatedClientAction: 'Return401'
    }
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          openIdIssuer: oauthAuthority
          clientId: aadAppClientId
        }
        validation: {
          allowedAudiences: [
            aadAppClientId
            aadApplicationIdUri
          ]
        }
      }
    }
  }
}
```
Этот ресурс включает встроенные возможности проверки подлинности и авторизации в приложении Функции Azure. Во-первых, в разделе globalValidation определяется, что приложение разрешает только запросы, прошедшие проверку подлинности. Если приложение получает запрос без проверки подлинности, оно отклоняет его с ошибкой HTTP 401. Затем в разделе identityProviders конфигурация определяет, что она использует Microsoft Entra ID (ранее известный как Azure Active Directory) для авторизации запросов. Он указывает, какой Microsoft Entra регистрации приложения используется для защиты API, и какие аудитории могут вызывать API.

Проверка регистрации приложения Microsoft Entra

Последняя часть, которую необходимо изучить, — это регистрация Microsoft Entra приложения, которую проект использует для защиты API. При использовании OAuth вы обеспечиваете безопасный доступ к ресурсам с помощью приложения. Обычно приложение определяет учетные данные, необходимые для получения маркера доступа, например секрет клиента или сертификат. Он также указывает различные разрешения (также известные как области), которые клиент может запрашивать при вызове API. Microsoft Entra регистрации приложения представляет приложение в облаке Майкрософт и определяет приложение для использования с потоками авторизации OAuth.

В Visual Studio Code:

Откройте файл ./aad.manifest.json .

Найдите свойство oauth2Permissions .

"oauth2Permissions": [
  {
    "adminConsentDescription": "Allows Copilot to read repair records on your behalf.",
    "adminConsentDisplayName": "Read repairs",
    "id": "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}",
    "isEnabled": true,
    "type": "User",
    "userConsentDescription": "Allows Copilot to read repair records.",
    "userConsentDisplayName": "Read repairs",
    "value": "repairs_read"
  }
],

Свойство определяет настраиваемую область с именем repairs_read, которая предоставляет клиенту разрешение на чтение исправлений из API восстановления.

Найдите свойство identifierUris .
```
"identifierUris": [
  "api://${{AAD_APP_CLIENT_ID}}"
]
```
Свойство identifierUris определяет идентификатор, который используется для полного определения область.

Протестируйте декларативный агент с помощью подключаемого модуля API в Microsoft 365 Copilot

Последним шагом является тестирование декларативного агента с помощью подключаемого модуля API в Microsoft 365 Copilot.

В Visual Studio Code:

На панели действий активируйте расширение Microsoft 365 Agents Toolkit .
На панели расширения Microsoft 365 Agents Toolkit в разделе Учетные записи убедитесь, что вы вошли в клиент Microsoft 365 с включенным Copilot.
На панели действий переключитесь в представление Запуск и отладка .
В списке конфигураций выберите Отладка в Copilot (Edge) и нажмите кнопку воспроизведения, чтобы начать отладку.

Visual Studio Code откроется новый веб-браузер с Microsoft 365 Copilot. При появлении запроса войдите в свою учетную запись Microsoft 365.

В веб-браузере:

На боковой панели выберите агент da-repairs-oauthlocal .
В текстовом поле запроса введите Show repair records assigned to Karin Blair и отправьте запрос.

Совет

Вместо ввода запроса можно выбрать его в начале беседы.
Убедитесь, что вы хотите отправить данные в подключаемый модуль API с помощью кнопки Всегда разрешать .
При появлении запроса войдите в API, чтобы продолжить использовать ту же учетную запись, которая используется для входа в клиент Microsoft 365, выбрав Войти в da-repairs-oauthlocal.
Дождитесь ответа агента.

Несмотря на то, что ваш API доступен анонимно, так как он работает на локальном компьютере, Microsoft 365 Copilot вызывает ваш API с проверкой подлинности, как указано в спецификации API. Вы можете убедиться, что запрос содержит маркер доступа, задав точку останова в функции repairs и отправив другой запрос в декларативном агенте. Когда код достигает точки останова, разверните коллекцию req.headers и найдите заголовок авторизации, содержащий веб-токен JSON (JWT).

Остановите сеанс отладки в Visual Studio Code после завершения тестирования.

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

Были ли сведения на этой странице полезными?