メッセージ拡張機能アプリで SSO を有効にするコードを追加します

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

注:

OnTeamsMessagingExtensionQueryAsync TeamsMessagingExtensionsSearchAuthConfigBot.cs ファイルの SSO ハンドラーは、ファイルからのOnTeamsAppBasedLinkQueryAsyncのみがサポートされます。その他の SSO ハンドラーはサポートされません。

この記事の内容:

開発環境変数を更新する
トークンを要求するコードを追加します
トークンを受け取るコードを追加します
Bot Framework トークンストアにトークンを追加する
アプリユーザーのログアウトを処理する

開発環境変数を更新する

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

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

アプリプロジェクトを開きます。
プロジェクトの ./env ファイルを開きます。
次の変数を更新します。
- MicrosoftAppIdの場合は、ボット登録 ID を Microsoft Entra ID から更新します。
- MicrosoftAppPasswordについては、ボット登録のクライアントシークレットを更新します。
- ConnectionNameについては、Microsoft Entra ID で構成した OAuth 接続の名前を更新します。
- MicrosoftAppTenantIdについては、テナント ID を更新します。
ファイルを保存します。

これで、ボットアプリと SSO に必要な環境変数が構成されました。次に、トークンを処理するためのコードを追加します。

トークンを要求するコードを追加します

トークンを取得する要求は、既存のメッセージスキーマを使用した POST メッセージ要求です。それは、OAuthCard の添付ファイルに含まれています。 OAuthCard クラスのスキーマは、 Microsoft Bot Schema 4.0 で定義されています。カードに TokenExchangeResource プロパティが設定されている場合、Teams はトークンを更新します。 Microsoft Teams チャンネルの場合、トークンの要求を一意に認識するプロパティ Id だけが引き受けられます。

注:

Microsoft Bot Framework OAuthPrompt または MultiProviderAuthDialog は、SSO 認証でサポートされています。

アプリのコードを更新するには:

TeamsSSOTokenExchangeMiddleware 用のコードスニペットを追加します。
- C#
- JavaScript
次のコードスニペットを AdapterWithErrorHandler.cs (またはアプリのコード内の同等のクラス) に追加します。
```
base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));
```
次のコードスニペットを index.js (またはアプリのコード内の同等のクラス) に追加します。
```
const {TeamsSSOTokenExchangeMiddleware} = require('botbuilder');
const tokenExchangeMiddleware = new TeamsSSOTokenExchangeMiddleware(memoryStorage, env.connectionName);
adapter.use(tokenExchangeMiddleware);
```
注:

ユーザーが複数のアクティブなエンドポイントを持っている場合、与えられた要求に対して複数の応答を受け取る場合があります。トークンを使用して、重複または冗長な応答をすべて排除する必要があります。 signin/tokenExchange の詳細については、「 TeamsSSOTokenExchangeMiddleware クラス」を参照してください。

トークンを要求するには、次のコードスニペットを使用します。

C#
JavaScript

AdapterWithErrorHandler.csを追加した後、次のコードが表示されます。

public class AdapterWithErrorHandler : CloudAdapter
{
    public AdapterWithErrorHandler(
        IConfiguration configuration,
        IHttpClientFactory httpClientFactory,
        ILogger<IBotFrameworkHttpAdapter> logger,
        IStorage storage,
        ConversationState conversationState)
        : base(configuration, httpClientFactory, logger)
    {
        base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));

        OnTurnError = async (turnContext, exception) =>
        {
            // Log any leaked exception from the application.
            // NOTE: In production environment, you must consider logging this to
            // Azure Application Insights. Visit https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-telemetry?view=azure-bot-service-4.0&tabs=csharp to see how
            // to add telemetry capture to your bot.
            logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

            // Send a message to the user.
            await turnContext.SendActivityAsync("The bot encountered an error or bug.");
            await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

            if (conversationState != null)
            {
                try
                {
                    // Delete the conversationState for the current conversation to prevent the
                    // bot from getting stuck in an error-loop caused by being in a bad state.
                    // ConversationState must be thought of as similar to "cookie-state" in a Web pages.
                    await conversationState.DeleteAsync(turnContext);
                }
                catch (Exception e)
                {
                    logger.LogError(e, $"Exception caught on attempting to Delete ConversationState : {e.Message}");
                }
            }

            // Send a trace activity, which will be displayed in the Bot Framework Emulator.
            await turnContext.TraceActivityAsync(
                "OnTurnError Trace",
                exception.Message,
                "https://www.botframework.com/schemas/error",
                "TurnError");
        };
    }
}

