Prise en charge de l’authentification dans TypeSpec pour Microsoft 365 Copilot

TypeSpec pour Microsoft 365 Copilot prend en charge plusieurs méthodes d’authentification pour sécuriser les plugins d’API et intégrer les services externes. Les types d’authentification pris en charge sont les suivants :

Remarque

Cette documentation couvre les scénarios d’authentification spécifiques à Microsoft 365 Copilot. Pour une documentation complète sur l’authentification TypeSpec, y compris tous les décorateurs et modèles d’authentification natifs, consultez la documentation TypeSpec sur l’authentification.

Aucune authentification (anonyme)

Points de terminaison publics qui ne nécessitent aucune information d’authentification. L’API ne nécessite rien de spécifique. Sans @useAuth décorateurs, toutes les API sont considérées comme anonymes.

Exemple

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

Authentification par clé API

Authentification à l’aide de clés API ou de jetons d’accès personnels appliqués à des espaces de noms entiers. Utilisez le natif ApiKeyAuth de TypeSpec.

Exemple

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

Microsoft 365 Agents Toolkit peut automatiquement enregistrer votre clé API et ajoute également l’action apiKey/register à m365agents.yml dans votre projet Agents Toolkit.

# 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

L’exemple Gérer les réparations à l’aide de Microsoft 365 Copilot met en évidence l’utilisation de l’authentification par clé API.

Flux de code d’autorisation OAuth2

Autorisations déléguées par l’utilisateur pour accéder aux données utilisateur à partir d’un service protégé par OAuth 2.0. Utilisez le natif OAuth2Auth de TypeSpec. Mettez à jour le authorizationUrl, tokenUrl, refreshUrlet scopes en fonction de l’API spécifique avec laquelle vous intégrez.

Découvrez comment créer automatiquement l’inscription d’application Microsoft Entra à l’aide d’Agents Toolkit et mettre à jour l’inscription d’application Microsoft Entra une fois l’inscription terminée.

Exemple

@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 peut enregistrer automatiquement votre configuration OAuth2 et ajoute également l’action oauth/register à m365agents.yml dans votre projet Agents Toolkit.

# 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

L’agent Tasks utilisant TypeSpec pour Microsoft 365 Copilot qui se connecte à l’exemple d’API Microsoft Graph met en évidence l’utilisation d’OAuth2 avec le flux de code d’autorisation.

Authentification SSO de Microsoft Entra

Authentification qui applique la session Microsoft 365 existante de l’utilisateur pour les scénarios d’intégration native. Pour terminer l’inscription SSO, utilisez le flux normal OAuth2Auth et effectuez les étapes manuelles.

Utilisation de configurations d’authentification inscrites

Pour les scénarios de production, enregistrez et gérez les informations d’identification d’authentification via le portail des développeurs Microsoft Teams au lieu de les incorporer directement dans le code TypeSpec. Utilisez le décorateur pour référencer les @authReferenceId configurations d’authentification préenregistrées par leurs identifiants uniques. Cette approche offre un moyen sécurisé de gérer les informations d’identification sans exposer les informations sensibles de votre base de code.

Lorsque vous utilisez @authReferenceId, spécifiez l’ID d’inscription à partir des inscriptions client OAuth ou des inscriptions de clé API configurées dans le portail des développeurs. Cette approche sépare la configuration d’authentification du code, ce qui permet d’améliorer les pratiques de sécurité et de faciliter la gestion des informations d’identification dans différents environnements.

Exemple

// 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">
  • Dernière mise à jour :