Lire en anglais

Partager via


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

Plug-in d’API à partir d’un plug-in 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 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.

    Capture d’écran montrant le bouton Plug-in.

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

    Capture d’écran montrant le bouton 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.

    Capture d’écran montrant l’ajout d’un plug-in OpenAI.

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

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

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 .

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.

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.

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.

Capture d’écran montrant la boîte de dialogue Définir le nom d’utilisateur et le mot de passe

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.

Capture d’écran montrant l’option de configuration

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.

Capture d’écran montrant l’image Paramètres.

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.

Capture d’écran montrant Définir la clé API

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.

Capture d’écran montrant l’option Configurer.

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.

Capture d’écran des paramètres

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.

    Capture d’écran montrant les connexions de Mon organization

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

    Capture d’écran montrant l’étape d’entrée de la clé secrète client

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

    Image du navigateur web.

  5. Le programme d’installation est terminé.

    Image de status.

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 : Image du message d’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.

Image de la page d’authentification.

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