Pour configurer l'authentification unique pour une compétence ou un assistant numérique dans Microsoft Teams, vous devez créer une application Azure AD. Cette application est en plus de l'application Azure AD que vous avez déjà créée dans le cadre de la configuration du canal Microsoft Teams.

Avant de commencer, assurez-vous que vous disposez des éléments suivants :

• Un compte Azure avec un abonnement actif.
• L'ID application Microsoft pour le robot que vous avez configuré avec votre canal Microsoft Teams.
• L'accès administrateur au portail Azure.

Voici les étapes de création d'une application Azure AD pour l'authentification unique :

1. Créer un enregistrement de nouvelle application :
   1. Naviguez jusqu'à https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade dans le portail Azure.
   2. Cliquez sur Nouvelle inscription.
   3. Remplissez le champ Name (Nom).
   4. Dans la section Supported account types (Types de compte pris en charge), sélectionnez le bouton radio Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) (Comptes dans tout répertoire organisationnel (tout répertoire Azure AD - Multi-client) et comptes Microsoft personnels (par exemple, Skype, Xbox)).
   5. Cliquez sur Register (Enregistrer).

      Une fois l'application créée, vous parvenez à la section Overview (Aperçu). L'ID application (client) et l'ID répertoire (locataire) doivent être créés pour votre application.

2. Ajouter une configuration de plate-forme Web :
   1. Dans la barre de navigation de gauche, sélectionnez Authentication (Authentification).
   2. Sous Configuration de la plate-forme, cliquez sur Ajouter une plate-forme et sélectionnez Web.
   3. Ajoutez une URI de redirection au format suivant :

      <YOUR_Oracle-Digital-Assistant_URL>/connectors/v2/callback

   4. Cliquez sur Configure (Configurer).
3. Créer une clé secrète client :
   1. Dans la barre de navigation de gauche, sélectionnez Certificates and secrets (Certificats et clés secrètes).
   2. Cliquez sur + New client secret (+ Nouvelle clé secrète client), remplissez les champs requis et cliquez sur Add (Ajouter).
   3. Copiez la valeur de la clé secrète client et conservez-la dans un endroit sécurisé. Vous aurez besoin de cette valeur plus tard.
