Auf Englisch lesen

Freigeben über


API-Plug-Ins in Microsoft Security Copilot

API-Plug-In aus vorhandenem OpenAI-Plug-In

In diesem Schnellstarttutorial erfahren Sie, wie Sie ein vorhandenes OpenAI-Plug-In in Security Copilot verwenden.

In dieser Übung wird diese Manifestdatei verwendet.

Hochladen des Plug-In-Manifests

  1. Melden Sie sich bei Microsoft Security Copilot an.

  2. Greifen Sie auf "Plug-Ins verwalten" zu, indem Sie in der Eingabeaufforderungsleiste auf die Schaltfläche Plug-Ins klicken.

    Screenshot: Schaltfläche

  3. Scrollen Sie nach unten zu Benutzerdefiniert, und wählen Sie Plug-In hinzufügen aus.

    Screenshot: Schaltfläche

  4. Wählen Sie OpenAI-Plug-In als Uploadformat aus, geben Sie https://hacktrack.routum.io/.well-known/ai-plugin.json als Link ein, und wählen Sie Hinzufügen aus.

    Screenshot: Hinzufügen des OpenAI-Plug-Ins

API-Plug-In aus vorhandener API

In diesem Schnellstarttutorial erfahren Sie, wie Sie eine vorhandene API in ein Security Copilot-API-Plug-In umwandeln.

Erstellen der OpenAPI-Spezifikation

Wenn die API bereits über eine OpenAPI-Spezifikation verfügt, können Sie diese einfach verwenden. Hosten Sie die OpenAPI-Spezifikation https://[Domäne]/template.yaml.

Erstellen Sie eine neue Plug-In-Manifestdatei mit folgendem Inhalt (ersetzen Sie den OpenaApiSpecUrl-Wert durch die URL zur OpenAPI-Spezifikationsdatei, die sie im vorherigen Abschnitt erstellt hat):

Descriptor:
  Name: 
  DisplayName: 
  Description: 

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

API-Authentifizierung

Unterstützte Schemata

Security Copilot unterstützt mehrere Schemata für die Authentifizierung von Plug-Ins:

Schema Beschreibung Copilot-Manifestunterstützung OpenAI-Unterstützung +
Keine Keine Authentifizierung. Ja Ja
Standard Standardauthentifizierung. Ja Nein
ApiKey ApiKey-basierte Authentifizierung, bei der von einem Entwickler bereitgestellter ApiKey in einem benutzerdefinierten Header oder Abfrageparameter übergeben wird. Ja Ja*
ServiceHttp Authentifizierung basierend auf dem bereitgestellten Token. Ja Ja
OAuthAuthorizationCodeFlow Der OAuth 2.0-Autorisierungscodeflow ist eine sicherere und komplexere Authentifizierungsmethode, die verwendet wird, um Zugriff auf Nicht-Microsoft-Anwendungen zu gewähren, ohne Benutzeranmeldeinformationen freizugeben. Ja Ja
OAuthClientCredentialsFlow Wie die Standardauthentifizierung, wird aber stattdessen für die Server-zu-Server-Kommunikation oder beim Zugriff auf öffentliche Daten verwendet, für die keine benutzerspezifischen Berechtigungen erforderlich sind. Ja Nein
Microsoft Entra-ID Nur Anwendungszugriff. Ja Ja*
AADDelegated Nur Benutzer- und Anwendungszugriff. Ja Ja*

+ Dieses Feld wird verwendet, um die beiden verschiedenen Uploadtypen anzugeben, die in Security Copilot unterstützt werden.

* Diese stellen Authentifizierungsmethoden dar, die über das hinaus erweitert werden, was ursprünglich von openAI unterstützt wurde.

Die folgende Tabelle zeigt die unterstützten Einstellungen für jeden Authentifizierungstyp.

