Plug-ins d’API dans Microsoft Copilot pour la Sécurité

Créer un plug-in d’API à partir d’un fichier de spécification OpenAI existant

Ce didacticiel de démarrage rapide montre comment utiliser un plug-in OpenAI existant dans Sécurité Copilot.

Pour cet exercice, ce fichier manifeste est https://hacktrack.routum.io/.well-known/ai-plugin.json utilisé.

Charger le manifeste du plug-in

1. Connectez-vous à Microsoft Security Copilot.

2. Accédez à Gérer les plug-ins en sélectionnant le bouton Plug-in dans la barre d’invite.

   

3. Faites défiler vers le bas jusqu’à Personnalisé et sélectionnez Ajouter un plug-in.

   

4. 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 le fichier de spécification OpenAPI

Si l’API a déjà un fichier de spécification OpenAPI, vous pouvez simplement l’utiliser. Hébergez la spécification OpenAPI https://[domaine]/template.yaml dans un dépôt accessible ou un gist GitHub.

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) :

Descriptor:
  Name: 
  DisplayName: 
  Description: 

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

Authentification d’API

Schémas pris en charge

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

Remarque

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 .

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

Plug-in d’API avec authentification de base

Ce tutoriel de démarrage rapide montre comment créer un plug-in qui utilise l’authentification HTTP de base.

Remarque

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.

Créez un fichier avec le contenu suivant et chargez-le dans un emplacement accessible publiquement. Ce tutoriel a utilisé GitHub Gist pour créer un gist avec le contenu à 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.

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.

Créez un fichier avec le contenu suivant et chargez-le dans un emplacement accessible publiquement. Ce tutoriel a utilisé GitHub Gist pour créer un gist avec le contenu à 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. 

Créer le manifeste du plug-in

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.

Configurer l’authentification

1. Connectez-vous à Microsoft Security Copilot.

2. Faites défiler vers le bas jusqu’à Personnalisé, puis sélectionnez Configuration.

   

3. Entrez la clé secrète client, puis sélectionnez Se connecter.

   

4. Vous verrez une notification indiquant que le compte a été lié avec succès.

   

5. Le programme d’installation est terminé.

   

Le plug-in doit maintenant être activé.

Si vous voyez un message d’erreur lorsque vous sélectionnez Se connecter, procédez comme suit pour résoudre l’erreur :

Ajoutez l’URL de rappel suivant (https://securitycopilot.microsoft.com/auth/v1/callback) comme indiqué dans l’image suivante et essayez de vous reconnecter.

Limitations

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

2. 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 :

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

   2.2 L’exemple de corps de requête suivant ne sera pas accepté, car la profondeur est supérieure à 1 :

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