Leggere in inglese

Condividi tramite


Plug-in API in Microsoft Security Copilot

Plug-in API dal plug-in OpenAI esistente

Questa esercitazione introduttiva illustra come usare un plug-in OpenAI esistente in Security Copilot.

Per questo esercizio viene usato questo file manifesto.

Caricare il manifesto del plug-in

  1. Accedere a Microsoft Security Copilot.

  2. Per accedere a Gestisci plug-in, selezionare il pulsante Plug-in dalla barra delle richieste.

    Screenshot che mostra il pulsante Plug-in.

  3. Scorrere verso il basso fino a Personalizzato e selezionare Aggiungi plug-in.

    Screenshot che mostra il pulsante Aggiungi plug-in.

  4. Selezionare il plug-in OpenAI come formato di caricamento, immettere https://hacktrack.routum.io/.well-known/ai-plugin.json come collegamento e selezionare Aggiungi.

    Screenshot che mostra Aggiungi plug-in OpenAI.

Plug-in API dall'API esistente

Questa esercitazione introduttiva illustra come trasformare un'API esistente in un plug-in dell'API Security Copilot.

Creare la specifica OpenAPI

Se l'API ha già una specifica OpenAPI, è sufficiente usarla. Ospitare la specifica OpenAPI https://[domain]/template.yaml.

