Complementos de API en Microsoft Copilot para seguridad
En este tutorial de inicio rápido se muestra cómo usar un complemento de OpenAI existente en Copilot de seguridad.
Para este ejercicio, se usaeste archivo de manifiesto.
Inicie sesión en Microsoft Security Copilot.
Para acceder a Administrar complementos, seleccione el botón Complemento en la barra de indicaciones.
Desplácese hacia abajo hasta Personalizado y seleccione Agregar complemento .
Seleccione elComplemento OpenAI como formato de carga, escriba
https://hacktrack.routum.io/.well-known/ai-plugin.json
como vínculo y seleccione Agregar.
En este tutorial de inicio rápido se muestra cómo convertir una API existente en un complemento de API de Copilot de seguridad.
Si la API ya tiene una especificación de OpenAPI, puede usarla. Hospede la especificación de OpenAPI https://[dominio]/template.yaml.
Cree un nuevo archivo de manifiesto de complemento con el siguiente contenido (reemplazando el OpenaApiSpecUrl
valor por la dirección URL del archivo de especificación de OpenAPI creado en la sección anterior):
Descriptor:
Name:
DisplayName:
Description:
SkillGroups:
- Format: API
Settings:
OpenApiSpecUrl: https://[domain]/template.yaml
Security Copilot admite varios esquemas para autenticar complementos:
Combinación | Descripción | Soporte de manifiesto de Copilot | Soporte técnico de OpenAI + |
---|---|---|---|
Ninguno | Sin autenticación. | Sí | Sí |
Basic | Autenticación básica. | Yes | No |
ApiKey | Autenticación basada en ApiKey en la que un desarrollador proporcionó ApiKey se pasa en un encabezado personalizado o un parámetro de consulta. | Sí | Sí* |
ServiceHttp | Autenticación basada en el token proporcionado. | Sí | Sí |
OAuthAuthorizationCodeFlow | OAuth 2.0 Authorization Code Flow es un método de autenticación más seguro y complejo que se usa para conceder acceso a aplicaciones que no son de Microsoft sin compartir credenciales de usuario. | Sí | Sí |
OAuthClientCredentialsFlow | Al igual que la autenticación básica, pero que se usa para la comunicación de servidor a servidor en su lugar o al acceder a datos públicos que no requieren permisos específicos del usuario. | Sí | No |
Microsoft Entra ID | Acceso solo a la aplicación. | Sí | Sí* |
AADDelegated | Acceso de usuario y aplicación solo. | Sí | Sí* |
+ Este campo se usa para indicar los dos tipos diferentes de carga admitidos en Security Copilot.
* Representan métodos de autenticación que se extienden más allá de lo que se admitía inicialmente en openAI.
En la tabla siguiente se muestra la configuración admitida para cada tipo de autenticación.
Tipo de autenticación | Configuración | Descripción |
---|---|---|
AAD o AADDelegated |
EntraScopes |
Lista separada por comas de Microsoft Entra ámbitos que se van a solicitar. |
Basic |
Username |
Nombre de usuario que se va a usar para la autenticación básica. |
Basic |
Password |
Contraseña que se va a usar para la autenticación básica. |
ApiKey o ServiceHttp |
Key |
Nombre del parámetro header/query. |
ApiKey o ServiceHttp |
AuthScheme |
Nombre del esquema de autenticación, antepuesto a cuando Value se usa en un encabezado. |
ApiKey o ServiceHttp |
Location |
Ubicación de la clave de API, ya sea Header o QueryParams . |
ApiKey o ServiceHttp |
Value |
Clave o token que se va a usar. |
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow |
TokenEndpoint |
Punto de conexión desde el que se va a solicitar el token. |
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow |
Scopes |
Lista separada por comas de los ámbitos que se van a solicitar. |
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow |
ClientId |
Identificador de cliente que se va a usar al solicitar el token. |
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow |
ClientSecret |
Secreto de cliente que se va a usar al solicitar el token. |
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow |
AuthorizationContentType |
Tipo de contenido usado al enviar la solicitud de token. |
OAuthAuthorizationCodeFlow |
AuthorizationEndpoint |
Punto de conexión desde el que se va a solicitar el código de autorización. |
Nota
Actualmente solo es posible preconfigurar la configuración de un tipo de autenticación.
Es posible preconfigurar la configuración de autenticación del complemento en los casos en los que se usarán los mismos valores para cada instancia del complemento (por ejemplo, el conjunto de ámbitos de Microsoft Entra). La preconfiguración de la configuración se controla rellenando el Authorization
campo en el descriptor con una colección de pares clave-valor junto con el tipo de autenticación.
En el ejemplo siguiente se muestra cómo especificar un conjunto predeterminado de ámbitos de Microsoft Entra para el AAD
tipo de autenticación.
Descriptor:
Name: SampleAPI
Description: Sample API
SupportedAuthTypes:
- AAD
Authorization:
Type: AAD
EntraScopes: https://graph.microsoft.com/.default
En este tutorial de inicio rápido se muestra cómo crear un complemento que usa la autenticación http básica.
Nota
Se recomienda encarecidamente que la autenticación básica solo se use con puntos de conexión de API que usan HTTPS.
En este ejemplo, usaremos el servicio httpbin.org para validar la autenticación básica. Httpbin.org ya publica y la especificación de OpenAPI, sin embargo, por ejemplo, solo vamos a usar una de las operaciones.
Cree un nuevo archivo con el siguiente contenido y cárguelo en algún lugar accesible públicamente. En este tutorial se ha usado GitHub Gist para crear un gist con el contenido en 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.
En este ejemplo, usaremos el servicio httpbin.org para validar la autenticación básica. Httpbin.org ya publica y la especificación de OpenAPI.
Cree un nuevo archivo plugin.yaml
de manifiesto de complemento con el siguiente contenido:
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 las instrucciones de Administración de complementos para cargar el manifiesto del complemento en Copilot de seguridad
Advertencia
NO escriba ningún nombre de usuario o contraseña existente al configurar este ejemplo. Las credenciales no se validan, por lo que se aceptarán los valores.
Después de cargar el complemento, escriba el nombre de usuario y la contraseña para la autenticación básica. Puede completar el paso ahora o seleccionar Hacer esto más adelante para configurarlo más adelante.
Si eligió la opción Hacer esto más adelante, puede configurar el nombre de usuario y la contraseña más adelante seleccionando el botónConfigurar en la página Administrar complementos.
Si desea actualizar la configuración después de la configuración, puede hacerlo haciendo clic en el icono de configuración de la página de complementos de administración.
En este tutorial de inicio rápido se muestra cómo crear un complemento que usa una clave de API para autenticarse. La autenticación de clave de API usa una clave secreta o token que se pasa como parte de la solicitud como parámetro de cadena de consulta o como encabezado. La clave de API se usa para autenticar la solicitud y no está vinculada a un usuario específico.
En este ejemplo, usaremos el servicio httpbin.org para validar la autenticación de la clave de API. Httpbin.org ya publica y la especificación de OpenAPI, sin embargo, por ejemplo, solo vamos a usar una de las operaciones.
Cree un nuevo archivo con el siguiente contenido y cárguelo en algún lugar accesible públicamente. En este tutorial se ha usado GitHub Gist para crear un gist con el contenido en 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.
En este ejemplo, configuraremos el complemento para enviar la clave de API mediante un x-test-api-key
encabezado. Preconfiguraremos la ubicación de la clave, pero se requerirá que el usuario escriba el valor de la clave al instalar el complemento.
Cree un nuevo archivo plugin.yaml
de manifiesto de complemento con el siguiente contenido:
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 las instrucciones de Administración de complementos para cargar el manifiesto del complemento en Copilot de seguridad
Advertencia
NO escriba ninguna clave de API existente al configurar este ejemplo. La clave de API no se valida, por lo que se aceptará cualquier valor.
Después de cargar el complemento, se le pedirá que escriba la clave de API para la autenticación. Puede completar esto ahora o seleccionar Hacer esto más adelante para configurarlo más adelante.
Si eligió la opción Hacer esto más adelante puede configurar el nombre de usuario y la contraseña más adelante seleccionando el botón Configurar en la página Administrar complementos.
Si desea actualizar la configuración después de la configuración, puede hacerlo haciendo clic en el icono de configuración de la página de complementos de administración.
En este ejemplo se agrega un nombre de configuración configurable "InstanceURL" que el usuario puede configurar a través de Security Copilot. A continuación, se agrega una configuración en el grupo de aptitudes de API que indica a Security Copilot que use el valor de la configuración "InstanceURL" como punto de conexión para realizar las solicitudes 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
En el ejemplo siguiente se muestra el uso de una dirección URL de punto de conexión personalizable con una clave 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
En este tutorial de inicio rápido se muestra cómo crear una aptitud que usa el flujo OAuthAuthorizationCodeFlow para la autenticación.
Cree un nuevo archivo plugin.yaml
de manifiesto de complemento con el siguiente contenido y reemplace los OpenApiSpecUrl
valores y EndpointUrl
de la aplicación 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 las instrucciones que se indican aquí para cargar el manifiesto del complemento en Security Copilot.
Inicie sesión en Microsoft Security Copilot.
Desplácese hacia abajo hasta Personalizado y seleccione Configuración .
Escriba el secreto de cliente y seleccione Conectar.
Verá una notificación de que la cuenta se ha vinculado correctamente.
La configuración está completa.
Ahora el complemento debe estar habilitado.
Si ve un mensaje de error al seleccionar Conectar, siga estos pasos para solucionar el error:
Agregue el siguiente URI de devolución de llamada (https://securitycopilot.microsoft.com/auth/v1/callback) como se muestra en la siguiente imagen e intente volver a conectarse.
Los verbos HTTP que normalmente permiten cambios de estado y operaciones de escritura (por ejemplo, POST) solo se pueden usar con fines de recuperación de datos. Actualmente no se admiten operaciones de escritura.
Los esquemas del cuerpo de la solicitud deben limitarse a una profundidad de 1. Esto significa que el objeto primario no puede contener objetos anidados dentro de sí mismo. Si se infringe esta limitación de profundidad, se producirá un error con el código 2006.
2.1 A continuación se muestra un ejemplo de que el cuerpo de la solicitud tiene profundidad = 1:
{ "id": "UserID", "name": "Alex Wilber", "email": "AlexW@contoso.com", "isActive": true }
2.2 El siguiente cuerpo de la solicitud de ejemplo no se aceptará, ya que la profundidad es 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" ] }