Microsoft Copilot for Security 中的 API 外掛程式
本快速入門教學課程顯示如何在 Security Copilot 中使用現有的 OpenAI 外掛程式。
在此練習中,會使用 此資訊清單檔案。
從提示欄選取 [外掛程式] 按鈕,以存取 [管理外掛程式]。
向下卷動至 [自訂],然後選取 [新增外掛程式]。
選取 [OpenAI 外掛程式] 作為上傳格式,輸入
https://hacktrack.routum.io/.well-known/ai-plugin.json
作為連結,然後選取 [新增]。
本快速入門教學課程顯示如何將現有的 API 轉換成 Security Copilot API 外掛程式。
如果 API 已經有 OpenAPI 規格,則您可以直接使用它。 裝載 OpenAPI 規格 https://[domain]/template.yaml。
使用下列內容建立新的外掛程式資訊清單檔案 (使用上一章節中建立之 OpenAPI 規格檔案的 URL 取代 OpenaApiSpecUrl
值):
Descriptor:
Name:
DisplayName:
Description:
SkillGroups:
- Format: API
Settings:
OpenApiSpecUrl: https://[domain]/template.yaml
Security Copilot 支援數種適用於驗證外掛程式的配置:
配置 | 描述 | Copilot 資訊清單支援 | OpenAI 支援 + |
---|---|---|---|
無 | 不使用驗證。 | 是 | 是 |
Basic | 基本身份驗證。 | 是 | 否 |
ApiKey | ApiKey 型驗證,開發人員提供的 ApiKey 會在自定義標頭或查詢參數中傳遞。 | 是 | 是* |
ServiceHttp | 根據提供的令牌進行驗證。 | 是 | 是 |
OAuthAuthorizationCodeFlow | OAuth 2.0 授權碼流程是更安全且複雜的驗證方法,可用來授與非Microsoft應用程式的存取權,而不需要共用用戶認證。 | 是 | 是 |
OAuthClientCredentialsFlow | 如同基本驗證,但改為用於伺服器對伺服器通訊,或在存取不需要使用者特定權限的公用資料時使用。 | 是 | 否 |
Microsoft Entra ID | 僅限應用程式存取。 | 是 | 是* |
AADDelegated | 僅限使用者 + 應用程式存取。 | 是 | 是* |
+ 此欄位可用來指出 Security Copilot 中支援的兩種不同上傳類型。
* 這些代表擴充超過 openAI 最初支援的驗證方法。
下表顯示每個驗證類型的支援設定。
驗證類型 | 設定 | 描述 |
---|---|---|
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 |
要求令牌時要使用的用戶端標識碼。 |
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 來建立新的 gist,其中內容位於 https://gist.githubusercontent.com/PetRich-MSFT/fd3a8a92cbd7b6c120569a7a2c96c93c/raw/d1716b9022b140d702c31da59ff431c4b1fc603e/openapi.yaml
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
請遵循 [管理外掛程式] 中的指示,將外掛程式資訊清單上傳至 Security Copilot。
警告
設定此範例時,請勿 輸入任何現有的使用者名稱或密碼。 認證不會經過驗證,因此系統會接受任何值。
上傳外掛程式之後,請輸入基本驗證的使用者名稱和密碼。 您可以立即完成步驟,或選取 [稍後再執行此動作] 以進行設定。
如果您選擇 [稍後再執行此動作] 選項,則您稍後可以選取 [管理外掛程式] 頁面上的 [設定] 按鈕,來設定使用者名稱和密碼。
如果您想要在設定之後更新設定,您可以按下管理外掛程式頁面中的設定圖示來進行。
本快速入門教學課程顯示如何建立使用 API 金鑰驗證的外掛程式。 API 金鑰驗證會使用作為查詢字串參數或標頭的要求之一部分傳遞的秘密金鑰/權杖。 API 金鑰可用來驗證要求,且不會繫結至特定使用者。
在此範例中,我們將使用 httpbin.org 服務來驗證 API 金鑰驗證。 Httpbin.org 已發佈和 OpenAPI 規格,但例如,我們只會使用其中一個作業。
建立具有下列內容的新檔案,並將之上傳至可公開存取的位置。 本教學課程使用 GitHub Gist 來建立新的 gist,其中內容位於 https://gist.githubusercontent.com/PetRich-MSFT/85c8ab522a15710302e5f1b6e7525f43/raw/99aab78b8e4cd933453591227565075d62ecd7df/openapi.yaml
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
請遵循 [管理外掛程式] 中的指示,將外掛程式資訊清單上傳至 Security Copilot。
警告
設定此範例時,請勿 輸入任何現有的 API 金鑰。 API 金鑰未經驗證,因此系統會接受任何值。
上傳外掛程式之後,系統會提示您輸入 API 金鑰以進行驗證。 您可以立即完成,或選取 [稍後再執行此動作] 以稍後再進行設定。
如果您選擇 [稍後再執行此動作] 選項,則您稍後可以選取 [管理外掛程式] 頁面上的 [設定] 按鈕,來設定使用者名稱和密碼。
如果您想要在設定之後更新設定,您可以按下管理外掛程式頁面中的設定圖示來進行。
本範例會新增使用者可透過 Security Copilot 設定的可設定設定名稱 「InstanceURL」。 接著系統會在 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
本快速入門教學課程顯示如何建立使用 OAuthAuthorizationCodeFlow 流程進行驗證的技能。
使用下列內容建立新的外掛程式指令清單檔案 plugin.yaml
,並取代 Webapp 中的 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。
向下卷動至 [自訂],然後選取 [設定]。
輸入用戶端密碼,然後選取 [連線]。
您將會看到已成功連結帳戶的通知。
設定已完成。
系統現在應該會啟用外掛程式。
如果您在選取 [ 連線] 時看到錯誤訊息,請使用下列步驟來解決此錯誤:
新增下列回呼 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" ] }