Microsoft Security Copilot の API プラグイン
[アーティクル] 2024/12/12
7 人の共同作成者
フィードバック
この記事の内容
既存の OpenAI プラグインからの API プラグイン
既存の API からの API プラグイン
API 認証
基本認証を使用した API プラグイン
API キー認証を使用した API プラグイン
カスタマイズ可能なエンドポイント URL を含む API プラグイン
OAuthAuthorizationCodeFlow を使用した API プラグイン
制限事項
さらに 4 個を表示
既存の OpenAI プラグインからの API プラグイン
このクイックスタート チュートリアルでは、Security Copilot で既存の OpenAI プラグインを使用する方法を示します。
この演習では、このマニフェスト ファイル が使用されます。
Microsoft Security Copilot にサインインします。
プロンプト バーから [プラグイン] ボタンを選択して、[プラグイン の管理] にアクセスします。
[カスタム] まで下にスクロールし、[プラグインの追加] を選択します。
アップロード形式として [OpenAI プラグイン] を選択し、リンクとして https://hacktrack.routum.io/.well-known/ai-plugin.json
を入力して [追加] を選択します。
このクイックスタート チュートリアルでは、既存の API を Security Copilot API プラグインに変える方法を示します。
API に既に OpenAPI 仕様がある場合は、それを使用できます。 OpenAPI 仕様 https://[domain]/template.yaml をホストします。
次の内容で新しいプラグイン マニフェスト ファイルを作成します (OpenaApiSpecUrl
値を、前のセクションで作成した OpenAPI 仕様ファイルへの URL に置き換えます):
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 でサポートされている 2 種類のアップロードを示すために使用されます。
* これらは、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
トークンを要求するときに使用するクライアント ID。
OAuthAuthorizationCodeFlow
または OAuthClientCredentialsFlow
ClientSecret
トークンを要求するときに使用するクライアント シークレット。
OAuthAuthorizationCodeFlow
または OAuthClientCredentialsFlow
AuthorizationContentType
トークン要求の送信時に使用されるコンテンツ タイプ。
OAuthAuthorizationCodeFlow
AuthorizationEndpoint
承認コードを要求するエンドポイント。
注意
現在、1 つの認証の種類の設定を事前に構成することのみ可能です。
プラグインのすべてのインスタンス (たとえば、Microsoft Entra スコープのセット) に同じ値が使用される場合は、プラグインの認証設定を事前構成できます。 設定の事前構成は、認証の種類とともにキーと値のペアのコレクションを記述子の Authorization
フィールドに設定することによって処理されます。
次の例は、AAD
認証の種類の Microsoft Entra スコープの既定のセットを指定する方法を示しています。
Descriptor:
Name: SampleAPI
Description: Sample API
SupportedAuthTypes:
- AAD
Authorization:
Type: AAD
EntraScopes: https://graph.microsoft.com/.default
このクイック スタート チュートリアルでは、HTTP Basic 認証を使用するプラグインを作成する方法について説明します。
注意
基本認証は、HTTPS を使用する API エンドポイントでのみ使用することを強くお勧めします。
この例では、httpbin.org サービスを使用して基本認証を検証します。 Httpbin.org は既に OpenAPI 仕様を公開していますが、たとえば、操作の 1 つだけを使用する目的で説明します。
次の内容を含む新しいファイルを作成し、公的にアクセスできる場所にアップロードします。 このチュートリアルでは、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
「プラグインの管理 」の手順に従って、プラグイン マニフェストを Security Copilot にアップロードします。
警告
この例を設定するときは、既存のユーザー名またはパスワードを入力しないでください 。
資格情報は検証されないため、任意の値が受け入れられます。
プラグインをアップロードした後、基本認証のユーザー名とパスワードを入力します。 この手順を今すぐ完了することも、[後で実行する] を選択して後で構成することもできます。
[後で実行する] オプションを選択した場合は、プラグインの管理ページで [設定] ボタンを選択することで、後でユーザー名とパスワードを構成できます。
構成後に設定を更新したい場合は、管理プラグイン ページの設定アイコンをクリックして更新できます。
このクイックスタート チュートリアルでは、API キーを使用して認証するプラグインを作成する方法を示します。 API キー認証では、要求の一部としてクエリ文字列パラメーターまたはヘッダーとして渡される秘密鍵/トークンを使用します。 API キーは要求の認証に使用され、特定のユーザーに関連付けられません。
この例では、httpbin.org サービスを使用して API キー認証を検証します。 Httpbin.org は既に OpenAPI 仕様を公開していますが、たとえば、操作の 1 つだけを使用する目的で説明します。
次の内容を含む新しいファイルを作成し、公的にアクセスできる場所にアップロードします。 このチュートリアルでは、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
「プラグインの管理 」の手順に従って、プラグイン マニフェストを Security Copilot にアップロードします。
警告
この例を設定するときは、既存の API キーを入力しないでください 。
API キーは検証されていないため、任意の値が受け入れられます。
プラグインをアップロードした後、認証用の API キーの入力を求められます。 これを今すぐ完了することも、[後で実行する] を選択して後で構成することもできます。
[後で実行する] オプションを選択した場合は、プラグインの管理ページで [設定] ボタンを選択することで、後でユーザー名とパスワードを構成できます。
構成後に設定を更新したい場合は、管理プラグイン ページの設定アイコンをクリックして更新できます。
カスタマイズ可能なエンドポイント URL を含む API プラグイン
この例では、ユーザーが Security Copilot を使用して構成できる構成可能な設定名 "InstanceURL" を追加します。 次に、API 要求を行うためのエンドポイントとして "InstanceURL" 設定の値を使用するように Security Copilot に指示する設定が 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
次の例は、API キーを使用したカスタマイズ可能なエンドポイント URL の使用を示しています:
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
を作成し、Web アプリの 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 にアップロードします。
Microsoft Security Copilot にサインインします。
[カスタム] まで下にスクロールし、[セットアップ] を選択します。
クライアント シークレットを入力し、[接続] を選択します。
アカウントが正常にリンクされたことを示す通知が表示されます。
セットアップが完了しました。
これでプラグインが有効になるはずです。
[接続] を選択したときにエラー メッセージが表示された場合は、次の手順に従ってエラーに対処します:
次の画像に示すように、次のコールバック URI (https://securitycopilot.microsoft.com/auth/v1/callback ) を追加し、再接続してみます。
通常、状態の変更や書き込み操作 (POST など) を許可する HTTP 動詞は、データ取得の目的でのみ使用できます。 書き込み操作は現在サポートされていません。
要求本文スキーマは、深さを 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"
]
}