Einrichten von OIDC für deine GitHub Copilot-Erweiterung

Einführung

Du kannst OIDC so einrichten, dass Agents und Skillsets von Copilot Benutzer sicherer authentifizieren und auf Cloudressourcen zugreifen können. Weitere Informationen zu OIDC findest du unter OpenID Connect (OIDC) für Copilot-Erweiterungen.

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

• Konfigurieren deines Tokenaustauschendpunkts
• Aktivieren von OIDC in den Einstellungen deiner Copilot-Erweiterung
• Ü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-Erweiterung-Instanz

Aktiviere OIDC in der Konfiguration deiner Copilot-Erweiterung-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.
   • Für eine App im Besitz eines Unternehmens:
     1. Wenn Sie Enterprise Managed Users verwenden, klicken Sie auf Ihr Unternehmen, um direkt zu den Enterprise-Konto Einstellungen zu wechseln.
     2. Wenn Sie persönliche Konten verwenden, klicken Sie auf Ihre Unternehmen und dann rechts neben dem Unternehmen auf Einstellungen.

3. Navigieren Sie zu den GitHub App-Einstellungen.

   • Für eine App, die einem persönlichen Konto oder einer Organisation gehört:
     1. Klicken Sie in der linken Randleiste auf Entwicklereinstellungen, und dann auf GitHub Apps.
   • Für eine App im Besitz eines Unternehmens:
     1. Klicken Sie in der linken Randleiste unter „Einstellungen“, auf GitHub Apps.

4. Klicke rechts neben der GitHub App, die du für deine Copilot-Erweiterung konfigurieren möchtest, auf Bearbeiten.

5. Klicken Sie in der linken Randleiste auf Copilot.

6. Aktivere unter OpenID Connect Token Exchange die Option Enabled.

7. Gib im Feld Token exchange endpoint deine Tokenaustausch-URL ein.

8. Gib im Feld Request header key den Headerschlüssel für das Token deines Diensts ein. Der Standardwert ist Authorization.

9. 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-Erweiterung-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-Erweiterung-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

Weiterführende Themen

• OpenID Connect (OIDC) für Copilot-Erweiterungen