Authentifizierungstyp Einstellung Beschreibung
AAD oder AADDelegated EntraScopes Eine durch Trennzeichen getrennte Liste von Microsoft Entra bereichen, die anzufordern sind.
Basic Username Der Benutzername, der für die Standardauthentifizierung verwendet werden soll.
Basic Password Das Kennwort, das für die Standardauthentifizierung verwendet werden soll.
ApiKey oder ServiceHttp Key Der Name des Header-/Abfrageparameters.
ApiKey oder ServiceHttp AuthScheme Der Name des Authentifizierungsschemas, das dem Value vorangestellt wird, wenn es in einem Header verwendet wird.
ApiKey oder ServiceHttp Location Der Speicherort des API-Schlüssels, entweder Header oder QueryParams.
ApiKey oder ServiceHttp Value Der zu verwendende Schlüssel/Token.
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow TokenEndpoint Der Endpunkt, von dem das Token angefordert werden soll.
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow Scopes Eine durch Trennzeichen getrennte Liste von Bereichen, die anzufordern sind.
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow ClientId Die Client-ID, die beim Anfordern des Tokens verwendet werden soll.
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow ClientSecret Der geheime Clientschlüssel, der beim Anfordern des Tokens verwendet werden soll.
OAuthAuthorizationCodeFlow oder OAuthClientCredentialsFlow AuthorizationContentType Der Inhaltstyp, der beim Senden der Tokenanforderung verwendet wird.
OAuthAuthorizationCodeFlow AuthorizationEndpoint Der Endpunkt, von dem der Autorisierungscode anzufordern ist.

Vorkonfigurieren von Authentifizierungseinstellungen

Hinweis

Es ist derzeit nur möglich, Einstellungen für einen Authentifizierungstyp vorzukonfigurieren.

Es ist möglich, Authentifizierungseinstellungen für Ihr Plug-In vorkonfigurieren, wenn die gleichen Werte für jede Instanz Ihres Plug-Ins verwendet werden (z. B. für den Satz von Microsoft Entra-Bereichen). Die Vorkonfiguration der Einstellungen erfolgt durch Auffüllen des Authorization-Felds im Deskriptor mit einer Auflistung von Schlüssel-Wert-Paaren zusammen mit dem Authentifizierungstyp.

Das folgende Beispiel zeigt, wie Sie einen Standardsatz von Microsoft Entra-Bereichen für den AAD-Authentifizierungstyp angeben.

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

API-Plug-In mit Standardauthentifizierung

In diesem Schnellstarttutorial erfahren Sie, wie Sie ein Plug-In erstellen, das die HTTP-Standardauthentifizierung verwendet.

Hinweis

Es wird dringend empfohlen, die Standardauthentifizierung nur mit APIs-Endpunkten zu verwenden, die HTTPS verwenden.

Erstellen der OpenAPI-Spezifikation

In diesem Beispiel verwenden wir den httpbin.org-Dienst, um die Standardauthentifizierung zu überprüfen. Httpbin.org veröffentlicht bereits eine OpenAPI-Spezifikation, aber beispielsweise verwenden wir nur einen der Vorgänge.

Erstellen Sie eine neue Datei mit den folgenden Inhalten, und laden Sie sie an einem öffentlich zugänglichen Ort hoch. In diesem Tutorial wurde GitHub Gist verwendet, um einen neuen Gist mit dem Inhalt auf https://gist.githubusercontent.com/PetRich-MSFT/fd3a8a92cbd7b6c120569a7a2c96c93c/raw/d1716b9022b140d702c31da59ff431c4b1fc603e/openapi.yaml zu erstellen

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.

Erstellen des Plug-In-Manifests

In diesem Beispiel verwenden wir den httpbin.org-Dienst, um die Standardauthentifizierung zu überprüfen. Httpbin.org veröffentlicht bereits eine OpenAPI-Spezifikation.

Erstellen Sie eine neue Plug-In-Manifestdatei plugin.yaml mit folgendem Inhalt:

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 

