To set up SSO for a skill or digital assistant within Microsoft Teams, you need to create an Azure AD application. This application is in addition to the Azure AD application you have already created as part of setting up the Microsoft Teams channel.

Before getting started, make sure that you have the following:

• An Azure account with an active subscription.
• The Microsoft App ID for the bot that you have set up with your Microsoft Teams channel.
• Admin access to the Azure portal.

Here are the steps for creating an Azure AD application for SSO:

1. Create a new application registration:
   1. Navigate to https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade in the Azure portal.
   2. Click New Registration.
   3. Fill in the Name field.
   4. In the Supported account types section, select the Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) radio button.
   5. Click Register.

      Once the application is created, you will land in the Overview section. The Application (client) ID and Directory (tenant) ID should be created for your app.

2. Add a web platform configuration:
   1. In the left navigation, select Authentication.
   2. Under Platform configurations, click Add a platform and select Web.
   3. Add a redirect URI using the following format:

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

   4. Click Configure.
3. Create a client secret:
   1. In the left navigation, select Certificates and secrets.
   2. Click + New client secret, fill in the required fields, and click Add.
   3. Copy the client secret value and store in a secure place. You'll need this value later.
4. Configure the token:
   1. In the left navigation, select Token configuration.
   2. Click + Add optional claim.
   3. For Token type, select Access.
   4. Select these claims:
      • given_name
      • upn
      • email
   5. Click Add.
   6. Select the Turn on the Microsoft Graph email, profile permission (required for claims to appear in token) option and click Add.
   7. In the left navigation, select API permissions.

      There you can see that three permissions are created.

   8. Click + Add a Permission and add User.ReadBasic.All.

      You will need this to access profile information.

5. Set the application ID URI:
   1. In the left navigation, select Expose an API.
   2. Click the Application ID URI field.
   3. Update the value in the format:

      api://botid-<Microsoft_App_ID_for_your_bot>

      Note
      
      This needs to be the application ID for the bot, not the one for the SSO APP.
   4. Click + Add a scope.
   5. In the panel that opens:
      • Set access_as_user as the Scope name.

        The domain part of the scope name displayed just below the text field should automatically match the Application ID URI set in the previous step, with /access_as_user added to the end.

      • Set Who can consent? to Admins and users.
   6. Fill in the fields for configuring the admin and user consent prompts with values that are appropriate for the access_as_user scope.

      Here are some suggestions:

      • Admin consent title: Teams can access the user’s profile.
      • Admin consent description: Allows Teams to call the app’s web APIs as the current user.
      • User consent title: Teams can access your user profile and make requests on your behalf.
      • User consent description: Enable Teams to call this app’s APIs with the same rights that you have
   7. Ensure that State is set to Enabled.
   8. In the Authorized client applications section, click + Add a client application.
   9. Enter the following IDs:
      • 1fec8e78-bce4-4aaf-ab1b-5451cc387264

        This is the Teams mobile and desktop application.

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

        This is the Teams web application.

6. Update the manifest:
   1. In the left navigation, select Manifest.
   2. Set "acceptMappedClaims" to true.
   3. Set "accessTokenAcceptedVersion" to 2.
   4. Click Save.
7. Grant tenant admin permissions to the Azure AD application.
   1. In the left navigation, select Overview.
   2. Copy the Application (client) ID, the Directory (tenant) ID and the Application ID URI and save them in a convenient place.
   3. In a private browser window, log in to the Microsoft admin account.
      The URL takes the following form:

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

      where you replace <tenant-id> with the Directory (tenant) ID that you just copied and you replace <client-id> with the Application (client) ID that you just copied.
8. In the Permissions requested dialog, review and accept the permissions.

Update your Microsoft bot with the SSO details you have configured:

1. Open the bot in the Teams Developer Portal and open the Manifest Editor.
2. Select the Basic information tab.
3. Scroll down to the Application (client) ID field and insert the application (client) ID.
4. Select the Single-Sign-On tab.
5. In the Application ID URI, add the application ID URI that you copied earlier.
6. In the left navigation, select Publish to org.

