Add authentication to a bot

Available for C#, JavaScript, and Python bots.

Available for C#, JavaScript, and Python bots.

Available for bots in all programming languages: C#, JavaScript, Java, and Python.

1. Open your bot's Azure Bot resource page in the Azure portal.

2. Select Settings.

3. Under OAuth Connection Settings near the bottom of the page, select Add Setting.

4. Fill in the form as follows:

   1. Name. Enter a name for your connection. You'll use it in your bot code.

   2. Service Provider. Select Microsoft Entra ID to display Microsoft Entra ID-specific fields.

   3. Client id. Enter the application (client) ID you recorded for your Microsoft Entra ID identity provider.

   4. Client secret. Enter the secret you recorded for your Microsoft Entra ID identity provider.

      Tip

      If you want to use certificates, you can select the AAD v2 with Certificates provider. You'll need to give Bot Service Token Store (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) the permission to get the certificate.

   5. Token Exchange URL. Leave it blank because it's used for SSO in Microsoft Entra ID only.

   6. Tenant ID. Enter the directory (tenant) ID that you recorded earlier for your Microsoft Entra ID app or common depending on the supported account types selected when you created the Azure DD app. To decide which value to assign, follow these criteria:

      • When creating the Microsoft Entra ID app, if you selected Accounts in this organizational directory only (Microsoft only - Single tenant), enter the tenant ID you recorded earlier for the Microsoft Entra ID app.
      • However, if you selected Accounts in any organizational directory (Any Microsoft Entra ID directory - Multi tenant and personal Microsoft accounts e.g. Xbox, Outlook.com) or Accounts in any organizational directory(Microsoft Entra ID directory - Multi tenant), enter common instead of a tenant ID. Otherwise, the Microsoft Entra ID app will verify through the tenant whose ID was selected and exclude personal Microsoft accounts.

      This will be the tenant associated with the users who can be authenticated. For more information, see Tenancy in Microsoft Entra ID.

   7. For Scopes, enter the names of the permission you chose from the application registration. For testing purposes, you can just enter: openid profile.

      Note

      For Microsoft Entra ID, Scopes field takes a case-sensitive, space-separated list of values.

5. Select Save.

1. Navigate to your bot's resource page on the Azure portal.

2. Select Settings.

3. Under OAuth Connection Settings near the bottom of the page, select Add Setting.

4. Fill in the form as follows:

   1. For Name, enter a name for your connection. You'll use this name in your bot code.

   2. For Service Provider, select Microsoft Entra ID. Once you select this, the Microsoft Entra ID-specific fields will be displayed.

   3. For Client id, enter the application (client) ID that you recorded for your Azure AD v1 application.

   4. For Client secret, enter the secret that you created to grant the bot access to the Microsoft Entra ID app.

   5. For Grant Type, enter authorization_code.

   6. For Login URL, enter https://login.partner.microsoftonline.cn.

   7. For Tenant ID, enter the directory (tenant) ID that you recorded earlier for your Microsoft Entra ID app or common depending on the supported account types selected when you created the ADD app. To decide which value to assign, follow these criteria:

      • When creating the Microsoft Entra ID app, if you selected Accounts in this organizational directory only (Microsoft only - Single tenant), enter the tenant ID you recorded earlier for the Microsoft Entra ID app.
      • However, if you selected Accounts in any organizational directory (Any Microsoft Entra ID directory - Multi tenant and personal Microsoft accounts e.g. Xbox, Outlook.com) or Accounts in any organizational directory(Microsoft Entra ID directory - Multi tenant), enter common instead of a tenant ID. Otherwise, the Microsoft Entra ID app will verify through the tenant whose ID was selected and exclude personal MS accounts.

      This will be the tenant associated with the users who can be authenticated. For more information, see Tenancy in Microsoft Entra ID.

   8. For Resource URL, enter https://graph.chinacloudapi.cn/.

   9. Leave Scopes blank.

5. Select Save.

1. Clone from the GitHub repository the sample you want to work with: Bot authentication or Bot authentication for Microsoft Graph.