Hochladen des Plug-In-Manifests

Befolgen Sie die Anweisungen in Verwalten von Plug-Ins, um das Plug-In-Manifest in Security Copilot hochzuladen.

Konfigurieren einer Authentifizierung

Warnung

Geben Sie bei der Einrichtung dieses Beispiels KEINEN bestehenden Benutzernamen und kein bestehendes Passwort ein. Die Anmeldeinformationen werden nicht überprüft, sodass alle Werte akzeptiert werden.

Geben Sie nach dem Hochladen des Plug-Ins den Benutzernamen und das Kennwort für die Standardauthentifizierung ein. Sie können den Schritt entweder jetzt abschließen oder Später tun auswählen, um ihn später zu konfigurieren.

Screenshot: Dialogfeld

Wenn Sie die Option Später tun ausgewählt haben, können Sie den Benutzernamen und das Kennwort später konfigurieren, indem Sie auf der Seite "Plug-Ins verwalten" die Schaltfläche Einrichten auswählen.

Screenshot: Option zum Einrichten

Wenn Sie die Einstellungen nach der Konfiguration aktualisieren möchten, können Sie dies tun, indem Sie auf der Seite mit den Verwaltungs-Plug-Ins auf das Einstellungssymbol klicken.

Screenshot: Abbildung

API-Plug-In mit API-Schlüsselauthentifizierung

In diesem Schnellstarttutorial erfahren Sie, wie Sie ein Plug-In erstellen, das einen API-Schlüssel für die Authentifizierung verwendet. Bei der API-Schlüsselauthentifizierung wird ein geheimer(s) Schlüssel/Token verwendet, der als Teil der Anforderung entweder als Abfragezeichenfolgenparameter oder als Header übergeben wird. Der API-Schlüssel wird zum Authentifizieren der Anforderung verwendet und ist nicht an einen bestimmten Benutzer gebunden.

Erstellen der OpenAPI-Spezifikation

In diesem Beispiel verwenden wir den httpbin.org-Dienst, um die API-Schlüsselauthentifizierung zu überprüfen. Httpbin.org veröffentlicht bereits eine OpenAPI-Spezifikation, aber beispielsweise verwenden wir nur einen der Vorgänge.

Erstellen Sie eine neue Datei mit den folgenden Inhalten, und laden Sie sie an einem öffentlich zugänglichen Ort hoch. In diesem Tutorial wurde GitHub Gist verwendet, um einen neuen Gist mit dem Inhalt auf https://gist.githubusercontent.com/PetRich-MSFT/85c8ab522a15710302e5f1b6e7525f43/raw/99aab78b8e4cd933453591227565075d62ecd7df/openapi.yaml zu erstellen

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. 

Erstellen des Plug-In-Manifests

In diesem Beispiel konfigurieren wir das Plug-In so, dass der API-Schlüssel mithilfe eines x-test-api-key Headers gesendet wird. Wir konfigurieren den Speicherort des Schlüssels vor, erfordern jedoch, dass der Benutzer bei der Installation des Plug-Ins den Schlüsselwert eingibt.

Erstellen Sie eine neue Plug-In-Manifestdatei plugin.yaml mit folgendem Inhalt:

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

Hochladen des Plug-In-Manifests

Befolgen Sie die Anweisungen in Verwalten von Plug-Ins, um das Plug-In-Manifest in Security Copilot hochzuladen.

Konfigurieren einer Authentifizierung

Warnung

Geben Sie bei der Einrichtung dieses Beispiels KEINEN bestehenden API-Schlüssel ein. Der API-Schlüssel wird nicht überprüft, sodass alle Werte akzeptiert werden.

Nach dem Hochladen des Plug-Ins werden Sie aufgefordert, den API-Schlüssel für die Authentifizierung einzugeben. Sie können den Schritt entweder jetzt abschließen oder Später tun auswählen, um ihn später zu konfigurieren.

