Per accedere a Gestisci plug-in, selezionare il pulsante Plug-in dalla barra delle richieste.
Scorrere verso il basso fino a Personalizzato e selezionare Aggiungi plug-in.
Selezionare il plug-in OpenAI come formato di caricamento, immettere https://hacktrack.routum.io/.well-known/ai-plugin.json come collegamento e selezionare Aggiungi.
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):
Security Copilot supporta diversi schemi per l'autenticazione dei plug-in:
Schema
Descrizione
Supporto del manifesto Copilot
Supporto di OpenAI +
Nessuno
Nessuna autenticazione.
Sì
Sì
Basic
Autenticazione di base.
Sì
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ì
Sì*
ServiceHttp
Autenticazione basata sul token fornito.
Sì
Sì
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.
Sì
Sì
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.
Sì
No
Microsoft Entra ID
Accesso solo all'applicazione.
Sì
Sì*
AADDelegated
Accesso solo utente e applicazione.
Sì
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.
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.
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.
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.
Per aggiornare le impostazioni dopo la configurazione, è possibile fare clic sull'icona delle impostazioni nella pagina dei plug-in di gestione.
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.
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.
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.
Se si desidera aggiornare le impostazioni dopo la configurazione, è possibile farlo facendo clic sull'icona delle impostazioni nella pagina dei plug-in di gestione.
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.
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.
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:
Estendere gli agenti dichiarativi per Microsoft 365 Copilot con i plug-in API è una serie in più parti che illustra i concetti di base dell'estensione degli agenti dichiarativi con azioni tramite plug-in API. Si apprendono quali sono i plug-in API, come funzionano e quando è consigliabile crearli. Si apprenderà anche come usare le schede adattive per visualizzare i dati in modo completo e come connettersi alle API protette.