2. Update appsettings.json:

   • Set ConnectionName to the name of the OAuth connection setting you added to your bot.

   • Set MicrosoftAppId and MicrosoftAppPassword to your bot's app ID and app secret.

     Depending on the characters in your bot secret, you may need to XML escape the password. For example, any ampersands (&) will need to be encoded as &.

   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "",
     "MicrosoftAppPassword": "",
     "MicrosoftAppTenantId": "",
     "ConnectionName": ""
   }
   
   

   To use OAuth in bot with data-residency in public cloud, you must add the following configurations in your appsettings

   "OAuthUrl": "<Regional-OAuth-Uri>",
   "ToChannelFromBotOAuthScope": "https://api.botframework.azure.cn",
   "ToChannelFromBotLoginUrlTemplate": "https://api.botframework.azure.cn",
   "PublicAzureChannel": "https://api.botframework.azure.cn",
   "ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.azure.cn/v1/.well-known/openidconfiguration",
   "ToBotFromEmulatorOpenIdMetadataUrl": "https://login.partner.microsoftonline.cn/common/v2.0/.well-known/openid-configuration",
   "ToBotFromChannelTokenIssuer": "https://api.botframework.azure.cn",
   "ToChannelFromBotLoginUrl": "https://login.partner.microsoftonline.cn/botframework.com",
   

3. Update Startup.cs:

   To use OAuth in non-public Azure clouds, like the government cloud, you must add the following code in the Startup.cs file.

   string uri = "<uri-to-use>";
   MicrosoftAppCredentials.TrustServiceUrl(uri);
   OAuthClientConfig.OAuthEndpoint = uri;
   
   

   Where <uri-to-use> is one of the following URIs:

   URI	Description
   https://api.botframework.azure.cn	For United States government-cloud bots without data residency.
   https://api.botframework.azure.cn	For public-cloud bots without data residency. This is the default URI and doesn't require a change to Startup.cs.

1. Clone from the GitHub repository you want to work with: Bot authentication or Bot authentication for Microsoft Graph.

2. Update .env:

   • Set connectionName to the name of the OAuth connection setting you added to your bot.

   • Set MicrosoftAppId and MicrosoftAppPassword values to your bot's app ID and app secret.

     Depending on the characters in your bot secret, you may need to XML escape the password. For example, any ampersands (&) will need to be encoded as &.

   MicrosoftAppType=
   MicrosoftAppId=
   MicrosoftAppPassword=
   MicrosoftAppTenantId=
   connectionName=
   

1. Clone from the GitHub repository the sample you want to work with: Bot authentication or Bot authentication for Microsoft Graph.

2. Update application.properties:

   • Set ConnectionName to the name of the OAuth connection setting you added to your bot.
   • Set MicrosoftAppId and MicrosoftAppPassword to your bot's app ID and app secret.

   MicrosoftAppType=
   MicrosoftAppId=
   MicrosoftAppPassword=
   MicrosoftAppTenantId=
   connectionName=
   

1. Clone the GitHub repository the sample you want to work with: Bot authentication or Bot authentication for Microsoft Graph.

2. Update config.py:

   • Set ConnectionName to the name of the OAuth connection setting you added to your bot.

   • Set MicrosoftAppId and MicrosoftAppPassword to your bot's app ID and app secret.

     Depending on the characters in your bot secret, you may need to XML escape the password. For example, any ampersands (&) will need to be encoded as &.

   #!/usr/bin/env python3
   # Copyright (c) Microsoft Corporation. All rights reserved.
   # Licensed under the MIT License.
   
   import os
   
   """ Bot Configuration """
   
   
   class DefaultConfig:
       """ Bot Configuration """
   
       PORT = 3978
       APP_ID = os.environ.get("MicrosoftAppId", "")
       APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
       APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
       APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
       CONNECTION_NAME = os.environ.get("ConnectionName", "")
   
   

Dialogs\MainDialog.cs

Add an OAuth prompt to MainDialog in its constructor. Here, the value for the connection name was retrieved from the appsettings.json file.

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)
    }));

Within a dialog step, use BeginDialogAsync to start the OAuth prompt, which asks the user to sign in.

• If the user is already signed in, this will generate a token response event, without prompting the user.
• Otherwise, this will prompt the user to sign in. The Azure AI Bot Service sends the token response event after the user attempts to sign in.

return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

Within the following dialog step, check for the presence of a token in the result from the previous step. If it's not null, the user successfully signed in.

// 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.
var tokenResponse = (TokenResponse)stepContext.Result;

dialogs/mainDialog.js

Add an OAuth prompt to MainDialog in its constructor. Here, the value for the connection name was retrieved from the .env file.

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

Within a dialog step, use beginDialog to start the OAuth prompt, which asks the user to sign in.

• If the user is already signed in, this will generate a token response event, without prompting the user.
• Otherwise, this will prompt the user to sign in. The Azure AI Bot Service sends the token response event after the user attempts to sign in.

const tokenResponse = stepContext.result;

Within the following dialog step, check for the presence of a token in the result from the previous step. If it's not null, the user successfully signed in.

await stepContext.context.sendActivity('Login was not successful please try again.');
return await stepContext.endDialog();

