从现有 OpenAI 规范文件创建 API 插件
本快速入门教程介绍如何在安全 Copilot 中使用现有的 OpenAI 插件。
在本练习中，使用此清单文件： https://hacktrack.routum.io/.well-known/ai-plugin.json 。
上传插件清单
通过从提示栏中选择“插件”按钮，访问“管理插件”。
向下滚动到“自定义，然后选择“添加插件”。
选择“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 支持 + |
|---|---|---|---|
| 无 | 无需身份验证。 | 是 | 是 |
| 基本 | 基本身份验证。 | 是 | 否 |
| ApiKey | 基于 ApiKey 的身份验证，其中开发人员提供的 ApiKey 在自定义标头或查询参数中传递。 | 是 | 是* |
| ServiceHttp | 基于提供的令牌进行身份验证。 | 是 | 是 |
| OAuthAuthorizationCodeFlow | OAuth 2.0 授权代码流是一种更安全、更复杂的身份验证方法，用于在不共享用户凭据的情况下授予对非Microsoft应用程序的访问权限。 | 是 | 是 |
| OAuthClientCredentialsFlow | 与基本身份验证类似，但用于服务器到服务器通信，或用于访问不需要用户特定权限的公共数据的情况。 | 是 | 否 |
| Microsoft Entra ID | 仅限应用程序的访问权限。 | 是 | 是* |
| AADDelegated | 仅限用户 + 应用程序的访问权限。 | 是 | 是* |
+ 此字段用于指示安全 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 |
请求令牌时要使用的客户端 ID。 |
OAuthAuthorizationCodeFlow 或 OAuthClientCredentialsFlow |
ClientSecret |
请求令牌时使用的客户端密码。 |
OAuthAuthorizationCodeFlow 或 OAuthClientCredentialsFlow |
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 密钥以进行身份验证。 可以立即完成此操作，也可以选择“稍后执行此操作”以稍后进行配置。
如果选择“稍后执行此操作”选项，则可以在稍后通过选择“管理插件”页上的“设置”按钮来配置用户名和密码。
如果要在配置后更新设置，可以通过单击管理插件页中的设置图标来执行此作。
具有可自定义终结点 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。
配置身份验证
向下滚动到“自定义，然后选择“设置”。
输入客户端密码，然后选择“连接”。
你将看到帐户已成功链接的通知。
设置完成。
现在应启用该插件。
如果在选择“ 连接”时看到错误消息，请使用以下步骤来解决此错误： 
添加以下回调 URI（https://securitycopilot.microsoft.com/auth/v1/callback），如下图所示，并尝试重新连接。
限制
- 通常允许状态更改和写入作的 HTTP 谓词 (例如 POST) 只能用于数据检索目的。 目前不支持写入作。