Per impostare SSO per una competenza o un assistente digitale in Microsoft Teams, è necessario creare un'applicazione Azure AD. Questa applicazione è oltre all'applicazione Azure AD già creata nell'ambito dell'impostazione del canale Microsoft Teams.

Prima di iniziare, assicurarsi di disporre delle informazioni riportate di seguito.

• Un account Azure con una sottoscrizione attiva.
• L'ID applicazione Microsoft per il bot impostato con il canale Microsoft Teams.
• Accesso amministratore al portale di Azure.

Di seguito sono riportati i passi per la creazione di un'applicazione Azure AD per SSO.

1. Creare una nuova registrazione dell'applicazione:
   1. Passare a https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade nel portale di Azure.
   2. Fare clic su Nuova registrazione.
   3. Compilare il campo Nome.
   4. Nella sezione Tipi di account supportati, selezionare il pulsante di opzione Account in qualsiasi directory organizzativa (qualsiasi directory Azure AD - Multitenant) e account Microsoft personali (ad esempio Skype, Xbox).
   5. Fare clic su Registra.

      Una volta creata l'applicazione, verrà visualizzata la sezione Panoramica. L'ID applicazione (client) e l'ID directory (tenant) devono essere creati per l'applicazione.

2. Aggiungere una configurazione di piattaforma Web:
   1. Nella navigazione a sinistra selezionare Autenticazione.
   2. In Configurazioni piattaforma fare clic su Aggiungi una piattaforma e selezionare Web.
   3. Aggiungere un URI di reindirizzamento utilizzando il seguente formato:

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

   4. Fare clic su Configura.
3. Creare un segreto client:
   1. Nella navigazione a sinistra selezionare Certificati e segreti.
   2. Fare clic su + Nuovo segreto client, compilare i campi obbligatori e fare clic su Aggiungi.
   3. Copiare il valore del segreto client e memorizzarlo in un luogo sicuro. Questo valore sarà necessario in seguito.
4. Configurare il token:
   1. Nella navigazione a sinistra, selezionare Configurazione token.
   2. Fare clic su + Aggiungi richiesta facoltativa.
   3. Per Tipo di token selezionare Accesso.
   4. Selezionare queste richieste di rimborso:
      • given_name
      • upn
      • e-mail
   5. Fare clic su Aggiungi.
   6. Selezionare l'opzione Attivare l'e-mail di Microsoft Graph, l'autorizzazione del profilo (obbligatoria per la visualizzazione delle richieste nel token) e fare clic su Aggiungi.
   7. Nella navigazione a sinistra selezionare Autorizzazioni API.

      Qui è possibile vedere che vengono create tre autorizzazioni.

   8. Fare clic su + Aggiungi un'autorizzazione e aggiungere User.ReadBasic.All.

      Sarà necessario accedere alle informazioni sul profilo.

5. Impostare l'URI ID applicazione:
   1. Nella navigazione a sinistra selezionare Esponi un'interfaccia API.
   2. Fare clic sul campo URI ID applicazione.
   3. Aggiornare il valore nel formato:

      api://botid-<Microsoft_App_ID_for_your_bot>

      Nota
      
      Deve essere l'ID applicazione per il bot, non quello per l'applicazione SSO.
   4. Fare clic su + Aggiungi un ambito.
   5. Nel pannello che si apre:
      • Impostare access_as_user come nome Ambito.

        La parte del dominio del nome ambito visualizzata appena sotto il campo di testo deve corrispondere automaticamente all'URI ID applicazione impostato nel passo precedente, con /access_as_user aggiunto alla fine.

      • Impostare Chi può fornire il consenso? su Amministratori e utenti.
   6. Compilare i campi per la configurazione dei prompt di consenso dell'amministratore e dell'utente con i valori appropriati per l'ambito access_as_user.

      Ecco alcuni suggerimenti:

      • Titolo consenso amministratore: i team possono accedere al profilo dell'utente.
      • Descrizione del consenso dell'amministratore: consente ai team di chiamare le API Web dell'applicazione come utente corrente.
      • Titolo del consenso dell'utente: i team possono accedere al proprio profilo utente ed effettuare richieste per conto dell'utente.
      • Descrizione del consenso dell'utente: consente ai team di chiamare le API di questa applicazione con gli stessi diritti di cui si dispone
   7. Assicurarsi che Stato sia impostato su Abilitato.
   8. Nella sezione Applicazioni client autorizzate fare clic su + Add a client application.
   9. Inserire i seguenti ID:
      • 1fec8e78-bce4-4aaf-ab1b-5451cc387264

        Questa è l'applicazione mobile e desktop Teams.

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

        Questa è l'applicazione Web Team.

