Microsoft 安全 Copilot 中的 API 插件
本文内容
现有 OpenAI 插件中的 API 插件
现有 API 中的 API 插件
API 身份验证
具有基本身份验证的 API 插件
包含 API 密钥身份验证的 API 插件
具有可自定义终结点 URL 的 API 插件
使用 OAuthAuthorizationCodeFlow 的 API 插件
限制
显示另外 4 个
本快速入门教程介绍如何在安全 Copilot 中使用现有的 OpenAI 插件。
本练习中将使用此清单文件 。
登录到 Microsoft Security Copilot 。
通过从提示栏中选择“插件 ”按钮,访问“管理插件”。
向下滚动到“自定义 ,然后选择“添加插件 ”。
选择“OpenAI 插件 ”作为上传格式,输入 https://hacktrack.routum.io/.well-known/ai-plugin.json
作为链接,然后选择“添加 ”。
本快速入门教程介绍如何将现有 API 转换为安全 Copilot API 插件。
如果 API 已具有 OpenAPI 规范,则可以使用它。 托管 OpenAPI 规范 https://[域]/template.yaml。
使用以下内容创建新的插件清单文件(将 OpenaApiSpecUrl
值替换为在之前部分中创建的 OpenAPI 规范文件的 URL):
Descriptor:
Name:
DisplayName:
Description:
SkillGroups:
- Format: API
Settings:
OpenApiSpecUrl: https://[domain]/template.yaml
安全 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 密钥的位置,或 Header
QueryParams
。
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
本快速入门教程介绍了如何创建使用 HTTP 基本身份验证的插件。
备注
强烈建议仅将基本身份验证与使用 HTTPS 的 API 终结点配合使用。
在此示例中,我们将使用 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 密钥用于对请求进行身份验证,不与特定用户相关联。
在此示例中,我们将使用 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 密钥以进行身份验证。 可以立即完成此操作,也可以选择“稍后执行此操作 ”以稍后进行配置。
如果选择“稍后执行此操作 ”选项,则可以在稍后通过选择“管理插件”页上的“设置 ”按钮来配置用户名和密码。
如果要在配置后更新设置,可以通过单击管理插件页中的设置图标来执行此操作。
此示例会添加用户可以通过安全 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。
登录到 Microsoft Security Copilot 。
向下滚动到“自定义 ,然后选择“设置 ”。
输入客户端密码,然后选择“连接 ”。
你将看到帐户已成功链接的通知。
设置完成。
现在应启用该插件。
如果在选择“ 连接 ”时看到错误消息,请使用以下步骤来解决此错误:
添加以下回调 URI(https://securitycopilot.microsoft.com/auth/v1/callback ),如下图所示,并尝试重新连接。
通常允许状态更改和写入操作的 HTTP 谓词 (例如 POST) 只能用于数据检索目的。 目前不支持写入操作。
请求正文架构的深度必须限制为 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"
]
}