Plug-ins de API no Copilot da Segurança da Microsoft
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.
Inicie sessão no Microsoft Security Copilot.
Acesse Gerenciar plug-ins selecionando o botão Plug-in na barra de solicitação.
Role para baixo até Personalizado e selecione Adicionar plug-in.
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.
Este tutorial de início rápido mostra como transformar uma API existente em um plug-in de API do Copilot da Segurança.
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
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 Header QueryParams . |
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. |
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
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.
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.
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
Siga as instruções em Gerenciar plug-ins para carregar o manifesto do plug-in no Copilot da Segurança.
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.
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 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.
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.
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.
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
Siga as instruções em Gerenciar plug-ins para carregar o manifesto do plug-in no Copilot da Segurança.
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.
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 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.
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
Este tutorial de início rápido mostra como criar uma habilidade que usa o fluxo OAuthAuthorizationCodeFlow para autenticação.
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
Siga as instruções aqui para carregar o manifesto do plug-in no Copilot da Segurança.
Inicie sessão no Microsoft Security Copilot.
Role para baixo até Personalizado e selecione Configuração.
Insira o segredo do cliente e selecione Conectar.
Você verá uma notificação de que a conta foi vinculada com sucesso.
A configuração foi concluída.
O plug-in agora deve ser habilitado.
Se vir uma mensagem de erro ao selecionar Ligar, utilize os seguintes passos 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.
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.
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" ] }