Pour configurer SSO pour une brique 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 de ce qui suit :

• Compte Azure avec abonnement actif
• ID d'application Microsoft pour le bot que vous avez configuré avec votre canal Microsoft Teams
• Accès administrateur au portail Azure

Voici la procédure de création d'une application Azure AD pour SSO :

1. Créez une inscription d'application :
   1. Accédez à https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade sur le portail Azure.
   2. Cliquez sur Nouvelle inscription.
   3. Remplissez le champ Nom.
   4. Dans la section Types de compte pris en charge, sélectionnez le bouton radio Comptes dans n'importe quel répertoire d'organisation (tout répertoire Azure AD colocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox).
   5. Cliquez sur Inscrire.

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

2. Ajoutez une configuration de plate-forme Web :
   1. Dans la navigation de gauche, sélectionnez Authentification.
   2. Sous Configurations de plate-forme, cliquez sur Ajouter une plate-forme et sélectionnez Web.
   3. Ajoutez un URI de réacheminement au format suivant :

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

   4. Cliquez sur Configurer.
3. Créez une clé secrète client :
   1. Dans la navigation de gauche, sélectionnez Certificats et clés secrètes.
   2. Cliquez sur + Nouvelle clé secrète client, remplissez les champs requis, puis cliquez sur Ajouter.
   3. Copiez la valeur de clé secrète client et stockez-la dans un emplacement sécurisé. Vous aurez besoin de cette valeur ultérieurement.
4. Configurez le jeton :
   1. Dans la navigation de gauche, sélectionnez Configuration de jeton.
   2. Cliquez sur + Ajouter une déclaration facultative.
   3. Dans Type de jeton, sélectionnez Accès.
   4. Sélectionnez les déclarations suivantes :
      • given_name
      • upn
      • email
   5. Cliquez sur Ajouter.
   6. Sélectionnez l'option Activer les droits d'accès de profil de courriel Microsoft Graph (requis pour que les déclarations apparaissent dans le jeton) et cliquez sur Ajouter.
   7. Dans la navigation de gauche, sélectionnez Droits d'accès d'API.

      Vous pouvez constater que trois droits d'accès sont créés.

   8. Cliquez sur + Ajouter un droit d'accès et ajoutez User.ReadBasic.All.

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

5. Définissez l'URI d'ID d'application :
   1. Dans la navigation de gauche, sélectionnez Exposer une API.
   2. Cliquez sur le champ URI d'ID d'application.
   3. Mettez à jour la valeur au format suivant :

      api://botid-<Microsoft_App_ID_for_your_bot>

      Remarque
      
      Il doit s'agir de l'ID d'application du bot, pas de celui de l'application SSO.
   4. Cliquez sur + Ajouter une portée.
   5. Dans le panneau qui apparaît, effectuez les opérations suivantes :
      • Définissez access_as_user comme nom de portée.

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

      • Définissez Qui peut accepter ? sur Administrateurs et utilisateurs.
   6. Remplissez les champs de configuration des invites de consentement administrateur et utilisateur avec les valeurs appropriées pour la portée access_as_user.

      Voici quelques suggestions :

      • Titre du consentement administrateur : Teams peut accéder au profil de l'utilisateur.
      • Description du consentement administrateur : Permet à Teams d'appeler les API Web de l'application sous le nom de l'utilisateur en cours.
      • Titre du consentement utilisateur : Teams peut accéder à votre profil utilisateur et effectuer des demandes en votre nom.
      • Description du consentement utilisateur : Autorisez Teams à appeler les API de cette application avec les mêmes droits que vous.
   7. Assurez-vous que Etat est défini sur Activé.
   8. Dans la section Applications client autorisées, cliquez sur + Ajouter une application client.
   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. Mettez à jour le manifeste :
   1. Dans la navigation de gauche, sélectionnez Manifeste.
   2. Définissez "acceptMappedClaims" sur true.
   3. Définissez "accessTokenAcceptedVersion" sur 2.
   4. Cliquez sur Enregistrer.
7. Accordez des droits d'accès d'administrateur de locataires à l'application Azure AD.
   1. Dans la navigation de gauche, sélectionnez Aperçu.
   2. Copiez l'ID d'application (client), l'ID de répertoire (locataire) et l'URI d'ID d'application, et enregistrez-les dans un emplacement pratique.
   3. Dans une fenêtre de navigateur privée, connectez-vous au compte d'administrateur Microsoft.
      L'URL présente le format suivant :

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

      où vous remplacez <tenant-id> par l'ID de répertoire (locataire) que vous venez de copier, et <client-id> par l'ID d'application (client) que vous venez de copier.
8. Dans la boîte de dialogue Droits d'accès demandés, vérifiez et acceptez les droits d'accès.

Mettez à jour votre bot Microsoft avec les détails SSO que vous avez configurés :

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

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

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

