Partager via

Authentification par clé API

  • Article

L’authentification par clé API est une méthode utilisée pour authentifier l’accès à votre application d’extension de message à l’aide d’une API. Cela implique l’utilisation d’une clé API unique, qui est transmise avec chaque demande d’API pour vérifier l’identité de l’utilisateur ou de l’application qui a lancé la demande. La clé API doit être inscrite dans Microsoft Teams et lorsqu’un utilisateur interagit avec votre extension de message, Teams utilise le secret pour s’authentifier auprès de votre API.

Les propriétés d’inscription de clé API suivantes vous aident à sécuriser votre clé et à vous assurer qu’elle est limitée à votre application :

  • URL de base : Teams transmet le secret aux points de terminaison d’URL qui commencent par la valeur dans ce champ.
  • Locataire cible : pour limiter l’accès de l’API à votre locataire Microsoft 365 ou à n’importe quel locataire.
  • ID d’application : pour limiter l’accès à la clé à une application spécifique ou à n’importe quelle application.
  • Clé API : pour authentifier l’accès à votre application.

Vous pouvez inscrire une clé API via le portail des développeurs pour Teams et générer un ID d’inscription de clé API. Mettez à jour le manifeste de l’application avec l’objet apiSecretServiceAuthConfiguration avec une apiSecretRegistrationId propriété . Cette propriété doit contenir l’ID d’inscription de clé API retourné lorsque vous avez envoyé la clé API via le portail des développeurs pour Teams.

Remarque

Vous devez veiller à sécuriser l’ID d’inscription de la clé API, car il peut être récupéré à partir du manifeste de l’application Teams. Pour plus d’informations sur la sécurisation de votre clé API, consultez bonnes pratiques.

Lorsqu’une demande d’API est lancée, le système récupère la clé API d’une base de données chiffrée et l’inclut dans l’en-tête d’autorisation, à l’aide du schéma de jeton du porteur. Le système envoie l’en-tête d’autorisation avec la clé API au point de terminaison défini dans le manifeste de l’application.

L’exemple suivant montre la charge utile avec l’en-tête d’autorisation à l’aide du schéma de jeton du porteur :

GET https://example.com/search?myQuery=test
Accept-Language: en-US
Authorization: Bearer <MY_API_KEY>

Inscrire une clé API

Pour inscrire une clé API, procédez comme suit :

  1. Accédez à Outils>Inscription de clé API.

    Capture d’écran montrant l’option d’inscription de clé API dans le Portail des développeurs pour Teams.

  2. Sélectionnez + Nouvelle clé API.

  3. Dans la page d’inscription de clé API , sélectionnez + Ajouter un secret. La boîte de dialogue Ajouter une clé API s’affiche.

  4. Entrez une valeur pour la clé, puis sélectionnez Enregistrer.

    Remarque

    Vous pouvez conserver jusqu’à deux clés API. Si vous devez en remplacer une, vous pouvez le faire sans interruption de service, car Teams utilise l’autre clé configurée pendant le processus de mise à jour.

    Capture d’écran montrant la boîte de dialogue Ajouter une clé API pour ajouter une clé API à votre application.

  5. Sous Nom de la clé API, ajoutez un nom explicite pour la clé API. Par exemple, clé API pour l’extension de message Contoso.

  6. Sous URL de base, spécifiez une URL de base commune pour tous les points de terminaison d’API qui doivent être appelés. Cette URL doit commencer par https, inclure un nom de domaine complet et éventuellement, un chemin d’accès. Teams transmet la clé au point de terminaison d’URL qui commence par la valeur dans ce champ. Par exemple : https://api.yelp.com.

    L’URL de base garantit que la clé reste sécurisée et qu’elle n’est pas divulguée aux points de terminaison aléatoires, même si une autre application acquiert de manière illicite l’ID d’inscription de clé API et l’incorpore dans sa propre application. Si l’URL inscrite dans la configuration de la clé API n’est pas un préfixe pour les points de terminaison cibles définis dans la spécification OpenAPI, l’appel est supprimé.

    Capture d’écran montrant les options Description et Ajouter un domaine dans la page d’inscription de clé API dans le Portail des développeurs pour Teams.

  7. Sous Locataire cible, sélectionnez l’une des options suivantes :

    • Locataire d’origine : la clé API n’est fonctionnelle que dans le locataire où elle est inscrite.
    • N’importe quel locataire : la clé API est utilisable dans n’importe quel locataire.

    Capture d’écran montrant les options Locataire d’accueil et Tout locataire sous Définir un en-tête de locataire cible dans le Portail des développeurs pour Teams.

  8. Sous Application Teams cible, sélectionnez l’une des options suivantes :

    • Application Teams existante : l’option d’applicationTeams existante lie l’ID d’inscription de clé API à votre application Teams spécifique.
    • N’importe quelle application Teams : la clé API peut être utilisée avec n’importe quelle application Teams.

    Capture d’écran montrant les options n’importe quelle application Teams et Application Teams existante sous Le titre Définir une application Teams dans le Portail des développeurs pour Teams.

    Un ID d’inscription de clé API est généré.

    Capture d’écran montrant l’ID d’inscription de clé API généré dans le Portail des développeurs pour Teams.

  9. Dans le Portail des développeurs pour Teams, sélectionnez Applications , puis sélectionnez une application dans laquelle vous souhaitez ajouter la clé API.

  10. Accédez à Fonctionnalités > de l’applicationExtension de message.

  11. Sous Authentification, sélectionnez Clé API et ajoutez l’ID d’inscription de la clé API.

    Capture d’écran montrant un exemple de la section Authentification avec aucune et les options de clé API dans le Portail des développeurs pour Teams.

  12. Sélectionnez Enregistrer.

