Um SSO für einen Skill oder digitalen Assistenten in Microsoft Teams einzurichten, müssen Sie eine Azure AD-Anwendung erstellen. Diese Anwendung ist zusätzlich zur Azure AD-Anwendung, die Sie bereits beim Einrichten des Microsoft Teams-Kanals erstellt haben.

Voraussetzungen:

• Ein Azure-Account mit einem aktiven Abonnement
• Die Microsoft-App-ID für den Bot, den Sie mit Ihrem Microsoft Teams-Kanal eingerichtet haben
• Admin-Zugriff auf das Azure-Portal

So erstellen Sie eine Azure AD-Anwendung für SSO:

1. Erstellen Sie eine neue Anwendungsregistrierung:
   1. Navigieren Sie im Azure-Portal zu https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade.
   2. Klicken Sie auf New Registration.
   3. Füllen Sie das Feld Name aus.
   4. Wählen Sie im Abschnitt Supported account types das Optionsfeld Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) aus.
   5. Klicken Sie auf Register.

      Nachdem die Anwendung erstellt wurde, gelangen Sie in den Abschnitt Overview. Die Anwendungs-ID (Client-ID) und Verzeichnis-ID (Mandanten-ID) sollten für Ihre App erstellt werden.

2. Fügen Sie eine Webplattformkonfiguration hinzu:
   1. Wählen Sie in der linken Navigationsleiste die Option Authentication aus.
   2. Klicken Sie unter Platformkonfigurationen auf Plattform hinzufügen, und wählen Sie Web aus.
   3. Fügen Sie eine Umleitungs-URI mit folgendem Format hinzu:

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

   4. Klicken Sie auf Configure.
3. Erstellen Sie ein Client Secret:
   1. Klicken Sie in der linken Navigationsleiste auf Certificates and secrets.
   2. Klicken Sie auf + New client secret, füllen Sie die Pflichtfelder aus, und klicken Sie auf Add.
   3. Kopieren Sie den Client-Secret-Wert, und speichern Sie ihn an einem sicheren Ort. Sie benötigen diesen Wert später.
4. Konfigurieren Sie das Token:
   1. Wählen Sie in der linken Navigationsleiste die Option Token configuration aus.
   2. Klicken Sie auf + Add optional claim.
   3. Wählen Sie als Token type Access aus.
   4. Wählen Sie die folgenden Claims aus:
      • given_name
      • upn
      • email
   5. Klicken Sie auf Add.
   6. Wählen Sie die Option Turn on the Microsoft Graph email, profile permission (required for claims to appear in token) aus, und klicken Sie auf Add.
   7. Wählen Sie in der linken Navigationsleiste die Option API permissions aus.

      Dort werden drei Berechtigungen erstellt.

   8. Klicken Sie auf + Berechtigung hinzufügen, und fügen Sie User.ReadBasic.All hinzu.

      Sie benötigen diese Option, um auf Profilinformationen zuzugreifen.

5. Legen Sie die Anwendungs-ID-URI fest:
   1. Wählen Sie in der linken Navigationsleiste die Option Expose an API aus.
   2. Klicken Sie auf das Feld Application ID URI.
   3. Aktualisieren Sie den Wert im folgenden Format:

      api://botid-<Microsoft_App_ID_for_your_bot>

      Hinweis
      
      Dies muss die Anwendungs-ID für den Bot sein, nicht die für die SSO-APP.
   4. Klicken Sie auf + Add a scope.
   5. Führen Sie im Bereich, der daraufhin geöffnet wird, folgende Schritte aus:
      • Legen Sie access_as_user als Namen für Scope fest.

        Der Domainteil des Geltungsbereichnamens, der direkt unter dem Textfeld angezeigt wird, sollte automatisch mit der im vorherigen Schritt festgelegten Anwendungs-ID-URI übereinstimmen, wobei /access_as_user am Ende hinzugefügt wird.

      • Setzen Sie Who can consent? auf Admins and users.
   6. Füllen Sie die Felder für die Konfiguration von Admin- und Benutzerzustimmungs-Prompts mit Werten aus, die für den Geltungsbereich access_as_user geeignet sind.

      Vorschläge:

      • Admin consent title: Teams kann auf das Benutzerprofil zugreifen.
      • Admin consent description: Teams kann die Web-APIs der App als aktueller Benutzer aufrufen.
      • User consent title: Teams kann auf Ihr Benutzerprofil zugreifen und in Ihrem Namen Anforderungen senden.
      • User consent description: Teams kann die APIs dieser App mit Ihren Rechten aufrufen.
   7. Stellen Sie sicher, dass State auf Enabled gesetzt ist.
   8. Klicken Sie im Abschnitt Authorized client applications auf + Add a client application.
   9. Geben Sie die folgenden IDs ein:
      • 1fec8e78-bce4-4aaf-ab1b-5451cc387264

        Das ist die Teams-App und -Desktopanwendung.

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

        Das ist die Teams-Webanwendung.

