使用英语阅读

通过


Microsoft 安全 Copilot 中的 API 插件

现有 OpenAI 插件中的 API 插件

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

本练习中将使用此清单文件

上传插件清单

  1. 登录到 Microsoft Security Copilot

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

    显示“插件”按钮的屏幕截图。

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

    显示“添加插件”按钮的屏幕截图。

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

    显示“添加 OpenAI 插件”的屏幕截图。

现有 API 中的 API 插件

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

创建 OpenAPI 规范

如果 API 已具有 OpenAPI 规范,则可以使用它。 托管 OpenAPI 规范 https://[域]/template.yaml。

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

Descriptor:
  Name: 
  DisplayName: 
  Description: 

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

API 身份验证

支持的方案

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

方案 说明 Copilot 清单支持 OpenAI 支持 +
无需身份验证。
基本 基本身份验证。
ApiKey 基于 ApiKey 的身份验证,其中开发人员提供的 ApiKey 在自定义标头或查询参数中传递。 是*
ServiceHttp 基于提供的令牌进行身份验证。
OAuthAuthorizationCodeFlow OAuth 2.0 授权代码流是一种更安全、更复杂的身份验证方法,用于在不共享用户凭据的情况下授予对非Microsoft应用程序的访问权限。
OAuthClientCredentialsFlow 与基本身份验证类似,但用于服务器到服务器通信,或用于访问不需要用户特定权限的公共数据的情况。
Microsoft Entra ID 仅限应用程序的访问权限。 是*
AADDelegated 仅限用户 + 应用程序的访问权限。 是*

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

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

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

身份验证类型 Setting 说明
AADAADDelegated EntraScopes 要请求的Microsoft Entra范围的逗号分隔列表。
Basic Username 用于基本身份验证的用户名。
Basic Password 用于基本身份验证的密码。
ApiKeyServiceHttp Key 标头/查询参数的名称。
ApiKeyServiceHttp AuthScheme 身份验证方案的名称,在标头中使用时,前面附加 Value 在 上。
ApiKeyServiceHttp Location API 密钥的位置,或 HeaderQueryParams
ApiKeyServiceHttp Value 要使用的密钥/令牌。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow TokenEndpoint 要从中请求令牌的终结点。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow Scopes 要请求的范围的逗号分隔列表。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow ClientId 请求令牌时要使用的客户端 ID。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow ClientSecret 请求令牌时使用的客户端密码。
OAuthAuthorizationCodeFlowOAuthClientCredentialsFlow AuthorizationContentType 发送令牌请求时使用的内容类型。
OAuthAuthorizationCodeFlow AuthorizationEndpoint 要从中请求授权代码的终结点。

预配置身份验证设置

备注

目前只能预配置一种身份验证类型的设置。

如果插件的每个实例(例如 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 基本身份验证的插件。

备注

强烈建议仅将基本身份验证与使用 HTTPS 的 API 终结点配合使用。

创建 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 密钥。 由于不会验证 API 密钥,因此将接受任何值。

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

显示“设置 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.yamlOpenApiSpecUrl 并替换 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. 你将看到帐户已成功链接的通知。

    Web 浏览器的图像。

  5. 设置完成。

    状态的图像。

现在应启用该插件。

如果在选择“ 连接”时看到错误消息,请使用以下步骤来解决此错误: 错误消息的图像。

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

身份验证页的图像。

限制

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

  2. 请求正文架构的深度必须限制为 1。 这意味着父对象本身不能包含嵌套对象。 违反此深度限制将导致代码为 2006 的错误。

    2.1 下面是请求正文的深度 = 1 的示例:

    {
        "id": "UserID",
        "name": "Alex Wilber",
        "email": "AlexW@contoso.com",
        "isActive": true
    }
    

    2.2 以下示例请求正文不会被接受,因为深度大于 1:

    {
        "productId": 123456,
        "name": "Widget",
        "price": 9.99,
        "manufacturer": {
           "name" :"Tailspin Toys",
           "address": {
              "street" : "123 Anystreet",
              "city" : "Redmond",
              "zipcode": "98005"
            }
        },
        "tags": [
           "Holiday2024", "Popular"
        ]
    }