6. Aggiornare il manifesto:
   1. Nella navigazione a sinistra selezionare Manifest.
   2. Impostare "acceptMappedClaims" su true.
   3. Impostare "accessTokenAcceptedVersion" su 2.
   4. Fare clic su Salva.
7. Concedere le autorizzazioni di amministratore tenant all'applicazione Azure AD.
   1. Nella navigazione a sinistra selezionare Panoramica.
   2. Copiare l'ID applicazione (client), l'ID directory (tenant) e l'URI ID applicazione e salvarli in una posizione comoda.
   3. In una finestra privata del browser, accedere all'account di amministrazione Microsoft.
      L'URL ha il formato seguente:

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

      dove si sostituisce <tenant-id> con l'ID directory (tenant) appena copiato e si sostituisce <client-id> con l'ID applicazione (client) appena copiato.
8. Nella finestra di dialogo Autorizzazioni richieste, rivedere e accettare le autorizzazioni.

Aggiornare il bot Microsoft con i dettagli SSO configurati:

1. Aprire il bot in Teams Developer Portal e aprire l'editor Manifest.
2. Selezionare la scheda Informazioni di base.
3. Scorrere fino al campo ID applicazione (client) e inserire l'ID applicazione (client).
4. Selezionare la scheda Single-Sign-On.
5. Nel campo URI ID applicazione aggiungere l'URI ID applicazione copiato in precedenza.
6. Nella navigazione a sinistra, selezionare Pubblica in organizzazione.

Ora è possibile registrare l'applicazione Azure AD come servizio di autenticazione in Oracle Digital Assistant.

1. In una finestra o scheda separata del browser, aprire Digital Assistant, espandere Impostazioni nel menu a sinistra e selezionare Servizi di autenticazione.

2. Fare clic su + Servizio.
3. Nella finestra di dialogo Nuovo servizio di autenticazione immettere i valori riportati di seguito.
   • Provider di identità: Piattaforma di identificazione Microsoft
   • Nome: nome per identificare il servizio di autenticazione.
   • URL endpoint token: l'URL del provider di identità per richiedere i token di accesso. Utilizzare:

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

   • Endpoint autorizzazione: l'URL del provider di identità per la pagina con cui gli utenti eseguono l'autenticazione immettendo il nome utente e la password. Utilizzare:

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

   • ID client e segreto client: l'ID e il segreto client per l'applicazione Azure AD (client OAuth) registrata. Utilizzare l'ID e il segreto applicazione.
   • Ambito: <Application(client)_ID_for_your_bot>/access_as_user
   • Richiesta di risarcimento oggetto: la richiesta di profilo con token di accesso da utilizzare per identificare l'utente. Usa e-mail.

Nelle competenze che richiedono l'autenticazione SSO, incorporare il componente OAuth 2.0 Account Link nel flusso della finestra di dialogo per gestire l'autenticazione tramite il servizio di autenticazione. In tale componente, assicurarsi di impostare la proprietà enableSingleSignOn su true. Per i flussi di dialogo basati su YAML, il componente è denominato System.OAuth2AccountLink.

Per eliminare più schede, è possibile utilizzare l'elemento iteratorVariable con l'elemento card all'interno di un elemento di risposta di tipo schede. Ecco un esempio per utilizzare una scheda adattiva per eliminare più carte 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}"

È possibile definire una scheda adattiva con un elemento di risposta di testo come indicato di seguito.

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