Now you'll register the Azure AD app as an authentication service in Oracle Digital Assistant.

1. In a separate browser window or tab, open Digital Assistant, expand Settings in the left menu, and select Authentication Services.

2. Click + Service.
3. In the New Authentication Service dialog, enter these values:
   • Identity Provider: Microsoft Identify Platform
   • Name: A name to identify the authentication service.
   • Token Endpoint URL: The identity provider's URL for requesting access tokens. Use:

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

   • Authorization Endpoint: The IDP's URL for the page that users authenticate with by entering their user name and password. Use:

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

   • Client ID and Client Secret: The client ID and secret for the Azure AD application (OAuth Client) that was registered. Use the application ID and secret.
   • Scope: <Application(client)_ID_for_your_bot>/access_as_user
   • Subject Claim: The access-token profile claim to use to identify the user. Use email.

In skills that need SSO authentication, incorporate the OAuth 2.0 Account Link component in the dialog flow to handle authentication through the authentication service. In that component, be sure to set the enableSingleSignOn property to true. (For YAML-based dialog flows, the component is called System.OAuth2AccountLink.)

To stamp out multiple cards, you can use the iteratorVariable with the card element within a response item of type cards. Here is an example to use an adaptive card to stamp out multiple pizza cards:

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

You can define an adaptive card with a text response item as follows:

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

You can also define multiple adaptive cards in this custom property. To do so, you prefix the type property with a hypen (-) to indicate a YAML list rather than a map:

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

This can be convenient if you need to stamp out multiple static cards, but it will be more common to stamp out multiple cards using the iteratorVariable property.

Adaptive Cards has a submit action (Action.Submit), which you can use to gather user input and send it to the skill.

You define the action's payload in the data property of the submit action. If you want the Common Response component to transition after the button is selected or set some variables, you can use the standard action and variables properties:

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

If you're using input fields in your card, the name and value of these fields will be added as key-value pairs to the data JSON object. The example above with the Edit Expense card includes three fields to modify the expense type, amount, and date. When the user taps the Submit button in this case, a JSON object like the following will be sent:

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

The Common Response component doesn't know how to process this information, as it does not follow the common payload structure with action and variables properties. To solve this, you have these options:

• Convert the JSON payload to a string, which will then be matched for entities. If any matches are found, the variable set with the component will be updated with the corresponding entity value or entity values (in case of a composite bag entity).

  To configure this option, you add the boolean system.convertToString property to the data property of the submit action:

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

• Have the skill update variables with the same name as the input fields. In the above example, the "Type", "Amount" and "Date" variables would be updated.

  To configure this option, you add the boolean system.setVariables property to the data property of the submit action:

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

If you don't configure any of these options, the submitted values will simply be ignored.

When using a Common Response component with a composite bag entity, you will typically use the first option, which will populate all the matched entities in the bag based on the stringified JSON payload.

When a user selects a button in an Adaptive Card, the conversation isn't updated to show that the user selected that option unless you include a messageBack action for the card.

To set up a messageBack action, see https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-action.

Though you can't technically disable buttons and fields in Adaptive Cards, you can create a similar effect by replacing the card when a submit action is invoked. You do so using the Boolean replaceMessage property that is specific to Microsoft Teams in Common Response components.

To enable the card to be re-rendered in this way, add this property within the channelCustomProperties section of the custom response component:

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

You can also use an Apache FreeMarker expression to set the property's value.

The adaptive cards JSON schema is relatively complex with many different constructs supported. As such, it is error prone when you try to define the adaptive card content by hand directly inside a Common Respone component. You may find it easier to use the following process to create the adaptive cards:

1. With the visual tools in Microsoft's Adaptive Cards Designer, create the adaptive card definition.
2. Click Copy Card JSON to get the definition in JSON format.
3. Use an online converter (such as https://jsonformatter.org/json-to-yaml) to convert the definition to YAML.
4. Copy the result into a text editor and insert the indentation that is required for where it will appear in the the dialog flow definition.
5. Paste the resulting text into the dialog flow.