コードを bot アプリで SSO を有効にする

シングル サインオン (SSO) を有効にするコードを追加する前に、必ず Microsoft Entra 管理センター でアプリとボット リソースを構成してください。

Microsoft Entra ID からアクセス トークンを取得するには、アプリのコードを構成する必要があります。 アクセス トークンは、ボット アプリに代わって発行されます。

注:

Microsoft Teams Toolkit を使用して Teams アプリを構築した場合は、ツールと SDK モジュールの手順を使用してアプリの SSO を有効にすることができます。 詳細については、「 Teams アプリにシングル サインオンを追加する」を参照してください。 Teams Toolkit は、Visual Studio Code の JavaScript、TypeScript、C# アプリの SSO をサポートしています。

このセクションでは、次の手順について説明します。

  1. 開発環境変数を更新する
  2. OAuth を使用してアプリを初期化する
  3. サインインとトークンの受信を処理する
  4. サインイン エラーを処理する
  5. アプリ ユーザーのサインアウトを処理する

開発環境変数を更新する

Microsoft Entra ID でアプリのクライアント シークレットと OAuth 接続設定を構成しました。 これらの値を使用してコードを構成する必要があります。

開発環境変数を更新するには:

  1. ボット アプリ プロジェクトを開きます。

  2. プロジェクトの環境ファイル (.env) を開きます。

  3. 次の変数を更新します。

    • CLIENT_IDの場合は、ボット ID を Microsoft Entra ID から更新します。
    • CLIENT_SECRETについては、クライアント シークレットを更新します。
    • CONNECTION_NAMEについては、Microsoft Entra ID で構成した OAuth 接続の名前を更新します。
    • TENANT_IDについては、テナント ID を更新します。

    注:

    ボットがパブリック クラウド、Microsoft Azure Government クラウド、21Vianet が運用する Microsoft Azure のいずれにあるかに関係なく、データ所在地の要件に基づいてボットと ID プロバイダーの OAuth リダイレクト URL をカスタマイズできます。 OAuth URL とデータ所在地リストについては、「Azure AI Bot Service での OAuth URL サポート」を参照してください。

  4. ファイルを保存します。

これで、ボット アプリと SSO に必要な環境変数が構成されました。 次に、OAuth を使用してアプリを初期化します。

OAuth を使用してアプリを初期化する

Teams SDK は、サーバーのライフサイクル、認証、トークン交換を内部で処理する単一の App クラスでアプリの初期化を簡素化します。

using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.OAuth;

var builder = WebApplication.CreateBuilder(args);

var connectionName = builder.Configuration["CONNECTION_NAME"]
    ?? throw new InvalidOperationException("Missing required configuration value: CONNECTION_NAME");

builder.Services.AddTeamsBotApplication(options =>
{
  options.AddOAuthFlow(connectionName);
});

var app = builder.Build();
var teams = app.UseTeamsBotApplication();

OAuthFlow auth = teams.GetOAuthFlow(connectionName);

注:

App クラスは、すべてのアダプター構成、ミドルウェア、エラー処理、およびサーバーのセットアップを内部で処理します。

サインインとトークンの受信を処理する

Teams SDK では、認証に単純なイベント駆動型ハンドラーが使用されます。 IsSignedIn を使用して認証ステータスをチェックし、SignIn() SSO フローをトリガーし、signin イベントをサブスクライブして認証の成功を処理します。

teams.OnMessage(async (context, cancellationToken) =>
{
  string? token = await auth.SignInAsync(context, cancellationToken);
  if (token is null)
    {
        return;
    }

  await context.SendAsync($"You are signed in. Token length: {token.Length}", cancellationToken);
});

auth.OnSignInComplete(async (context, tokenResponse, cancellationToken) =>
{
  await context.SendAsync("Successfully signed in! You can now use the bot.", cancellationToken);
});

注:

SDK は、トークンの交換と検証を内部で処理します。 OAuthPrompt、WaterfallDialog、またはMainDialogクラスを手動で管理する必要がなくなりました。

サインイン エラーを処理する

SSO を使用する場合、トークン交換が失敗した場合、Teams は signin/failure 呼び出しアクティビティをアプリに送信します。 SDK には、アクション可能なトラブルシューティング ガイダンスとともに警告をログに記録する組み込みの既定ハンドラーが含まれています。 必要に応じて、独自のハンドラーを登録して動作をカスタマイズできます。

auth.OnSignInFailure(async (context, failure, cancellationToken) =>
{
    Console.WriteLine($"Sign-in failed: {failure?.Code} - {failure?.Message}");
    await context.SendAsync("Sign-in failed. Please try again.", cancellationToken);
});