4. Configurer le jeton :
   1. Dans la barre de navigation de gauche, sélectionnez Token configuration (Configuration de jeton).
   2. Cliquez sur + Add optional claim (Ajouter une revendication facultative).
   3. Pour Token Type (Type de jeton), sélectionnez Access (Accès).
   4. Sélectionnez ces revendications :
      • given_name
      • upn
      • email
   5. Cliquez sur Add (Ajouter).
   6. Sélectionnez l'option Turn on the Microsoft Graph email, profile permission (required for claims to appear in token) (Activer le courriel de Microsoft Graph, l'autorisation de profil (requise pour que les revendications apparaissent dans le jeton)) et cliquez sur Add (Ajouter).
   7. Dans la barre de navigation de gauche, sélectionnez API permissions (Autorisations d'API).

      Vous pouvez voir que trois autorisations sont créées.

   8. Cliquez sur + Add a Permission (Ajouter une autorisation) et ajoutez User.ReadBasic.All.

      Vous en aurez besoin pour accéder aux informations de profil.

5. Définir l'URI d'ID application :
   1. Dans la barre de navigation de gauche, sélectionnez Expose an API (Exposer une API).
   2. Cliquez sur le champ Application ID URI (URI de l'ID application).
   3. Mettez à jour la valeur au format :

      api://botid-<Microsoft_App_ID_for_your_bot>

      Note
      
      Il doit s'agir de l'ID application du robot, pas celui de l'API d'authentification unique.
   4. Cliquez sur + Add a scope (Ajouter une étendue).
   5. Dans le panneau qui s'ouvre :
      • Définissez le nom access_as_user dans l'option Scope (Étendue).

        La partie de domaine du nom de l'étendue affichée juste au-dessous du champ de texte doit correspondre automatiquement à l'URI d'ID application définie à l'étape précédente, avec /access_as_user ajouté à la fin.

      • Réglez Who can consent? (Qui peut consentir) à Admins and users (Administrateurs et utilisateurs).
   6. Remplissez les champs de configuration des invites de consentement pour les administrateurs et les utilisateurs avec des valeurs appropriées à l'étendue access_as_user.

      Voici quelques suggestions :

      • Admin consent title (Titre de consentement d'administrateur) : Teams peut accéder au profil de l'utilisateur.
      • Admin consent description (Description du consentement d'administrateur) : Permet à Teams d'appeler les API Web de l'application en tant qu'utilisateur actuel.
      • User consent title (Titre de consentement d'utilisateur) : Teams peut accéder à votre profil d'utilisateur et faire des demandes en votre nom.
      • User consent description (Description du consentement d'utilisateur) : Permet à Teams d'appeler les API de cette application avec les mêmes droits que vous
   7. Assurez-vous que l'option State (État) est réglée à Enabled (Activé).
   8. Dans la section Authorized client applications (Applications clientes autorisées), cliquez sur + Add a client application (Ajouter une application cliente).
   9. Entrez les ID suivants :
      • 1fec8e78-bce4-4aaf-ab1b-5451cc387264

        Il s'agit de l'application mobile et de bureau Teams.

      • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346

        Il s'agit de l'application Web Teams.

6. Mettre à jour le manifeste :
   1. Dans la barre de navigation de gauche, sélectionnez Manifest (Manifeste).
   2. Réglez "acceptMappedClaims" à true.
   3. Réglez "accessTokenAcceptedVersion" à 2.
   4. Cliquez sur Save (Enregistrer).
7. Accorder des autorisations d'administrateur de locataire à l'application Azure AD.
   1. Dans la barre de navigation de gauche, sélectionnez Overview (Aperçu).
   2. Copiez l'ID application (client), l'ID répertoire (locataire) et l'URI d'ID application et enregistrez-les dans un endroit pratique.
   3. Dans une fenêtre de navigateur privé, connectez-vous au compte d'administrateur Microsoft.
      L'URL a le format suivant :

       https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>

      où vous remplacez <tenant-id> par l'ID répertoire (locataire) que vous venez de copier et <client-id> par l'ID application (client).
8. Dans la boîte de dialogue Permissions requested(Autorisations demandées), vérifiez et acceptez les autorisations.

Mettez à jour votre robot Microsoft avec les détails d'authentification unique que vous avez configurés :

1. Ouvrez le robot dans le portail des développeurs Teams et ouvrez l'éditeur de manifeste.
2. Sélectionnez l'onglet Informations de base.
3. Faites défiler l'affichage vers le bas jusqu'au champ ID application (client) et insérez l'ID application (client).
4. Sélectionnez l'onglet Connexion unique.
5. Dans l'URI de l'ID application, ajoutez l'URI de l'ID application que vous avez copié précédemment.
6. Dans le panneau de navigation de gauche, sélectionnez Publier dans l'organisation.

Vous allez maintenant enregistrer l'application Azure AD en tant que service d'authentification dans Oracle Digital Assistant.

1. Dans une fenêtre ou un onglet distinct du navigateur, ouvrez Digital Assistant, développez Settings (Paramètres) dans le menu de gauche et sélectionnez Authentication Services (Services d'authentification).

2. Cliquez sur + Service.
3. Dans la boîte de dialogue New Authentication Service (Nouveau service d'authentification), entrez les valeurs suivantes :
   • Fournisseur d'identités : Microsoft Identity Platform
   • Name (Nom) : Nom servant à identifier le service d'authentification.
   • Token Endpoint URL (URL du point d'extrémité du jeton) : URL du fournisseur d'identités pour les demandes de jetons d'accès. Utilisez :

     https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/token

   • Authorization Endpoint (Point d'extrémité d'autorisation) : URL du fournisseur d'identités pour la page dans laquelle les utilisateurs s'authentifient en entrant leur nom d'utilisateur et leur mot de passe. Utilisez :

     https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/authorize

   • Client ID and Client Secret (ID client et Clé secrète client) : ID client et clé secrète client de l'application Azure AD (client OAuth) enregistrée. Utilisez l'ID et la clé secrète de l'application.
   • Portée : <Application(client)_ID_for_your_bot>/access_as_user
   • Subject Claim (Revendication du sujet) : Revendication du profil de jeton d'accès à utiliser pour identifier l'utilisateur. Utilisez l'adresse de courriel.

Dans les compétences qui nécessitent une authentification unique, incorporez le composant OAuth 2.0 Account Link dans le flux de dialogue pour que le service d'authentification s'en charge. Dans ce composant, assurez-vous de régler la propriété enableSingleSignon à true. (Pour les flux de dialogue basés sur YAML, le composant est appelé System.OAuth2AccountLink.)

Pour créer plusieurs cartes, vous pouvez utiliser la propriété iteratorVariable avec l'élément card dans un élément de réponse de type carte. Voici un exemple d'utilisation d'une carte adaptative pour créer plusieurs cartes de pizza :

responseItems:
  - type: "cards"
    headerText: "Here are our pizzas you can order today:"
    cardLayout: "horizontal"
    cards:
      - title: "${pizzas.name}"
        description: "${pizzas.description}"
        imageUrl: "${pizzas.image}"
        iteratorVariable: "pizzas"
        actions:
          - label: "Order Now"
            type: "postback"
            payload:
              action: "order"
              variables:
                orderedPizza: "${pizzas.name}"
                orderedPizzaImage: "${pizzas.image}"
        channelCustomProperties:
        - channel: "msteams"
          properties:
            adaptiveCard:
              type: "AdaptiveCard"
              version: "1.0"
              fallbackText: "Adaptive card version not supported"
              body:
              - type: "TextBlock"
                text: "${pizzas.name}"
                weight: "bolder"
              - type: "TextBlock"
                text: "${pizzas.description}"
                wrap: true
              - type: "Image"
                url: "${pizzas.image}"
                horizontalAlignment: "center"
              actions:
              - type: "Action.Submit"
                title: "Order"
                data: 
                  action: "order" 
                  variables:
                    orderedPizza: "${pizzas.name}"
                    orderedPizzaImage: "${pizzas.image}"

Vous pouvez définir une carte adaptative avec un élément de réponse textuelle comme suit :

responseItems:
  - type: "text"
    text: "This text is replaced with adaptive card defined in custom property"
    footerText: "Is that correct?"
    visible:
      expression: "${system.channelType=='msteams' && system.entityToResolve.value.name=='Confirmed'}"
    channelCustomProperties:
      - channel: "msteams"
        properties:
          adaptiveCard:
            type: "AdaptiveCard"
            version: '1.0'          
            fallbackText: "Adaptive card version not supported"                                             
            body:
            - type: TextBlock
              text: 'I have all information needed to create your expense. Just to verify my understanding, here is an overview of your expense:'
              wrap: true
            - type: FactSet
              facts:
              - title: Expense Type
                value: "${expense.value.Type}"
              - title: Amount
                value: "${expense.value.Amount.totalCurrency}"
              - title: Date
                value: "${expense.value.Date.date?number_to_date}"
              - title: Receipt URL
                value: "${expense.value.Receipt?has_content?then(expense.value.Receipt.url,'N/A')}"
 
            actions:
            - type: Action.ShowCard
              title: Edit
              id: edit
              card:
                type: AdaptiveCard             
                version: '1.0'
                body:
                - type: TextBlock
                  size: Medium
                  weight: Bolder
                  text: Edit Expense
                - type: TextBlock
                  text: Expense Type
                  weight: Bolder
                - type: Input.ChoiceSet
                  choices:
                  - title: Metro, bus, train
                    value: Public transport
                  - title: Taxi
                    value: Taxi
                  - title: Breakfast, lunch, dinner
                    value: dinner
                  id: Type
                  value: "${expense.value.Type!''}"
                  spacing: None
                - type: TextBlock
                  text: Amount
                  weight: Bolder
                - type: Input.Text
                  id: amount
                  spacing: None
                  value: "${expense.value.Amount?has_content?then(expense.value.Amount.totalCurrency,'')}"
                - type: TextBlock
                  text: Date
                  weight: Bolder
                - type: Input.Date
                  id: Date
                  value: "${expense.value.Date?has_content?then(expense.value.Date.date?number_to_date,'')}"
                  spacing: None
                actions:
                - type: Action.Submit
                  title: Submit
                  id: submit

Vous pouvez également définir plusieurs cartes adaptatives dans cette propriété personnalisée. Pour ce faire, ajoutez un trait d'union (-) devant la propriété type afin d'indiquer une liste YAML plutôt qu'un mappage :

channelCustomProperties:
  - channel: "msteams"
    properties:
      adaptiveCard:
      - type: AdaptiveCard
        body: ...
      - type: AdaptiveCard
        body: ...

Cela peut être pratique si vous devez produire plusieurs cartes statiques, mais il est plus courant de créer plusieurs cartes à l'aide de la propriété iteratorVariable.

Les cartes adaptatives contiennent une action de soumission (Action.Submit), que vous pouvez utiliser pour collecter les entrées de l'utilisateur et les envoyer à la compétence.

Définissez les données utiles de l'action dans la propriété data de l'action de soumission. Si vous voulez que le composant de réponse commune effectue une transition après la sélection du bouton ou la définition de certaines variables, vous pouvez utiliser les propriétés action et variables standard :

actions:
- type: "Action.Submit"
  title: "Order"
  data: 
    action: "order" 
    variables:
      orderedPizza: "${pizzas.name}"
      orderedPizzaImage: "${pizzas.image}"

Si vous utilisez des champs d'entrée dans votre carte, le nom et la valeur de ceux-ci seront ajoutés sous la forme de paires clé-valeur à l'objet JSON data. L'exemple ci-dessus avec la carte Edit Expense (Modifier les frais) inclut trois champs pour modifier le type, le montant et la date des frais. Lorsque l'utilisateur touche le bouton Soumettre dans ce cas, un objet JSON semblable au suivant est envoyé :

{
  "Type" : "Taxi",
  "Amount" : "10.0 dollar"
  "Date" : "2019-09-02"
}

Le composant Réponse commune ne sait pas comment traiter ces informations, car elles ne respectent pas la structure commune des données utiles avec les propriétés action et variables. Pour résoudre ce problème, vous disposez des options suivantes :

• Convertissez les données utiles JSON en chaîne pour laquelle une correspondance sera recherchée parmi les entités. Si des correspondances sont trouvées, la variable définie avec le composant est mise à jour avec la ou les valeurs d'entité correspondantes (en cas d'entité composite).

  Pour configurer cette option, ajoutez la propriété booléenne system.convertToString booléenne à la propriété data de l'action de soumission :

  actions:
  - type: Action.Submit
    title: Submit
    id: submit                   
    data:
      system.convertToString: true

• Configurez la compétence pour qu'elle mette à jour les variables portant le même nom que les champs d'entrée. Dans l'exemple ci-dessus, les variables "Type", "Amount" et "Date" sont mises à jour.

  Pour configurer cette option, ajoutez la propriété system.setVariables booléenne à la propriété data de l'action de soumission :

  actions:
  - type: Action.Submit
    title: Submit
    id: submit                   
    data:
      system.setVariables: true

Si vous ne configurez aucune de ces options, les valeurs soumises sont simplement ignorées.

Lorsque vous utilisez un composant de réponse commune avec une entité composite, vous utilisez généralement la première option, qui alimente toutes les entités mises en correspondance dans l'entité composite en fonction des données utiles JSON transformées en chaîne.

Lorsqu'un utilisateur sélectionne un bouton dans une carte adaptative, la conversation n'est mise à jour pour refléter ce choix que si vous incluez une action messageBack pour la carte.

Pour configurer une action messageBack, voir https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-action.

Bien que vous ne puissiez pas désactiver techniquement les boutons et les champs des cartes adaptatives, vous pouvez créer un effet similaire en remplaçant la carte lorsqu'une action de soumission est appelée. Pour ce faire, utilisez la propriété booléenne replaceMessage propre à Microsoft Teams dans les composants de réponse commune.

Pour permettre le rendu de la carte de cette façon, ajoutez cette propriété dans la section channelCustomProperties du composant de réponse personnalisé :

        ...
           - type: "text"
             text: "This text is replaced with the adaptive card defined in custom property"
             channelCustomProperties:
               - channel: "msteams"
                 properties:
                   replaceMessage: "true"
                   adaptiveCard:
                     ...

Vous pouvez également utiliser une expression Apache FreeMarker pour définir la valeur de la propriété.

Le schéma JSON des cartes adaptatives est relativement complexe et prend en charge de nombreuses constructions. En tant que tel, il est source d'erreur lorsque vous essayez de définir le contenu de la carte adaptative à la main directement dans un composant Common Respone. Il vous semblera peut-être plus simple d'utiliser le processus suivant pour créer les cartes adaptatives :

1. Grâce aux outils visuels du concepteur de cartes adaptatives Microsoft, créez la définition de la carte adaptative.
2. Cliquez sur Copy Card JSON (Copier l'objet JSON de carte) pour obtenir la définition dans le format JSON.
3. Utilisez un convertisseur en ligne (par exemple, https://jsonformatter.org/json-to-yaml) pour convertir la définition au format YAML.
4. Copiez le résultat dans un éditeur de texte et insérez l'indentation requise à l'emplacement où il doit apparaître dans la définition du flux de dialogue.
5. Collez le texte résultant dans le flux de dialogue.