Authentifizierungsunterstützung in TypeSpec für Microsoft 365 Copilot

TypeSpec für Microsoft 365 Copilot unterstützt mehrere Authentifizierungsmethoden, um API-Plug-Ins zu sichern und in externe Dienste zu integrieren. Zu den unterstützten Authentifizierungstypen gehören:

Hinweis

Diese Dokumentation behandelt Microsoft 365 Copilot spezifische Authentifizierungsszenarien. Eine umfassende TypeSpec-Authentifizierungsdokumentation, einschließlich aller nativen Authentifizierungsdekoratoren und -muster, finden Sie in der TypeSpec-Dokumentation zur Authentifizierung.

Keine Authentifizierung (anonym)

Öffentliche Endpunkte, für die keine Anmeldeinformationen für die Authentifizierung erforderlich sind. Die API erfordert nichts Spezifisches. Ohne @useAuth Dekorateure gelten alle APIs als anonym.

Beispiel

@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
namespace API {
  // Endpoints
}

API-Schlüssel-Authentifizierung

Authentifizierung mithilfe von API-Schlüsseln oder persönlichen Zugriffstoken, die auf ganze Namespaces angewendet werden. Verwenden Sie die native ApiKeyAuth aus TypeSpec.

Beispiel

@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">)
namespace API {
  // Endpoints
}

Microsoft 365 Agents Toolkit kann Ihren API-Schlüssel automatisch registrieren und fügt die apiKey/register Aktion auch zu m365agents.yml in Ihrem Agents Toolkit-Projekt hinzu.

# m365agents.yml
# After the typespec/compile step
- uses: apiKey/register
  with:
    name: ApiKeyAuth
    appId: ${{TEAMS_APP_ID}}
    apiSpecPath: ./appPackage/.generated/api-openapi.yml
  writeToEnvironmentFile:
    registrationId: APIKEYAUTH_REGISTRATION_ID

Im Beispiel "Reparaturen mit Microsoft 365 Copilot verwalten" wird die Verwendung der API-Schlüsselauthentifizierung hervorgehoben.

OAuth2-Autorisierungscodeflow

Vom Benutzer delegierte Berechtigungen für den Zugriff auf Benutzerdaten von einem OAuth 2.0-geschützten Dienst. Verwenden Sie die native OAuth2Auth aus TypeSpec. Aktualisieren Sie die authorizationUrl, tokenUrl, refreshUrlund scopes basierend auf der spezifischen API, mit der Sie integrieren möchten.

Erfahren Sie, wie Sie die Microsoft Entra-App-Registrierung automatisch mit dem Agents Toolkit erstellen und die Microsoft Entra-App-Registrierung aktualisieren, sobald die Registrierung abgeschlossen ist.

Beispiel

@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(OAuth2Auth<[{
  type: OAuth2FlowType.authorizationCode;
  authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
  tokenUrl: "https://contoso.com/oauth2/v2.0/token";
  refreshUrl: "https://contoso.com/oauth2/v2.0/token";
  scopes: ["scope-1", "scope-2"];
}]>)
namespace API {
  // Endpoints
}

Agents Toolkit kann Ihre OAuth2-Konfiguration automatisch registrieren und fügt die oauth/register Aktion auch zu m365agents.yml in Ihrem Agents Toolkit-Projekt hinzu.

# m365agents.yml
# After the typespec/compile step
- uses: oauth/register
  with:
    name: OAuth2Auth
    appId: ${{TEAMS_APP_ID}}
    clientId: ${{AAD_APP_CLIENT_ID}}
    clientSecret: ${{SECRET_AAD_APP_CLIENT_SECRET}}
    apiSpecPath: ./appPackage/.generated/api-openapi.yml
    flow: authorizationCode
  writeToEnvironmentFile:
    configurationId: OAUTH2AUTH_REGISTRATION_ID

Der Aufgaben-Agent, der TypeSpec für Microsoft 365 Copilot verwendet, der eine Verbindung mit dem Beispiel für Microsoft Graph-APIs herstellt, hebt die Verwendung von OAuth2 mit dem Autorisierungscodeflow hervor.

Microsoft Entra SSO-Authentifizierung

Authentifizierung, die die vorhandene Microsoft 365-Sitzung des Benutzers für native Integrationsszenarien anwendet. Um die SSO-Registrierung abzuschließen, verwenden Sie den regulären OAuth2Auth Ablauf, und führen Sie die manuellen Schritte aus.

Verwenden registrierter Authentifizierungskonfigurationen

Registrieren und verwalten Sie für Produktionsszenarien die Anmeldeinformationen für die Authentifizierung über das Microsoft Teams-Entwicklerportal, anstatt sie direkt in den TypeSpec-Code einzubetten. Verwenden Sie den @authReferenceId Dekorator, um anhand ihrer eindeutigen Bezeichner auf vorregistrierte Authentifizierungskonfigurationen zu verweisen. Dieser Ansatz bietet eine sichere Möglichkeit zum Umgang mit Anmeldeinformationen, ohne vertrauliche Informationen in Ihrer Codebasis verfügbar zu machen.

Wenn Sie verwenden @authReferenceId, geben Sie die Registrierungs-ID entweder aus OAuth-Clientregistrierungen oder API-Schlüsselregistrierungen an, die im Entwicklerportal konfiguriert sind. Dieser Ansatz trennt die Authentifizierungskonfiguration vom Code und ermöglicht bessere Sicherheitspraktiken und eine einfachere Verwaltung von Anmeldeinformationen in verschiedenen Umgebungen.

Beispiel

// Reference to OAuth2 client registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
  // Endpoints
}

@authReferenceId("NzFmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IyM5NzQ5Njc3Yi04NDk2LTRlODYtOTdmZS1kNDUzODllZjUxYjM=")
model Auth is OAuth2Auth<[{
  type: OAuth2FlowType.authorizationCode;
  authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
  tokenUrl: "https://contoso.com/oauth2/v2.0/token";
  refreshUrl: "https://contoso.com/oauth2/v2.0/token";
  scopes: ["scope-1", "scope-2"];
}]>

// Reference to API key registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
  // Endpoints
}

@authReferenceId("5f701b3e-bf18-40fb-badd-9ad0b60b31c0")
model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">
  • Zuletzt aktualisiert um