MainDialog.java

Add an OAuth prompt to MainDialog in its constructor. Here, the value for the connection name was retrieved from the application.properties file.

OAuthPromptSettings settings = new OAuthPromptSettings();
settings.setText("Please Sign In");
settings.setTitle("Sign In");
settings.setConnectionName(configuration.getProperty("ConnectionName"));
settings.setTimeout(300000); // User has 5 minutes to login (1000 * 60 * 5)

addDialog(new OAuthPrompt("OAuthPrompt", settings));

Within a dialog step, use beginDialog to start the OAuth prompt, which asks the user to sign in.

• If the user is already signed in, this will generate a token response event, without prompting the user.
• Otherwise, this will prompt the user to sign in. The Azure AI Bot Service sends the token response event after the user attempts to sign in.

return stepContext.beginDialog("OAuthPrompt");

Within the following dialog step, check for the presence of a token in the result from the previous step. If it's not null, the user successfully signed in.

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There instanceof an example of this in the next method.
TokenResponse tokenResponse = (TokenResponse) stepContext.getResult();

dialogs/main_dialog.py

Add an OAuth prompt to MainDialog in its constructor. Here, the value for the connection name was retrieved from the config.py file.

self.add_dialog(
    WaterfallDialog(
        "WFDialog",
        [
            self.prompt_step,
            self.login_step,
            self.display_token_phase1,
            self.display_token_phase2,
        ],
    )
)

Within a dialog step, use begin_dialog to start the OAuth prompt, which asks the user to sign in.

• If the user is already signed in, this will generate a token response event, without prompting the user.
• Otherwise, this will prompt the user to sign in. The Azure AI Bot Service sends the token response event after the user attempts to sign in.

return await step_context.begin_dialog(OAuthPrompt.__name__)

Within the following dialog step, check for the presence of a token in the result from the previous step. If it's not null, the user successfully signed in.

if step_context.result:
    await step_context.context.send_activity("You are now logged in.")
    return await step_context.prompt(
        ConfirmPrompt.__name__,
        PromptOptions(
            prompt=MessageFactory.text("Would you like to view your token?")
        ),
    )

await step_context.context.send_activity(
    "Login was not successful please try again."
)

Bots\AuthBot.cs

AuthBot derives from ActivityHandler and explicitly handles token response event activities. Here, we continue the active dialog, which allows the OAuth prompt to process the event and retrieve the token.

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

bots/authBot.js

AuthBot derives from ActivityHandler and explicitly handles token response event activities. Here, we continue the active dialog, which allows the OAuth prompt to process the event and retrieve the token.

await this.dialog.run(context, this.dialogState);

await next();

AuthBot.java

AuthBot derives from Dialog and explicitly handles token response event activities. Here, we continue the active dialog, which allows the OAuth prompt to process the event and retrieve the token.

@Override
protected CompletableFuture<Void> onTokenResponseEvent(TurnContext turnContext) {
    LoggerFactory.getLogger(AuthBot.class).info("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

bots/auth_bot.py

AuthBot explicitly handles token response event activities. Here, we continue the active dialog, which allows the OAuth prompt to process the event and retrieve the token.

async def on_token_response_event(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

Dialogs\LogoutDialog.cs

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();

        if (text == "logout")
        {
            // 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;
}

dialogs/logoutDialog.js

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();
        }
    }

LogoutDialog.java

private CompletableFuture<DialogTurnResult> interrupt(DialogContext innerDc) {
    if (innerDc.getContext().getActivity().getType().equals(ActivityTypes.MESSAGE)) {
        String text = innerDc.getContext().getActivity().getText().toLowerCase();

        if (text.equals("logout")) {
            // The bot adapter encapsulates the authentication processes.
            BotFrameworkAdapter botAdapter = (BotFrameworkAdapter) innerDc.getContext().getAdapter();
            botAdapter.signOutUser(
                innerDc.getContext(),
                getConnectionName(),
                innerDc.getContext().getActivity().getFrom().getId())
                    .thenApply(result -> innerDc.getContext().sendActivity(MessageFactory.text("You have been signed out."))
                    .thenApply(sendResult -> null));
            return innerDc.cancelAllDialogs();
        }
    }

    return CompletableFuture.completedFuture(null);
}

dialogs/logout_dialog.py

return result
    return await super().on_continue_dialog(inner_dc)

async def _interrupt(self, inner_dc: DialogContext):
    if inner_dc.context.activity.type == ActivityTypes.message:
        text = inner_dc.context.activity.text.lower()
        if text == "logout":
            user_token_client: UserTokenClient = inner_dc.context.turn_state.get(