ボットのシングル サインオン (SSO) のサポートSingle sign-on (SSO) support for bots

Azure Active Directory (AAD) のシングル サインオン認証では、ユーザーがサインイン資格情報を入力する必要がある回数を最小限に抑えるために、認証トークンをサイレント 更新します。Single sign-on authentication in Azure Active Directory (AAD) minimizes the number of times users need to enter their sign in credentials by silently refreshing the authentication token. ユーザーがアプリの使用に同意した場合、別のデバイスでもう一度同意する必要はありません。また、自動的にサインインできます。If users agree to use your app, they need not provide consent again on another device and can sign in automatically. フローはMicrosoft Teamsタブ SSO サポートのフローと似ていますが、ボットがトークンを要求して応答を受信する方法のプロトコルが異なっていますThe flow is similar to that of Microsoft Teams tab SSO support, however, the difference is in the protocol for how a bot requests tokens and receives responses.

注意

OAuth 2.0 は、AAD や他の多くの ID プロバイダーで使用される認証と承認のオープン標準です。OAuth 2.0 is an open standard for authentication and authorization used by AAD and many other identity providers. OAuth 2.0 の基本的な理解は、Teams で認証を操作する場合の前提条件です。A basic understanding of OAuth 2.0 is a prerequisite for working with authentication in Teams.

実行時の Bot SSOBot SSO at runtime

実行時のボット SSO の図

認証トークンとボット アプリケーション トークンを取得するには、次の手順を実行します。Complete the following steps to get authentication and bot application tokens:

  1. ボットは、プロパティを含む OAuthCard でメッセージを送信 tokenExchangeResource します。The bot sends a message with an OAuthCard that contains the tokenExchangeResource property. ボット アプリケーションの認証トークンを取得するために Teams に指示します。It tells Teams to obtain an authentication token for the bot application. ユーザーは、すべてのアクティブなユーザー エンドポイントでメッセージを受信します。The user receives messages at all the active user endpoints.

    注意

    • ユーザーは一度に複数のアクティブなエンドポイントを持つ可能性があります。A user can have more than one active endpoint at a time.
    • ボット トークンは、すべてのアクティブユーザー エンドポイントから受信されます。The bot token is received from every active user endpoint.
    • SSO をサポートするには、アプリを個人用スコープでインストールする必要があります。The app must be installed in personal scope for SSO support.
  2. 現在のユーザーがボット アプリケーションを初めて使用する場合は、次のいずれかの操作をユーザーに要求する要求プロンプトが表示されます。If the current user is using your bot application for the first time, a request prompt appears requesting the user to do one of the following:

    • 必要に応じて同意を提供します。Provide consent, if required.
    • 2 要素認証などのステップ アップ認証を処理します。Handle step-up authentication, such as two-factor authentication.
  3. Teams は、現在のユーザーの AAD エンドポイントからボット アプリケーション トークンを要求します。Teams requests the bot application token from the AAD endpoint for the current user.

  4. AAD はボット アプリケーション トークンを Teams アプリケーションに送信します。AAD sends the bot application token to the Teams application.

  5. Teams は、サインイン /トークンExchange という名前で、呼び出しアクティビティによって返される値オブジェクトの一部としてボットにトークンを送信します。Teams sends the token to the bot as part of the value object returned by the invoke activity with the name sign-in/tokenExchange.

  6. ボット アプリケーションで解析されたトークンは、ユーザーの電子メール アドレスなどの必要な情報を提供します。The parsed token in the bot application provides the required information, such as the user's email address.

SSO Teams ボットを開発するDevelop an SSO Teams bot

SSO Teams ボットを開発するには、次の手順を実行します。Complete the following steps to develop an SSO Teams bot:

  1. AAD ポータルからアプリを登録しますRegister your app through the AAD portal.
  2. ボットの Teams アプリケーション マニフェストを更新しますUpdate your Teams application manifest for your bot.
  3. ボット トークンを要求および受信するコードを追加しますAdd the code to request and receive a bot token.

