Bot Connector API를 통한 인증Authentication with the Bot Connector API

봇은 보안된 채널(SSL/TLS)의 HTTP를 통해 Bot Connector 서비스와 통신합니다.Your bot communicates with the Bot Connector service using HTTP over a secured channel (SSL/TLS). 봇이 Connector 서비스에 요청을 보낼 때는 Connector 서비스가 ID 확인에 사용할 수 있는 정보를 포함해야 합니다.When your bot sends a request to the Connector service, it must include information that the Connector service can use to verify its identity. 마찬가지로 Connector 서비스가 봇에 요청을 보낼 때는 봇이 ID 확인에 사용할 수 있는 정보를 포함해야 합니다.Likewise, when the Connector service sends a request to your bot, it must include information that the bot can use to verify its identity. 이 문서에서는 봇과 Bot Connector 서비스 간에 발생하는 서비스 수준 인증을 위한 인증 기술과 요구 사항에 대해 설명합니다.This article describes the authentication technologies and requirements for the service-level authentication that takes place between a bot and the Bot Connector service. 자체 인증 코드를 작성한다면 이 문서에서 설명하는 보안 절차를 구현하여 봇이 Bot Connector 서비스와의 메시지 교환을 사용하도록 설정해야 합니다.If you are writing your own authentication code, you must implement the security procedures described in this article to enable your bot to exchange messages with the Bot Connector service.

중요

자체 인증 코드를 작성할 경우 모든 보안 절차를 정확하게 구현하는 것이 중요합니다.If you are writing your own authentication code, it is critical that you implement all security procedures correctly. 이 문서의 모든 단계를 구현하면 공격자가 봇에게 전송된 메시지를 읽고 봇을 가장하는 메시지를 보내고 비밀 키를 도용하는 위험을 줄일 수 있습니다.By implementing all steps in this article, you can mitigate the risk of an attacker being able to read messages that are sent to your bot, send messages that impersonate your bot, and steal secret keys.

.NET용 Bot Framework SDK 또는 Node.js용 Bot Framework SDK를 사용할 경우 SDK가 자동으로 작업을 수행하므로 이 문서의 보안 절차를 실행할 필요가 없습니다.If you are using the Bot Framework SDK for .NET or the Bot Framework SDK for Node.js, you do not need to implement the security procedures described in this article, because the SDK automatically does it for you. 등록 중에 봇에 대해 얻은 앱 ID와 암호로 프로젝트를 구성하기만 하면 SDK가 나머지를 처리합니다.Simply configure your project with the App ID and password that you obtained for your bot during registration and the SDK will handle the rest.

경고

2016년 12월에 Bot Framework 보안 프레임워크 v3.1이 도입되어 토큰 생성 및 유효성 검사 중에 사용되는 몇 가지 값에 대한 변경이 있었습니다.In December 2016, v3.1 of the Bot Framework security protocol introduced changes to several values that are used during token generation and validation. 2017년 늦가을에 토큰 생성 및 유효성 검사 중에 사용되는 값에 대한 변경 내용을 포함하는 Bot Framework 보안 프로토콜 v3.2가 도입되었습니다.In late fall of 2017, v3.2 of the Bot Framework security protocol was introduced which included changes to values that are used during token generation and validation. 자세한 내용은 보안 프로토콜 변경 내용을 참조하세요.For more information, see Security protocol changes.

인증 기술Authentication technologies

봇과 Bot Connector 간에 신뢰를 설정하는 데는 4가지 인증 기술이 사용됩니다.Four authentication technologies are used to establish trust between a bot and the Bot Connector:

기술Technology DescriptionDescription
SSL/TLSSSL/TLS SSL/TLS는 모든 서비스 간 연결에 사용됩니다.SSL/TLS is used for all service-to-service connections. X.509v3 인증서는 모든 HTTPS 서비스의 ID를 설정하는 데 사용됩니다.X.509v3 certificates are used to establish the identity of all HTTPS services. 클라이언트는 항상 서비스 인증서가 신뢰할 수 있고 유효한지 검사해야 합니다.Clients should always inspect service certificates to ensure they are trusted and valid. 클라이언트 인증서는 이 스키마의 일부로 사용되지 않습니다.(Client certificates are NOT used as part of this scheme.)
OAuth 2.0OAuth 2.0 OAuth 2.0은 Azure AD(Azure Active Directory) v2 계정 로그인 서비스를 사용하여 봇에서 메시지를 보내는 데 사용할 수 있는 보안 토큰을 생성합니다.OAuth 2.0 uses the Azure Active Directory (Azure AD) v2 account login service to generate a secure token that a bot can use to send messages. 이 토큰은 서비스 간 토큰으로, 사용자 로그인이 필요하지 않습니다.This token is a service-to-service token; no user login is required.
JWT(JSON 웹 토큰)JSON Web Token (JWT) JSON 웹 토큰은 봇으로 오고 간 토큰을 인코딩하는 데 사용됩니다.JSON Web Tokens are used to encode tokens that are sent to and from the bot. 이 문서에서 설명한 요구 사항에 따라 클라이언트는 수신한 모든 JWT 토큰 을 완전히 확인해야 합니다.Clients should fully verify all JWT tokens that they receive, according to the requirements outlined in this article.
OpenID 메타데이터OpenID metadata Bot Connector 서비스는 잘 알려진 정적 엔드포인트에서 OpenID 메타데이터에 대한 자체 JWT 토큰을 서명하는 데 사용하는 유효한 토큰 목록을 게시합니다.The Bot Connector service publishes a list of valid tokens that it uses to sign its own JWT tokens to OpenID metadata at a well-known, static endpoint.

이 문서에서는 표준 HTTPS 및 JSON을 통해 이러한 기술을 사용하는 방법을 설명합니다.This article describes how to use these technologies via standard HTTPS and JSON. OpenID 도우미 등이 유용할 수는 있지만 특수한 SDK가 필요하지 않습니다.No special SDKs are required, although you may find that helpers for OpenID etc. are useful.

봇에서 Bot Connector 서비스에 대한 요청 인증Authenticate requests from your bot to the Bot Connector service

Bot Connector Service와 통신하려면 다음 형식을 사용하여 각 API 요청의 Authorization 헤더에 액세스 토큰을 지정해야 합니다.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

이 다이어그램에서는 봇-커넥터 인증의 단계를 보여 줍니다.This diagram shows the steps for bot-to-connector authentication:

MSA 로그인 서비스와 봇에 대해 차례로 인증

1단계: Azure AD v2 로그인 서비스에서 액세스 토큰 요청Step 1: Request an access token from the Azure AD v2 account login service

중요

아직 수행하지 않은 경우 Bot Framework에 봇을 등록하여 해당 AppID 및 암호를 가져와야 합니다.If you have not already done so, you must register your bot with the Bot Framework to obtain its AppID and password. 액세스 토큰을 요청하려면 봇의 앱 ID와 암호가 필요합니다.You need the bot's App ID and password to request an access token.

로그인 서비스에서 액세스 토큰을 요청하려면 다음 요청을 실행하여 MICROSOFT-APP-ID의MICROSOFT-APP-PASSWORD 를 Bot Framework에 봇을 등록할 때 획득한 봇의 AppID 및 암호로 바꿉니다.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 Framework.

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%2Fapi.botframework.com%2F.default

2단계: Azure AD v2 계정 로그인 서비스 응답에서 JWT 토큰 가져오기Step 2: Obtain the JWT token from the the Azure AD v2 account login service response

로그인 서비스에서 권한을 애플리케이션에 부여하면 JSON 응답 본문에 액세스 토큰, 해당 형식 및 만료 시간(초)이 지정됩니다.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).

