Microsoft 安全 Copilot 中的 API 插件

从现有 OpenAI 规范文件创建 API 插件

本快速入门教程介绍如何在安全 Copilot 中使用现有的 OpenAI 插件。

在本练习中，使用此清单文件： https://hacktrack.routum.io/.well-known/ai-plugin.json 。

上传插件清单

1. 登录到 智能 Microsoft Security Copilot 副驾驶®。

2. 通过从提示栏中选择“插件”按钮，访问“管理插件”。

   

3. 向下滚动到“自定义，然后选择“添加插件”。

   

4. 选择“OpenAI 插件”作为上传格式，输入 https://hacktrack.routum.io/.well-known/ai-plugin.json 作为链接，然后选择“添加”。

   

现有 API 中的 API 插件

本快速入门教程介绍如何将现有 API 转换为安全 Copilot API 插件。

创建 OpenAPI 规范文件

如果 API 已有 OpenAPI 规范文件，则可以使用它。 将 OpenAPI 规范 https://[domain]/template.yaml 托管在可访问的存储库或 GitHub gist 中。

使用以下内容创建新的插件清单文件（将 OpenaApiSpecUrl 值替换为在之前部分中创建的 OpenAPI 规范文件的 URL）：

Descriptor:
  Name: 
  DisplayName: 
  Description: 

SkillGroups:
  - Format: API
    Settings:
      OpenApiSpecUrl: https://[domain]/template.yaml

API 身份验证

支持的方案

安全 Copilot 支持多种验证插件身份的方案：

+ 此字段用于指示安全 Copilot 支持的两种不同类型的上传。

* 这些表示超出 openAI 最初支持范围的身份验证方法。

下表显示了每个身份验证类型的受支持设置。

预配置身份验证设置

如果插件的每个实例（例如 Microsoft Entra 作用域集）将使用相同的值，则可以为插件预配置身份验证设置。 预配置设置是通过使用键/值对集合以及身份验证类型在描述符中填充 Authorization 字段来处理的。

下面的示例演示了如何为 AAD 身份验证类型指定一组默认的 Microsoft Entra 作用域。

Descriptor:
  Name: SampleAPI
  Description: Sample API
  SupportedAuthTypes:
    - AAD
  Authorization:
    Type: AAD
    EntraScopes: https://graph.microsoft.com/.default

以下部分显示了不同身份验证类型的示例。

具有基本身份验证的 API 插件

本快速入门教程介绍了如何创建使用 HTTP 基本身份验证的插件。

创建 OpenAPI 规范

在此示例中，我们将使用 httpbin.org 服务来验证基本身份验证。 Httpbin.org 已发布和 OpenAPI 规范，但例如，我们只会使用其中一个操作。

创建包含以下内容的新文件，并将其上传到可公开访问的某个位置。 本教程使用 GitHub Gist 创建了包含位于 https://gist.githubusercontent.com/PetRich-MSFT/fd3a8a92cbd7b6c120569a7a2c96c93c/raw/d1716b9022b140d702c31da59ff431c4b1fc603e/openapi.yaml 的内容的新 gist

openapi: 3.0.0

info:
    title: httpbin.org
    description: A simple HTTP Request & Response Service.
    version: "0.9.2"

servers:
    - url: https://httpbin.org/

paths:
    /basic-auth/{user}/{passwd}:
        get: 
            operationId: TestBasicAuth
            description: |
              This is a plugin to test basic authentication 
              #ExamplePrompts Test Basic Auth using HTTPbin plugin
              #ExamplePrompts Use HTTPbin to test basic authorization 
            summary: Prompts the user for authorization using HTTP Basic 
            parameters:
                - in: path 
                  name: user
                  schema:
                    type: string
                  required: true
                - in: path
                  name: passwd 
                  schema:
                    type: string
                  required: true
            responses:
                200:
                    description: Successful authentication. 
                401:
                    description: Unsuccessful authentication.

创建插件清单

在此示例中，我们将使用 httpbin.org 服务来验证基本身份验证。 Httpbin.org 已发布和 OpenAPI 规范。

创建包含以下内容的新插件清单文件 plugin.yaml：