Creare un nuovo file manifesto del plug-in con il contenuto seguente (sostituendo il valore OpenaApiSpecUrl con l'URL del file della specifica OpenAPI creato nella sezione precedente):

Descriptor:
  Name: 
  DisplayName: 
  Description: 

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

Autenticazione API

Schemi supportati

Security Copilot supporta diversi schemi per l'autenticazione dei plug-in:

Schema Descrizione Supporto del manifesto Copilot Supporto di OpenAI +
Nessuno Nessuna autenticazione.
Basic Autenticazione di base. No
ApiKey L'autenticazione basata su ApiKey in cui uno sviluppatore ha fornito ApiKey viene passata in un'intestazione personalizzata o in un parametro di query. Sì*
ServiceHttp Autenticazione basata sul token fornito.
OAuthAuthorizationCodeFlow Il flusso di codice di autorizzazione OAuth 2.0 è un metodo di autenticazione più sicuro e complesso usato per concedere l'accesso ad applicazioni non Microsoft senza condividere le credenziali utente.
OAuthClientCredentialsFlow È analoga all'autenticazione di base, ma viene usata per la comunicazione da server a server o quando si accede a dati pubblici che non richiedono autorizzazioni specifiche dell'utente. No
Microsoft Entra ID Accesso solo all'applicazione. Sì*
AADDelegated Accesso solo utente e applicazione. Sì*

+ Questo campo viene usato per indicare i due diversi tipi di caricamento supportati in Security Copilot.

* Rappresentano metodi di autenticazione al di là di quanto inizialmente supportato da openAI.

La tabella seguente illustra le impostazioni supportate per ogni tipo di autenticazione.

Tipo di autenticazione Impostazione Descrizione
AAD o AADDelegated EntraScopes Elenco delimitato da virgole di ambiti Microsoft Entra da richiedere.
Basic Username Nome utente da usare per l'autenticazione di base.
Basic Password Password da usare per l'autenticazione di base.
ApiKey o ServiceHttp Key Nome del parametro di intestazione/query.
ApiKey o ServiceHttp AuthScheme Nome dello schema di autenticazione anteposto all'oggetto Value quando viene usato in un'intestazione.
ApiKey o ServiceHttp Location Percorso della chiave API, Header o QueryParams.
ApiKey o ServiceHttp Value Chiave/token da usare.
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow TokenEndpoint Endpoint da cui richiedere il token.
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow Scopes Elenco delimitato da virgole di ambiti da richiedere.
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow ClientId ID client da usare quando si richiede il token.
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow ClientSecret Segreto client da usare quando si richiede il token.
OAuthAuthorizationCodeFlow o OAuthClientCredentialsFlow AuthorizationContentType Tipo di contenuto usato durante l'invio della richiesta di token.
OAuthAuthorizationCodeFlow AuthorizationEndpoint Endpoint da cui richiedere il codice di autorizzazione.

Preconfigurazione delle impostazioni di autenticazione

Nota

Attualmente è possibile preconfigurare solo le impostazioni per un tipo di autenticazione.

È possibile preconfigurare le impostazioni di autenticazione per il plug-in nei casi in cui verranno usati gli stessi valori per ogni istanza del plug-in (ad esempio il set di ambiti Microsoft Entra). La preconfigurazione delle impostazioni viene gestita popolando il campo Authorization nel descrittore con una raccolta di coppie chiave/valore insieme al tipo di autenticazione.

Nell'esempio seguente viene illustrato come specificare un set predefinito di ambiti Microsoft Entra per il tipo di autenticazione AAD.

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

Plug-in API con autenticazione di base

Questa esercitazione introduttiva illustra come creare un plug-in che usa l'autenticazione di base HTTP.

Nota

È consigliabile usare l'autenticazione di base solo con gli endpoint API che usano HTTPS.

Creare la specifica OpenAPI

In questo esempio verrà usato il servizio httpbin.org per convalidare l'autenticazione di base. Httpbin.org già pubblica e specifica OpenAPI, tuttavia ai fini esplicativi, si userà solo una delle operazioni.

Creare un nuovo file con il contenuto seguente e caricarlo in un punto accessibile pubblicamente. Questa esercitazione ha usato GitHub Gist per creare un nuovo gist con il contenuto all'indirizzo 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.

Creare il manifesto del plug-in

In questo esempio verrà usato il servizio httpbin.org per convalidare l'autenticazione di base. Httpbin.org già pubblica e specifica OpenAPI.

Creare un nuovo file manifesto plugin.yaml del plug-in con il contenuto seguente:

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 

Caricare il manifesto del plug-in

Seguire le istruzioni in Gestire i plug-in per caricare il manifesto del plug-in in Security Copilot.

Configurare l'autenticazione

Avviso

NON immettere alcun nome utente o password esistente durante la configurazione di questo esempio. Le credenziali non vengono convalidate, pertanto tutti i valori verranno accettati.

Dopo aver caricato il plug-in, immettere il nome utente e la password per l'autenticazione di base. È possibile completare il passaggio ora oppure selezionare Esegui in un secondo momento per una configurazione successiva.

Screenshot che mostra la finestra di dialogo Imposta nome utente e password

Se si sceglie l'opzione Esegui in un secondo momento, è possibile configurare il nome utente e la password successivamente selezionando il pulsante Configura nella pagina di gestione plug-in.

Screenshot che mostra l'opzione per la configurazione

Per aggiornare le impostazioni dopo la configurazione, è possibile fare clic sull'icona delle impostazioni nella pagina dei plug-in di gestione.

Screenshot che mostra l'immagine Impostazioni.

Plug-in API con autenticazione della chiave API

Questa esercitazione introduttiva illustra come creare un plug-in che usa una chiave API per l'autenticazione. L'autenticazione della chiave API usa una chiave privata o un token trasmessi come parte della richiesta come parametro della stringa di query o come intestazione. La chiave API viene usata per autenticare la richiesta e non è associata a un utente specifico.

Creare la specifica OpenAPI

In questo esempio verrà usato il servizio httpbin.org per convalidare l'autenticazione della chiave API. Httpbin.org già pubblica e specifica OpenAPI, tuttavia ai fini esplicativi, si userà solo una delle operazioni.

Creare un nuovo file con il contenuto seguente e caricarlo in un punto accessibile pubblicamente. Questa esercitazione ha usato GitHub Gist per creare un nuovo gist con il contenuto all'indirizzo 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. 

Creare il manifesto del plug-in

In questo esempio si configurerà il plug-in in modo da inviare la chiave API usando un'intestazione x-test-api-key . Preconfigureremo la posizione della chiave, ma l'utente dovrà immetterne il valore all'installazione del plug-in.

Creare un nuovo file manifesto plugin.yaml del plug-in con il contenuto seguente:

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

Caricare il manifesto del plug-in

Seguire le istruzioni in Gestire i plug-in per caricare il manifesto del plug-in in Security Copilot.

Configurare l'autenticazione

Avviso

NON immettere chiavi API esistenti nella configurazione di questo esempio. La chiave API non viene convalidata, pertanto tutti i valori verranno accettati.

Dopo aver caricato il plug-in, verrà richiesto di immettere la chiave API per l'autenticazione. È possibile completare l'operazione subito o selezionare Esegui in un secondo momento per una configurazione successiva.

Screenshot che mostra Set API Key (Imposta chiave API)

Se si sceglie l'opzione Esegui in un secondo momento, è possibile configurare il nome utente e la password successivamente selezionando il pulsante Configura nella pagina di gestione plug-in.

Screenshot che mostra l'opzione Configura.

Se si desidera aggiornare le impostazioni dopo la configurazione, è possibile farlo facendo clic sull'icona delle impostazioni nella pagina dei plug-in di gestione.

Screenshot delle impostazioni

Plug-in API con URL dell'endpoint personalizzabile

In questo esempio viene aggiunto un nome di impostazioni configurabile "InstanceURL" che l'utente può configurare tramite Security Copilot. Viene quindi aggiunta un'impostazione nel gruppo di competenze dell'API che indica a Security Copilot di usare il valore dell'impostazione "InstanceURL" come endpoint per le richieste 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

L'esempio seguente illustra l'uso di un URL di endpoint personalizzabile con una chiave 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 API con OAuthAuthorizationCodeFlow

Questa esercitazione introduttiva illustra come creare una competenza che usa il flusso OAuthAuthorizationCodeFlow per l'autenticazione.

Creare il manifesto del plug-in

Creare un nuovo file plugin.yaml manifesto del plug-in con il contenuto seguente e sostituire i valori e EndpointUrl dell'app OpenApiSpecUrl 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

Caricare il manifesto del plug-in

Seguire le istruzioni riportate qui per caricare il manifesto del plug-in in Security Copilot.

Configurare l'autenticazione

  1. Accedere a Microsoft Security Copilot.

  2. Scorrere verso il basso fino a Personalizzato e selezionare Imposta.

    Screenshot che mostra le connessioni dell'organizzazione

  3. Immettere il segreto client e selezionare Connetti.

    Screenshot che mostra il passaggio per immettere il segreto client

  4. Verrà visualizzata una notifica che indica che l'account è stato collegato.

    Immagine del Web browser.

  5. Installazione completata.

    Immagine dello stato.

Il plug-in deve ora essere abilitato.

Se viene visualizzato un messaggio di errore quando si seleziona Connetti, seguire questa procedura per risolvere l'errore: Immagine del messaggio di errore.

Aggiungere l'URI di callback seguente (https://securitycopilot.microsoft.com/auth/v1/callback) come illustrato nell'immagine seguente e provare a riconnettersi.

Immagine della pagina di autenticazione.

Limitazioni

  1. I verbi HTTP che in genere consentono modifiche dello stato e operazioni di scrittura (ad esempio POST) possono essere usati solo a scopo di recupero dei dati. Le operazioni di scrittura non sono attualmente supportate.

  2. Gli schemi del corpo della richiesta devono essere limitati a una profondità pari a 1. Ciò significa che l'oggetto padre non può contenere oggetti annidati all'interno di se stesso. La violazione di questa limitazione di profondità genererà un errore con il codice 2006.

    2.1 Di seguito è riportato un esempio di corpo della richiesta con profondità = 1:

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

    2.2 Il corpo della richiesta di esempio seguente non verrà accettato perché la profondità è maggiore di 1:

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