Plug-ins de API no Copilot da Segurança da Microsoft

Crie um plug-in de API a partir de um arquivo de especificação OpenAI existente

Este tutorial de início rápido mostra como usar um plug-in da OpenAI existente no Copilot da Segurança.

Para este exercício, este arquivo de manifesto: https://hacktrack.routum.io/.well-known/ai-plugin.json é usado.

Carregar o manifesto do plug-in

1. Entre no Microsoft Security Copilot.

2. Acesse Gerenciar plug-ins selecionando o botão Plug-in na barra de solicitação.

   

3. Role para baixo até Personalizado e selecione Adicionar plug-in.

   

4. Selecione o plug-in da OpenAI como formato de upload, insira https://hacktrack.routum.io/.well-known/ai-plugin.json como o link e selecione Adicionar.

   

Plug-in de API da API existente

Este tutorial de início rápido mostra como transformar uma API existente em um plug-in de API do Copilot da Segurança.

Criar o arquivo de especificação de OpenAPI

Se a API já tiver um arquivo de especificação OpenAPI, você poderá simplesmente usá-lo. Hospede a especificação OpenAPI https://[domain]/template.yaml em um repositório acessível ou em um GitHub gist.

Crie um novo arquivo de manifesto do plug-in com o seguinte conteúdo (substituindo o valor OpenaApiSpecUrl pelo URL do arquivo de especificação da OpenAI criado na seção anterior):

Descriptor:
  Name: 
  DisplayName: 
  Description: 

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

Autenticação de API

Esquemas com suporte

O Copilot da Segurança dá suporte a vários esquemas para autenticação de plug-ins:

+ Este campo é usado para indicar os dois tipos diferentes de carregamento com suporte no Copilot da Segurança.

* Estes representam métodos de autenticação que são estendidos além do que foi inicialmente suportado pelo OpenAI.

A tabela a seguir mostra as configurações com suporte para cada tipo de autenticação.

Configurações de autenticação de predefinidas

É possível predefinir as configurações de autenticação do seu plug-in nos casos em que os mesmos valores serão usados para cada instância do seu plug-in (por exemplo, o conjunto de escopos do Microsoft Entra). A predefinição das configurações é feita preenchendo o campo Authorization no descritor com uma coleção de pares chave/valor junto com o tipo de autenticação.

O exemplo a seguir mostra como especificar um conjunto padrão de escopos do Microsoft Entra para o tipo de autenticação AAD.

Descriptor:
  Name: SampleAPI
  Description: Sample API
  SupportedAuthTypes:
    - AAD
  Authorization:
    Type: AAD
    EntraScopes: https://graph.microsoft.com/.default

As seções a seguir mostram exemplos de diferentes tipos de autenticação.

Plug-in de API com autenticação básica

Este tutorial de início rápido mostra como criar um plug-in que usa a autenticação Básica HTTP.

Criar a especificação da OpenAI

Neste exemplo, usaremos o serviço httpbin.org para validar a autenticação Básica. O httpbin.org já publica e especifica a OpenAI, porém, para fins de exemplo, usaremos apenas uma das operações.

Crie um novo arquivo com o conteúdo a seguir e carregue-o em um local publicamente acessível. Este tutorial usou o GitHub Gist para criar um novo gist com o conteúdo em 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.

Criar o manifesto do plug-in

Neste exemplo, usaremos o serviço httpbin.org para validar a autenticação Básica. O httpbin.org já publica e especifica a OpenAI.

Crie um novo arquivo de manifesto do plug-in plugin.yaml com o seguinte conteúdo:

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 

Carregar o manifesto do plug-in

Siga as instruções em Gerenciar plug-ins para carregar o manifesto do plug-in no Copilot da Segurança.

Configurar autenticação

Depois de carregar o plug-in, insira o nome de usuário e a senha para a autenticação Básica. Você pode concluir a etapa agora ou selecionar Fazer isso mais tarde para configurá-la posteriormente.

Se você escolher a opção Fazer isso mais tarde, poderá configurar o nome de usuário e a senha posteriormente selecionando o botão Configurar na página de gerenciamento de plug-ins.