6. Aktualisieren Sie das Manifest:
   1. Wählen Sie in der linken Navigationsleiste die Option Manifest aus.
   2. Setzen Sie "acceptMappedClaims" auf true.
   3. Setzen Sie "accessTokenAcceptedVersion" auf 2.
   4. Klicken Sie auf Speichern.
7. Erteilen Sie der Azure AD-Anwendung Mandanten-Admin-Berechtigungen.
   1. Wählen Sie in der linken Navigationsleiste die Option Overview aus.
   2. Kopieren Sie die Anwendungs-ID (Client-ID) unter Application (client) ID, die Verzeichnis-ID (Mandanten-ID) unter Directory (tenant) ID und die Anwendungs-ID-URI unter Application ID URI, und speichern Sie sie an einem geeigneten Ort.
   3. Melden Sie sich in einem privaten Browserfenster beim Microsoft-Admin-Account an.
      Die URL hat das folgende Format:

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

      Dabei ersetzen Sie <tenant-id> durch die gerade kopierte Verzeichnis-ID (Mandanten-ID) und <client-id> durch die gerade kopierte Anwendungs-ID (Client-ID).
8. Prüfen und akzeptieren Sie im Dialogfeld Permissions requested die Berechtigungen.

Aktualisieren Sie den Microsoft-Bot mit den konfigurierten SSO-Details:

1. Öffnen Sie den Bot im Teams-Entwicklerportal, und öffnen Sie den Manifesteditor.
2. Wählen Sie die Registerkarte Basisinformationen.
3. Scrollen Sie nach unten zum Feld Application (client) ID, und fügen Sie die Anwendungs-(Client-)ID ein.
4. Wählen Sie die Registerkarte Single-Sign-On aus.
5. Fügen Sie in der Anwendungs-ID-URI die zuvor kopierte Anwendungs-ID-URI hinzu.
6. Wählen Sie in der linken Navigation In Organisation veröffentlichen aus.

Jetzt registrieren Sie die Azure AD-App als Authentifizierungsservice in Oracle Digital Assistant.

1. Öffnen Sie in einem separaten Browserfenster oder in einer separaten Registerkarte Digital Assistant, blenden Sie Einstellungen im linken Menü ein, und wählen Sie Authentifizierungsservices aus.

2. Klicken Sie auf + Service.
3. Geben Sie im Dialogfeld Neuer Authentifizierungsservice die folgenden Werte ein:
   • Identitätsprovider: Microsoft Identify Platform
   • Name: Ein Name, mit dem der Authentifizierungsservice identifiziert wird.
   • Tokenendpunkt-URL: Die URL des Identitätsproviders für die Anforderung von Zugriffstokens. Verwenden Sie:

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

   • Autorisierungsendpunkt: Die IDP-URL für die Seite, über die sich Benutzer authentifizieren, indem sie ihren Benutzernamen und ihr Kennwort eingeben. Verwenden Sie:

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

   • Client-ID und Client Secret: Die Client-ID und das Secret für die registrierte Azure AD-Anwendung (OAuth-Client). Verwenden Sie die Anwendungs-ID und das Anwendungs-Secret.
   • Geltungsbereich: <Application(client)_ID_for_your_bot>/access_as_user
   • Subject-Anspruch: Der zu verwendende Zugriffstoken-Profilanspruch zur Identifizierung des Benutzers. Verwenden Sie E-Mail.

Nehmen Sie in Skills, die eine SSO-Authentifizierung erfordern, die Komponente OAuth 2.0-Accountlink in den Dialogablauf auf, um die Authentifizierung über den Authentifizierungsservice zu verarbeiten. Setzen Sie die Eigenschaft enableSingleSignOn in dieser Komponente auf true. (Bei YAML-basierten Dialogabläufen heißt die Komponente System.OAuth2AccountLink.)

Um mehrere Karten auszuschließen, können Sie die Eigenschaft iteratorVariable mit dem Element card in einem Antwortelement des Typs "Karten" verwenden. Im folgenden Beispiel werden mit einer adaptiven Karte mehrere Pizzakarten ausgeschlossen:

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}"

Sie können eine adaptive Karte mit einem Textantwortelement wie folgt definieren:

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

Sie können auch mehrere adaptive Karten in dieser benutzerdefinierten Eigenschaft definieren. Stellen Sie dazu der Eigenschaft type einen Bindestrich (-) voran, um eine YAML-Liste anstelle einer Zuordnung anzugeben:

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

