Настройка аутентификации с помощью ключа API

Совет

Рекомендуется: Начните с Work IQ Dev Tools для поддерживаемых сценариев декларативного агента и плагинов для кода. См. краткое руководство по WIQD. Инструкции на основе набора средств остаются доступными для существующих проектов и рабочих процессов, для которых они требуются. Перед выбором инструмента проверьте поддержку возможностей и целевого интерфейса : WIQD не нацелен на агентов пользовательской подсистемы.

Некоторые API используют ключи API для авторизации. Ключ API — это общий секрет, который клиент включает в запросы API для проверки подлинности и получения доступа. Подключаемые модули API поддерживают отправку ключа API тремя способами:

  • В качестве маркера носителя в верхнем колонтитуле Authorization
  • В качестве значения в настраиваемом верхнем колонтитуле
  • В качестве параметра запроса

Примечание

Для действий декларативного агента аутентификация ключа API применяется к плагинам API, созданным из документа OpenAPI, а не к плагинам MCP. Для подключаемого модуля MCP агента используйте OAuth 2.0 (включая динамическую регистрацию клиентов) или Microsoft Entra SSO. Удаленное подключение MCP на уровне пакета использует другую конфигурацию; См. проверку подлинности в манифесте приложения.

Настройте аутентификацию API-ключа в два шага: добавьте ключ API в документ OpenAPI и создайте конфигурацию проверки подлинности ключа API.

Шаг 1. Добавьте ключ API в документ OpenAPI

Microsoft 365 Copilot определяет, securitySchemes как отправлять ключ API, на основе записи в документе OpenAPI.

Маркер на предъявителя

Если API принимает ключ API в качестве токена носителя, включите аутентификацию Bearer в документе OpenAPI. Дополнительные сведения см. в разделе Аутентификация носителя.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Пользовательский верхний колонтитул

Если API принимает ключ API в пользовательском заголовке, включите проверку подлинности ключа API в документе OpenAPI со свойством inheadername и именем заголовка. Дополнительные сведения см. в разделе Ключи API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

Параметр запроса

Если API принимает ключ API в параметре запроса, включите проверку подлинности ключа API в документе OpenAPI, задав свойству in значение queryname и имя параметра запроса. Дополнительные сведения см. в разделе Ключи API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

Шаг 2. Создание конфигурации проверки подлинности ключа API

Проверка подлинности ключа API зависит от конфигурации проверки подлинности (конфигурация проверки подлинности) — записи, хранящейся в хранилище токенов Microsoft Enterprise, которую Microsoft 365 Copilot использует для отправки ключа API, когда ваш подключаемый модуль вызывает API. Начните с WIQD для поддерживаемого проекта pro-code. Набор средств и процедуры портала разработчика Microsoft Teams по-прежнему доступны в качестве альтернатив. Навык разработчика декларативного агента не поддерживает проверку подлинности ключа API, так как он создает подключаемые модули MCP.

Для существующего манифеста подключаемого модуля API используйте wiqd agent add auth с --plugin-manifest, --auth-name, и --auth-type api-key. Установите --api-key-in значение или headerquery и --api-key-name имя из схемы безопасности OpenAPI. Если API принимает ключ в качестве маркера носителя, выберите --auth-type bearer-token.

При добавлении действия из документа wiqd agent add action OpenAPI принимается --api-key за ключ API или учетные данные носителя. Команда документирует заполнители среды, если значение опущено. Следуйте инструкциям по обработке учетных данных выбранной команды и завершите рабочий процесс подготовки проекта. Эти варианты API-ключа не обеспечивают поддержку ключа API для подключаемого модуля MCP агента.

Использование набора средств агентов Microsoft 365

При создании подключаемого модуля API из существующего документа OpenAPI в наборе инструментов агентов Microsoft 365 набор средств регистрирует ключ API, создает конфигурацию проверки подлинности и обновляет манифест подключаемого модуля. Вы должны определить свойство securitySchemes в документе OpenAPI.

Использование портала разработчика Teams

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

  1. Откройте портал разработки Teams. Выберите Инструменты ->Регистрация ключа API.

  2. Если у вас нет существующих регистраций, выберите "Создать ключ API". Если у вас уже есть регистрации, выберите Новый ключ API.

  3. Выберите "Добавить секрет" и введите ключ API.

  4. Заполните следующие поля.

    • Имя ключа API: понятное имя для регистрации.
    • Базовый URL-адрес: базовый URL-адрес вашего API. Это значение должно соответствовать записи в массивеservers в документе OpenAPI.
    • Целевой клиент: ограничение доступа к API для домашнего клиента или разрешение любого клиента.
    • Целевое приложение Teams: выберите любое приложение Teams , если вы не знаете окончательный идентификатор приложения. После публикации приложения привяжите его к опубликованному идентификатору приложения.
  5. Нажмите кнопку Сохранить.

  6. После завершения регистрации создается идентификатор конфигурации проверки подлинности (в настоящее время называется идентификатором регистрации ключа API на портале разработчика Teams).

Добавление идентификатора конфигурации проверки подлинности в манифест подключаемого модуля

При создании конфигурации проверки подлинности вручную на портале разработки Teams задайте type свойству объекта проверки подлинности среды выполнения значение ApiKeyPluginVault, а затем reference_id значение идентификатор конфигурации проверки подлинности. Набор средств для агентов делает это за вас.

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "auth config ID"
},