L’ID d’inscription de clé API est mis à jour en tant que valeur de la propriété dans le apiSecretRegistrationId manifeste de l’application. Vous pouvez vérifier votre ID d’inscription de clé API dans le manifeste de l’application dans le Portail des développeurs pour Teams.

Mettre à jour le manifeste de l’application

Ajoutez un apiSecretServiceAuthConfiguration objet avec une apiSecretRegistrationId propriété, qui contient l’ID de référence lorsque vous envoyez la clé API via le Portail des développeurs pour Teams. Pour plus d’informations, consultez composeExtensions.commands.

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

Meilleures pratiques

  • Clé API :

    • La clé API doit comporter au moins 10 caractères et au maximum 128 caractères.
    • Une fois que vous avez mis à jour la clé API, il faut jusqu’à une heure pour que la clé se reflète dans tout le système.

  • URL de base :

    • L’URL de base doit commencer par https pour garantir une communication sécurisée.
    • Vous devez inclure le nom d’hôte complet pour spécifier le domaine exact.
    • Vous pouvez ajouter un chemin d’accès facultatif pour définir un point d’entrée spécifique pour l’API.

    Cette structure est cruciale pour la sécurité de vos clés API, car Teams envoie la clé API aux points de terminaison qui commencent par l’URL de base spécifiée.

  • Locataire cible : au fur et à mesure que vous développez votre application au sein de votre locataire Microsoft 365, vous la testerez initialement en tant qu’application personnalisée conçue pour votre organisation (application métier) ou application personnalisée. Au cours de cette étape, vous devez inscrire la clé API auprès de votre locataire d’origine en tant que locataire cible pour vous assurer que la clé reste exclusive à votre locataire.

    Une fois que vous avez terminé le test et que vous êtes prêt à envoyer votre manifeste d’application à l’Espace partenaires pour le Magasin Teams, vous devez basculer le paramètre de locataire cible sur N’importe quel locataire. Cette modification permet d’utiliser votre ID d’inscription de clé API sur différents locataires une fois que votre application est disponible dans le Magasin Teams.

  • ID d’application Teams : à mesure que vous développez votre application au sein de votre locataire Microsoft 365 et que vous commencez à la tester en tant qu’application personnalisée conçue pour votre organisation (LOB) ou votre application personnalisée, vous devez définir l’ID d’inscription de clé API avec l’ID d’application Teams en tant qu’application Teams. Cette configuration permet d’utiliser la clé avec n’importe quelle application Teams chargée en tant qu’application personnalisée et les applications personnalisées conçues pour votre organisation (applications métier) pour générer des ID après leur chargement. Vous n’aurez pas l’ID de l’application à ce stade.

    La sécurité de votre clé est toujours maintenue via le locataire d’origine et l’URL de base. Lorsque vous êtes prêt à publier votre application dans le monde entier, vous devez modifier le paramètre ID d’application Teams sur Application Teams existante et entrer votre ID d’application Teams. Enfin, envoyez le manifeste de votre application à l’Espace partenaires pour l’inclure dans le Magasin Teams. Votre inscription de clé API est désormais liée à votre application Teams spécifique et ne peut pas être utilisée avec d’autres personnes.

Voir aussi