Se você deseja atualizar as configurações após a configuração, pode fazê-lo clicando no ícone de configurações na página de plug-ins de gerenciamento.

Plug-in de API com autenticação de chave de API

Este tutorial de início rápido mostra como criar um plug-in que usa uma Chave de API para autenticação. A autenticação de Chave de API usa uma chave secreta/token que é passada como parte da solicitação como um parâmetro de cadeia de caracteres de consulta ou como um cabeçalho. A Chave de API é usada para autenticar a solicitação e não está vinculada a um usuário específico.

Criar a especificação da OpenAI

Neste exemplo, usaremos o serviço httpbin.org para validar a autenticação de chave de API. O httpbin.org já publica e especifica a OpenAI, porém, para fins de exemplo, usaremos apenas uma das operações.

Crie um novo arquivo com o conteúdo a seguir e carregue-o em um local publicamente acessível. Este tutorial usou o GitHub Gist para criar um novo gist com o conteúdo em 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. 

Criar o manifesto do plug-in

Neste exemplo, configuraremos o plug-in para enviar a chave de API usando um x-test-api-key cabeçalho. Pré-configuraremos o local da chave, mas exigiremos que o usuário insira o valor da chave ao instalar o plug-in.

Crie um novo arquivo de manifesto do plug-in plugin.yaml com o seguinte conteúdo:

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

Carregar o Manifesto do Plug-in

Siga as instruções em Gerenciar plug-ins para carregar o manifesto do plug-in no Copilot da Segurança.

Configurar autenticação

Depois de carregar o plug-in, você será solicitado a inserir a Chave de API para autenticação. Você pode concluir isso agora ou selecionar Fazer isso mais tarde para configurá-lo posteriormente.

Se você escolher a opção Fazer isso mais tarde, poderá configurar o nome de usuário e a senha posteriormente selecionando o botão Configurar na página de gerenciamento de plug-ins.

Se você deseja atualizar as configurações após a configuração, pode fazê-lo clicando no ícone de configurações na página de plug-ins de gerenciamento.

Plug-in de API com URL de ponto de extremidade personalizável

Este exemplo adiciona um nome de definições configuráveis "InstanceURL" que o usuário pode configurar por meio do Copilot da Segurança. Em seguida, uma configuração é adicionada no grupo de habilidades da API que instrui o Copilot da Segurança a usar o valor da configuração "InstanceURL" como o ponto de extremidade para fazer as solicitações de 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

O exemplo a seguir mostra o uso de um URL de ponto de extremidade personalizável com uma Chave de 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

Plug-in de API com OAuthAuthorizationCodeFlow

Este tutorial de início rápido mostra como criar uma habilidade que usa o fluxo OAuthAuthorizationCodeFlow para autenticação.

Criar o Manifesto do Plug-in

Crie um novo arquivo plugin.yaml de manifesto do plug-in com o conteúdo a seguir e substitua os OpenApiSpecUrl valores and EndpointUrl do seu aplicativo Web.

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

Carregar o Manifesto do Plug-in

Siga as instruções aqui para carregar o manifesto do plug-in no Copilot da Segurança.

Configurar a Autenticação

1. Entre no Microsoft Security Copilot.

2. Role para baixo até Personalizado e selecione Configuração.

   

3. Insira o segredo do cliente e selecione Conectar.

   

4. Você verá uma notificação de que a conta foi vinculada com sucesso.

   

5. A configuração foi concluída.

   

O plug-in agora deve ser habilitado.

Se você vir uma mensagem de erro ao selecionar Conectar, use as seguintes etapas para resolver o erro:

Adicione o seguinte URI de retorno de chamada (https://securitycopilot.microsoft.com/auth/v1/callback) conforme mostrado na imagem a seguir e tente se reconectar.

Limitações

1. Os verbos HTTP que normalmente permitem alterações de estado e operações de gravação (por exemplo, POST) só podem ser usados para fins de recuperação de dados. No momento, não há suporte para operações de gravação.