Dies kann praktisch sein, wenn Sie mehrere statische Karten ausschließen müssen. In der Regel werden jedoch mehrere Karten mit der Eigenschaft iteratorVariable ausgeschlossen.

Adaptive Karten verfügen über eine Weiterleitungsaktion (Action.Submit), mit der Sie Benutzereingaben erfassen und an den Skill senden können.

Sie definieren die Payload der Aktion in der Eigenschaft data der Weiterleitungsaktion. Wenn die Komponente "Allgemeine Antwort" den Übergang nach Auswahl der Schaltfläche durchführen soll oder Sie Variablen festlegen möchten, können Sie die Standardeigenschaften action und variables verwenden:

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

Wenn Sie Eingabefelder in der Karte verwenden, werden Name und Wert dieser Felder als Schlüssel/Wert-Paare zum JSON-Objekt data hinzugefügt. Das Beispiel oben mit der Karte Spesen bearbeiten enthält drei Felder zur Änderung von Spesentyp, Betrag und Datum. Wenn der Benutzer in diesem Fall auf die Schaltfläche Weiterleiten tippt, wird ein JSON-Objekt wie das Folgende gesendet:

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

Die Komponente "Gemeinsame Antwort" kann diese Informationen nicht verarbeiten, da sie nicht der gemeinsamen Payload-Struktur mit den Eigenschaften action und variables entspricht. Um dieses Problem zu beheben, haben Sie folgende Optionen:

• Konvertieren Sie die JSON-Payload in eine Zeichenfolge, die anschließend für Entitys abgeglichen wird. Wenn Übereinstimmungen gefunden werden, wird die mit der Komponente festgelegte Variable mit dem entsprechenden Entitywert bzw. den entsprechenden Entitywerten aktualisiert (bei einer Mischentität).

  Um diese Option zu konfigurieren, fügen Sie die boolesche Eigenschaft system.convertToString der Eigenschaft data der Weiterleitungsaktion hinzu:

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

• Überlassen es dem Skill, Variablen mit denselben Namen wie die Eingabefelder zu aktualisieren. Im obigen Beispiel werden die Variablen "Type", "Amount" und "Date" aktualisiert.

  Um diese Option zu konfigurieren, fügen Sie die boolesche Eigenschaft system.setVariables der Eigenschaft data der Weiterleitungsaktion hinzu:

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

Wenn Sie keine dieser Optionen konfigurieren, werden die weitergeleiteten Werte einfach ignoriert.

Wenn Sie eine Komponente "Gemeinsame Antwort" mit einer Mischentity verwenden, werden Sie in der Regel die erste Option verwenden, die alle übereinstimmenden Entitys in der Tasche basierend auf der Zeichenfolgen-JSON-Payload auffüllt.

Wenn ein Benutzer eine Schaltfläche in einer adaptiven Karte auswählt, wird dies in der Unterhaltung nur angezeigt, wenn Sie eine messageBack-Aktion für die Karte aufnehmen.

Informationen zum Einrichten einer messageBack-Aktion finden Sie unter https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-action.

Obwohl Sie Schaltflächen und Felder in adaptiven Karten eigentlich nicht deaktivieren können, können Sie eine ähnliche Wirkung erzielen, indem Sie die Karte bei Aufruf einer Weiterleitungsaktion ersetzen. Dazu verwenden Sie die für Microsoft Teams spezifische boolesche Eigenschaft replaceMessage in gemeinsamen Antwortkomponenten.

Damit die Karte auf diese Weise neu gerendert werden kann, fügen Sie diese Eigenschaft im Abschnitt channelCustomProperties der benutzerdefinierten Antwortkomponente hinzu:

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

Sie können auch einen Apache FreeMarker-Ausdruck verwenden, um den Eigenschaftswert festzulegen.

Das JSON-Schema für adaptive Karten ist relativ komplex und unterstützt viele verschiedene Konstrukte. Daher ist es fehleranfällig, wenn Sie versuchen, den Inhalt adaptiver Karten direkt innerhalb einer Common Respone-Komponente von Hand zu definieren. Der folgende Prozess zur Erstellung der adaptiven Karten ist möglicherweise einfacher:

1. Erstellen Sie mit den visuellen Tools im Designer für adaptive Karten von Microsoft die Definition für die adaptiven Karten.
2. Klicken Sie auf Karten-JSON kopieren, um die Definition im JSON-Format abzurufen.
3. Verwenden Sie einen Online-Converter (wie https://jsonformatter.org/json-to-yaml), um die Definition in YAML zu konvertieren.
4. Kopieren Sie das Ergebnis in einen Texteditor, und fügen Sie den für die entsprechende Stelle in der Definition des Dialogablaufs erforderlichen Einzug ein.
5. Fügen Sie den daraus resultierenden Text in den Dialogablauf ein.