토큰을 요청의 Authorization 헤더에 추가할 때는 이 응답에 지정된 정확한 값을 사용해야 합니다(즉 이스케이프하지 않거나 토큰 값을 인코딩하지 않음).When adding the token to the Authorization header of a request, you must use the exact value that is specified in this response (i.e., do not 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.

다음 예제에서는 Azure AD v2 계정 로그인 서비스로부터의 응답을 보여 줍니다.This example shows a response from the the Azure AD v2 account login service:

HTTP/1.1 200 OK
... (other headers)
{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

3단계: 요청의 인증 헤더에 JWT 토큰 지정Step 3: Specify the JWT token in the Authorization header of requests

Bot Connector 서비스에 API 요청을 보낼 때 다음 형식을 사용하여 요청의 Authorization 헤더에 액세스 토큰을 지정합니다.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

Bot Connector 서비스에 보내는 모든 요청은 Authorization 헤더에 액세스 토큰을 포함해야 합니다.All requests that you send to the Bot Connector service must include the access token in the Authorization header. 토큰이 올바르게 구성되고, 만료되지 않았으며, Azure AD v2 계정 로그인 서비스에서 생성되었으면 Bot Connector 서비스에서 권한을 해당 요청에 부여합니다.If the token is correctly formed, is not expired, and was generated by the the Azure AD v2 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.

다음 예제에서는 요청의 Authorization 헤더에서 액세스 토큰을 지정하는 방법을 보여 줍니다.The following example shows how to specify the access token in the Authorization header of the request.

POST https://smba.trafficmanager.net/apis/v3/conversations/12345/activities
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

(JSON-serialized Activity message goes here)

중요

사용자가 Bot Connector 서비스에 보낸 요청의 Authorization 헤더에만 JWT 토큰을 지정합니다.Only specify the JWT token in the Authorization header of requests you send to the Bot Connector service. 보안되지 않은 채널을 통해 토큰을 보내거나 다른 서비스로 보낸 HTTP 요청에 토큰을 포함하지 않아야 합니다.Do NOT send the token over unsecured channels and do NOT include it in HTTP requests that you send to other services. Azure AD v2 계정 로그인 서비스에서 가져온 JWT 토큰은 암호와 비슷하며 매우 신중하게 처리해야 합니다.The JWT token that you obtain from the the Azure AD v2 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.

커넥터에 대한 봇: JWT 구성 요소 예제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
}

참고

현실에서는 실제 필드가 다를 수 있습니다.Actual fields may vary in practice. 위에서 지정한 대로 모든 JWT 토큰을 만들고 그 유효성을 검사합니다.Create and validate all JWT tokens as specified above.

Bot Connector 서비스에서 봇에 대한 요청 인증Authenticate requests from the Bot Connector service to your bot

Bot Connector 서비스가 봇에 요청을 보낼 때는 요청의 Authorization 헤더에 서명된 JWT 토큰을 지정합니다.When the Bot Connector service sends a request to your bot, it specifies a signed JWT token in the Authorization header of the request. 봇은 서명된 JWT 토큰의 인증을 확인하여 Bot Connector 서비스로부터의 호출을 인증할 수 있습니다.Your bot can authenticate calls from the Bot Connector service by verifying the authenticity of the signed JWT token.

이 다이어그램에서는 커넥터-봇 인증의 단계를 보여 줍니다.This diagram shows the steps for connector-to-bot authentication:

Bot Connector에서 봇에 대한 호출 인증

2단계: OpenID 메타데이터 문서 가져오기Step 2: Get the OpenID metadata document

OpenID 메타데이터 문서는 Bot Connector 서비스의 유효한 서명 키를 나열하는 두 번째 문서의 위치를 지정합니다.The OpenID metadata document specifies the location of a second document that lists the Bot Connector service's valid signing keys. OpenID 메타데이터 문서를 가져오려면 HTTPS를 통해 이 요청을 실행합니다.To get the OpenID metadata document, issue this request via HTTPS:

GET https://login.botframework.com/v1/.well-known/openidconfiguration

이것은 애플리케이션에 하드 코딩할 수 있는 정적 URL입니다.This is a static URL that you can hardcode into your application.

다음 예제에서는 GET 요청에 대한 응답으로 반환되는 OpenID 메타데이터 문서를 보여 줍니다.The following example shows an OpenID metadata document that is returned in response to the GET request. jwks_uri 속성은 Bot Connector 서비스의 유효한 서명 키가 포함된 문서의 위치를 지정합니다.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"
    ]
}