AAD ポータルを通じてアプリを登録するRegister your app through the AAD portal

AAD ポータルを通じてアプリを登録する手順は、タブ SSO フロー に似ていますThe steps to register your app through the AAD portal are similar to the tab SSO flow. アプリを登録するには、次の手順を実行します。Complete the following steps to register your app:

  1. Azure Active Directory アプリ登録ポータルに 新しいアプリケーションを登録 します。Register a new application in the Azure Active Directory – App Registrations portal.

  2. [新規 登録] を選択しますSelect New Registration. [ アプリケーションの登録] ページ が表示されます。The Register an application page appears.

  3. [アプリケーション の登録] ページで 、次の値を入力します。In the Register an application page, enter the following values:

    1. アプリの 名前 を入力します。Enter a Name for your app.

    2. サポートされている アカウントの種類を選択し、 単一テナントアカウントの種類またはマルチテナント アカウントの種類を選択します。Choose the Supported account types, select single tenant or multitenant account type.

      注意

      AAD アプリが Teams で認証要求を行っているのと同じテナントに登録されている場合、ユーザーは同意を求めではなく、アクセス トークンを直接付与されます。The users are not asked for consent and are granted access tokens right away, if the AAD app is registered in the same tenant where they are making an authentication request in Teams. ただし、AAD アプリが別のテナントに登録されている場合、ユーザーはアクセス許可に同意する必要があります。However, the users must provide consent to the permissions, if the AAD app is registered in a different tenant.

    3. [登録] を選択します。Choose Register.

  4. [概要] ページで、アプリケーション (クライアント) ID をコピーして保存しますOn the overview page, copy and save the Application (client) ID. 後で Teams アプリケーション マニフェストを更新するときに必要になります。You need it later when updating your Teams application manifest.

  5. [管理] で [API の公開] を選択します。Under Manage, select Expose an API.

    重要

    • スタンドアロン ボットを作成する場合は、アプリケーション ID URI を次のように入力します api://botid-{YourBotId}If you are building a standalone bot, enter the Application ID URI as api://botid-{YourBotId}. ここで 、YourBotId は AAD アプリケーション ID です。Here YourBotId is your AAD application ID.
    • ボットとタブを使用してアプリを作成する場合は、アプリケーション ID URI を次のように入力します api://fully-qualified-domain-name.com/botid-{YourBotId}If you are building an app with a bot and a tab, enter the Application ID URI as api://fully-qualified-domain-name.com/botid-{YourBotId}.
  6. アプリケーションが AAD エンドポイントに必要とするアクセス許可と、必要に応じて Microsoft Graph に必要なアクセス許可を選択します。Select the permissions that your application needs for the AAD endpoint and, optionally, for Microsoft Graph.

  7. Teamsのデスクトップ、Web、モバイル アプリケーションのアクセス許可を付与します。Grant permissions for Teams desktop, web, and mobile applications.

  8. [スコープの追加] を選択します。Select Add a scope.

  9. 開くパネルで、スコープ名として入力してクライアント access_as_user アプリを 追加しますIn the panel that opens, add a client app by entering access_as_user as the Scope name.

    注意

    クライアント アプリのaccess_as_user "管理者とユーザー" のスコープです。The "access_as_user" scope used to add a client app is for "Administrators and users".

    次の重要な制限に注意する必要があります。You must be aware of the following important restrictions:

    • ユーザー レベルの Microsoft Graph API のアクセス許可 (メール、プロファイル、offline_access、OpenId など) だけがサポートされます。Only user-level Microsoft Graph API permissions, such as email, profile, offline_access, and OpenId are supported. その他の Microsoft Graph スコープにアクセスする必要がある場合 (または、推奨される回避策 User.Read Mail.Read を参照してください)。If you need access to other Microsoft Graph scopes, such as User.Read or Mail.Read, see recommended workaround.
    • アプリケーションのドメイン名は、AAD アプリケーションに登録したドメイン名と同じである必要があります。Your application's domain name must be same as the domain name that you have registered for your AAD application.
    • 現在、アプリごとに複数のドメインはサポートされていません。Multiple domains per app are currently not supported.
    • ドメインを使用するアプリケーションは、一般的であり、セキュリティ上のリスクが azurewebsites.net 高い可能性からサポートされていません。Applications that use the azurewebsites.net domain are not supported because it is common and may be a security risk.