2. Cliquez sur + Service.
3. Dans la boîte de dialogue Nouveau service d'authentification, entrez les valeurs suivantes :
   • Fournisseur d'identités : Plate-forme d'identité Microsoft
   • Nom : nom permettant d'identifier le service d'authentification.
   • URL endpoint de jeton : URL du fournisseur d'identités pour la demande de jetons d'accès. Utilisez :

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

   • Adresse d'autorisation : URL du fournisseur d'identités pour la page avec laquelle les utilisateurs s'authentifient en entrant leur nom utilisateur et leur mot de passe. Utilisez :

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

   • ID client et clé secrète client : ID et clé secrète client pour l'application Azure AD (client OAuth) inscrite. Utilisez l'ID et la clé secrète d'application.
   • Portée : <Application(client)_ID_for_your_bot>/access_as_user
   • Déclaration du sujet : déclaration de profil access-token à utiliser pour identifier l'utilisateur. Utilisez le courriel.

Dans les briques nécessitant une authentification SSO, intégrez le composant OAuth 2.0 Account Link dans le flux de dialogue pour gérer l'authentification via le service d'authentification. Dans ce composant, veillez à définir la propriété enableSingleSignOn sur true. (Pour les flux de dialogue basés sur YAML, le composant est appelé System.OAuth2AccountLink.)

Pour appliquer plusieurs cartes, vous pouvez utiliser l'élément iteratorVariable avec l'élément card d'un élément de réponse de type cartes. Voici un exemple d'utilisation d'une carte adaptative pour appliquer 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 texte 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 préfixe à la propriété type avec un tiret (-) pour indiquer une liste YAML plutôt qu'une correspondance :

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

Ceci peut s'avérer utile si vous devez appliquer plusieurs cartes statiques, mais en règle générale vous appliquerez plusieurs cartes à l'aide de la propriété iteratorVariable.

Les cartes adaptatives disposent d'une action de soumission (Action.Submit) que vous pouvez utiliser pour collecter les saisies utilisateur et les envoyer à la brique.

Vous devez définir la charge utile de l'action dans la propriété data de l'action de soumission. Pour que le composant Common Response (Réponse commune) effectue une transition lorsque le bouton est sélectionné ou définisse des variables, vous pouvez utiliser les propriétés standard action et variables :

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

Si vous utilisez des champs de saisie dans votre carte, le nom et la valeur de ces champs seront ajoutés en tant que paires clé-valeur à l'objet JSON data. L'exemple ci-dessus pour la carte Modifier les dépenses inclut trois champs permettant de modifier le type de dépense, le montant et la date. Dans cet exemple, lorsque l'utilisateur appuie sur le bouton Soumettre, 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 il ne suit pas la même structure de charge utile commune que les propriétés action et variables. Pour résoudre ce problème, vous disposez des options suivantes :

• Convertissez la charge utile JSON en une chaîne qui sera ensuite mise en correspondance avec les entités. Si des correspondances sont trouvées, la variable définie par le composant est mise à jour avec la valeur d'entité correspondante (ou les valeurs d'entité dans le cas d'une entité de conteneur composite).

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

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

• Mettez à jour les variables de la brique de façon à utiliser le même nom que les champs d'entrée. Dans l'exemple ci-dessus, les variables "Type", "Amount" et "Date" seraient mises à jour.

  Pour configurer cette option, ajoutez la propriété booléenne system.setVariables à 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 seront simplement ignorées.

Lorsque vous utilisez un composant Réponse commune avec une entité de conteneur composite, vous utilisez généralement la première option, qui renseigne toutes les entités correspondantes du conteneur sur la base de la charge utile JSON indiquée sous forme de chaîne.

Lorsqu'un utilisateur sélectionne un bouton dans une carte adaptative, la conversation n'est pas mise à jour pour montrer que l'utilisateur a sélectionné cette option, sauf si vous incluez une action messageBack pour la carte.

Pour configurer une action messageBack, reportez-vous à 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 dans les 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 aux composants Microsoft Teams in Common Response.

Pour permettre l'affichage de la carte de cette manière, 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 structures différentes. C'est pourquoi des erreurs sont susceptibles de survenir lorsque vous essayez de définir manuellement le contenu de la carte adaptative directement dans un composant Common Respone. Nous vous recommandons d'utiliser la procédure suivante pour créer des cartes adaptatives :

1. Utilisez les outils visuels du concepteur de cartes adaptatives de Microsoft pour créer une définition de carte adaptative.
2. Cliquez sur Copier le fichier JSON de la carte pour obtenir la définition au format JSON.
3. Utilisez un convertisseur en ligne (tel que https://jsonformatter.org/json-to-yaml) pour convertir la définition en YAML.
4. Copiez le résultat dans un éditeur de texte et insérez la mise en retrait nécessaire à l'endroit où celui-ci apparaît dans la définition de flux de dialogue.
5. Collez le texte obtenu dans le flux de dialogue.