Microsoft Teams内でスキルまたはデジタル・アシスタントのSSOを設定するには、Azure ADアプリケーションを作成する必要があります。このアプリケーションは、Microsoft Teamsチャネルの設定の一部としてすでに作成したAzure ADアプリケーションに加えてあります。

開始する前に、次のものがあることを確認してください:

• アクティブなサブスクリプションが含まれるAzureアカウント。
• Microsoft Teamsチャネルに対して設定したボットのMicrosoftアプリID。
• Azureポータルへの管理者アクセス権。

SSO対応のAzure ADアプリケーションを作成するステップは次のとおりです:

1. 新しいアプリケーション登録を作成します:
   1. Azureポータルでhttps://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBladeに移動します。
   2. 「新しい登録」をクリックします。
   3. 「Name」フィールドに入力します。
   4. 「サポートされているアカウントの種類」セクションで、「任意の組織のディレクトリ (任意の Azure AD ディレクトリ - マルチテナント) 内のアカウントと、個人用の Microsoft アカウント (Skype、Xboxなど)」ラジオ・ボタンを選択します。
   5. 「Register」をクリックします。

      アプリケーションが作成されると、「Overview」セクションが表示されます。アプリケーション(クライアント) IDおよびディレクトリ(テナント) IDをアプリケーション用に作成する必要があります。

2. Webプラットフォーム構成を追加します:
   1. 左側のナビゲーションで、「Authentication」を選択します。
   2. 「プラットフォーム構成」で、「プラットフォームの追加」をクリックし、「Web」を選択します。
   3. 次のフォーマットを使用してリダイレクトURIを追加します:

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

   4. 「Configure」をクリックします。
3. クライアント・シークレットを作成します:
   1. 左側のナビゲーションで、「Certificates and secrets」を選択します。
   2. 「+ New client secret」をクリックし、必要なフィールドに入力して、「Add」をクリックします。
   3. クライアント・シークレット値をコピーし、安全な場所に格納します。この値は、後で必要になります。
4. トークンを構成します:
   1. 左側のナビゲーションで、「Token configuration」を選択します。
   2. 「+ Add optional claim」をクリックします。
   3. 「Token type」で、「Access」を選択します。
   4. 次の要求を選択します:
      • given_name
      • upn
      • email
   5. 「Add」をクリックします。
   6. 「Turn on the Microsoft Graph email, profile permission (required for claims to appear in token)」オプションを選択し、「Add」をクリックします。
   7. 左側のナビゲーションで、「API permissions」を選択します。

      ここで、3つの権限が作成されていることを確認します。

   8. 「+権限の追加」をクリックし、User.ReadBasic.Allを追加します。

      プロファイル情報にアクセスするには、これが必要になります。

5. アプリケーションID URIを設定します:
   1. 左側のナビゲーションで、「Expose an API」を選択します。
   2. 「Application ID URI」フィールドをクリックします。
   3. 次のフォーマットで値を更新します:

      api://botid-<Microsoft_App_ID_for_your_bot>

      ノート
      
      これは、SSO APPのアプリケーションIDではなくボットのアプリケーションIDである必要があります。
   4. 「+ Add a scope」をクリックします。
   5. 開いたパネルで:
      • 「Scope」名としてaccess_as_userを設定します。

        スコープ名のドメイン・パートがテキスト・フィールドのすぐ下に表示され、前のステップで設定したアプリケーションID URIの末尾に/access_as_userが追加されます。

      • 「Who can consent?」を「Admins and users」に設定します。
   6. 管理者とユーザーの同意のプロンプトを構成するためのフィールドに、access_as_userスコープに適した値を入力します。

      いくつかの推奨設定を次に示します:

      • Admin consent title: Teamsがユーザーのプロファイルにアクセスできます。
      • Admin consent description: Teamsが、現在のユーザーとしてアプリケーションのWeb APIをコールできます。
      • User consent title: Teamsが、ユーザー・プロファイルにアクセスして、ユーザーのかわりに要求を行うことができます。
      • User consent description: Teamsが、ユーザーと同じ権限を使用して、このアプリのAPIをコールできるようになります。
   7. 「State」が「Enabled」に設定されていることを確認します。
   8. 「Authorized client applications」セクションで、「+ Add a client application」をクリックします。
   9. 次のIDを入力します:
      • 1fec8e78-bce4-4aaf-ab1b-5451cc387264

        これは、Teamsモバイルおよびデスクトップ・アプリケーションです。

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

        これは、Teams Webアプリケーションです。