index.js にコードを追加した後、次のコードが表示されます。

// index.js is used to setup and configure your bot.

// Import required packages.
const path = require('path');

// Read botFilePath and botFileSecret from .env file.
const ENV_FILE = path.join(__dirname, '.env');
require('dotenv').config({ path: ENV_FILE });

const express = require("express");

// Import required bot services.
// See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication,
    TeamsSSOTokenExchangeMiddleware
} = require('botbuilder');

const { TeamsBot } = require('./bots/teamsBot');
const { MainDialog } = require('./dialogs/mainDialog');
const { env } = require('process');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

var conname = env.connectionName;

console.log(`\n${ conname } is the con name`);

// Create adapter.
// See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);
const memoryStorage = new MemoryStorage();
const tokenExchangeMiddleware = new TeamsSSOTokenExchangeMiddleware(memoryStorage, env.connectionName);

adapter.use(tokenExchangeMiddleware);
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you must consider logging this to Azure application insights. See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-telemetry?view=azure-bot-service-4.0&tabs=csharp for telemetry configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

    // Send a trace activity, which will be displayed in the Bot Framework Emulator.
    await context.sendTraceActivity(
        'OnTurnError Trace',
        `${ error }`,
        'https://www.botframework.com/schemas/error',
        'TurnError'
    );

    // Send a message to the user.
    await context.sendActivity('The bot encountered an error or bug.');
    await context.sendActivity('To continue to run this bot, please fix the bot source code.');
    // Clear out state.
    await conversationState.delete(context);
};

// Define the state store for your bot.
// See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-v4-state?view=azure-bot-service-4.0&branch=live&tabs=csharp to learn more about using MemoryStorage.
// A bot requires a state storage system to persist the dialog and user state between messages.
// const memoryStorage = new MemoryStorage();

// Create conversation and user state with in-memory storage provider.
const conversationState = new ConversationState(memoryStorage);
const userState = new UserState(memoryStorage);

// Create the main dialog.
const dialog = new MainDialog();
// Create the bot that will handle incoming messages.
const bot = new TeamsBot(conversationState, userState, dialog);

// Create express application.
const expressApp = express();
expressApp.use(express.json());

const server = expressApp.listen(process.env.port || process.env.PORT || 3978, () => {
    console.log(`\n${ expressApp.name } listening to`, server.address());
    console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator');
    console.log('\nTo talk to your bot, open the emulator select "Open Bot"');
});

// Listen for incoming requests.
expressApp.post('/api/messages', async (req, res) => {
    // Route received a request to adapter for processing.
    await adapter.process(req, res, (context) => bot.run(context));
});

アプリユーザーがアプリを初めて使用する場合は、SSO 認証に同意する必要があります。

アプリユーザーがユーザー名を選択すると、アクセス許可が付与され、アプリを使用できます。

メッセージ拡張機能アプリの SSO 認証が完了しました

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

重要

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

管理者がテナントに代わって同意を付与した場合、アプリユーザーに同意を求めるプロンプトを表示する必要はありません。つまり、アプリユーザーには同意ダイアログが表示されず、シームレスにアプリにアクセスできます。

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

トークンを受け取るコードを追加します

トークンを使用した応答は、ボットが今日受け取る他の呼び出しアクティビティと同じスキーマを持つ呼び出しアクティビティを介して送信されます。唯一の違いは、呼び出し名、サインイン/tokenExchange、 および値 フィールドです。値フィールドには、ID、トークンを取得するための最初の要求の文字列、トークン フィールド、トークンを含む文字列値が含まれます。

応答を呼び出すには、次のコードスニペットの例を使用します。

C#
JavaScript

public MainDialog(IConfiguration configuration, ILogger<MainDialog> logger)
    : base(nameof(MainDialog), configuration["ConnectionName"])
{
    AddDialog(new OAuthPrompt(
        nameof(OAuthPrompt),
        new OAuthPromptSettings
        {
            ConnectionName = ConnectionName,
            Text = "Please Sign In",
            Title = "Sign In",
            Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
            EndOnInvalidMessage = true
        }));

    AddDialog(new ConfirmPrompt(nameof(ConfirmPrompt)));

    AddDialog(new WaterfallDialog(nameof(WaterfallDialog), new WaterfallStep[]
    {
        PromptStepAsync,
        LoginStepAsync,
    }));

    // The initial child Dialog to run.
    InitialDialogId = nameof(WaterfallDialog);
}

private async Task<DialogTurnResult> PromptStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);
}

