Freigeben über

Unterstützung der Authentifizierung in TypeSpec für Microsoft 365 Copilot

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

Hinweis

In dieser Dokumentation werden Microsoft 365 Copilot spezifische Authentifizierungsszenarien behandelt. Eine umfassende Dokumentation zur TypeSpec-Authentifizierung, einschließlich aller nativen Authentifizierungsdekortoren und -muster, finden Sie in der TypeSpec-Dokumentation zur Authentifizierung.

Keine Authentifizierung (anonym)

Öffentliche Endpunkte, die keine Anmeldeinformationen für die Authentifizierung erfordern. Für die API sind keine spezifischen Anforderungen erforderlich. Ohne @useAuth Decorators gelten alle APIs als anonym.

Beispiel

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

API-Schlüsselauthentifizierung

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
}

Das Microsoft 365 Agents Toolkit kann Ihren API-Schlüssel automatisch registrieren und fügt die apiKey/register Aktion auch 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 Verwalten von Reparaturen mit Microsoft 365 Copilot wird die Verwendung der API-Schlüsselauthentifizierung hervorgehoben.

OAuth2-Autorisierungscodeflow

Vom Benutzer delegierte Berechtigungen für den Zugriff auf Benutzerdaten eines durch OAuth2 geschützten Diensts. Verwenden Sie die native OAuth2Auth aus TypeSpec. Aktualisieren Sie , authorizationUrltokenUrl, refreshUrlund scopes basierend auf der spezifischen API, mit der Sie eine Integration durchführen.

Erfahren Sie, wie Sie die Entra ID-App automatisch mit dem Agents Toolkit erstellen und die Entra ID-App aktualisieren , nachdem 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
}

Das Microsoft 365 Agents Toolkit kann Ihre OAuth2-Konfiguration automatisch registrieren und fügt die oauth/register Aktion auch 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 den Microsoft Graph-APIs herstellt, hebt die Verwendung von OAuth2 mit Autorisierungscodeflow hervor.

Entra ID SSO-Authentifizierung

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

Verwenden von registrierten Authentifizierungskonfigurationen

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

Wenn Sie verwenden @authReferenceId, geben Sie die Registrierungs-ID aus OAuth-Clientregistrierungen oder API-Schlüsselregistrierungen an, die im Entwicklerportal konfiguriert sind. Dieser Ansatz trennt die Authentifizierungskonfiguration vom Code und ermöglicht bessere Sicherheitsmethoden 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">
  • Last updated on