3단계: 유효한 서명 키 목록 가져오기Step 3: Get the list of valid signing keys

유효한 서명 키의 목록을 가져오려면 OpenID 메타데이터 문서에서 jwks_uri 속성이 지정한 URL에 대한 HTTPS를 통해 GET 요청을 실행합니다.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

응답 본문이 JWK 형식으로 문서를 지정하지만 각 키에 대한 추가 속성 endorsements도 포함합니다.The response body specifies the document in the JWK format but also includes an additional property for each key: endorsements.

키 목록은 안정적이며 캐시될 수 있지만 언제든지 새 키를 추가할 수 있습니다.The list of keys is stable and may be cached, but new keys may be added at any time. 이러한 키를 사용하기 전에 봇에 문서의 최신 복사본이 있는지 확인하려면 모든 봇 인스턴스가 적어도 24시간마다 한 번 문서의 로컬 캐시를 새로 고쳐야 합니다.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.

각 키 안의 endorsements 속성은 들어오는 요청의 Activity 개체 내 channelId 속성에서 지정한 채널 ID가 진짜인지 확인하는 데 사용할 수 있는 하나 이상의 인증 문자열을 포함합니다.The endorsements property within each key contains one or more endorsement strings which you can use to verify that the channel ID specified in the channelId property within the Activity object of the incoming request is authentic. 인증이 필요한 채널 ID 목록은 각 봇 안에서 구성할 수 있습니다.The list of channel IDs that require endorsements is configurable within each bot. 봇 개발자가 선택한 채널 ID 값을 어떤 식으로든 재정의할 수는 있지만 기본적으로 모든 게시된 채널 ID의 목록입니다.By default, it will be the list of all published channel IDs, although bot developers may override selected channel ID values either way.

4단계: JWT 토큰 확인Step 4: Verify the JWT token

Bot Connector 서비스에서 보낸 토큰의 신뢰성을 확인하려면 요청의 Authorization 헤더에서 토큰을 추출하고 구문 분석하여 그 콘텐츠와 서명을 확인해야 합니다.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 구문 분석 라이브러리는 일반적으로 특정 토큰 문자(발급자, 대상 등)가 정확한 값을 포함하도록 요구하기 위해 이 라이브러리를 구성해야 하기는 하지만, 여러 폴랫폼에 사용할 수 있고 대부분은 JWT 토큰을 위한 안전하고 믿을 수 있는 구문 분석을 구현합니다.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, etc.) 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:

  1. 토큰이 HTTP Authorization 헤더에서 "Bearer" 스키마로 전송되었습니다.The token was sent in the HTTP Authorization header with "Bearer" scheme.
  2. 토큰이 JWT 표준에 부합하는 유효한 JSON입니다.The token is valid JSON that conforms to the JWT standard.
  3. 토큰이 값이 https://api.botframework.com인 "issuer" 클레임을 포함합니다.The token contains an "issuer" claim with value of https://api.botframework.com.
  4. 토큰이 봇의 Microsoft 앱 ID와 동일한 값을 갖는 "audience" 클레임을 포함합니다.The token contains an "audience" claim with a value equal to the bot's Microsoft App ID.
  5. 토큰이 유효 기간 범위 안에 있습니다.The token is within its validity period. 업계 표준 클록 오차는 5분입니다.Industry-standard clock-skew is 5 minutes.
  6. 토큰이 2단계에서 검색한 Open ID 메타데이터의 id_token_signing_alg_values_supported 속성에서 지정한 서명 알고리즘을 사용하여 3단계에서 검색한 OpenID 키 문서에 나열된 키와 유효한 암호화 서명을 갖습니다.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.
  7. 토큰이 들어오는 요청의 Activity 개체 루트에서 serviceUrl 속성과 일치하는 값과 "serviceUrl" 클레임을 포함합니다.The token contains a "serviceUrl" claim with value that matches the serviceUrl property at the root of the Activity object of the incoming request.

