Accédez à Gérer les plug-ins en sélectionnant le bouton Plug-in dans la barre d’invite.
Faites défiler vers le bas jusqu’à Personnalisé et sélectionnez Ajouter un plug-in.
Sélectionnez le plug-in OpenAI comme format de chargement, entrez https://hacktrack.routum.io/.well-known/ai-plugin.json comme lien et sélectionnez Ajouter.
Plug-in d’API à partir de l’API existante
Ce didacticiel de démarrage rapide montre comment transformer une API existante en plug-in d’API Sécurité Copilot.
Créer la spécification OpenAPI
Si l’API a déjà une spécification OpenAPI, vous pouvez simplement l’utiliser. Hébergez la spécification OpenAPI https://[domaine]/template.yaml.
Créez un fichier manifeste de plug-in avec le contenu suivant (en remplaçant la valeur OpenaApiSpecUrl par l’URL du fichier de spécification OpenAPI créé dans la section précédente) :
Sécurité Copilot prend en charge plusieurs schémas pour l’authentification des plug-ins :
Jeu
Description
Prise en charge du manifeste Copilot
Prise en charge d’OpenAI +
Aucun
Pas d'authentification.
Oui
Oui
Basic
Authentification de base.
Oui
Non
ApiKey
Authentification basée sur ApiKey où un apiKey fourni par un développeur est passé dans un en-tête ou un paramètre de requête personnalisé.
Oui
Oui*
ServiceHttp
Authentification basée sur le jeton fourni.
Oui
Oui
OAuthAuthorizationCodeFlow
Le flux de code d’autorisation OAuth 2.0 est une méthode d’authentification plus sécurisée et plus complexe utilisée pour accorder l’accès à des applications non-Microsoft sans partager les informations d’identification de l’utilisateur.
Oui
Oui
OAuthClientCredentialsFlow
Comme l’authentification de base, mais utilisée pour la communication de serveur à serveur à la place ou lors de l’accès à des données publiques qui ne nécessitent pas d’autorisations spécifiques de l’utilisateur.
Oui
Non
Identifiant Microsoft Entra
Accès à l’application uniquement.
Oui
Oui*
AADDelegated
Accès utilisateur + application uniquement.
Oui
Oui*
+ Ce champ est utilisé pour indiquer les deux types de chargement pris en charge dans Sécurité Copilot.
* Celles-ci représentent des méthodes d’authentification qui sont étendues au-delà de ce qui était initialement pris en charge par openAI.
Le tableau suivant présente les paramètres pris en charge pour chaque type d’authentification.
Type d’authentification
Setting
Description
AAD ou AADDelegated
EntraScopes
Liste séparée par des virgules des étendues Microsoft Entra à demander.
Basic
Username
Nom d’utilisateur à utiliser pour l’authentification de base.
Basic
Password
Mot de passe à utiliser pour l’authentification de base.
ApiKey ou ServiceHttp
Key
Nom du paramètre header/query.
ApiKey ou ServiceHttp
AuthScheme
Nom du schéma d’authentification, ajouté au Value lorsqu’il est utilisé dans un en-tête.
ApiKey ou ServiceHttp
Location
Emplacement de la clé API, ou HeaderQueryParams.
ApiKey ou ServiceHttp
Value
Clé/jeton à utiliser.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow
TokenEndpoint
Point de terminaison à partir duquel demander le jeton.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow
Scopes
Liste séparée par des virgules des étendues à demander.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow
ClientId
ID client à utiliser lors de la demande du jeton.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow
ClientSecret
Clé secrète client à utiliser lors de la demande du jeton.
OAuthAuthorizationCodeFlow ou OAuthClientCredentialsFlow
AuthorizationContentType
Type de contenu utilisé lors de l’envoi de la demande de jeton.
OAuthAuthorizationCodeFlow
AuthorizationEndpoint
Point de terminaison à partir duquel demander le code d’autorisation.
Préconfiguration des paramètres d’authentification
Notes
Il n’est actuellement possible de préconfigurer les paramètres que pour un seul type d’authentification.
Il est possible de préconfigurer les paramètres d’authentification pour votre plug-in dans les cas où les mêmes valeurs seront utilisées pour chaque instance de votre plug-in (par exemple, l’ensemble des étendues Microsoft Entra). La préconfiguration des paramètres est gérée en complétant le Authorization champ dans le descripteur avec une collection de paires clé/valeur avec le type d’authentification.
L’exemple suivant montre comment spécifier un ensemble par défaut d’étendues Microsoft Entra pour le type d’authentification AAD .
Ce tutoriel de démarrage rapide montre comment créer un plug-in qui utilise l’authentification HTTP de base.
Notes
Il est fortement recommandé d’utiliser l’authentification de base uniquement avec les points de terminaison d’API qui utilisent HTTPS.
Créer la spécification OpenAPI
Dans cet exemple, nous allons utiliser le service httpbin.org pour valider l’authentification de base. Httpbin.org publie déjà et la spécification OpenAPI. Toutefois, par exemple, nous n’allons utiliser qu’une seule des opérations.
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.
Créer le manifeste du plug-in
Dans cet exemple, nous allons utiliser le service httpbin.org pour valider l’authentification de base. Httpbin.org publie déjà et la spécification OpenAPI.
Créez un fichier plugin.yaml manifeste de plug-in avec le contenu suivant :
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
Charger le manifeste du plug-in
Suivez les instructions de Gestion des plug-ins pour charger le manifeste du plug-in dans Security Copilot.
Configuration de l’authentification
Avertissement
N’ENTREZ AUCUN nom d’utilisateur ou mot de passe existant lors de la configuration de cet exemple.
Les informations d’identification ne sont pas validées et toutes les valeurs sont donc acceptées.
Après avoir chargé le plug-in, entrez le nom d’utilisateur et le mot de passe de l’authentification de base. Vous pouvez effectuer l’étape maintenant ou sélectionner Effectuer ultérieurement pour la configurer ultérieurement.
Si vous avez choisi l’option Effectuer ultérieurement, vous pouvez configurer le nom d’utilisateur et le mot de passe ultérieurement en sélectionnant le bouton Configurer sur la page Gérer les plug-ins.
Si vous souhaitez mettre à jour les paramètres après la configuration, vous pouvez le faire en cliquant sur l’icône des paramètres dans la page des plug-ins de gestion.
Plug-in d’API avec authentification par clé API
Ce tutoriel de démarrage rapide montre comment créer un plug-in qui utilise une clé API pour s’authentifier. L’authentification par clé API utilise une clé secrète/un jeton qui est passé dans le cadre de la requête en tant que paramètre de chaîne de requête ou en tant qu’en-tête. La clé API est utilisée pour authentifier la demande et n’est pas liée à un utilisateur spécifique.
Créer la spécification OpenAPI
Dans cet exemple, nous allons utiliser le service httpbin.orgpour valider l’authentification par clé API. Httpbin.org publie déjà et la spécification OpenAPI. Toutefois, par exemple, nous n’allons utiliser qu’une seule des opérations.
Dans cet exemple, nous allons configurer le plug-in afin d’envoyer la clé API à l’aide d’un x-test-api-key en-tête. Nous allons préconfigurer l’emplacement de la clé, mais demander à l’utilisateur d’entrer la valeur de la clé lors de l’installation du plug-in.
Créez un fichier plugin.yaml manifeste de plug-in avec le contenu suivant :
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
Téléchargez le manifeste du plugin
Suivez les instructions de Gestion des plug-ins pour charger le manifeste du plug-in dans Security Copilot.
Configuration de l’authentification
Avertissement
N’ENTREZ aucune clé API existante lors de la configuration de cet exemple.
La clé API n’étant pas validée, toutes les valeurs seront acceptées.
Après avoir chargé le plug-in, vous êtes invité à entrer la clé API pour l’authentification. Vous pouvez effectuer cette opération maintenant ou sélectionner Effectuer ultérieurement pour la configurer ultérieurement.
Si vous avez choisi l’option Effectuer ultérieurement, vous pouvez configurer le nom d’utilisateur et le mot de passe ultérieurement en sélectionnant le bouton Configurer sur la page Gérer les plug-ins.
Si vous souhaitez mettre à jour les paramètres après la configuration, vous pouvez le faire en cliquant sur l’icône des paramètres dans la page des plug-ins de gestion.
Plug-in d’API avec URL de point de terminaison personnalisable
Cet exemple ajoute un nom de paramètre configurable « InstanceURL » que l’utilisateur peut configurer via Sécurité Copilot. Un paramètre est ensuite ajouté sous le groupe de compétences d’API qui indique à Sécurité Copilot d’utiliser la valeur du paramètre « InstanceURL » comme point de terminaison pour effectuer les demandes d’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’exemple suivant montre l’utilisation d’une URL de point de terminaison personnalisable avec une clé 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 d’API avec OAuthAuthorizationCodeFlow
Ce tutoriel de démarrage rapide montre comment créer une compétence qui utilise le flux OAuthAuthorizationCodeFlow pour l’authentification.
Créer le manifeste du plug-in
Créez un fichier plugin.yaml manifeste de plug-in avec le contenu suivant et remplacez les OpenApiSpecUrl valeurs et EndpointUrl de votre application 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
Charger le manifeste du plug-in
Suivez les instructions fournies ici pour charger le manifeste du plug-in dans Sécurité Copilot.
Les verbes HTTP qui autorisent généralement les modifications d’état et les opérations d’écriture (par exemple, POST) ne peuvent être utilisés qu’à des fins de récupération de données. Les opérations d’écriture ne sont actuellement pas prises en charge.
Les schémas du corps de la demande doivent être limités à une profondeur de 1. Cela signifie que l’objet parent ne peut pas contenir d’objets imbriqués en lui-même. Le non-respect de cette limitation de profondeur entraîne une erreur avec le code 2006.
2.1 Voici un exemple de corps de requête dont la profondeur est = 1 :
Étendre des agents déclaratifs pour Microsoft 365 Copilot avec des plug-ins d’API est une série en plusieurs parties qui vous apprend les concepts de base de l’extension des agents déclaratifs avec des actions à l’aide de plug-ins d’API. Vous découvrez ce que sont les plug-ins d’API, comment ils fonctionnent et quand vous devez envisager de les créer. Vous apprenez également à utiliser des cartes adaptatives pour afficher des données de manière enrichie et à vous connecter à des API sécurisées.