ボットにシングルサインオンを追加する

[アーティクル]
12/26/2023

この記事の対象: SDK v4

この記事では、ボットでシングルサインオン (SSO) 機能を使用する方法について説明します。これを行うために、この機能では、コンシューマー ボット (ルートまたは親ボットとも呼ばれます) を使用して、スキルまたは子ボットと対話します。この記事では、条件ルートボットとスキルボットという用語を使用します。

SSO サポートを含める場合、ユーザーは ID プロバイダーを使用してルートボットにサインインすることができ、コントロールがスキルに渡されるときに再度サインインする必要はありません。

ルートボットとスキルボットは別のボットであり、異なるサーバー上で実行されている可能性があり、それぞれに個別のメモリと状態が存在します。 (スキルの詳細については、「スキルの概要」と「スキルの実装」のページを参照してください。) ユーザー認証の詳細については、「Bot Framework 認証の基本」、「ユーザー認証」、および「ボットへの認証の追加」を参照してください。

重要

Web チャットで Azure AI Bot Service 認証を使用する場合、注意する必要がある重要なセキュリティの考慮事項がいくつかあります。詳細については、REST 認証に関する記事の「セキュリティに関する考慮事項」セクションを参照してください。

前提条件

ボットの基本情報、状態の管理、シングルサインオンに関する知識。
ダイアログライブラリ、シーケンシャル会話フローの実装方法、およびダイアログの再利用に関する知識。
Azure と OAuth 2.0 開発の知識。
.NET 用の Visual Studio 2019 以降。
シンプルなスキルコンシューマーとスキルを使用した SSO (C#)

サンプルについて

この記事では、RootBot と SkillBot という 2 つのボットを参照しています。 RootBot で SkillBot にアクティビティを転送します。それらによって、この "一般的な" スキルのシナリオをモデル化します。

"ルート" ボットで 1 つまたは複数のスキルボットを呼び出します。
ルートボットとスキルボットの両方で、「ボットに認証を追加する」に記載されている基本認証を実装します。
ユーザーはルートボットにログインします。
SSO により、既にルートボットにログインしているため、ユーザーによる操作を再度必要とすることなく、スキルボットへのログインが行われます。

Bot Framework での認証の処理方法の概要については、「ユーザー認証」を参照してください。 SSO の背景情報については、「シングルサインオン」を参照してください。

RootBot は SSO をサポートします。ユーザーに代わって SkillBot との通信が行われるため、ユーザーが _SkillBot で再度認証される必要はありません。

サンプル内のプロジェクトごとに、次のものが必要です。

Azure にボットリソースを登録するための Microsoft Entra ID アプリケーション。
認証を行う Microsoft Entra ID ID プロバイダーアプリケーション

Note

現時点では、Microsoft Entra ID ID プロバイダーのみがサポートされています。

Azure RootBot リソースの作成

Azure portal で RootBot 用の Azure ボットリソースを作成する「Azure ボットリソースを作成する」で説明されている手順に従います。
ボット登録のアプリ ID とクライアントシークレットをコピーし、保存します。

RootBot の Microsoft Entra ID ID を作成する

Microsoft Entra ID は、OAuth 2.0 などの業界標準プロトコルを使用して、ユーザーを安全にサインインさせるアプリケーションをビルドすることができるクラウド ID サービスです。

Microsoft Entra ID を使用してユーザーを認証する ID アプリケーションを RootBot 用に作成します。「Microsoft Entra ID ID プロバイダーの作成」にある手順に従います。
左側のペインで [マニフェスト] を選択します。
accessTokenAcceptedVersion を 2 に設定します。
[保存] を選択します。
左側ウィンドウで、[API を公開する] を選択します。
右側ウィンドウで、[範囲の追加] を選択します。
右端にある [範囲の追加] セクションで、[保存して続行] を選択します。
表示されたウィンドウの [同意できるユーザー] で、[管理者とユーザー] を選択します。
残りの必要な情報を入力します。
[スコープの追加] を選択します。
スコープの値をコピーして保存します。

RootBot 用の OAuth の接続設定を作成する

RootBot ボットの登録で Microsoft Entra ID 接続を作成し、「Microsoft Entra ID」に記載されている値と、次に示す値を入力します。
[トークン交換 URL] は空のままにしておきます。
[スコープ] ボックスに、前の手順で保存した RootBot スコープの値を入力します。

Note

[スコープ] には、ユーザーが最初にルートボットにサインインしたときの URL が含まれますが、[トークン交換 URL] は空のままです。

たとえば、ルートボット appid が rootAppId で、スキルボット appid が skillAppId であると仮定します。ルートボットの [スコープ] は、api://rootAppId/customScope のようになり、ユーザーのログインに使用されます。このルートボットの [スコープ]は、その後 SSO 中に api://skillAppId/customscope と交換されます。
接続の名前をコピーして保存します。

Azure SkillBot リソースを作成する

Azure portal で SkillBot 用の Azure ボットリソースを作成する「Azure ボットリソースを作成する」で説明されている手順に従います。
ボット登録のアプリ ID とクライアントシークレットをコピーし、保存します。

SkillBot の Microsoft Entra ID ID を作成する

SkillBot 用に、Microsoft Entra ID を使用してボットを認証する ID アプリケーションを作成します。「Microsoft Entra ID ID プロバイダーの作成」にある手順に従います。
左側のペインで [マニフェスト] を選択します。
accessTokenAcceptedVersion を 2 に設定します。
[保存] を選択します。
左側ウィンドウで、[API を公開する] を選択します。
右側ウィンドウで、[範囲の追加] を選択します。
右端にある [範囲の追加] セクションで、[保存して続行] を選択します。
表示されたウィンドウの [同意できるユーザー] で、[管理者とユーザー] を選択します。
残りの必要な情報を入力します。
[スコープの追加] を選択します。
スコープの値をコピーして保存します。
クライアントアプリケーションの追加を選択します。右端のセクションの [クライアント ID] ボックスに、以前に保存したアプリ ID である RootBot ID を入力します。必ず、登録アプリ ID ではなく RootBot ID を使用します。

Note

クライアントアプリケーションの場合、Azure AI Bot Service では、Microsoft Entra ID B2C ID プロバイダーでのシングルサインオンはサポートされていません。
[Authorized scope]\(承認済みのスコープ\) で、スコープ値の横のチェックボックスをオンにします。
[アプリケーションの追加] をクリックします。
左側のナビゲーションウィンドウで [API のアクセス許可] を選択します。アプリの API アクセス許可を明示的に設定するのが成功事例です。
1. 右側のウィンドウで、[アクセス許可の追加] をクリックします。
2. [Microsoft API] を選択し、次に [Microsoft Graph] を選択します。
3. [委任されたアクセス許可] を選択し、必要とするアクセス許可が選択されていることを確認します。このサンプルには、以下に示すアクセス許可が必要です。
  
  Note
  
  [管理者の同意が必要] とマークされているアクセス許可については、ユーザーとテナント管理者の両方がログインする必要があります。
  - openid
  - profile
  - User.Read
  - User.ReadBasic.All
4. [アクセス許可の追加] を選択します.

SkillBot 用の OAuth 接続設定を作成する

SkillBot ボットの登録で Microsoft Entra ID 接続を作成し、「Microsoft Entra ID」に記載されている値と、次に示す値を入力します。
[トークン交換 URL] ボックスに、前の手順で保存した SkillBot 範囲の値を入力します。
[範囲] ボックスに、次の値を空白スペースで区切って入力します。profileUser.ReadUser.ReadBasic.All[範囲] ボックスに、次の値を空白スペースで区切って入力します。openid
接続の名前をコピーして、ファイルに保存します。

接続をテストする

接続入力を選択して、作成した接続を開きます。
[サービスプロバイダー接続設定] ウィンドウの上部にある [テスト接続] を選択します。
初回は新しいブラウザータブが開き、アプリが要求しているアクセス許可の一覧が表示され、承認を求められます。
[Accept](承認) を選択します。
これにより、[<your-connection-name> への接続テストに成功しました] ページにリダイレクトされます。

詳細については、「開発者向け Microsoft Entra ID (v1.0) の概要」と「Microsoft ID プラットフォーム (v2.0) の概要」を参照してください。 v1 と v2 エンドポイントの違いについては、「Microsoft ID プラットフォーム (v2.0) に更新する理由」を参照してください。全情報については、「Microsoft ID プラットフォーム (旧「開発者向け Microsoft Entra ID」)」を参照してください。

サンプルコードを準備する

次に示すように、両方のサンプルの appsettings.json ファイルを更新する必要があります。

GitHub リポジトリから、「SSO with Simple Skill Consumer and Skill」 (シンプルなスキルコンシューマーとスキルを使用した SSO) というサンプルをクローンします。

SkillBot プロジェクトの appsettings.json ファイルを開きます。保存したファイルから、次の値を割り当てます。

{
    "MicrosoftAppId": "<SkillBot registration app ID>",
    "MicrosoftAppPassword": "<SkillBot registration password>",
    "ConnectionName": "<SkillBot connection name>",
    "AllowedCallers": [ "<RootBot registration app ID>" ]
}

RootBot プロジェクトの appsettings.json ファイルを開きます。保存したファイルから、次の値を割り当てます。

{
    "MicrosoftAppId": "<RootBot registration app ID>",
    "MicrosoftAppPassword": "<RootBot registration password>",
    "ConnectionName": "<RootBot connection name>",
    "SkillHostEndpoint": "http://localhost:3978/api/skills/",
    "BotFrameworkSkills": [
            {
            "Id": "SkillBot",
            "AppId": "<SkillBot registration app ID>",
            "SkillEndpoint": "http://localhost:39783/api/messages"
            }
        ]
}

サンプルをテストする

テストには次のものを使用します。

RootBot コマンド
- login では、ユーザーが RootBot を使用して Microsoft Entra ID 登録にサインインできるようにします。サインインすると、SSO によって SkillBot へのサインインも自動的に行われます。ユーザーはもう一度サインインする必要がありません。
- token ではユーザーのトークンを表示します。
- logout では、ユーザーを RootBot からログアウトします。
SkillBot コマンド
- skill login では、ユーザーに代わって RootBot による SkillBot へのサインインができるようにします。ユーザーが既にサインインしている場合、SSO に失敗しない限り、ユーザーにサインインカードは表示されません。
- skill token では、SkillBot からのユーザーのトークンを表示します。
- skill logout では、ユーザーを SkillBot からログアウトします。

Note

ユーザーが初めてスキルで SSO を試すときには、ログインするための OAuth カードが表示されることがあります。これは、スキルの Microsoft Entra ID アプリに対する同意がまだ付与されていないためです。これを回避するために、Microsoft Entra ID アプリによって要求されたグラフのアクセス許可に対して管理者の同意を付与することができます。

エミュレーター
Web チャット

Bot Framework Emulator をインストールします (まだインストールしていない場合)。「エミュレーターを使用したデバッグ」もご覧ください。

ボットのサンプルログインが機能するように、エミュレーターを構成する必要があります。「エミュレーターを認証用に構成する」に示されているように、次の手順を使用します。

認証メカニズムを構成したら、実際にボットサンプルテストを実行できます。

Visual Studio で、SSOWithSkills.sln ソリューションを開き、複数のプロセスのデバッグを開始するように構成します。
ご自身のコンピューター上でローカルにデバッグを開始します。 RootBot プロジェクトの appsettings.json ファイル内に、次の設定があることに注意してください。
```
"SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"
```
Note

これらの設定は、RootBot と SkillBot の両方がローカルコンピューター上で実行されていることを意味します。エミュレーターと RootBot の通信はポート 3978 で、RootBot と SkillBot の通信はポート 39783 で行われます。デバッグを開始するとすぐに、2 つの既定のブラウザーウィンドウが開きます。 1 つはポート 3978、もう 1 つはポート 39783 についてのものです。
エミュレーターを起動します。
ボットに接続するときに、RootBot の登録アプリ ID とパスワードを入力します。
「hi」と入力して会話を開始します。
「login」と入力します。 RootBot によって [AAD にサインイン] 認証カードが表示されます。
[サインイン] を選択します。 [Confirm Open URL]\(URL を開く確認\) ポップアップダイアログが表示されます。
確認を選択します。ログイン後、RootBot トークンが表示されます。
「token」と入力してトークンを再度表示します。

これで、SkillBot と通信する準備ができました。 RootBot を使用してサインインした後は、サインアウトするまで、認証情報を再度入力する必要はありません。これにより、SSO が正常に動作していることがわかります。
エミュレーターボックスに「skill login」と入力します。もう一度ログインするように求められることはありません。代わりに、SkillBot のトークンが表示されます。
「skill token」と入力してトークンを再度表示します。
これで、「skill logout」と入力して SkillBot からサインアウトできます。次に、「logout」と入力して SimpleRootBoot からサインアウトします。

ルートボットとスキルボットを Azure にデプロイします。詳細については、「チュートリアル: Azure でボットをプロビジョニングする」と「チュートリアル: 基本的なボットを発行する」を参照してください。
Visual Studio などのコードエディターで、RootBot プロジェクトの appsetting.js ファイル内の localhost アドレスを、次に示す実際の Microsoft Entra アドレスに置き換えます。
```
"SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
"SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
```
ブラウザーで、Azure portal に移動します。
ご自身のルートボット登録を開きます。左側のウィンドウで、[Web チャットでテスト] をクリックします。ルートボットを示すダイアログウィンドウが、ボットのあいさつメッセージと共に表示されます。
たとえば「hi」と入力してボットとの会話を開始します。ご自身のメッセージがボットからエコーされます。
「login」と入力します。 RootBot によって [AAD にサインイン] 認証カードが表示されます。
[サインイン] を選択します。検証コードを含む Web ページが表示されます。
コードをコピーし、入力ボックスに入力してサインインを完了します。 RootBot トークンが表示されます。
「token」と入力してトークンを再度表示します。

これで、SkillBot と通信する準備ができました。 RootBot にサインインした後は、サインアウトするまで、認証情報を再度入力する必要はありません。これにより、SSO が正常に動作していることがわかります。
「skill login」と入力します。 SkillBot のトークンが表示されます。
「skill token」と入力してトークンを再度表示します。これにより、もう一度サインインする必要なく SkillBot と通信していることがわかります。 SSO が機能しています。
これで、「skill logout」と入力して SkillBot からサインアウトできます。次に、「logout」と入力して SimpleRootBoot からサインアウトします。

追加情報

次のタイムシーケンス図は、この記事で使用されているサンプルに適用され、関連するさまざまなコンポーネント間のやりとりを示しています。 ABS は Azure AI Bot Service を表します。

スキルトークンのフローを示すシーケンス図。

初回時、ユーザーは RootBot に対する login コマンドを入力します。
ユーザーにサインインを求める OAuthCard が RootBot から送信されます。
ユーザーが認証情報を入力し、それが ABS (Azure AI Bot Service) に送信されます。
ユーザーの資格情報に基づいて生成された認証トークンが、ABS から RootBot に送信されます。
ユーザーに示されるルートのトークンが、RootBot に表示されます。
ユーザーは SkillBot に対する skill login コマンドを入力します。
SkillBot から RootBot に OAuthCard が送信されます。
RootBot で ABS に交換可能なトークンが要求されます。
SSO は、SkillBot スキルトークン を RootBot に送信します。
ユーザーに示されるスキルのトークンが、RootBot に表示されます。ユーザーが SkillBot にサインインする必要なく、スキルのトークンが生成されたことに注意してください。これは SSO によるものです。

次の例は、トークン交換がどのように行われるかを示しています。このコードは TokenExchangeSkillHandler.cs ファイルからのコードです。

private async Task<bool> InterceptOAuthCards(ClaimsIdentity claimsIdentity, Activity activity)
{
    var oauthCardAttachment = activity.Attachments?.FirstOrDefault(a => a?.ContentType == OAuthCard.ContentType);
    if (oauthCardAttachment != null)
    {
        var targetSkill = GetCallingSkill(claimsIdentity);
        if (targetSkill != null)
        {
            var oauthCard = ((JObject)oauthCardAttachment.Content).ToObject<OAuthCard>();

            if (!string.IsNullOrWhiteSpace(oauthCard?.TokenExchangeResource?.Uri))
            {
                using (var context = new TurnContext(_adapter, activity))
                {
                    context.TurnState.Add<IIdentity>("BotIdentity", claimsIdentity);

                    // AAD token exchange
                    try
                    {
                        var result = await _tokenExchangeProvider.ExchangeTokenAsync(
                            context,
                            _connectionName,
                            activity.Recipient.Id,
                            new TokenExchangeRequest() { Uri = oauthCard.TokenExchangeResource.Uri }).ConfigureAwait(false);

                        if (!string.IsNullOrEmpty(result?.Token))
                        {
                            // If token above is null, then SSO has failed and hence we return false.
                            // If not, send an invoke to the skill with the token. 
                            return await SendTokenExchangeInvokeToSkill(activity, oauthCard.TokenExchangeResource.Id, result.Token, oauthCard.ConnectionName, targetSkill, default).ConfigureAwait(false);
                        }
                    }
                    catch
                    {
                        // Show oauth card if token exchange fails.
                        return false;
                    }

                    return false;
                }
            }
        }
    }
    return false;
}

次の方法で共有

ボットにシングルサインオンを追加する

前提条件

サンプルについて

Azure RootBot リソースの作成

RootBot の Microsoft Entra ID ID を作成する

RootBot 用の OAuth の接続設定を作成する

Azure SkillBot リソースを作成する

SkillBot の Microsoft Entra ID ID を作成する

SkillBot 用の OAuth 接続設定を作成する

接続をテストする

サンプルコードを準備する

サンプルをテストする

追加情報

その他のリソース

次の方法で共有

ボットにシングル サインオンを追加する

前提条件

サンプルについて

Azure RootBot リソースの作成

RootBot の Microsoft Entra ID ID を作成する

RootBot 用の OAuth の接続設定を作成する

Azure SkillBot リソースを作成する

SkillBot の Microsoft Entra ID ID を作成する

SkillBot 用の OAuth 接続設定を作成する

接続をテストする

サンプル コードを準備する

サンプルをテストする

追加情報

その他のリソース

ボットにシングルサインオンを追加する

サンプルコードを準備する