OAuth 接続を使用して Azure Portal を更新するUpdate the Azure portal with the OAuth connection

OAuth 接続を使用して Azure Portal を更新するには、次の手順を実行します。Complete the following steps to update the Azure portal with the OAuth connection:

  1. Azure Portal で、アプリの登録 に移動しますIn the Azure Portal, navigate to App registrations.

  2. API の アクセス許可に移動しますGo to API Permissions. [Microsoft Graph 委任されたアクセス 許可のアクセス許可の追加] を選択し、Microsoft Graph API から次のアクセス > > 許可を追加します。Select Add a permission > Microsoft Graph > Delegated permissions, then add the following permissions from Microsoft Graph API:

    • User.Read (既定で有効)User.Read (enabled by default)
    • メールemail
    • offline_accessoffline_access
    • OpenIdOpenId
    • profileprofile
  3. Azure Portal で、ボット チャネル登録 に移動しますIn the Azure Portal, navigate to Bot Channels Registration.

  4. 左側 のウィンドウで [ 設定] を選択し、[OAuth 接続 の設定] セクションで [ 設定の追加] を選択 します。Select Settings on the left pane and choose Add Setting under the OAuth Connection Settings section.

    SSOBotHandle2 ビュー

  5. [新しい接続設定] フォームを完了するには 、次の手順を実行 します。Perform the following steps to complete the New Connection Setting form:

    注意

    AAD アプリケーション では暗黙的な許可が必要になる場合があります。Implicit grant may be required in the AAD application.

    1. [新しい 接続設定 ] ページに名前を入力 します。Enter a Name in the New Connection Setting page. これは、実行時に Bot SSO の手順 5 でボット サービス コードの設定内で参照される 名前ですThis is the name that is referred to inside the settings of your bot service code in step 5 of Bot SSO at runtime.
    2. [サービス プロバイダー] ドロップダウンから****、Azure Active Directory v2 を選択しますFrom the Service Provider drop-down, select Azure Active Directory v2.
    3. AAD アプリケーションのクライアント IDクライアント シークレットなどのクライアント資格情報を入力します。Enter the client credentials, such as Client id and Client secret for the AAD application.
    4. トークン交換 URL の場合は、「ボットの Teams アプリケーション マニフェストを更新 する」で定義されているスコープ値を使用しますFor the Token Exchange URL, use the scope value defined in Update your Teams application manifest for your bot. Token Exchange URL は、この AAD アプリケーションが SSO 用に構成されていることを SDK に示します。The Token Exchange URL indicates to the SDK that this AAD application is configured for SSO.
    5. [テナント ID] ボックスに 「共通」と 入力しますIn the Tenant ID box, enter common.
    6. AAD アプリケーションのダウンストリーム API へのアクセス許可を指定するときに構成されたスコープを追加します。Add all the Scopes configured when specifying permissions to downstream APIs for your AAD application. クライアント ID とクライアント シークレットが提供された場合、トークン ストアは、定義されたアクセス許可を持つグラフ トークンのトークンを交換します。With the Client id and Client secret provided, the token store exchanges the token for a graph token with defined permissions.
    7. [保存] を選択します。Select Save.

    VuSSOBotConnection 設定ビュー

ボットの Teams アプリケーション マニフェストを更新するUpdate your Teams application manifest for your bot

アプリケーションにスタンドアロン ボットが含まれている場合は、次のコードを使用して新しいプロパティを Teams アプリケーション マニフェストに追加します。If the application contains a standalone bot, then use the following code to add new properties to the Teams application manifest:

    "webApplicationInfo": 
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "resource": "api://botid-00000000-0000-0000-0000-000000000000"
        }

