영어로 읽기

다음을 통해 공유


Microsoft Security Copilot의 API 플러그 인

기존 OpenAI 플러그 인의 API 플러그 인

이 빠른 시작 자습서에서는 Security Copilot에서 기존 OpenAI 플러그 인을 사용하는 방법을 보여줍니다.

이 연습에서는 이 매니페스트 파일이 사용됩니다.

플러그 인 매니페스트 업로드

  1. Microsoft Security Copilot 로그인합니다.

  2. 프롬프트 표시줄에서 플러그 인 단추를 선택하여 플러그 인 관리에 액세스합니다.

    플러그 인 단추를 보여 주는 스크린샷

  3. 사용자 지정까지 아래로 스크롤하고 플러그 인 추가를 선택합니다.

    플러그 인 추가 단추를 보여 주는 스크린샷

  4. 업로드 형식으로 OpenAI 플러그 인을 선택하고 링크로 https://hacktrack.routum.io/.well-known/ai-plugin.json을(를) 입력한 다음 추가를 선택합니다.

    OpenAI 플러그 인 추가를 보여 주는 스크린샷

기존 API의 API 플러그 인

이 빠른 시작 자습서에서는 기존 API를 Security Copilot API 플러그 인으로 전환하는 방법을 보여 줍니다.

OpenAPI 사양 만들기

API에 이미 OpenAPI 사양이 있는 경우 이를 사용할 수 있습니다. OpenAPI 사양 https://[domain]/template.yaml을 호스트합니다.

다음 내용으로 새 플러그 인 매니페스트 파일을 만듭니다(OpenaApiSpecUrl 값을 이전 섹션에서 만든 OpenAPI 사양 파일의 URL로 바꾸기).

Descriptor:
  Name: 
  DisplayName: 
  Description: 

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

API 인증

지원되는 체계

Security Copilot은 플러그 인을 인증하기 위한 몇 가지 체계를 지원합니다.

구성표 설명 Copilot 매니페스트 지원 OpenAI 지원 +
없음 인증이 없습니다.
Basic 기본 인증. 아니요
ApiKey 개발자가 제공한 ApiKey 기반 인증은 사용자 지정 헤더 또는 쿼리 매개 변수에 전달됩니다. 예*
ServiceHttp 제공된 토큰을 기반으로 하는 인증입니다.
OAuthAuthorizationCodeFlow OAuth 2.0 권한 부여 코드 흐름은 사용자 자격 증명을 공유하지 않고 타사 애플리케이션에 대한 액세스 권한을 부여하는 데 사용되는 보다 안전하고 복잡한 인증 방법입니다.
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 키 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 

플러그 인 매니페스트 업로드

플러그 인 관리의 지침에 따라 플러그 인 매니페스트를 Security 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. 

플러그 인 매니페스트 만들기

이 예제에서는 헤더를 사용하여 API 키를 보내도록 플러그 인을 x-test-api-key 구성합니다. 키의 위치를 미리 구성하지만 플러그 인을 설치할 때 사용자가 키 값을 입력하도록 요구합니다.

다음 내용을 사용하여 새 플러그 인 매니페스트 파일 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 키를 입력하라는 메시지가 표시됩니다. 지금 이 작업을 완료하거나 나중에 수행을 선택하여 나중에 구성할 수 있습니다.

API 키 설정을 보여 주는 스크린샷

나중에 수행 옵션을 선택한 경우 나중에 플러그 인 관리 페이지에서 설정 버튼을 선택하여 사용자 이름과 암호를 구성할 수 있습니다.

설정 옵션을 보여 주는 스크린샷.

구성 후 설정을 업데이트하려면 관리 플러그 인 페이지의 설정 아이콘을 클릭하여 이 작업을 수행할 수 있습니다.

설정 스크린샷

사용자 지정 가능한 엔드포인트 URL이 있는 API 플러그 인

이 예제에서는 사용자가 Security Copilot을 통해 구성할 수 있는 구성 가능한 설정 이름 "InstanceURL"을 추가합니다. 그런 다음, "InstanceURL" 설정의 값을 API 요청을 만들기 위한 엔드포인트로 사용하도록 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 만들고 웹앱의 OpenApiSpecUrlEndpointUrl 값을 바꿉니다.

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에 업로드합니다.

인증 구성

  1. Microsoft Security Copilot 로그인합니다.

  2. 사용자 지정까지 아래로 스크롤하고 설정을 선택합니다.

    내 organization 연결을 보여 주는 스크린샷

  3. 클라이언트 암호를 입력하고 연결을 선택합니다.

    클라이언트 암호를 입력하는 단계를 보여 주는 스크린샷

  4. 계정이 성공적으로 연결되었다는 알림이 표시됩니다.

    웹 브라우저의 이미지입니다.

  5. 설정이 완료되었습니다.

    상태 이미지입니다.

이제 플러그 인을 사용하도록 설정해야 합니다.

연결을 선택할 때 오류 메시지가 표시되면 다음 단계를 사용하여 오류 메시지 이미지를 해결합니다.

다음 이미지와 같이 다음 콜백 URI(https://securitycopilot.microsoft.com/auth/v1/callback)를 추가하고 다시 연결해 보세요.

인증 페이지의 이미지입니다.

제한 사항

  1. 일반적으로 상태 변경 및 쓰기 작업(예: POST)을 허용하는 HTTP 동사는 데이터 검색 목적으로만 사용할 수 있습니다. 쓰기 작업은 현재 지원되지 않습니다.

  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"
        ]
    }