채널 ID에 대한 인증 필요한 경우If endorsement for a channel ID is required:

  • 이 채널 ID로 봇에 전송된 모든 Activity 개체에는 해당 채널에 대한 인증을 통해 서명된 JWT 토큰이 함께 있도록 요구해야 합니다.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.
  • 인증이 없으면 봇은 HTTP 403(금지 됨) 상태 코드를 반환하여 요청을 거부해야 합니다.If the endorsement is not present, your bot should reject the request by returning an HTTP 403 (Forbidden) status code.

중요

이 요구 사항은 모두 중요하며 특히 4와 6번 요구 사항이 중요합니다.All of these requirements are important, particularly requirements 4 and 6. 이러한 인증 요구 사항을 하나라도 구현하지 못하면 봇이 JWT 토큰을 공개할 수 있는 공격에 노출됩니다.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.

구현자는 봇으로 전송되는 JWT 토큰의 유효성 검사를 비활성화하는 방법을 노출해서는 안 됩니다.Implementers should not expose a way to disable validation of the JWT token that is sent to the bot.

봇에 대한 커넥터: JWT 구성 요소 예제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
}

참고

현실에서는 실제 필드가 다를 수 있습니다.Actual fields may vary in practice. 위에서 지정한 대로 모든 JWT 토큰을 만들고 그 유효성을 검사합니다.Create and validate all JWT tokens as specified above.

Bot Framework Emulator에서 봇에 대한 요청 인증Authenticate requests from the Bot Framework Emulator to your bot

경고

2017년 늦가을에 Bot Framework 보안 프로토콜 v3.2가 발표되었습니다.In late fall of 2017, v3.2 of the Bot Framework security protocol was introduced. 이 새 버전에는 Bot Framework Eumaltor와 봇 간에 교환되는 토큰 내에 새 "issuer" 값이 포함됩니다.This new version includes a new "issuer" value within tokens that are exchanged between the Bot Framework Eumaltor and your bot. 이러한 변경에 대비하여 아래 단계에서는 v3.1 및 v3.2 발급자 값을 모두 확인하는 방법을 간략하게 설명합니다.To prepare for this change, the below steps outline how to check for both the v3.1 and v3.2 issuer values.

Bot Framework Emulator는 봇 기능 테스트에 사용할 수 있는 데스크톱 도구입니다.The Bot Framework Emulator is a desktop tool that you can use to test the functionality of your bot. Bot Framework Emulator가 앞에서 설명한 것과 같은 인증 기술을 사용하더라도 실제 Bot Connector 서비스를 가장하는 것은 불가능합니다.Although the Bot Framework Emulator uses the same authentication technologies as described above, it is unable to impersonate the real Bot Connector service. 대신, 사용자가 봇에 에뮬레이터를 연결 하 여 지정한 Microsoft 앱 ID 및 Microsoft 앱 암호를 사용 하 여 봇과 동일한 토큰을 만듭니다.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. 에뮬레이터가 사용자의 봇에 요청을 보내면 요청을 Authorization 인증 하는 데 봇의 자체 자격 증명을 사용 하 여 요청 헤더에 JWT 토큰을 지정 합니다.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.

인증 라이브러리를 구현하고 Bot Framework Emulator의 요청을 수락하려면 이 추가적인 인증 경로를 추가해야 합니다.If you are implementing an authentication library and want to accept requests from the Bot Framework Emulator, you must add this additional verification path. 경로는 커넥터 > 봇 확인 경로와 구조적으로 유사 하지만 봇 커넥터의 openid connect 문서 대신 MSA의 openid connect 문서를 사용 합니다.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.

