Verwenden von OIDC mit GitHub Copilot Extensions

Hier erfährst du, wie du OpenID Connect (OIDC) mit deinen Copilot Extension-Instanzen verwendest, um die Sicherheit zu erhöhen.

In diesem Artikel

Informationen zu OpenID Connect (OIDC) für Copilot Extensions-Instanzen

OpenID Connect (OIDC) ermöglicht Copilot Extensions-Instanzen das Austauschen kurzlebiger Tokens direkt über den Cloudanbieter, anstatt langlebige GitHub-Anmeldeinformationen zu speichern. Mit diesem Feature können Copilot-Agents und Skillsets Benutzende sicherer authentifizieren und auf Cloudressourcen zugreifen.

Übersicht über OIDC

Copilot Extensions-Instanzen erfordern häufig den Zugriff auf Ressourcen oder APIs von Drittanbietern im Namen der Benutzenden. Hierfür mussten üblicherweise GitHub-Tokens als Geheimnisse gespeichert und zusätzliche API-Aufrufe durchgeführt werden, um diese Tokens den Benutzeridentitäten in deinem System zuzuordnen. Mit OIDC kann deine Erweiterung kurzlebige Zugriffstokens direkt über den Authentifizierungsdienst anfordern, indem GitHub-Identitätsinformationen ausgetauscht werden.

Bei Aktivierung generiert der OIDC-Anbieter von GitHub automatisch ein Token, das Ansprüche hinsichtlich der Benutzenden und des Anforderungskontexts enthält. Dein Authentifizierungsdienst kann diese Ansprüche überprüfen und gegen ein Zugriffstoken austauschen, das speziell für deinen Dienst vorgesehen ist.

Die Verwendung von OIDC ist besonders nützlich für die Entwicklung von Copilot-Skillsets, da du auf diese Weise deine vorhandenen API-Endpunkte nutzen kannst, ohne separate und für GitHub spezifische Endpunkte verwalten zu müssen. Anstatt Endpunkte zu duplizieren, um GitHub-Tokens zu akzeptieren, kannst du OIDC zum Übersetzen von GitHub-Identitäten in native Authentifizierungstokens deines Diensts verwenden.

Vorteile der Verwendung von OIDC

Durch die Implementierung des OIDC-Tokenaustauschs in deine Copilot Extension-Instanz ist Folgendes möglich:

  • Vermeiden des Speicherns langlebiger GitHub-Tokens oder Verwalten einer Zuordnung zwischen GitHub und den Identitäten deines Diensts
  • Verwenden kurzlebiger Tokens, die automatisch ablaufen und speziell auf die Anforderungen deines Diensts ausgerichtet werden können
  • Vermeiden zusätzlicher Aufrufe der GitHub-API zum Überprüfen von Tokens und Fetchen von Benutzerinformationen
  • Aktivieren der direkten Integration für Copilot-Skills mit deinen vorhandenen APIs, ohne separate Endpunkte für GitHub zu verwalten
  • Wiederverwenden vorhandener API-Endpunkte durch Übersetzen der GitHub-Authentifizierung in native Tokens deines Diensts

Tokenaustauschflow

Im Folgenden wird beschrieben, wie Copilot Extensibility Platform ein OIDC-Token gegen ein Zugriffstoken austauscht, um Anforderungen bei deiner Erweiterung zu authentifizieren.

Erste Anforderung

  1. Die Benutzenden senden eine Nachricht an deine Copilot Extension-Instanz.
  2. GitHub generiert ein OIDC-Token, das Benutzeridentitätsinformationen enthält.
  3. GitHub ruft deinen Tokenaustauschendpunkt mit dem OIDC-Token auf.
  4. Dein Dienst überprüft das Token und gibt ein Zugriffstoken zurück.
  5. GitHub schließt dein Zugriffstoken in die Anforderung an deine Erweiterung ein.
# HTTP header
Authorization: Bearer <your-service-token>
X-GitHub-Token: <github-token>

Nachfolgende Anforderungen

  1. GitHub kann dein Zugriffstoken für bis zu zehn Minuten zwischenspeichern.
  2. Das zwischengespeicherte Token wird für nachfolgende Anforderungen wiederverwendet.
  3. Wenn das Token abläuft oder ungültig wird, fordert GitHub ein neues Token an.

Grundlegendes zu OIDC-Tokens

Das OIDC-Token von GitHub ist ein JSON Web Token (JWT), das Ansprüche hinsichtlich der Benutzenden und des Anforderungskontexts enthält:

{
  "jti": "<unique-token-id>",
  "sub": "<github-user-id>",
  "aud": "<your-client-id>",
  "iss": "https://github.com/login/oauth",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567,
  "act": {
    "sub": "api.copilotchat.com"
  }
}

Einrichten von OIDC für deine Erweiterung

Es sind drei Schritte erforderlich, um OIDC für deine Erweiterung einzurichten.

  1. Konfigurieren deines Tokenaustauschendpunkts
  2. Aktivieren von OIDC in den Einstellungen deiner Copilot-Erweiterung
  3. Überprüfen von OIDC-Tokens

Konfigurieren deines Tokenaustauschendpunkts

Erstelle einen Endpunkt in deinem Dienst, der der Spezifikation RFC 8693 OAuth 2.0 Token Exchange entspricht. Dieser Endpunkt sollte Folgendes ermöglichen:

  • Akzeptieren von POST-Anforderungen mit den folgenden formularcodierten Parametern:

    grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=<https://your-service.com/resource>
