Ler em inglês

Compartilhar via


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

Plug-in de API do Plug-in da 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 é usado.

Carregar o manifesto do plug-in

  1. Inicie sessão no Microsoft Security Copilot.

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

    Captura de ecrã a mostrar o botão Plug-in.

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

    Captura de ecrã a mostrar o botão 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.

    Captura de ecrã que mostra o plug-in Adicionar OpenAI.

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 a especificação da OpenAI

Se a API já tiver uma Especificação da OpenAI, você poderá usá-la normalmente. Hospede a especificação da OpenAI https://[domain]/template.yaml.

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:

Esquema Descrição Suporte ao manifesto do Copilot Suporte da OpenAI +
Nenhum Sem autenticação. Sim Sim
Básica Autenticação básica. Sim Não
ApiKey Autenticação baseada em ApiKey na qual um programador forneceu ApiKey é transmitida num cabeçalho personalizado ou parâmetro de consulta. Sim Sim*
ServiceHttp Autenticação com base no token fornecido. Sim Sim
OAuthAuthorizationCodeFlow O OAuth 2.0 Authorization Code Flow é um método de autenticação mais seguro e complexo utilizado para conceder acesso a aplicações que não sejam da Microsoft sem partilhar credenciais de utilizador. Sim Sim
OAuthClientCredentialsFlow Como a Autenticação Básica, mas usada para comunicação de servidor para servidor ou ao acessar dados públicos que não exigem permissões específicas do usuário. Sim Não
Microsoft Entra ID Acesso apenas à aplicação. Sim Sim*
AADDelegado Acesso apenas ao utilizador + aplicação. Sim Sim*

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

* Representam métodos de autenticação que são estendidos além do que inicialmente tinha suporte do OpenAI.

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

Tipo de Autenticação Setting Descrição
AAD ou AADDelegated EntraScopes Uma lista separada por vírgulas de âmbitos Microsoft Entra a pedir.
Basic Username O nome de utilizador a utilizar para autenticação básica.
Basic Password A palavra-passe a utilizar para autenticação básica.
ApiKey ou ServiceHttp Key O nome do parâmetro de cabeçalho/consulta.
ApiKey ou ServiceHttp AuthScheme O nome do esquema de autenticação, anexado ao Value quando utilizado num cabeçalho.
ApiKey ou ServiceHttp Location A localização da chave de API, ou HeaderQueryParams.
ApiKey ou ServiceHttp Value A chave/token a utilizar.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow TokenEndpoint O ponto final a partir do que pedir o token.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow Scopes Uma lista separada por vírgulas de âmbitos a pedir.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow ClientId O ID de cliente a utilizar ao pedir o token.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow ClientSecret O segredo do cliente a utilizar ao pedir o token.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow AuthorizationContentType O tipo de conteúdo utilizado ao enviar o pedido de token.
OAuthAuthorizationCodeFlow AuthorizationEndpoint O ponto final para pedir o código de autorização.

Configurações de autenticação de predefinidas

Observação

Atualmente, só é possível pré-configurar definições para um tipo de autenticação.

É 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

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.

Observação

É altamente recomendável que a autenticação básica seja usada apenas com pontos de extremidade de APIs que usam HTTPS.

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

Aviso

NÃO insira nenhum nome de usuário ou senha existente ao configurar este exemplo. As credenciais não são validadas, portanto, todos os valores serão aceitos.

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.

Captura de ecrã que mostra a caixa de diálogo Definir nome de utilizador e palavra-passe

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.

Captura de ecrã que mostra a Opção para configuração

Se quiser atualizar as definições após a configuração, pode fazê-lo ao clicar no ícone de definições na página de plug-ins de gestão.

Captura de ecrã a mostrar a imagem Definições.

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, vamos configurar o plug-in para enviar a Chave de API com 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

Aviso

NÃO insira nenhuma Chave de API existente ao configurar este exemplo. A chave de API não é validada, portanto, todos os valores serão aceitos.

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.

Captura de ecrã que mostra Definir Chave de API

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.

Captura de ecrã a mostrar a opção Configurar.

Se quiser atualizar as definições após a configuração, pode fazê-lo ao clicar no ícone de definições na página de plug-ins de gestão.

Captura de tela das configurações

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 ficheiro plugin.yaml de manifesto plug-in com os seguintes conteúdos e substitua os OpenApiSpecUrl valores e EndpointUrl da sua aplicação 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. Inicie sessão no Microsoft Security Copilot.

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

    Captura de ecrã que mostra as ligações da minha organização

  3. Insira o segredo do cliente e selecione Conectar.

    Captura de ecrã a mostrar Passo para introduzir o segredo do cliente

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

    Imagem do browser.

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

    Imagem de status.

O plug-in agora deve ser habilitado.

Se vir uma mensagem de erro ao selecionar Ligar, utilize os seguintes passos para resolver o erro: Imagem da mensagem de 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.

Imagem da página de autenticação.

Limitações

  1. Os verbos HTTP que normalmente permitem alterações de estado e operações de escrita (por exemplo, POST) só podem ser utilizados para fins de obtenção de dados. As operações de escrita não são atualmente suportadas.

  2. Os esquemas do corpo do pedido têm de estar limitados a uma profundidade de 1. Isto significa que o objeto principal não pode conter objetos aninhados dentro de si. Violar esta limitação de profundidade resultará num erro com o código 2006.

    2.1 Segue-se um exemplo de que o corpo do pedido tem profundidade = 1:

    {
        "id": "UserID",
        "name": "Alex Wilber",
        "email": "AlexW@contoso.com",
        "isActive": true
    }
    

    2.2 O corpo do pedido de exemplo seguinte não será aceite, uma vez que a profundidade é superior a 1:

    {
        "productId": 123456,
        "name": "Widget",
        "price": 9.99,
        "manufacturer": {
           "name" :"Tailspin Toys",
           "address": {
              "street" : "123 Anystreet",
              "city" : "Redmond",
              "zipcode": "98005"
            }
        },
        "tags": [
           "Holiday2024", "Popular"
        ]
    }