다음 다이어그램에서는 에뮬레이터-봇 인증 단계를 보여 줍니다.This diagram shows the steps for Emulator-to-bot authentication:

Bot Framework Emulator에서 봇에 대한 호출 인증


2단계: MSA OpenID 메타데이터 문서 가져오기Step 2: Get the MSA OpenID metadata document

OpenID 메타데이터 문서는 유효한 서명 키를 나열하는 두 번째 문서의 위치를 지정합니다.The OpenID metadata document specifies the location of a second document that lists the valid signing keys. MSA OpenID 메타데이터 문서를 가져오려면 HTTPS를 통해 이 요청을 실행합니다.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

다음 예제에서는 GET 요청에 대한 응답으로 반환되는 OpenID 메타데이터 문서를 보여 줍니다.The following example shows an OpenID metadata document that is returned in response to the GET request. jwks_uri 속성은 유효한 서명 키가 포함된 문서의 위치를 지정합니다.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",
    ...
}

3단계: 유효한 서명 키 목록 가져오기Step 3: Get the list of valid signing keys

유효한 서명 키의 목록을 가져오려면 OpenID 메타데이터 문서에서 jwks_uri 속성이 지정한 URL에 대한 HTTPS를 통해 GET 요청을 실행합니다.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

응답 본문은 JWK 형식으로 문서를 지정합니다.The response body specifies the document in the JWK format.

4단계: JWT 토큰 확인Step 4: Verify the JWT token

에뮬레이터에서 보낸 토큰의 신뢰성을 확인 하려면 요청 헤더에서 토큰을 추출 하 고, Authorization 토큰을 구문 분석 하 고, 내용을 확인 하 고, 서명을 확인 해야 합니다.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 구문 분석 라이브러리는 일반적으로 특정 토큰 문자(발급자, 대상 등)가 정확한 값을 포함하도록 요구하기 위해 이 라이브러리를 구성해야 하기는 하지만, 여러 폴랫폼에 사용할 수 있고 대부분은 JWT 토큰을 위한 안전하고 믿을 수 있는 구문 분석을 구현합니다.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, etc.) 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:

  1. 토큰이 HTTP Authorization 헤더에서 "Bearer" 스키마로 전송되었습니다.The token was sent in the HTTP Authorization header with "Bearer" scheme.
  2. 토큰이 JWT 표준에 부합하는 유효한 JSON입니다.The token is valid JSON that conforms to the JWT standard.
  3. 토큰은 비 정부 사례에 대해 강조 표시 된 값 중 하나가 포함 된 "발급자" 클레임을 포함 합니다.The token contains an "issuer" claim with one of the highlighted values for non governmental cases. 두 발급자 값을 모두 확인 하면 보안 프로토콜 v 3.1 및 v 3.2 발급자 값을 모두 확인 하 게 됩니다.Checking for both issuer values will ensure you are checking for both the security protocol v3.1 and v3.2 issuer values.
  4. 토큰이 봇의 Microsoft 앱 ID와 동일한 값을 갖는 "audience" 클레임을 포함합니다.The token contains an "audience" claim with a value equal to the bot's Microsoft App ID.
  5. 버전에 따라 에뮬레이터는 appid 클레임 (버전 1) 또는 인증 된 파티 클레임 (버전 2)을 통해 AppId를 보냅니다.The Emulator, depending on the version, sends the AppId via either the appid claim (version 1) or the authorized party claim (version 2).
  6. 토큰이 유효 기간 범위 안에 있습니다.The token is within its validity period. 업계 표준 클록 오차는 5분입니다.Industry-standard clock-skew is 5 minutes.
  7. 토큰이 3단계에서 검색한 OpenID 키 문서에 나열된 키와 유효한 암호화 키를 갖습니다.The token has a valid cryptographic signature with a key listed in the OpenID keys document that was retrieved in Step 3.

