[Azure Bot Framework ]Bot框架中的身份验证

How authentication is integrated into the Bot Framework.

• High Level Authorization Flow Using OAuth 2.0
• Adding Authentication to Your Bot
• Channel to Bot Authentication and Authorization
• Architecture of Authentication in Bot Framework
• OAuthPrompt

---

Within Bot Framework, an OAuth flow typically boils down to your bot wanting to access a protected resource on behalf of the user (i.e. the resource owner). In order to do this, we must verify that the user is someone who has the authority to access the protected resource, and can in turn also delegate part of their authority to the bot to access the resource.

The protected resource accepts an access token as "proof" that the bot has been delegated permission to access it. The token acts as a limited-access key.

The access token is used, because:

• It does not expose the user's log-in credentials for the protected resource to the bot
  
  • Bot cannot impersonate user
• Provides scopes (subset of functions or permissions) that the user allows the bot to perform
  
  • This thus allows the user to limit the actions the bot can do on his/her behalf
  • For example, a bot may be granted permission to read your social media contacts, but it cannot send messages to them or delete any of them

Giving Bot Access to the Proteced Resource

Goal:

Another participant in the OAuth flow is the authorization server (AS) or identity provider (IdP). An Azure Active Directory (AAD) app is an example of an identity provider in the cloud. AAD:

• Authenticates users
• Provides access tokens to authorized clients

You can register AS/IdP to your bot from within Azure Bot Service.

The protected resource trusts tokens issued from specified authorization servers. (OAuth protocol does not specify how the trust is established between the protected resource and the authorization server, only that it does happen--allowing for flexibility at the same time as mandating what is necessary for security.) When a user wants the bot to access the protected resource, the bot sends the user to the authorization server to allow the user to authorize the bot to access the resource. Once authorized, the authorization server sends the acess token to the bot. The bot can now use the external service, making sure to include the token in its calls to the resrouce's API.

Authenticating

Issue Token to Authorized Bot and Make Request with Token on Behalf of User

High Level View of OAuth Flow in Bot Framework

Sequence diagram of the authentication and authorization flow that takes place when a user asks a bot to send an email on their behalf.

For more information on foundational OAuth concepts, see Azure Active Directory V2 Protocols documentation.

---

Contains diagrams of adding authentication to your bot as described by examples in BF documentation.

Click to view diagrams of the following articles:

• User authentication within a conversation
• Add authentciation to your bot via Azure Bot Service

---

Illustrating example in User authentication within a conversation, deep diving into the details of OAuth flow with the user, Bot Framework Token Service and the bot.

"For example, a bot that can check a user's recent emails, using the Microsoft Graph API, will require an Azure Active Directory user token. At design time, the bot developer would register an Azure Active Directory application with the Bot Framework Token Service (via the Azure Portal), and then configure an OAuth connection setting (named GraphConnection) for the bot."

 

It's helpful to preview the architecture in this block diagram of participants in the flow of an activity and in the Authenctication doc example before diving into the detailed "OAuth dance" in the sequence diagram following.

OAuth Flow - no access token stored in Token Service's Token Storage yet

1. Authorization Server (AS).
   
   • The AS can be within Azure, such as using AAD as our token provider, or outside of Azure as well, like in the case of using GitHub as the AS.
2. There are many different authorization grants, or OAuth flows, that detail how exactly how to use the identity of the owner of the protected resource in exchange for an access token (e.g. authorization code, client credentials, device code, refresh token, implicit, etc.)

OAuth Flow - access token already stored in Token Service's Token Storage

---

This section diagrams the concepts introduced in the Add authentication to your bot via Azure Bot Service, which is linked in our authentication samples' READMEs.

Higher Level

• AAD is an Identity Provider, used as the authorization server to which:
  
  • User authenticates their identity to, and authorizes bot to act on their behalf
  • If authenticated, then auth server provides the bot with an access token
• Protected Resource separately sepcifies which auth servers it trusts to issue Tokens
• Bot can use the token obtained from auth server in its requests to access the protected resource's APIs

Detailed View

• *Created automatically when creating a Web App Bot in Azure Portal
• ** Auth Server can be AAD, GitHub, Uber, FB, etc.
  
  • Auth Server simply must be a provider that the Protected Resource trusts and can consume Tokens issued from

---

See Channel-to-Bot Authentication and Authorization.

---

Class diagrams and flow charts illustrating the structural components related to authentication using an OAuthPrompt.

On TurnContext Initialization

OAuthPrompt has various methods* that uses BotFrameworkAdapter within its logic:

• Methods in OAuthPrompt that use this adapter: BeginDialogAsync(), GetUserTokenAsync(), SignUserOutAsync(), SendOAuthCardAsync(), RecognizeTokenAsync()

• C#
• JS

Notes:

• These class diagrams obscure some class properties in order to better highlight the portions related specifically to authentication and authorization.
• Class diagrams are read from top to bottom (regarding the relativity of which class the link notes pertain to)

OAuthPrompt uses a BotFrameworkAdapter that implements ICredentialTokenProvider to acquire tokens.

• The OAuthPrompt's ICredentialTokenProvider creates an OAuthClient to send a request to get a token.
• You must use ServiceClientCredentials in order to initialize an OAuthClient instance.

• ServiceClientCredentials is an MS REST class.

You can see a more formal flow chart on creating an OAuthClient logic here.

• HttpOperationResponseTokenResponse should be HttpOperationResponse<TokenResponse> (diagram tool breaks on special chars in class diagram).
• ServiceClient is an MS REST class.

OAuthPrompt uses a BotFrameworkAdapter that implements ExtendedUserTokenProvider to acquire tokens.

• The OAuthPrompt's ExtendedUserTokenProvider creates a TokenApiClient to send a request to get a token.
• You must use ServiceClientCredentials in order to initialize an TokenApiClient instance.

• ServiceClientCredentials is an ms-rest interface.

• TokenApiClient and TokenApiClientContext are classes generated by auto-rest.
• ServiceClient is an msrest class.

---

See OAuthPrompt Behavioral Flow Charts.