Screenshot: Festlegen des API-Schlüssels

Wenn Sie die Option Später tun ausgewählt haben, können Sie den Benutzernamen und das Kennwort später konfigurieren, indem Sie auf der Seite "Plug-Ins verwalten" die Schaltfläche Einrichten auswählen.

Screenshot: Option

Wenn Sie die Einstellungen nach der Konfiguration aktualisieren möchten, können Sie dies tun, indem Sie auf der Seite mit den Verwaltungs-Plug-Ins auf das Einstellungssymbol klicken.

Screenshot der Einstellungen

API-Plug-In mit anpassbarer Endpunkt-URL

In diesem Beispiel wird der konfigurierbare Einstellungsname "InstanceURL" hinzugefügt, den der Benutzer über Security Copilot konfigurieren kann. Anschließend wird unter der API-Qualifikationsgruppe eine Einstellung hinzugefügt, die Security Copilot anweist, den Wert der Einstellung "InstanceURL" als Endpunkt für die API-Anforderungen zu verwenden:

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

Das folgende Beispiel zeigt die Verwendung einer anpassbaren Endpunkt-URL mit einem API-Schlüssel:

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

API-Plug-In mit OAuthAuthorizationCodeFlow

In diesem Schnellstarttutorial erfahren Sie, wie Sie eine Fähigkeit erstellen, die den OAuthAuthorizationCodeFlow-Fluss für die Authentifizierung verwendet.

Erstellen des Plug-In-Manifests

Erstellen Sie eine neue Plug-In-Manifestdatei plugin.yaml mit dem folgenden Inhalt, und ersetzen Sie die OpenApiSpecUrl Werte und EndpointUrl aus Ihrer Web-App.

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

Hochladen des Plug-In-Manifests

Befolgen Sie die Anweisungen hier, um das Plug-In-Manifest in Security Copilot hochzuladen.

Konfigurieren der Authentifizierung

  1. Melden Sie sich bei Microsoft Security Copilot an.

  2. Scrollen Sie nach unten zu Benutzerdefiniert, und wählen Sie Setup aus.

    Screenshot: Verbindungen von

  3. Geben Sie den geheimen Clientschlüssel ein, und wählen Sie Verbinden aus.

    Screenshot: Schritt zum Eingeben des geheimen Clientschlüssels

  4. Es wird eine Benachrichtigung angezeigt, dass das Konto erfolgreich verknüpft wurde.

    Abbildung des Webbrowsers.

  5. Das Setup ist abgeschlossen.

    Abbildung von status.

Das Plug-In sollte jetzt aktiviert sein.

Wenn beim Auswählen von Verbinden eine Fehlermeldung angezeigt wird, führen Sie die folgenden Schritte aus, um den Fehler zu beheben: Abbildung der Fehlermeldung.

Fügen Sie den folgenden Rückruf-URI (https://securitycopilot.microsoft.com/auth/v1/callback) hinzu, wie in der folgenden Abbildung dargestellt, und versuchen Sie, die Verbindung wiederherzustellen.

Abbildung der Authentifizierungsseite.

Begrenzungen

  1. HTTP-Verben, die in der Regel Zustandsänderungen und Schreibvorgänge zulassen (z. B. POST), können nur für Datenabrufzwecke verwendet werden. Schreibvorgänge werden derzeit nicht unterstützt.

  2. Anforderungstextschemas müssen auf eine Tiefe von 1 beschränkt sein. Dies bedeutet, dass das übergeordnete Objekt keine geschachtelten Objekte in sich selbst enthalten kann. Ein Verstoß gegen diese Tiefeneinschränkung führt zu einem Fehler mit Code 2006.

    2.1 Im Folgenden finden Sie ein Beispiel für den Anforderungstext mit der Tiefe = 1:

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

    2.2 Der folgende Beispielanforderungstext wird nicht akzeptiert, da die Tiefe größer als 1 ist:

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