참고

요구 사항 5는 에뮬레이터 확인 경로에 대 한 특정입니다.Requirement 5 is a specific to the Emulator verification path.

토큰이 이 요구 사항에 일부라도 부합하지 않으면 봇은 HTTP 403(금지 됨) 상태 코드를 반환하여 요청을 종료해야 합니다.If the token does not meet all of these requirements, your bot should terminate the request by returning an HTTP 403 (Forbidden) status code.

중요

이 요구 사항은 모두 중요하며 특히 4와 7번 요구 사항이 중요합니다.All of these requirements are important, particularly requirements 4 and 7. 이러한 인증 요구 사항을 하나라도 구현하지 못하면 봇이 JWT 토큰을 공개할 수 있는 공격에 노출됩니다.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.

봇에 대한 에뮬레이터: JWT 구성 요소 예제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
}

참고

현실에서는 실제 필드가 다를 수 있습니다.Actual fields may vary in practice. 위에서 지정한 대로 모든 JWT 토큰을 만들고 그 유효성을 검사합니다.Create and validate all JWT tokens as specified above.

보안 프로토콜 변경 내용Security protocol changes

경고

보안 프로토콜 v3.0 지원이 2017년 7월 31일 중단되었습니다.Support for v3.0 of the security protocol was discontinued on July 31, 2017. 자체 인증 코드를 작성한 경우(즉 Bot Framework SDK를 사용하여 봇을 만들지 않음) 아래 목록의 v3.1 값을 사용하도록 애플리케이션을 업데이트하여 보안 프로토콜 v3.1로 업그레이드해야 합니다.If you have written your own authentication code (i.e., did not use the Bot Framework SDK to create your bot), you must upgrade to v3.1 of the security protocol by updating your application to use the v3.1 values that are listed below.

커넥터에 대한 봇 인증Bot to Connector authentication

OAuth 로그인 URLOAuth login URL

프로토콜 버전Protocol version 유효한 값Valid value
v3.1 & v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth 범위OAuth scope

프로토콜 버전Protocol version 유효한 값Valid value
v3.1 & v3.2v3.1 & v3.2 https://api.botframework.com/.default

봇에 대한 커넥터 인증Connector to Bot authentication

OpenID 메타데이터 문서OpenID metadata document

프로토콜 버전Protocol version 유효한 값Valid value
v3.1 & v3.2v3.1 & v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

JWT 발급자JWT Issuer

프로토콜 버전Protocol version 유효한 값Valid value
v3.1 & v3.2v3.1 & v3.2 https://api.botframework.com

봇에 대한 에뮬레이터 인증Emulator to Bot authentication

OAuth 로그인 URLOAuth login URL

프로토콜 버전Protocol version 유효한 값Valid value
v3.1 & v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth 범위OAuth scope

프로토콜 버전Protocol version 유효한 값Valid value
v3.1 & v3.2v3.1 & v3.2 사용자의 봇 Microsoft 앱 ID + /.defaultYour bot's Microsoft App ID + /.default

JWT 대상JWT Audience

프로토콜 버전Protocol version 유효한 값Valid value
v3.1 & v3.2v3.1 & v3.2 사용자의 봇 Microsoft 앱 IDYour bot's Microsoft App ID

JWT 발급자JWT Issuer

프로토콜 버전Protocol version 유효한 값Valid value
v 3.1 1.0v3.1 1.0 https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
v 3.1 2.0v3.1 2.0 https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v 3.2 1.0v3.2 1.0 https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
v 3.2 2.0v3.2 2.0 https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

또한 비 정부 케이스의 경우 강조 표시 된 값 을 참조 하세요.See also the highlighted values for non governmental cases.

OpenID 메타데이터 문서OpenID metadata document

프로토콜 버전Protocol version 유효한 값Valid value
v3.1 & v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

추가 리소스Additional resources