アプリケーションにボットとタブが含まれている場合は、次のコードを使用して新しいプロパティを Teams アプリケーション マニフェストに追加します。If the application contains a bot and a tab, then use the following code to add new properties to the Teams application manifest:

    "webApplicationInfo": 
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "resource": "api://subdomain.example.com/botid-00000000-0000-0000-0000-000000000000"
        }

webApplicationInfo は、次の要素の親です。webApplicationInfo is the parent of the following elements:

  • id - アプリケーションのクライアント ID。id - The client ID of the application. これは、アプリケーションを AAD に登録する一部として取得したアプリケーション ID です。This is the application ID that you obtained as part of registering the application with AAD.
  • resource - アプリケーションのドメインとサブドメイン。resource - The domain and subdomain of your application. これは api:// scope 、AADポータルからアプリを登録するときに登録したプロトコルを含め、同じ URI です。This is the same URI, including the api:// protocol that you registered when creating your scope in Register your app through the AAD portal. リソースにパスを access_as_user 含めずにしてください。You must not include the access_as_user path in your resource. この URI のドメイン部分は、Teams アプリケーション マニフェストの URL で使用されるドメインとサブドメインと一致している必要があります。The domain part of this URI must match the domain and subdomains used in the URLs of your Teams application manifest.

ボット トークンを要求して受信するコードを追加するAdd the code to request and receive a bot token

ボット トークンを要求するRequest a bot token

トークンを取得する要求は、既存のメッセージ スキーマを使用した通常の POST メッセージ要求です。The request to get the token is a normal POST message request using the existing message schema. OAuthCard の添付ファイルに含まれています。It is included in the attachments of an OAuthCard. OAuthCard クラスのスキーマは Microsoft Bot Schema 4.0 で定義され、サインイン カードに似ています。The schema for the OAuthCard class is defined in Microsoft Bot Schema 4.0 and it is similar to a sign-in card. カードにプロパティが設定されている場合、Teams は、この要求をサイレント トークン取得 TokenExchangeResource として処理します。Teams treats this request as a silent token acquisition if the TokenExchangeResource property is populated on the card. Teams チャネルでは、トークン要求を一意に識別するプロパティ Id だけが使用されます。For the Teams channel, only the Id property, which uniquely identifies a token request, is honored.

注意

Microsoft Bot Framework または SSO OAuthPrompt MultiProviderAuthDialog 認証がサポートされています。The Microsoft Bot Framework OAuthPrompt or the MultiProviderAuthDialog is supported for SSO authentication.

ユーザーがアプリケーションを初めて使用し、ユーザーの同意が必要な場合は、次のダイアログ ボックスが表示され、同意エクスペリエンスが続行されます。If the user is using the application for the first time and user consent is required, the following dialog box appears to continue with the consent experience:

[同意] ダイアログ ボックス

ユーザーが [続行] を選択 すると、次のイベントが発生します。When the user selects Continue, the following events occur:

  • ボットがサインイン ボタンを定義している場合、ボットのサインイン フローは、メッセージ ストリーム内の OAuth カード ボタンからのサインイン フローと同様にトリガーされます。If the bot defines a sign-in button, the sign in flow for bots is triggered similar to the sign in flow from an OAuth card button in a message stream. 開発者は、ユーザーの同意を必要とするアクセス許可を決定する必要があります。The developer must decide which permissions require user's consent. この方法は、それ以上のアクセス許可を持つトークンが必要な場合に推奨されます openIdThis approach is recommended if you require a token with permissions beyond openId. たとえば、グラフ リソースのトークンを交換する場合です。For example, if you want to exchange the token for graph resources.

  • ボットが OAuth カードにサインイン ボタンを提供していない場合は、最小限のアクセス許可セットに対してユーザーの同意が必要です。If the bot is not providing a sign-in button on the OAuth card, user consent is required for a minimal set of permissions. このトークンは、基本認証やユーザーの電子メール アドレスの取得に役立ちます。This token is useful for basic authentication and to get the user's email address.

