Перейдите в раздел Управление подключаемыми модулями, нажав кнопку Подключаемый модуль на панели запросов.
Прокрутите вниз до пункта Пользовательский и выберите Добавить подключаемый модуль.
Выберите Подключаемый модуль OpenAI в качестве формата отправки, введите https://hacktrack.routum.io/.well-known/ai-plugin.json в качестве ссылки и нажмите кнопку Добавить.
Подключаемый модуль API из существующего API
В этом кратком руководстве показано, как превратить существующий API в подключаемый модуль API Security Copilot.
Создание спецификации OpenAPI
Если у API уже есть спецификация OpenAPI, ее можно просто использовать. Разместите спецификацию OpenAPI https://[domain]/template.yaml.
Создайте файл манифеста подключаемого модуля со следующим содержимым (заменив OpenaApiSpecUrl значение URL-адресом файла спецификации OpenAPI, созданного в предыдущем разделе):
Security Copilot поддерживает несколько схем проверки подлинности подключаемых модулей:
Схема
Описание
Поддержка манифеста Copilot
Поддержка OpenAI +
Нет
Проверка подлинности не выполняется.
Да
Да
Обычный
Обычная проверка подлинности.
Да
Нет
ApiKey
Проверка подлинности на основе ApiKey, при которой разработчик предоставил ApiKey в пользовательском заголовке или параметре запроса.
Да
Да*
ServiceHttp
Проверка подлинности на основе предоставленного маркера.
Да
Да
OAuthAuthorizationCodeFlow
Поток кода авторизации OAuth 2.0 — это более безопасный и сложный метод проверки подлинности, используемый для предоставления доступа к приложениям сторонних корпораций без предоставления доступа к учетным данным пользователя.
Да
Да
OAuthClientCredentialsFlow
Как и обычная проверка подлинности, но используется для обмена данными между серверами или при доступе к общедоступным данным, для которых не требуются разрешения пользователя.
Да
Нет
Microsoft Entra ID
Доступ только к приложению.
Да
Да*
AADDelegated
Доступ только для пользователей и приложений.
Да
Да*
+ Это поле используется для указания двух разных типов отправки, поддерживаемых в Security Copilot.
* Они представляют собой методы проверки подлинности, которые выходят за рамки первоначально поддерживаемых openAI.
В следующей таблице показаны поддерживаемые параметры для каждого типа проверки подлинности.
Тип проверки подлинности
Setting
Описание
AAD или AADDelegated
EntraScopes
Разделенный запятыми список областей Microsoft Entra для запроса.
Basic
Username
Имя пользователя, используемое для обычной проверки подлинности.
Basic
Password
Пароль, используемый для обычной проверки подлинности.
ApiKey или ServiceHttp
Key
Имя параметра заголовка или запроса.
ApiKey или ServiceHttp
AuthScheme
Имя схемы проверки подлинности, которая добавляется к Value при использовании в заголовке.
ApiKey или ServiceHttp
Location
Расположение ключа API, либо HeaderQueryParams.
ApiKey или ServiceHttp
Value
Используемый ключ или маркер.
OAuthAuthorizationCodeFlow или OAuthClientCredentialsFlow
TokenEndpoint
Конечная точка для запроса маркера.
OAuthAuthorizationCodeFlow или OAuthClientCredentialsFlow
Scopes
Список областей, разделенных запятыми, для запроса.
OAuthAuthorizationCodeFlow или OAuthClientCredentialsFlow
ClientId
Идентификатор клиента, используемый при запросе маркера.
OAuthAuthorizationCodeFlow или OAuthClientCredentialsFlow
ClientSecret
Секрет клиента, используемый при запросе маркера.
OAuthAuthorizationCodeFlow или OAuthClientCredentialsFlow
AuthorizationContentType
Тип контента, используемый при отправке запроса маркера.
В настоящее время можно предварительно настроить параметры только для одного типа проверки подлинности.
Можно предварительно настроить параметры проверки подлинности для подключаемого модуля в тех случаях, когда одинаковые значения будут использоваться для каждого экземпляра подключаемого модуля (например, для набора областей Microsoft Entra). Предварительная настройка параметров обрабатывается путем заполнения поля Authorization в дескрипторе коллекцией пар "ключ-значение" и типом проверки подлинности.
В следующем примере показано, как указать набор областей Microsoft Entra по умолчанию для типа проверки подлинности AAD.
Подключаемый модуль API с обычной проверкой подлинности
В этом кратком руководстве показано, как создать подключаемый модуль, использующий обычную проверку подлинности HTTP.
Примечание
Настоятельно рекомендуется использовать обычную проверку подлинности только с конечными точками API, которые используют HTTPS.
Создание спецификации OpenAPI
В этом примере мы будем использовать службу httpbin.org для проверки обычной проверки подлинности. Httpbin.org уже публикует и спецификацию OpenAPI, однако, например, для целей мы будем использовать только одну из операций.
НЕ ВВОДИТЕ существующее имя пользователя или пароль при настройке этого примера.
Учетные данные не проверяются, поэтому любые значения будут приняты.
После отправки подключаемого модуля введите имя пользователя и пароль для обычной проверки подлинности. Вы можете выполнить шаг сейчас или выбрать Сделать это позже, чтобы настроить его позже.
Если вы выбрали параметр Сделать это позже, вы можете настроить имя пользователя и пароль позже, нажав кнопку Настроить на странице управление подключаемыми модулями.
Если вы хотите обновить параметры после настройки, это можно сделать, щелкнув значок параметров на странице подключаемых модулей управления.
Подключаемый модуль API с проверкой подлинности ключа API
В этом кратком руководстве показано, как создать подключаемый модуль, который использует ключ API для проверки подлинности. При проверке подлинности с помощью ключа API используется секретный ключ или маркер, который передается как часть запроса либо в качестве параметра строки запроса, либо в качестве заголовка. Ключ API используется для проверки подлинности запроса и не привязан к конкретному пользователю.
Создание спецификации OpenAPI
В этом примере мы будем использовать службу httpbin.org для проверки подлинности ключа API. Httpbin.org уже публикует и спецификацию OpenAPI, однако, например, для целей мы будем использовать только одну из операций.
В этом примере мы настроим подключаемый модуль таким образом, чтобы отправить ключ API с помощью заголовка x-test-api-key . Мы предварительно настроим расположение ключа, но требуем, чтобы пользователь ввел значение ключа при установке подключаемого модуля.
Создайте файл plugin.yaml манифеста подключаемого модуля со следующим содержимым:
Descriptor:
Name: SampleAPIForApiKeyAuth
DisplayName: httpbin.org - API Key Authentication
Description: Plugin for making example http requests
SupportedAuthTypes:
- ApiKey
Authorization:
Type: APIKey
Key: x-test-api-key
Location: Header
AuthScheme: ''
SkillGroups:
- Format: API
Settings:
OpenApiSpecUrl: https://gist.githubusercontent.com/PetRich-MSFT/85c8ab522a15710302e5f1b6e7525f43/raw/99aab78b8e4cd933453591227565075d62ecd7df/openapi.yaml
НЕ вводите существующий ключ API при настройке этого примера.
Ключ API не проверяется, поэтому любые значения будут приняты.
После отправки подключаемого модуля вам будет предложено ввести ключ API для проверки подлинности. Вы можете завершить это сейчас или выбрать Сделать это позже, чтобы настроить его позже.
Если вы выбрали параметр Сделать это позже, вы можете настроить имя пользователя и пароль позже, нажав кнопку Настроить на странице управление подключаемыми модулями.
Если вы хотите обновить параметры после настройки, это можно сделать, щелкнув значок параметров на странице подключаемых модулей управления.
Подключаемый модуль API с настраиваемым URL-адресом конечной точки
В этом примере добавляется настраиваемое имя параметров InstanceURL, которое пользователь может настроить с помощью Security Copilot. Затем в группе навыков API добавляется параметр, который сообщает Security Copilot использовать значение параметра InstanceURL в качестве конечной точки для выполнения запросов API:
Descriptor:
Name: Example
Settings:
- Name: InstanceURL
Label: Instance URL
Description: The URL of the instance to connect to
HintText: "e.g. https://example.com"
SettingType: String
Required: true
SkillGroups:
- Format: API
Settings:
OpenApiSpecURL: https://example.com/openapi.json
EndpointUrlSettingName: InstanceURL
В следующем примере показано использование настраиваемого URL-адреса конечной точки с ключом API:
Descriptor:
Name: Example
Settings:
- Name: InstanceURL
Label: Instance URL
Description: The URL of the instance to connect to
HintText: "e.g. https://example.com"
SettingType: String
Required: true
SupportedAuthTypes:
- ApiKey
Authorization:
Type: APIKey
Key: session
Location: Header
AuthScheme: ''
SkillGroups:
- Format: API
Settings:
OpenApiSpecURL: https://example.com/openapi.json
EndpointUrlSettingName: InstanceURL
Подключаемый модуль API с OAuthAuthorizationCodeFlow
В этом кратком руководстве показано, как создать навык, который использует поток OAuthAuthorizationCodeFlow для проверки подлинности.
Создание манифеста подключаемого модуля
Создайте файл plugin.yaml манифеста подключаемого модуля со следующим содержимым и замените OpenApiSpecUrl значения и EndpointUrl из веб-приложения.
Descriptor:
Name: SamplePluginManifestOAuth
Description: Gets info via OAuth
DescriptionDisplay: Current DateTime, report status
DescriptionForModel: Shows an OAUTH Sample
DisplayName: WeatherNew
Authorization:
Type: OAuthAuthorizationCodeFlow
ClientId: <id of client that wants to auth>
AuthorizationEndpoint: https://sample.com/oauth2/v2.0/authorize
TokenEndpoint: https://sample.com/oauth2/v2.0/token
Scopes: <Scopes>
AuthorizationContentType: application/x-www-form-urlencoded
SkillGroups:
- Format: API
Settings:
OpenApiSpecUrl: https://sample.com
EndpointUrl: https://sample.com
Отправка манифеста подключаемого модуля
Следуйте инструкциям здесь, чтобы отправить манифест подключаемого модуля в Security Copilot.
Команды HTTP, которые обычно разрешают изменения состояния и операции записи (например, POST), можно использовать только для получения данных. Операции записи в настоящее время не поддерживаются.
Схема текста запроса должна быть ограничена глубиной до 1. Это означает, что родительский объект не может содержать вложенные объекты внутри себя. Нарушение этого ограничения глубины приведет к ошибке с кодом 2006.
2.1 Ниже приведен пример текста запроса с глубиной = 1:
Расширение декларативных агентов для Microsoft 365 Copilot с помощью подключаемых модулей API — это серия из нескольких частей, в котором описаны основные понятия расширения декларативных агентов с помощью действий с помощью подключаемых модулей API. Вы узнаете, что такое подключаемые модули API, как они работают и когда их следует создавать. Вы также узнаете, как использовать адаптивные карточки для полнофункциональной демонстрации данных и как подключиться к защищенным API.