private async Task<DialogTurnResult> LoginStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var tokenResponse = (TokenResponse)stepContext.Result;
    if (tokenResponse?.Token != null)
    {
        var token = tokenResponse.Token;

        // On successful login, the token contains sign in token.
    }
    else
    {
        await stepContext.Context.SendActivityAsync(MessageFactory.Text("Login was not successful please try again."), cancellationToken);
    }

    return await stepContext.EndDialogAsync(cancellationToken: cancellationToken);
}

class MainDialog {
    this.addDialog(new OAuthPrompt(OAUTH_PROMPT, {
        connectionName: process.env.connectionName,
        text: 'Please Sign In',
        title: 'Sign In',
        timeout: 300000
    }));

    this.addDialog(new ConfirmPrompt(CONFIRM_PROMPT));

    this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
        this.promptStep.bind(this),
        this.loginStep.bind(this),
    ]));

    this.initialDialogId = MAIN_WATERFALL_DIALOG;
}

async promptStep(stepContext) {
    try {
        return await stepContext.beginDialog(OAUTH_PROMPT);
    } catch (err) {
        console.error(err);
    }
}

async loginStep(stepContext) {
    // Get the token from the previous step. Note that we could also have gotten the
    // token directly from the prompt itself. There is an example of this in the next method.
    const tokenResponse = stepContext.result;
    if (!tokenResponse || !tokenResponse.token) {
        await stepContext.context.sendActivity('Login was not successful please try again.');
    } else {
        const token = tokenResponse.token;
        // On successful login, the token contains sign in token.
    }
    return await stepContext.endDialog();
}

注:

コードスニペットでは、ウォーターフォールダイアログボットを使用します。ウォーターフォールダイアログの詳細については、「コンポーネントとウォーターフォールダイアログについて」を参照してください。

トークン OnTeamsMessagingExtensionQueryAsync SSO を有効にするシナリオに応じて、 turnContext.Activity.Value ペイロードまたは OnTeamsAppBasedLinkQueryAsync内のハンドラーでトークンを受け取ります。

JObject valueObject = JObject.FromObject(turnContext.Activity.Value);
if (valueObject["authentication"] != null)
{
    JObject authenticationObject = JObject.FromObject(valueObject["authentication"]);
    if (authenticationObject["token"] != null)
    {
        // Process the token.
    }
}

アクセストークンを検証する

サーバー上の Web API はアクセストークンをデコードし、クライアントから送信されたかどうかを確認する必要があります。

注:

Bot Framework を使用する場合は、アクセストークンの検証が処理されます。 Bot Framework を使用しない場合は、このセクションのガイドラインに従ってください。

アクセストークンの検証の詳細については、「トークンの検証」を参照してください。

JWT の検証を処理できるライブラリが複数入手可能です。基本的な検証には、次のものが含まれます。

トークンが整形式であることを確認します。
トークンが目的の機関によって発行されたことを確認します。
トークンが Web API をターゲットにしていることを確認します。

トークンの検証時には、次のガイドラインに注意してください。

有効な SSO トークンは Microsoft Entra ID によって発行されます。トークン内の iss クレームは、この値で始まる必要があります。
トークンの aud1 パラメーターは、アプリの登録時に生成されるアプリ ID に設定されMicrosoft Entra。
トークンの scp パラメーターが access_as_user に設定されています。

アクセストークンの例

次のコードスニペットは、アクセストークンの典型的なデコードされたペイロードです。

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

Bot Framework トークンストアにトークンを追加する

OAuth 接続を使用している場合は、Bot Framework トークンストアでトークンを更新または追加する必要があります。ストアでトークンを更新または追加するために、次のコードスニペット例を TeamsMessagingExtensionsSearchAuthConfigBot.cs (またはアプリのコード内の同等のファイル) に追加します。

注:

タブ、ボット、およびメッセージ拡張機能 (ME) SSO にあるサンプル TeamsMessagingExtensionsSearchAuthConfigBot.csを見つけることができます。

C#
JavaScript

protected override async Task<InvokeResponse> OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    JObject valueObject = JObject.FromObject(turnContext.Activity.Value);
    if (valueObject["authentication"] != null)
    {
        JObject authenticationObject = JObject.FromObject(valueObject["authentication"]);
        if (authenticationObject["token"] != null)
        {
            // If the token is NOT exchangeable, then return 412 to require user consent.
            if (await TokenIsExchangeable(turnContext, cancellationToken))
            {
                return await base.OnInvokeActivityAsync(turnContext, cancellationToken).ConfigureAwait(false);
            }

            var response = new InvokeResponse();
            response.Status = 412;
            return response;
        }
    }

    return await base.OnInvokeActivityAsync(turnContext, cancellationToken).ConfigureAwait(false);
}

