Partager via

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

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

Remarque

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

Aucune authentification (anonyme)

Points de terminaison publics qui ne nécessitent aucune information d’identification d’authentification. L’API ne nécessite rien de spécifique. Sans @useAuth éléments décoratifs, 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 inscrire automatiquement votre clé API et ajoutera é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 d’un service protégé par OAuth2. Utilisez le natif OAuth2Auth de TypeSpec. Mettez à jour , authorizationUrltokenUrl, refreshUrlet scopes en fonction de l’API spécifique à laquelle vous intégrez.

Découvrez comment créer automatiquement l’application Entra ID à l’aide du Kit de ressources Agents et mettre à jour l’application Entra ID 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
}

Microsoft 365 Agents Toolkit peut inscrire automatiquement votre configuration OAuth2 et ajoutera é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 unique Entra ID

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

Utilisation de configurations d’authentification inscrites

Pour les scénarios de production, inscrivez 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 l’élément @authReferenceId décoratif pour référencer les configurations d’authentification préinscription par leurs identificateurs uniques. Cette approche offre un moyen sécurisé de gérer les informations d’identification sans exposer d’informations sensibles dans votre codebase.

Lorsque vous utilisez @authReferenceId, spécifiez l’ID d’inscription à partir des inscriptions de client OAuth ou des inscriptions de clés API configurées dans le portail des développeurs. Cette approche sépare la configuration de l’authentification du code, ce qui permet de meilleures pratiques de sécurité et une gestion plus facile 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">
  • Last updated on