category
您的机器人通过安全通道(SSL/TLS)使用HTTP与机器人连接器服务通信。当你的机器人向连接器服务发送请求时,它必须包含连接器服务可以用来验证其身份的信息。同样,当连接器服务向您的机器人发送请求时,它必须包含机器人可以用来验证其身份的信息。本文描述了在机器人和机器人连接器服务之间进行的服务级别身份验证的身份验证技术和要求。如果您正在编写自己的身份验证代码,则必须实现本文中描述的安全过程,以使您的机器人能够与bot Connector服务交换消息。
重要事项
如果你正在编写自己的身份验证代码,正确实施所有安全程序至关重要。通过实施本文中的所有步骤,您可以降低攻击者能够读取发送给您的机器人的消息、发送冒充您的机器人和窃取密钥的风险。
如果您使用的是Bot Framework SDK,则不需要实现本文中描述的安全过程,因为SDK会自动为您完成。只需使用您在注册过程中为机器人获得的应用程序ID和密码配置您的项目,SDK将处理其余部分。
Authentication technologies
Four authentication technologies are used to establish trust between a bot and the Bot Connector:
Technology | Description |
---|---|
SSL/TLS | SSL/TLS用于所有服务到服务连接。X.509v3证书用于建立所有HTTPS服务的身份。客户端应始终检查服务证书,以确保其可信且有效。(客户端证书不作为此方案的一部分。) |
OAuth 2.0 | OAuth 2.0使用Microsoft Entra ID帐户登录服务来生成机器人可以用来发送消息的安全令牌。此令牌是服务到服务令牌;不需要用户登录。 |
JSON Web Token (JWT) | JSON Web令牌用于对发送到机器人和从机器人发送的令牌进行编码。根据本文中概述的要求,客户端应完全验证他们收到的所有JWT令牌。 |
OpenID metadata | Bot Connector服务发布一个有效令牌列表,用于在已知的静态端点将自己的JWT令牌签名为OpenID元数据。 |
This article describes how to use these technologies via standard HTTPS and JSON. No special SDKs are required, although you may find that helpers for OpenID and others
are useful.
Authenticate requests from your bot to the Bot Connector service
To communicate with the Bot Connector service, you must specify an access token in the Authorization
header of each API request, using this format:
Authorization: Bearer ACCESS_TOKEN
To get and use a JWT token for your bot:
- Your bot sends a GET HTTP request to the MSA Login Service.
- The response from the service contains the JWT token to use.
- Your bot includes this JWT token in the authorization header in requests to the Bot Connector service.
Step 1: Request an access token from the Microsoft Entra ID account login service
Important
If you haven't already done so, you must register your bot with the Bot Framework to obtain its AppID and password. You need the bot's App ID and password to
request an access token.
Your bot identity can be managed in Azure in a few different ways.
- As a user-assigned managed identity, so that you don't need to manage the bot's credentials yourself.
- As a single-tenant app.
- As a multi-tenant app.
Request an access token based on your bot's application type.
To request an access token from the login service, issue the following request, replacing MICROSOFT-APP-ID and MICROSOFT-APP-PASSWORD with the bot's
AppID and password that you obtained when you registered your bot with the Bot Service.
POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2F
api.botframework.com%2F.default
Step 2: Obtain the JWT token from the Microsoft Entra ID account login service response
If your application is authorized by the login service, the JSON response body will specify your access token, its type, and its expiration (in seconds).
When adding the token to the Authorization
header of a request, you must use the exact value that is specified in this response—don't escape or encode the token value. The access token is valid until its expiration. To prevent token expiration from impacting your bot's performance, you may choose to cache and proactively refresh the token.
This example shows a response from the Microsoft Entra ID account login service:
HTTP/1.1 200 OK
... (other headers)
{
"token_type":"Bearer",
"expires_in":3600,
"ext_expires_in":3600,
"access_token":"eyJhbGciOiJIUzI1Ni..."
}
Step 3: Specify the JWT token in the Authorization header of requests
When you send an API request to the Bot Connector service, specify the access token in the Authorization
header of the request using this format:
Authorization: Bearer ACCESS_TOKEN
All requests that you send to the Bot Connector service must include the access token in the Authorization
header. If the token is correctly formed, isn't expired, and was generated by the Microsoft Entra ID account login service, the Bot Connector service will authorize the request. Additional checks are performed to ensure that the token belongs to the bot that sent the request.
The following example shows how to specify the access token in the Authorization
header of the request.
POST https://smba.trafficmanager.net/teams/v3/conversations/12345/activities
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
(JSON-serialized Activity message goes here)
Important
Only specify the JWT token in the Authorization
header of requests you send to the Bot Connector service. Do NOT send the token over unsecured channels and do NOT include it in HTTP requests that you send to other services. The JWT token that you obtain from the the Microsoft Entra ID account login service is like a password and should be handled with great care. Anyone that possesses the token may use it to perform operations on behalf of your bot.
Bot to Connector: example JWT components
header:
{
typ: "JWT",
alg: "RS256",
x5t: "<SIGNING KEY ID>",
kid: "<SIGNING KEY ID>"
},
payload:
{
aud: "https://api.botframework.com",
iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
nbf: 1481049243,
exp: 1481053143,
appid: "<YOUR MICROSOFT APP ID>",
... other fields follow
}
Note
Actual fields may vary in practice. Create and validate all JWT tokens as specified above.
Authenticate requests from the Bot Connector service to your bot
When the Bot Connector service sends a request to your bot, it specifies a signed JWT token in the Authorization
header of the request. Your bot can authenticate calls from the Bot Connector service by verifying the authenticity of the signed JWT token.
To authenticate calls from the Bot Connector service:
- Your bot gets the JWT token from the authorization header in requests sent from the Bot Connector service.
- Your bot gets the OpenID metadata document for the Bot Connector service.
- Your bot gets the list of valid signing keys from the document.
- Your bot verifies the authenticity of the JWT token.
Step 2: Get the OpenID metadata document
The OpenID metadata document specifies the location of a second document that lists the Bot Connector service's valid signing keys. To get the OpenID metadata document, issue this request via HTTPS:
GET https://login.botframework.com/v1/.well-known/openidconfiguration
Tip
This is a static URL that you can hardcode into your application.
The following example shows an OpenID metadata document that is returned in response to the GET
request. The jwks_uri
property specifies the location of the document that contains the Bot Connector service's valid signing keys.
{
"issuer": "https://api.botframework.com",
"authorization_endpoint": "https://invalid.botframework.com",
"jwks_uri": "https://login.botframework.com/v1/.well-known/keys",
"id_token_signing_alg_values_supported": [
"RS256"
],
"token_endpoint_auth_methods_supported": [
"private_key_jwt"
]
}
Step 3: Get the list of valid signing keys
To get the list of valid signing keys, issue a GET
request via HTTPS to the URL specified by the jwks_uri
property in the OpenID metadata document. For example:
GET https://login.botframework.com/v1/.well-known/keys
The response body specifies the document in the JWK format but also includes an additional property for each key: endorsements
.
Tip
The list of keys is stable and may be cached, but new keys may be added at any time. To ensure your bot has an up-to-date copy of the document before these keys are used, all bot instances should refresh their local cache of the document at least once every 24 hours.
The endorsements
property within each key contains one or more endorsement strings that you can use to verify that the channel ID specified in the channelId
property within the Activity object of the incoming request is authentic. The list of channel IDs that require endorsements is configurable within each bot. By default, it will be the list of all published channel IDs, although bot developers may override selected channel ID values either way.
Step 4: Verify the JWT token
To verify the authenticity of the token that was sent by the Bot Connector service, you must extract the token from the Authorization
header of the request, parse the token, verify its contents, and verify its signature.
JWT parsing libraries are available for many platforms and most implement secure and reliable parsing for JWT tokens, although you must typically configure these libraries to require that certain characteristics of the token (its issuer, audience, and so on) contain correct values. When parsing the token, you must configure the parsing library or write your own validation to ensure the token meets these requirements:
- The token was sent in the HTTP
Authorization
header with "Bearer" scheme. - The token is valid JSON that conforms to the JWT standard.
- The token contains an "issuer" claim with value of
https://api.botframework.com
. - The token contains an "audience" claim with a value equal to the bot's Microsoft App ID.
- The token is within its validity period. Industry-standard clock-skew is 5 minutes.
- The token has a valid cryptographic signature, with a key listed in the OpenID keys document that was retrieved in Step 3, using the signing algorithm that is specified in the
id_token_signing_alg_values_supported
property of the Open ID Metadata document that was retrieved in Step 2. - The token contains a "serviceUrl" claim with value that matches the
serviceUrl
property at the root of the Activity object of the incoming request.
If endorsement for a channel ID is required:
- You should require that any
Activity
object sent to your bot with that channel ID is accompanied by a JWT token that is signed with an endorsement for that channel. - If the endorsement isn't present, your bot should reject the request by returning an HTTP 403 (Forbidden) status code.
Important
All of these requirements are important, particularly requirements 4 and 6. Failure to implement ALL of these verification requirements will leave the bot open to attacks which could cause the bot to divulge its JWT token.
Implementers shouldn't expose a way to disable validation of the JWT token that is sent to the bot.
Connector to Bot: example JWT components
header:
{
typ: "JWT",
alg: "RS256",
x5t: "<SIGNING KEY ID>",
kid: "<SIGNING KEY ID>"
},
payload:
{
aud: "<YOU MICROSOFT APP ID>",
iss: "https://api.botframework.com",
nbf: 1481049243,
exp: 1481053143,
... other fields follow
}
Note
Actual fields may vary in practice. Create and validate all JWT tokens as specified above.
Authenticate requests from the Bot Framework Emulator to your bot
The Bot Framework Emulator is a desktop tool that you can use to test the functionality of your bot. Although the Bot Framework Emulator uses the same authentication technologies as described above, it's unable to impersonate the real Bot Connector service. Instead, it uses the Microsoft App ID and Microsoft App Password that you specify when you connect the Emulator to your bot to create tokens that are identical to those that the bot creates. When the Emulator sends a request to your bot, it specifies the JWT token in the Authorization
header of the request—in essence, using the bot's own credentials to authenticate the request.
If you're implementing an authentication library and want to accept requests from the Bot Framework Emulator, you must add this additional verification path. The path is structurally similar to the Connector -> Bot verification path, but it uses MSA's OpenID document instead of the Bot Connector's OpenID document.
To authenticate calls from the Bot Framework Emulator:
- Your bot gets the JWT token from the authorization header in requests sent from the Bot Framework Emulator.
- Your bot gets the OpenID metadata document for the Bot Connector service.
- Your bot gets the list of valid signing keys from the document.
- Your bot verifies the authenticity of the JWT token.
Step 2: Get the MSA OpenID metadata document
The OpenID metadata document specifies the location of a second document that lists the valid signing keys. To get the MSA OpenID metadata document, issue this request via HTTPS:
GET https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration
The following example shows an OpenID metadata document that is returned in response to the GET
request. The jwks_uri
property specifies the location of the document that contains the valid signing keys.
{
"authorization_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
"token_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/token",
"token_endpoint_auth_methods_supported":["client_secret_post","private_key_jwt"],
"jwks_uri":"https://login.microsoftonline.com/common/discovery/v2.0/keys",
...
}
Step 3: Get the list of valid signing keys
To get the list of valid signing keys, issue a GET
request via HTTPS to the URL specified by the jwks_uri
property in the OpenID metadata document. For example:
GET https://login.microsoftonline.com/common/discovery/v2.0/keys
Host: login.microsoftonline.com
The response body specifies the document in the JWK format.
Step 4: Verify the JWT token
To verify the authenticity of the token that was sent by the Emulator, you must extract the token from the Authorization
header of the request, parse the token, verify its contents, and verify its signature.
JWT parsing libraries are available for many platforms and most implement secure and reliable parsing for JWT tokens, although you must typically configure these libraries to require that certain characteristics of the token (its issuer, audience, and so on) contain correct values. When parsing the token, you must configure the parsing library or write your own validation to ensure the token meets these requirements:
- The token was sent in the HTTP
Authorization
header with "Bearer" scheme. - The token is valid JSON that conforms to the JWT standard.
- The token contains an "issuer" claim with one of the highlighted values for non governmental cases. Checking for both issuer values will ensure you're checking for both the security protocol v3.1 and v3.2 issuer values.
- The token contains an "audience" claim with a value equal to the bot's Microsoft App ID.
- The Emulator, depending on the version, sends the AppId via either the appid claim (version 1) or the authorized party claim (version 2).
- The token is within its validity period. Industry-standard clock-skew is 5 minutes.
- The token has a valid cryptographic signature with a key listed in the OpenID keys document that was retrieved in Step 3.
Note
Requirement 5 is a specific to the Emulator verification path.
If the token doesn't meet all of these requirements, your bot should terminate the request by returning an HTTP 403 (Forbidden) status code.
Important
All of these requirements are important, particularly requirements 4 and 7. Failure to implement ALL of these verification requirements will leave the bot open to attacks which could cause the bot to divulge its JWT token.
Emulator to Bot: example JWT components
header:
{
typ: "JWT",
alg: "RS256",
x5t: "<SIGNING KEY ID>",
kid: "<SIGNING KEY ID>"
},
payload:
{
aud: "<YOUR MICROSOFT APP ID>",
iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
nbf: 1481049243,
exp: 1481053143,
... other fields follow
}
Note
Actual fields may vary in practice. Create and validate all JWT tokens as specified above.
Security protocol changes
OAuth login URL
Protocol version | Valid value |
---|---|
v3.1 & v3.2 | https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token |
OAuth scope
Protocol version | Valid value |
---|---|
v3.1 & v3.2 | https://api.botframework.com/.default |
OpenID metadata document
Protocol version | Valid value |
---|---|
v3.1 & v3.2 | https://login.botframework.com/v1/.well-known/openidconfiguration |
JWT Issuer
Protocol version | Valid value |
---|---|
v3.1 & v3.2 | https://api.botframework.com |
OAuth login URL
Protocol version | Valid value |
---|---|
v3.1 & v3.2 | https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token |
OAuth scope
Protocol version | Valid value |
---|---|
v3.1 & v3.2 | Your bot's Microsoft App ID + /.default |
JWT Audience
Protocol version | Valid value |
---|---|
v3.1 & v3.2 | Your bot's Microsoft App ID |
JWT Issuer
Protocol version | Valid value |
---|---|
v3.1 1.0 | https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/ |
v3.1 2.0 | https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0 |
v3.2 1.0 | https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/ |
v3.2 2.0 | https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0 |
See also the highlighted values for non governmental cases.
OpenID metadata document
Protocol version | Valid value |
---|---|
v3.1 & v3.2 | https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration |
Additional resources
- 登录 发表评论
- 4 次浏览
最新内容
- 11 hours 37 minutes ago
- 13 hours 54 minutes ago
- 14 hours ago
- 3 days 5 hours ago
- 3 days 13 hours ago
- 3 days 13 hours ago
- 3 days 13 hours ago
- 3 days 14 hours ago
- 1 week ago
- 1 week ago