Descriptor:
  Name: SampleAPIForBasicAuth
  DisplayName: httpbin.org
  Description: Plugin for making example http requests
  SupportedAuthTypes:
    - Basic

SkillGroups:
  - Format: API
    Settings:
      OpenApiSpecUrl: https://gist.githubusercontent.com/PetRich-MSFT/fd3a8a92cbd7b6c120569a7a2c96c93c/raw/d1716b9022b140d702c31da59ff431c4b1fc603e/openapi.yaml 

上传插件清单

按照管理插件中的说明将插件清单上传到安全 Copilot。

配置身份验证

上传插件后，输入用于基本身份验证的用户名和密码。 可以立即完成该步骤，也可以选择“稍后执行此操作”以稍后进行配置。

如果选择“稍后执行此操作”选项，则可以在稍后通过选择“管理插件”页上的“设置”按钮来配置用户名和密码。

如果要在配置后更新设置，可以通过单击管理插件页中的设置图标来执行此作。

包含 API 密钥身份验证的 API 插件

本快速入门教程介绍如何创建使用 API 密钥进行身份验证的插件。 API 密钥身份验证使用机密密钥/令牌，该密钥/令牌将以查询字符串参数或标头形式作为请求的一部分传递。 API 密钥用于对请求进行身份验证，不与特定用户相关联。

创建 OpenAPI 规范

在此示例中，我们将使用 httpbin.org 服务来验证 API 密钥身份验证。 Httpbin.org 已发布和 OpenAPI 规范，但例如，我们只会使用其中一个操作。

创建包含以下内容的新文件，并将其上传到可公开访问的某个位置。 本教程使用 GitHub Gist 创建了包含位于 https://gist.githubusercontent.com/PetRich-MSFT/85c8ab522a15710302e5f1b6e7525f43/raw/99aab78b8e4cd933453591227565075d62ecd7df/openapi.yaml 的内容的新 gist

openapi: 3.0.0

info:
    title: httpbin.org
    description: A simple HTTP Request & Response Service.
    version: "0.9.2"

servers:
    - url: https://httpbin.org/

paths:
    /headers:
        get: 
            operationId: TestApiKeyAuth
            summary: Returns the provided headers
            responses:
                200:
                    description: Successful request. 

创建插件清单

在此示例中，我们将配置插件，以便使用 x-test-api-key 标头发送 API 密钥。 我们将预配置密钥的位置，但要求用户在安装插件时输入密钥值。

创建包含以下内容的新插件清单文件 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

上传插件清单

按照管理插件中的说明将插件清单上传到安全 Copilot。

配置身份验证

上传插件后，系统会提示输入 API 密钥以进行身份验证。 可以立即完成此操作，也可以选择“稍后执行此操作”以稍后进行配置。

如果选择“稍后执行此操作”选项，则可以在稍后通过选择“管理插件”页上的“设置”按钮来配置用户名和密码。

如果要在配置后更新设置，可以通过单击管理插件页中的设置图标来执行此作。

具有可自定义终结点 URL 的 API 插件

此示例会添加用户可以通过安全 Copilot 配置的可配置设置名称“InstanceURL”。 然后，将在 API 技能组下添加一个设置，用于告知安全 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

使用 OAuthAuthorizationCodeFlow 的 API 插件

本快速入门教程介绍如何创建使用 OAuthAuthorizationCodeFlow 流进行身份验证的技能。

创建插件清单

使用以下内容创建新的插件清单文件 plugin.yaml ， OpenApiSpecUrl 并替换 Web 应用中的 和 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

上传插件清单

按照此处的说明将插件清单上传到安全 Copilot。

配置身份验证

1. 登录到 智能 Microsoft Security Copilot 副驾驶®。

2. 向下滚动到“自定义，然后选择“设置”。

   

3. 输入客户端密码，然后选择“连接”。

   

4. 你将看到帐户已成功链接的通知。

   

5. 设置完成。

   

现在应启用该插件。

如果在选择“ 连接”时看到错误消息，请使用以下步骤来解决此错误：

添加以下回调 URI（https://securitycopilot.microsoft.com/auth/v1/callback），如下图所示，并尝试重新连接。

限制

1. 通常允许状态更改和写入作的 HTTP 谓词 (例如 POST) 只能用于数据检索目的。 目前不支持写入作。