Leer en inglés

Compartir a través de


Complementos de API en Microsoft Copilot para seguridad

Complemento de API del complemento OpenAI existente

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.

Carga del manifiesto del complemento

  1. Inicie sesión en Microsoft Security Copilot.

  2. Para acceder a Administrar complementos, seleccione el botón Complemento en la barra de indicaciones.

    Captura de pantalla que muestra el botón Complemento.

  3. Desplácese hacia abajo hasta Personalizado y seleccione Agregar complemento .

    Captura de pantalla que muestra el botón Agregar complemento.

  4. Seleccione elComplemento OpenAI como formato de carga, escriba https://hacktrack.routum.io/.well-known/ai-plugin.json como vínculo y seleccione Agregar.

    Captura de pantalla que muestra el complemento Agregar OpenAI.

Complemento de API de la API existente

En este tutorial de inicio rápido se muestra cómo convertir una API existente en un complemento de API de Copilot de seguridad.

Creación de la especificación de OpenAPI

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

Autenticación API

Esquemas admitidos

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.
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í*
ServiceHttp Autenticación basada en el token proporcionado.
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.
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. No
Microsoft Entra ID Acceso solo a la aplicación. Sí*
AADDelegated Acceso de usuario y aplicación solo. 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.

Configuración de autenticación preconfigurada

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

Complemento de API con autenticación básica

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.

Creación de la especificación de OpenAPI

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.

Creación del manifiesto del complemento

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 

Carga del manifiesto del complemento

Siga las instrucciones de Administración de complementos para cargar el manifiesto del complemento en Copilot de seguridad

Configurar la autenticación

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.

Captura de pantalla que muestra el cuadro de diálogo Establecer nombre de usuario y contraseña

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.

Captura de pantalla que muestra la opción para configurar

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.

Captura de pantalla que muestra la imagen configuración.

Complemento de API con autenticación de clave de API

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.

Creación de la especificación de OpenAPI

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. 

Creación del manifiesto del complemento

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

Carga del manifiesto del complemento

Siga las instrucciones de Administración de complementos para cargar el manifiesto del complemento en Copilot de seguridad

Configurar la autenticación

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.

Captura de pantalla que muestra Establecer clave de API

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.

Captura de pantalla que muestra la opción Configurar.

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.

Captura de pantalla de la configuración

Complemento de API con dirección URL de punto de conexión personalizable

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

Complemento de API con OAuthAuthorizationCodeFlow

En este tutorial de inicio rápido se muestra cómo crear una aptitud que usa el flujo OAuthAuthorizationCodeFlow para la autenticación.

Creación del manifiesto del complemento

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

Carga del manifiesto del complemento

Siga las instrucciones que se indican aquí para cargar el manifiesto del complemento en Security Copilot.

Configurar la autenticación

  1. Inicie sesión en Microsoft Security Copilot.

  2. Desplácese hacia abajo hasta Personalizado y seleccione Configuración .

    Captura de pantalla que muestra las conexiones de mi organización

  3. Escriba el secreto de cliente y seleccione Conectar.

    Captura de pantalla que muestra El paso para escribir el secreto de cliente

  4. Verá una notificación de que la cuenta se ha vinculado correctamente.

    Imagen del explorador web.

  5. La configuración está completa.

    Imagen de estado.

Ahora el complemento debe estar habilitado.

Si ve un mensaje de error al seleccionar Conectar, siga estos pasos para solucionar el error: Imagen del mensaje de 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.

Imagen de la página de autenticación.

Limitaciones

  1. 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.

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