Bot Framework authentication basics

APPLIES TO: SDK v4

Often a bot must access protected resources, for example email account, on behalf of the user. In order to do that the bot must be authorized based on the user's credentials. Before that, the user must be authenticated first. The bot must be a known entity, that is, it must be authenticated within the Azure AI Bot Service context. This happens prior to the bot being authorized to operate on behalf of the user.

Let's see if we can untangle this bundle by starting with a bird's eye view of the Bot Framework authentication context.

• When you register a bot in Azure via a Azure Bot resource, Azure creates an Microsoft Entra ID registration application. This application has an app ID (MicrosoftAppId) and a client secret (MicrosoftAppPassword). You use these values in the bot configuration files as described below.

• Microsoft Entra ID is a cloud identity service that allows you to build applications that securely sign in users using industry standard protocols like OAuth 2.0. You create an Active Directory application and use its app ID and password to select an identity provider and generate an authentication connection. You add this connection to your bot resource. You also add the connection name in the bot configuration files as described below.

• A bot is identified by its Azure Bot resource app ID and password. You add the related values in the bot's configuration file or to a secrets or key manager. You also add the connection name. The bot uses a token based on the app ID and password to access protected resources. The bot uses different tokens, based on the authentication connection, to access the user's protected resources.

Bot authentication and authorization

The following are the main steps to authenticate a bot and authorize it to access user's protected resources:

1. Create a bot channel registration application.
2. Add the registration app ID and password to the bot configuration file. This allows the bot to be authenticated to access protected resources.
3. Create an Microsoft Entra ID application to select an identity provider to authenticate the user.
4. Create an authentication connection and add it to the channel registration settings.
5. Add the connection name to the bot's configuration files. This allows the bot to be authorized to access user's protected resources.

For a complete example, see Add authentication to a bot.

Best practices

• Keep the Microsoft Entra ID app registration restricted to its original purpose of service to service application.
• Create an additional Microsoft Entra ID app for any user to service authentication, for more finite control over disabling authentication connections, rolling secrets, or reusing the Microsoft Entra ID app with other applications.

Some of the problems you encounter if you also use the Microsoft Entra ID registration app for authentication are:

• If the certificate attached to the Microsoft Entra ID app registration needs to be renewed, it would impact users that have authenticated with other Microsoft Entra ID services using the certificate.
• In general, it creates a single point of failure and control for all authentication-related activities with the bot.

Related topics

The following articles provide in-depth information and examples about authentication within the Bot Framework. Start by looking at the Authentication types and then Identity providers.

Article	Description
Authentication types	Describes the two Bot Framework authentication types and the tokens they use.
Identity providers	Describes the use of identity providers. They allow you to build applications that securely sign in users using industry standard protocols like OAuth2.0.
User authentication	Describes user's authentication and the related token to authorize a bot to perform tasks on the user's behalf.
Single sign on	Describes single user authentication for multiple protected resources access.
Register a bot with Azure	Shows how to register a bot with the Azure AI Bot Service.
Bot Framework security guidelines	Describes security in general and as it applies to the Bot Framework.
Add authentication to a bot	Shows how to create bot channel registration, create an authentication connection, and prepare the code.
Add single sign on to a bot	Shows how to add single sign-on authentication to a bot.