6. マニフェストを更新します:
   1. 左側のナビゲーションで、「Manifest」を選択します。
   2. "acceptMappedClaims"をtrueに設定します。
   3. "accessTokenAcceptedVersion"を2に設定します。
   4. 「Save」をクリックします。
7. テナント管理者権限をAzure ADアプリケーションに付与します。
   1. 左側のナビゲーションで、「Overview」を選択します。
   2. アプリケーション(クライアント) ID、ディレクトリ(テナント) IDおよびアプリケーションID URIをコピーし、便利な場所に保存します。
   3. プライベート・ブラウザ・ウィンドウで、Microsoft管理者アカウントにログインします。
      URLの形式は次のとおりです:

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

      ここで、<tenant-id>をコピー済のディレクトリ(テナント) IDで置き換え、<client-id>をコピー済のアプリケーション(クライアント) IDで置き換えます。
8. 「Permissions requested」ダイアログで、権限を確認して受け入れます。

構成したSSOの詳細でMicrosoftボットを更新します:

1. Teams開発者ポータルでボットを開き、マニフェスト・エディタを開きます。
2. 「基本情報」タブを選択します。
3. 「Application (client) ID」フィールドにスクロール・ダウンし、アプリケーション(クライアント) IDを挿入します。
4. 「シングル・サインオン」タブを選択します。
5. 「アプリケーションID URI」で、前にコピーしたアプリケーションID URIを追加します。
6. 左側のナビゲーションで、「組織に公開」を選択します。

ここで、Azure ADアプリケーションを認証サービスとしてOracle Digital Assistantに登録します。

1. 別のブラウザ・ウィンドウまたはタブで、デジタル・アシスタントを開き、左側のメニューで「設定」を展開して「認証サービス」を選択します。

2. 「+サービス」をクリックします。
3. 「新規認証サービス」ダイアログで、次の値を入力します:
   • アイデンティティ・プロバイダ: Microsoft IDプラットフォーム
   • 名前: 認証サービスを識別するための名前。
   • トークン・エンドポイントURL: アクセス・トークンをリクエストするためのアイデンティティ・プロバイダのURL。次を使用します:

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

   • 認可エンドポイント: ユーザーがユーザー名とパスワードを入力して認証するページのIDPのURL。次を使用します:

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

   • クライアントIDおよびクライアント・シークレット: 登録されたAzure ADアプリケーション(OAuthクライアント)のクライアントIDおよびシークレット。アプリケーションIDとシークレットを使用します。
   • スコープ: <Application(client)_ID_for_your_bot>/access_as_user
   • サブジェクト要求: ユーザーの識別に使用するアクセス・トークン・プロファイル要求。電子メールを使用します。

SSO認証を必要とするスキルでは、ダイアログ・フローにOAuth 2.0アカウント・リンク・コンポーネントを組み込み、認証サービスを介して認証を処理します。そのコンポーネントでは、必ずenableSingleSignOnプロパティをtrueに設定してください。(YAMLベースのダイアログ・フローの場合、コンポーネントはSystem.OAuth2AccountLinkと呼ばれます。)

複数のカードをスタンプ・アウトするには、タイプがcardsのレスポンス・アイテム内のcard要素でiteratorVariableを使用します。アダプティブ・カードを使用して複数のピザ・カードをスタンプ・アウトする例を次に示します:

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

textレスポンス・アイテムを使用して、次のようにアダプティブ・カードを定義できます:

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