private async Task<bool> TokenIsExchangeable(ITurnContext turnContext, CancellationToken cancellationToken)
{
    TokenResponse tokenExchangeResponse = null;
    try
    {
        JObject valueObject = JObject.FromObject(turnContext.Activity.Value);
        var tokenExchangeRequest =
            ((JObject)valueObject["authentication"])?.ToObject<TokenExchangeInvokeRequest>();
        var userTokenClient = turnContext.TurnState.Get<UserTokenClient>();
        tokenExchangeResponse = await userTokenClient.ExchangeTokenAsync(
            turnContext.Activity.From.Id,
            _connectionName,
            turnContext.Activity.ChannelId,
            new TokenExchangeRequest
            {
                Token = tokenExchangeRequest.Token,
            },
            cancellationToken).ConfigureAwait(false);
    }
#pragma warning disable CA1031 // Do not catch general exception types (ignoring, see comment below)
    catch
#pragma warning restore CA1031 // Do not catch general exception types
    {
        // Ignore exceptions. If token exchange fails for any reason,
        // tokenExchangeResponse remains null and a failure invoke response is sent.
    }

    if (tokenExchangeResponse == null || string.IsNullOrEmpty(tokenExchangeResponse.Token))
    {
        return false;
    }

    return true;
}

async onInvokeActivity(context) {
    console.log('onInvoke, ' + context.activity.name);
    const valueObj = context.activity.value;
    if (valueObj.authentication) {
        const authObj = valueObj.authentication;
        if (authObj.token) {
            // If the token is NOT exchangeable, then do NOT deduplicate requests.
            if (await this.tokenIsExchangeable(context)) {
                return await super.onInvokeActivity(context);
            } else {
                const response = {
                    status: 412
                };
                return response;
            }
        }
    }
    return await super.onInvokeActivity(context);
}

async tokenIsExchangeable(context) {
    let tokenExchangeResponse = null;
    try {
        const valueObj = context.activity.value;
        const tokenExchangeRequest = valueObj.authentication;
        tokenExchangeResponse = await context.adapter.exchangeToken(
            context,
            process.env.connectionName,
            context.activity.from.id,
            { token: tokenExchangeRequest.token }
        );
    } catch (err) {
        console.log('tokenExchange error: ' + err);
        // Ignore exceptions. If token exchange fails for any reason,
        // tokenExchangeResponse remains null and a failure invoke response is sent.
    }
    if (!tokenExchangeResponse || !tokenExchangeResponse.token) {
        return false;
    }
    return true;
}

アプリユーザーのログアウトを処理する

次のコードスニペットを使用して、アプリユーザーがログアウトした場合にアクセストークンを処理します。

C#
JavaScript

private async Task<DialogTurnResult> InterruptAsync(
    DialogContext innerDc,
    CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        // Allow logout anywhere in the command.
        if (text.IndexOf("logout") >= 0)
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(
                innerDc.Context.Activity.From.Id,
                ConnectionName,
                innerDc.Context.Activity.ChannelId,
                cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(
                MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(
                innerDc.context.adapter.UserTokenClientKey
            );

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(
                activity.from.id,
                this.connectionName,
                activity.channelId
            );

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }
    }
}

コードサンプル

このセクションでは、ボット認証 v3 SDK のサンプルを提供します。

サンプルの名前	説明	.NET	Node.js	Python	マニフェスト
ボット認証	このサンプルアプリでは、ボットが Teams 認証を使用する方法を示します。	表示	表示	表示	該当なし
タブ、ボット、メッセージ拡張機能の SSO	このサンプルアプリでは、安全な認証のために C# と Microsoft Entra ID を使用したタブ、ボット、メッセージ拡張機能の Teams SSO 統合を示します。	表示	表示	該当なし	表示
タブ、ボット、メッセージ拡張機能	このサンプルでは、Microsoft Teams のボット、タブ、メッセージ拡張機能全体での Microsoft Entra ID と Facebook 認証について説明します。	表示	表示	該当なし	表示

次の手順

SSO 用のマニフェストを更新しアプリをプレビューする

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-10-15

メッセージ拡張機能アプリで SSO を有効にするコードを追加します

開発環境変数を更新する

トークンを要求するコードを追加します

アクセス トークンを取得するための同意ダイアログ

トークンを受け取るコードを追加します

アクセス トークンを検証する

アクセス トークンの例

Bot Framework トークン ストアにトークンを追加する

アプリ ユーザーのログアウトを処理する

コード サンプル