In questa proprietà personalizzata è inoltre possibile definire più schede adattive. A tale scopo, la proprietà type deve essere preceduta da un trattino (-) per indicare una lista YAML anziché una mappa:

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

Questo può essere conveniente se è necessario eliminare più carte statiche, ma sarà più comune eliminare più carte utilizzando la proprietà iteratorVariable.

Le schede adattive hanno un'azione di sottomissione (Action.Submit), che è possibile utilizzare per raccogliere l'input dell'utente e inviarlo alla competenza.

Definire il payload dell'azione nella proprietà data dell'azione di sottomissione. Se si desidera che la transizione del componente Risposta comune dopo la selezione del pulsante o l'impostazione di alcune variabili, è possibile utilizzare le proprietà action e variables standard:

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

Se si utilizzano campi di input nella scheda, il nome e il valore di questi campi verranno aggiunti come coppie chiave-valore all'oggetto JSON data. L'esempio precedente con la scheda Modifica spesa include tre campi per modificare il tipo di spesa, l'importo e la data. Quando l'utente tocca il pulsante Sottometti in questo caso, verrà inviato un oggetto JSON simile al seguente:

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

Il componente Risposta comune non sa come elaborare queste informazioni, in quanto non segue la struttura del payload comune con le proprietà action e variables. Per risolvere questo problema, sono disponibili le opzioni riportate di seguito.

• Convertire il payload JSON in una stringa, che verrà quindi trovata una corrispondenza per le entità. Se vengono trovate corrispondenze, la variabile impostata con il componente verrà aggiornata con il valore entità o i valori entità corrispondenti (nel caso di un'entità sacchetto composito).

  Per configurare questa opzione, aggiungere la proprietà booleana system.convertToString alla proprietà data dell'azione di sottomissione:

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

• Impostare le variabili di aggiornamento dello skill con lo stesso nome dei campi di input. Nell'esempio precedente, le variabili "Type", "Amount" e "Date" verranno aggiornate.

  Per configurare questa opzione, aggiungere la proprietà booleana system.setVariables alla proprietà data dell'azione di sottomissione:

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

Se non si configura alcuna di queste opzioni, i valori sottomessi verranno semplicemente ignorati.

Quando si utilizza un componente Risposta comune con un'entità bag composta, in genere si utilizza la prima opzione, che popolerà tutte le entità corrispondenti nel bag in base al payload JSON codificato.

Quando un utente seleziona un pulsante in una scheda adattiva, la conversazione non viene aggiornata per mostrare che l'utente ha selezionato tale opzione a meno che non si includa un'azione messageBack per la scheda.

Per impostare un'azione messageBack, vedere https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-action.

Sebbene non sia possibile disabilitare tecnicamente pulsanti e campi nelle schede adattive, è possibile creare un effetto simile sostituendo la scheda quando viene richiamata un'azione di sottomissione. A tale scopo, utilizzare la proprietà replaceMessage booleana specifica di Microsoft Teams nei componenti di Common Response.

Per consentire la restituzione della scheda in questo modo, aggiungere questa proprietà nella sezione channelCustomProperties del componente di risposta personalizzato:

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

È inoltre possibile utilizzare un'espressione FreeMarker Apache per impostare il valore della proprietà.

Lo schema JSON delle schede adattive è relativamente complesso con molti costrutti diversi supportati. Pertanto, è soggetto a errori quando si tenta di definire il contenuto della scheda adattiva a mano direttamente all'interno di un componente Respone comune. È possibile utilizzare il seguente processo per creare le schede adattive:

1. Con gli strumenti visivi disponibili in Progettazione schede adattive di Microsoft, creare la definizione della scheda adattiva.
2. Fare clic su Copia JSON scheda per ottenere la definizione in formato JSON.
3. Utilizzare un convertitore in linea, ad esempio https://jsonformatter.org/json-to-yaml, per convertire la definizione in YAML.
4. Copiare il risultato in un editor di testo e inserire l'indentazione necessaria per la posizione in cui verrà visualizzato nella definizione del flusso della finestra di dialogo.
5. Incollare il testo risultante nel flusso della finestra di dialogo.