サインイン ボタンのない C# トークン要求C# token request without a sign-in button
    var attachment = new Attachment
            {
                Content = new OAuthCard
                {
                    TokenExchangeResource = new TokenExchangeResource
                    {
                        Id = requestId
                    }
                },
                ContentType = OAuthCard.ContentType,
            };
            var activity = MessageFactory.Attachment(attachment);

            // NOTE: This activity needs to be sent in the 1:1 conversation between the bot and the user. 
            // If the bot supports group and channel scope, this code should be updated to send the request to the 1:1 chat. 

       await turnContext.SendActivityAsync(activity, cancellationToken);

ボット トークンを受信するReceive the bot token

トークンを含む応答は、ボットが現在受け取る他の呼び出しアクティビティと同じスキーマを持つ呼び出しアクティビティを通じて送信されます。The response with the token is sent through an invoke activity with the same schema as other invoke activities that the bots receive today. 唯一の違いは、呼び出し名、サインイン/トークンExchange、****および値 フィールドです。The only difference is the invoke name, sign-in/tokenExchange and the value field. フィールド には 、Id、 トークンとトークン フィールドを取得する最初の要求の文字列、トークンを含む文字列値が含まれます。The value field contains the Id, a string of the initial request to get the token and the token field, a string value including the token.

注意

ユーザーが複数のアクティブなエンドポイントを持つ場合、特定の要求に対して複数の応答を受け取る場合があります。You might receive multiple responses for a given request if the user has multiple active endpoints. トークンを使用して応答を重複排除する必要があります。You must deduplicate the responses with the token.

呼び出しアクティビティを処理する C# コードC# code to handle the invoke activity
    protected override async Task<InvokeResponse> OnInvokeActivityAsync
    (ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
            {
                try
                {
                    if (turnContext.Activity.Name == SignInConstants.TokenExchangeOperationName && turnContext.Activity.ChannelId == Channels.Msteams)
                    {
                        await OnTokenResponseEventAsync(turnContext, cancellationToken);
                        return new InvokeResponse() { Status = 200 };
                    }
                    else
                    {
                        return await base.OnInvokeActivityAsync(turnContext, cancellationToken);
                    }
                }
                catch (InvokeResponseException e)
                {
                    return e.CreateInvokeResponse();
                }
            }

turnContext.activity.value TokenExchangeInvokeRequest 型であり、ボットでさらに使用できるトークンが含まれます。The turnContext.activity.value is of type TokenExchangeInvokeRequest and contains the token that can be further used by your bot. パフォーマンス上の理由からトークンを保存し、更新する必要があります。You must store the tokens for performance reasons and refresh them.

認証サンプルを更新するUpdate the auth sample

Teams 認証サンプルを開き、次の手順を実行して更新します。Open Teams auth sample and then complete the following steps to update it:

  1. 次のコードを含めて、受信要求の重複を処理するために TeamsBot を更新します。Update the TeamsBot to handle the deduping of the incoming request by including the following code:

        protected override async Task OnSignInInvokeAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
            {
                await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
            }
        protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
            {
                await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
            }
    
  2. appsettings.json「OAuth 接続を使用して Azure portal を更新する」で定義されている接続名 、パスワード botId を含める更新Update appsettings.json to include the botId, password, and the connection name defined in Update the Azure portal with the OAuth connection.

  3. マニフェストを更新し、有効 token.botframework.com なドメインの一覧に含まれています。Update the manifest and ensure that token.botframework.com is in the valid domains list. 詳細については 、Teams 認証サンプルを参照してくださいFor more information, see Teams auth sample.

  4. マニフェストをプロファイル イメージと一緒に Zip し、Teams にインストールします。Zip the manifest with the profile images and install it in Teams.

その他のコード サンプルAdditional code samples