&subject_token=<github-jwt-token>
&subject_token_type=urn:ietf:params:oauth:token-type:id_token

  • Zurückgeben einer JSON-Antwort mit dem Zugriffstoken deines Diensts:

    {
  "access_token": <"your-service-token">,
  "Issued_token_type":"urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

  • Zurückgeben einer Fehlerantwort, wenn die Überprüfung fehlschlägt:

    {
  "error": "invalid_request"
}

Aktivieren von OIDC in den Einstellungen deiner Copilot Extension-Instanz

Aktiviere OIDC in der Konfiguration deiner Copilot Extension-Instanz:

  1. Klicke auf GitHub in der oberen rechten Ecke einer beliebigen Seite auf dein Profilfoto.
  2. Navigieren Sie zu den Einstellungen für Ihr Konto.
    • Klicken Sie bei einer App, die zu einem persönlichen Konto gehört, auf Einstellungen.
    • Für eine App im Besitz einer Organisation:
      1. Klicke Sie auf Ihre Organisationen.
      2. Klicken Sie rechts neben der Organisation auf Einstellungen.
  3. Klicke auf der linken Seitenleiste auf Entwicklereinstellungen.
  4. Klicke auf der linken Randleiste auf GitHub Apps .
  5. Klicken Sie rechts neben der GitHub App, die Sie für Ihre Copilot Extension konfigurieren möchten, auf Bearbeiten.
  6. Klicken Sie in der linken Randleiste auf Copilot.
  7. Aktivere unter OpenID Connect Token Exchange die Option Enabled.
  8. Gib im Feld Token exchange endpoint deine Tokenaustausch-URL ein.
  9. Gib im Feld Request header key den Headerschlüssel für das Token deines Diensts ein. Der Standardwert ist Authorization.
  10. Gib im Feld Request header value das Headerwertformat ein. Der Standardwert ist Bearer ${token}.

Überprüfen von OIDC-Tokens

Dein Tokenaustauschendpunkt sollte die GitHub-OIDC-Tokens durch Ausführung der folgenden Schritte überprüfen:

  1. Fetchen des JSON Web Key Set (JWKS) von https://github.com/login/oauth/.well-known/openid-configuration
  2. Überprüfen der Tokensignatur
  3. Validieren der erforderlichen Ansprüche
    • aud (Audience): Client-ID deiner Copilot Extension-Instanz.
    • sub (Subject): GitHub-Benutzer-ID, die die Anforderung übermittelt. Die Antwort ist auf Daten beschränkt, für die die Benutzenden über Zugriffsberechtigungen verfügen. Wenn die Benutzenden über keine Berechtigungen verfügen, wird 400 Bad Request angezeigt.
    • iat (Issued At): Zeitstempel für die Tokenerstellung. Es handelt sich in der Regel um einen Zeitstempel in der Vergangenheit, aber diese Angabe stellt den genauen Zeitpunkt dar, zu dem das Token erstellt wurde.
    • nbf (Not Before): Zeitstempel, vor dem das Token ungültig ist. Dies sollte ein Zeitstempel in der Vergangenheit sein.
    • exp (Expiration Time): Zeitstempel, der angibt, wann das Token abläuft. Dies sollte ein Zeitstempel in der Zukunft sein.
    • act (Actor): Handelnde Entität beim delegierten Zugriff. Dies sollte eine konstante Zeichenfolge sein.

Problembehandlung

In den folgenden Abschnitten werden häufige Probleme und Best Practices für die Implementierung von OIDC für deine Copilot Extension-Instanz beschrieben.

Tokenvalidierungsfehler

  • Sicherstellen, dass der richtige JWKS-Endpunkt verwendet wird
  • Überprüfen, ob alle erforderlichen Ansprüche vorhanden und gültig sind
  • Überprüfen, ob die Zeitstempel (iat, nbf und exp) innerhalb der gültigen Bereiche liegen

Tokenaustauschfehler

  • Zurückgeben von HTTP 400 für ungültige Tokens
  • Zurückgeben von HTTP 403, wenn die Benutzenden nicht über die erforderlichen Berechtigungen verfügen
  • Wenn GitHub eine 403-Antwort empfängt, wird die Anforderung mit einem neuen Token wiederholt.

Leistungsprobleme

  • Implementieren einer effizienten Tokenvalidierung, um die Latenz zu minimieren
  • Verwenden geeigneter Tokenablaufzeiten (empfohlen: zehn Minuten oder weniger)
  • Erwägen der Zwischenspeicherung von Auswirkungen für Erweiterungen mit hohem Datenverkehr

Bewährte Methoden

  • Beschränken von Tokens auf die mindestens erforderlichen Berechtigungen
  • Implementieren einer geeigneten Fehlerbehandlung und Protokollierung
  • Überwachen von Tokenaustauschmustern auf Sicherheitsanomalien
  • Verwenden kurzlebiger Tokens, um Sicherheitsrisiken zu minimieren
  • Überprüfen aller Ansprüche vor dem Ausstellen von Zugriffstokens
  • Erwägen der Implementierung von Ratenbegrenzungen für den Tokenaustauschendpunkt
  • Verwenden von HTTPS für die gesamte Tokenaustauschkommunikation