また、このカスタム・プロパティで複数のアダプティブ・カードを定義することもできます。そのためには、typeプロパティの前にハイフン(-)を付けて、マップではなくYAMLリストを指定します:

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

これは、複数の静的カードをスタンプ・アウトする必要がある場合に便利なことがありますが、iteratorVariableプロパティを使用して複数のカードをスタンプ・アウトするほうが一般的です。

アダプティブ・カードには送信アクション(Action.Submit)があり、これを使用してユーザー入力を収集し、スキルに送信できます。

アクションのペイロードは、送信アクションのdataプロパティで定義します。共通レスポンス・コンポーネントで、ボタンが選択された後に遷移したり、いくつかの変数を設定するようにする場合、標準のactionプロパティとvariablesプロパティを使用できます:

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

カードで入力フィールドを使用する場合、それらのフィールドの名前と値がキーと値のペアとしてdata JSONオブジェクトに追加されます。「Edit Expense」カードが含まれている上の例には、経費タイプ、金額および日付を変更するための3つのフィールドがあります。この場合、ユーザーが「Submit」ボタンをタップすると、次のようなJSONオブジェクトが送信されます:

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

共通レスポンス・コンポーネントは、actionプロパティとvariablesプロパティを使用する一般的なペイロード構造に従っていないため、この情報をどのように処理すればよいですか。これを解決するには、次のオプションがあります:

• JSONペイロードを文字列に変換します。後で、これがエンティティに対して照合されます。一致するものが見つかった場合、そのコンポーネントで設定された変数が、対応するエンティティ値(コンポジット・バッグ・エンティティの場合はエンティティ値)に更新されます。

  このオプションを構成するには、送信アクションのdataプロパティにブール型のsystem.convertToStringプロパティを追加します:

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

• 入力フィールドと同じ名前を持つ変数がスキルで更新されるようにします。上の例では、"Type"、"Amount"および"Date"変数が更新されます。

  このオプションを構成するには、送信アクションのdataプロパティにブール型のsystem.setVariablesプロパティを追加します:

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

これらのいずれのオプションも構成しない場合、送信された値は無視されます。

共通レスポンス・コンポーネントをコンポジット・バッグ・エンティティとともに使用する場合は、通常、最初のオプションを使用します。これにより、文字列化されたJSONペイロードに基づいて、バッグ内のすべての一致したエンティティが設定されます。

ユーザーがアダプティブ・カードでボタンを選択しても、カードにmessageBackアクションを含めないかぎり、ユーザーがそのオプションを選択したことを示すように会話は更新されません。

messageBackアクションを設定するには、https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-actionを参照してください。

技術的にはアダプティブ・カードのボタンやフィールドを無効にすることはできませんが、送信アクションの起動時にカードを置き換えることで同様の効果を実現できます。これは、共通レスポンス・コンポーネントでMicrosoft Teams固有のブール型のreplaceMessageプロパティを使用して行います。

このようにカードを再レンダリングできるようにするには、カスタム・レスポンス・コンポーネントのchannelCustomPropertiesセクション内にこのプロパティを追加します:

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

Apache FreeMarker式を使用して、プロパティの値を設定することもできます。

アダプティブ・カードのJSONスキーマは比較的複雑で、様々なコンストラクトをサポートしています。そのため、Common Responeコンポーネント内で直接、アダプティブ カードの内容を手動で定義しようとすると、エラーが発生しやすくなります。次のプロセスを使用したほうが、アダプティブ・カードをより簡単に作成できる可能性があります:

1. Microsoftのアダプティブ・カード・デザイナのビジュアル・ツールを使用して、アダプティブ・カード定義を作成します。
2. 「カード JSON のコピー」をクリックして、定義をJSONフォーマットで取得します。
3. オンライン・コンバータ(https://jsonformatter.org/json-to-yamlなど)を使用して、定義をYAMLに変換します。
4. 結果をテキスト・エディタにコピーし、ダイアログ・フロー定義内で表示される場所に必要なインデントを挿入します。
5. 結果のテキストをダイアログ・フローに貼り付けます。