アプリ ユーザーのサインアウトを処理する

signout メソッドを呼び出してユーザーの認証トークンをユーザー トークン サービス キャッシュから削除し、事実上サインアウトさせます。Teams SDK は、DialogContext、UserTokenClient、CancelAllDialogsAsync を使用する以前のパターンを単純なメソッド呼び出しに置き換えます。

teams.OnMessage("/signout", async (context, cancellationToken) =>
{
  await auth.SignOutAsync(context, cancellationToken);
  await context.SendAsync("You have been signed out.", cancellationToken);
});

アクセス トークンを取得するには、ユーザーはボット アプリによって要求されるアクセス許可に同意する必要があります。 アプリのスコープに基づいて、同意ダイアログが表示されます。

1 対 1 のチャット

アプリ ユーザーがアプリケーションを初めて使用し、ユーザーの同意が必要な場合、次のダイアログ ボックスが表示されます。

インフォグラフィックは、ボットと個人的な範囲内のユーザーの対話を示しています

ユーザーが [続行] を選択すると、次のいずれかのイベントが発生します。

  • ボット UI にサインイン ボタンがある場合は、ボットのサインイン フローがアクティブ化されます。 アプリ ユーザーの同意が必要なアクセス許可を決定できます。 アプリで openid 以外の Graph アクセス許可が必要な場合は、この方法を使用します。

  • ボットの OAuth カードにサインイン ボタンがない場合、最小限のアクセス許可セットに対してアプリ ユーザーの同意が必要です。 このトークンは、基本認証とアプリ ユーザーのメール アドレスを取得する場合に便利です。

表示される同意ダイアログは、Microsoft Entra ID で定義されたオープン ID スコープ用です。 アプリ ユーザーは同意を 1 回だけ行う必要があります。 同意すると、アプリ ユーザーは、付与されたアクセス許可とスコープでボット アプリにアクセスして使用できます。

グループ チャット

グループ スコープでの認証の 2 つのシナリオを次に示します。

ボットが初めてグループ チャットに追加され、特定のユーザーの同意が必要な場合、ボットを @mentions したユーザーにのみ同意ダイアログ ボックスが表示されます。 ユーザーは、アクセス トークンを取得するためにボット アプリによって要求されたアクセス許可に 1 回同意する必要があります。

ユーザーがボット @mentions 。 アダプティブ カードが表示され、ユーザーの同意が求められます。

デスクトップの同意ダイアログ ボックスを示す画像

  • ユーザーが [追加] を選択すると、アクセス許可ダイアログ ボックスが表示されます。

    この画像は、デスクトップの [アクセス許可要求] ポップアップを示しています

    ユーザーは、同意するには [同意する ] を選択する必要があります。

  • ユーザーが拒否した場合、または要求がタイムアウトした場合、ユーザーはボットを再度 @mention してトークン取得のアクセス許可を付与する必要があります。 グループは、認証が成功しなかったことを示すボット メッセージを表示できます。

    この画像は、ユーザーの同意が拒否されたとき、または要求がタイムアウトしたときのボットの対話を示しています

ユーザーのアクセス許可が既定で付与されている場合、または信頼済みアプリに対して付与されている場合、ボット @mentions ユーザーは同意を与えなくてもボットと直接対話できます。

注:

アプリ ユーザーが同意した後は、他のアクセス許可について再度同意する必要はありません。 Microsoft Entra スコープで定義されているアクセス許可が変更された場合は、アプリ ユーザーの同意が再度必要になる場合があります。 ただし、同意プロンプトでアプリ ユーザーへのアクセスが許可されない場合、ボット アプリはサインイン カードにフォールバックします。

重要

同意ダイアログが不要なシナリオ:

  • 管理者がテナントに代わって同意を付与する場合、アプリ ユーザーに同意を求めるプロンプトを表示する必要はありません。 つまり、アプリ ユーザーには同意ダイアログが表示されず、シームレスにアプリにアクセスできます。
  • Microsoft Entra アプリが、Teams で認証を要求しているのと同じテナントに登録されている場合、アプリ ユーザーに同意を求めることはできず、すぐにアクセス トークンが付与されます。 アプリ ユーザーは、Microsoft Entra アプリが別のテナントに登録されている場合にのみ、これらのアクセス許可に同意します。

エラーが発生した場合は、「 Teams での SSO 認証のトラブルシューティング」を参照してください。

コード サンプル

サンプルの名前 説明 .NET Node.js
ボット会話の SSO クイック スタート SSO を使用して Teams ボットをすばやくセットアップすると、1 対 1 のチャットとグループ チャットでシームレスなユーザー認証を実現できます。 表示 表示

次の手順