Bot Framework 인증 문제 해결Troubleshooting Bot Framework authentication

적용 대상: SDK v4APPLIES TO: SDK v4

이 가이드를 통해 일련의 시나리오를 평가하여 문제의 위치를 확인하는 방식으로 봇 관련 인증 문제를 해결할 수 있습니다.This guide can help you to troubleshoot authentication issues with your bot by evaluating a series of scenarios to determine where the problem exists.

참고

이 가이드의 모든 단계를 완료하려면 Bot Framework Emulator 다운로드하여 사용해야 하며 Azure Portal 봇의 등록 설정에 액세스할 수 있어야 합니다.To complete all steps in this guide, you will need to download and use the Bot Framework Emulator and must have access to the bot's registration settings in the Azure portal.

앱 ID 및 암호App ID and password

봇 보안은 Bot Framework에 봇을 등록할 때 받은 Microsoft 앱 IDMicrosoft 앱 암호 를 통해 구성됩니다.Bot security is configured by the Microsoft App ID and Microsoft App Password that you obtain when you register your bot with the Bot Framework. 일반적으로 이러한 값은 봇의 구성 파일 내에서 지정되고 Microsoft 계정 서비스에서 액세스 토큰을 검색하는 데 사용됩니다.These values are typically specified within the bot's configuration file and used to retrieve access tokens from the Microsoft Account service.

아직 수행하지 않은 경우 Azure에 봇을 배포하여 인증에 사용할 수 있는 Microsoft 앱 ID 및 Microsoft 앱 암호를 얻습니다.If you have not yet done so, deploy your bot to Azure to obtain a Microsoft App ID and Microsoft App Password that it can use for authentication.

참고

이미 배포된 봇의 AppIDAppPassword 를 찾으려면 MicrosoftAppID 및 MicrosoftAppPassword를 참조하세요.To find your bot's AppID and AppPassword for an already deployed bot, see MicrosoftAppID and MicrosoftAppPassword.

1단계: localhost에서 보안 및 테스트 사용 안 함Step 1: Disable security and test on localhost

이 단계에서는 보안이 사용되지 않을 경우 봇이 localhost에서 액세스 가능하고 작동하는지 확인합니다.In this step, you will verify that your bot is accessible and functional on localhost when security is disabled.

경고

봇에 대한 보안을 사용하지 않으면 알 수 없는 공격자가 사용자를 가장할 수 있습니다.Disabling security for your bot may allow unknown attackers to impersonate users. 보호된 디버깅 환경에서 운영 중인 경우에만 다음 절차를 구현합니다.Only implement the following procedure if you are operating in a protected debugging environment.

보안 사용 안 함Disable security

봇에 대한 보안을 사용하지 않으려면 해당 구성 설정을 편집하여 앱 ID 및 암호의 값을 제거합니다.To disable security for your bot, edit its configuration settings to remove the values for app ID and password.

.NET용 Bot Framework SDK를 사용하는 경우 파일의 appsettings.js 설정을 추가하거나 편집합니다.If you're using the Bot Framework SDK for .NET, add or edit the settings in your appsettings.json file:

  "MicrosoftAppId": "",
  "MicrosoftAppPassword": ""

localhost에서 봇 테스트Test your bot on localhost

그런 다음, Bot Framework Emulator를 사용하여 localhost에서 봇을 테스트합니다.Next, test your bot on localhost by using the Bot Framework Emulator.

  1. localhost에서 봇을 시작합니다.Start your bot on localhost.
  2. Bot Framework Emulator를 시작합니다.Start the Bot Framework Emulator.
  3. Emulator 사용하여 봇에 커넥트.Connect to your bot using the Emulator.
    • http://localhost:port-number/api/messagesEmulator 주소 표시줄에 를 입력합니다. 여기서 포트 번호는 애플리케이션이 실행 중인 브라우저에 표시된 포트 번호와 일치합니다.Type http://localhost:port-number/api/messages into the Emulator's address bar, where port-number matches the port number shown in the browser where your application is running.
    • Microsoft 앱 IDMicrosoft 앱 암호 필드가 둘 다 비어 있는지 확인합니다.Ensure that the Microsoft App ID and Microsoft App Password fields are both empty.
    • 연결 을 클릭합니다.Click Connect.
  4. 봇에 대한 연결을 테스트하려면 Emulator 텍스트를 입력하고 Enter 키를 누릅니다.To test connectivity to your bot, type some text into the Emulator and press Enter.

봇이 입력에 응답하고 채팅 창에 오류가 없으면 보안이 사용되지 않을 때 봇이 localhost에서 액세스 가능하고 작동함을 확인했습니다.If the bot responds to the input and there are no errors in the chat window, you have verified that your bot is accessible and functional on localhost when security is disabled. 2단계로 진행합니다.Proceed to Step 2.

채팅 창에서 하나 이상의 오류가 표시되면 오류를 클릭하여 자세한 내용을 확인합니다.If one or more error(s) are indicated in the chat window, click the error(s) for details. 일반적인 문제는 다음과 같습니다.Common issues include:

  • Emulator 설정은 봇에 대한 잘못된 엔드포인트를 지정합니다.The Emulator settings specify an incorrect endpoint for the bot. URL에 적절한 포트 번호를 포함하고 URL 끝에 적절한 경로를 포함했는지 확인합니다(예: /api/messages).Make sure you have included the proper port number in the URL and the proper path at the end of the URL (e.g., /api/messages).
  • Emulator 설정은 로 시작하는 봇 엔드포인트를 https 지정합니다.The Emulator settings specify a bot endpoint that begins with https. Localhost에서 엔드포인트는 http로 시작해야 합니다.On localhost, the endpoint should begin with http.
  • Emulator 설정은 Microsoft 앱 ID 필드 및/또는 Microsoft 앱 암호 필드의 값을 지정합니다.The Emulator settings specify a value for the Microsoft App ID field and/or the Microsoft App Password field. 두 필드가 모두 비어 있어야 합니다.Both fields should be empty.
  • 봇의 보안이 사용하지 않도록 설정되지 않았습니다.Security has not been disabled of for the bot. 봇이 앱 ID 또는 암호의 값을 지정하지 않았는지 확인합니다.Verify that the bot does not specify a value for either app ID or password.

2단계: 봇의 앱 ID 및 암호 확인Step 2: Verify your bot's app ID and password

이 단계에서는 봇이 인증에 사용할 앱 ID 및 암호가 유효한지 확인합니다.In this step, you will verify that the app ID and password that your bot will use for authentication are valid. (이러한 값을 모르는 경우, 지금 값을 가져옵니다.)(If you do not know these values, obtain them now.)

경고

다음 지침은 login.microsoftonline.com에 대한 SSL 확인을 사용하지 않도록 설정합니다.The following instructions disable SSL verification for login.microsoftonline.com. 이 절차는 보안 네트워크에서만 수행하고 이후 애플리케이션의 암호를 변경하는 것이 좋습니다.Only perform this procedure on a secure network and consider changing your application's password afterward.

Microsoft 로그인 서비스에 대한 HTTP 요청 실행Issue an HTTP request to the Microsoft login service

이러한 지침은 cURL을 사용하여 Microsoft 로그인 서비스에 대한 HTTP 요청을 실행하는 방법을 설명합니다.These instructions describe how to use cURL to issue an HTTP request to the Microsoft login service. Postman과 같은 대체 도구를 사용할 수 있습니다. 요청이 Bot Framework 인증 프로토콜을 따르는지만 확인하세요.You may use an alternative tool such as Postman, just ensure that the request conforms to the Bot Framework authentication protocol.

봇의 앱 ID 및 암호가 유효한지 확인하려면 APP_IDAPP_PASSWORD를 봇의 앱 ID 및 암호로 바꾸고 cURL 을 사용하여 다음 요청을 실행합니다.To verify that your bot's app ID and password are valid, issue the following request using cURL, replacing APP_ID and APP_PASSWORD with your bot's app ID and password.

암호에 다음 호출을 무효화하는 특수 문자가 포함될 수 있습니다.Your password may contain special characters that make the following call invalid. 이 경우 암호를 URL 인코딩으로 변환합니다.If so, try converting your password to URL encoding.

curl -k -X POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token -d "grant_type=client_credentials&client_id=APP_ID&client_secret=APP_PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default"

이 요청의 목적은 액세스 토큰에 대한 봇의 앱 ID 및 암호를 교환하는 것입니다.This request attempts to exchange your bot's app ID and password for an access token. 요청에 성공하면 무엇보다 access_token 속성이 포함된 JSON 페이로드를 받게 됩니다.If the request is successful, you will receive a JSON payload that contains an access_token property, amongst others.

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAJKV1Q..."}

요청에 성공하면 요청에서 지정한 앱 ID 및 암호가 유효한 것을 확인했습니다.If the request is successful, you have verified that the app ID and password that you specified in the request are valid. 3단계로 진행합니다.Proceed to Step 3.

요청에 대한 응답으로 오류가 표시되면 응답을 검사하여 오류의 원인을 확인합니다.If you receive an error in response to the request, examine the response to identify the cause of the error. 응답이 앱 ID 또는 암호가 잘못되었다고 나타내면 Bot Framework 포털에서 올바른 값을 가져오고 새 값으로 요청을 실행하여 값이 유효한지 확인합니다.If the response indicates that the app ID or the password is invalid, obtain the correct values from the Bot Framework Portal and re-issue the request with the new values to confirm that they are valid.

3단계: localhost에서 보안 및 테스트 사용Step 3: Enable security and test on localhost

현재 보안이 사용되지 않을 때 봇이 localhost에서 액세스 가능하고 작동함을 확인했고 봇이 인증에 사용할 앱 ID 및 암호가 유효한 것을 확인했습니다.At this point, you have verified that your bot is accessible and functional on localhost when security is disabled and confirmed that the app ID and password that the bot will use for authentication are valid. 이 단계에서는 보안이 사용될 경우 봇이 localhost에서 액세스 가능하고 작동하는지 확인합니다.In this step, you will verify that your bot is accessible and functional on localhost when security is enabled.

보안 사용Enable security

봇이 localhost에서만 실행되는 경우에도 봇의 보안은 Microsoft 서비스를 사용합니다.Your bot's security relies on Microsoft services, even when your bot is running only on localhost. 봇에 대한 보안을 사용하려면 해당 구성 설정을 편집하여 2단계에서 확인한 값으로 앱 ID 및 암호를 채웁니다.To enable security for your bot, edit its configuration settings to populate app ID and password with the values that you verified in Step 2. 또한 패키지, 특히 System.IdentityModel.Tokens.JwtMicrosoft.IdentityModel.Tokens를 최신 상태로 유지합니다.Additionally, make sure your packages are up to date, specifically System.IdentityModel.Tokens.Jwt and Microsoft.IdentityModel.Tokens.

.NET용 Bot Framework SDK를 사용 중인 경우 appsettings.config 파일에서 다음 설정을 채우거나 appsettings.json 파일에서 해당 값을 채웁니다.If you're using the Bot Framework SDK for .NET, populate these settings in your appsettings.config or the corresponding values in your appsettings.json file:

<appSettings>
  <add key="MicrosoftAppId" value="APP_ID" />
  <add key="MicrosoftAppPassword" value="PASSWORD" />
</appSettings>

Node.js용 Bot Framework SDK를 사용 중인 경우 다음 설정을 채우거나 해당 환경 변수를 업데이트합니다.If you're using the Bot Framework SDK for Node.js, populate these settings (or update the corresponding environment variables):

var connector = new builder.ChatConnector({
  appId: 'APP_ID',
  appPassword: 'PASSWORD'
});

참고

봇의 AppIDAppPassword 를 찾으려면 MicrosoftAppID 및 MicrosoftAppPassword를 참조하세요.To find your bot's AppID and AppPassword, see MicrosoftAppID and MicrosoftAppPassword.

localhost에서 봇 테스트Test your bot on localhost

그런 다음, Bot Framework Emulator를 사용하여 localhost에서 봇을 테스트합니다.Next, test your bot on localhost by using the Bot Framework Emulator.

  1. localhost에서 봇을 시작합니다.Start your bot on localhost.
  2. Bot Framework Emulator를 시작합니다.Start the Bot Framework Emulator.
  3. Emulator 사용하여 봇에 커넥트.Connect to your bot using the Emulator.
    • http://localhost:port-number/api/messagesEmulator 주소 표시줄에 를 입력합니다. 여기서 포트 번호는 애플리케이션이 실행 중인 브라우저에 표시된 포트 번호와 일치합니다.Type http://localhost:port-number/api/messages into the Emulator's address bar, where port-number matches the port number shown in the browser where your application is running.
    • 봇의 앱 ID를 Microsoft 앱 ID 필드에 입력합니다.Enter your bot's app ID into the Microsoft App ID field.
    • 봇의 암호를 Microsoft 앱 암호 필드에 입력합니다.Enter your bot's password into the Microsoft App Password field.
    • 연결 을 클릭합니다.Click Connect.
  4. 봇에 대한 연결을 테스트하려면 Emulator 텍스트를 입력하고 Enter 키를 누릅니다.To test connectivity to your bot, type some text into the Emulator and press Enter.

봇이 입력에 응답하고 채팅 창에 오류가 없으면 보안이 사용될 때 봇이 localhost에서 액세스 가능하고 작동함을 확인했습니다.If the bot responds to the input and there are no errors in the chat window, you have verified that your bot is accessible and functional on localhost when security is enabled. 4단계로 진행합니다.Proceed to Step 4.

채팅 창에서 하나 이상의 오류가 표시되면 오류를 클릭하여 자세한 내용을 확인합니다.If one or more error(s) are indicated in the chat window, click the error(s) for details. 일반적인 문제는 다음과 같습니다.Common issues include:

  • Emulator 설정은 봇에 대한 잘못된 엔드포인트를 지정합니다.The Emulator settings specify an incorrect endpoint for the bot. URL에 적절한 포트 번호를 포함하고 URL 끝에 적절한 경로를 포함했는지 확인합니다(예: /api/messages).Make sure you have included the proper port number in the URL and the proper path at the end of the URL (e.g., /api/messages).
  • Emulator 설정은 로 시작하는 봇 엔드포인트를 https 지정합니다.The Emulator settings specify a bot endpoint that begins with https. Localhost에서 엔드포인트는 http로 시작해야 합니다.On localhost, the endpoint should begin with http.
  • Emulator 설정에서 Microsoft 앱 ID 필드 및/또는 Microsoft 앱 암호는 유효한 값을 포함하지 않습니다.In the Emulator settings, the Microsoft App ID field and/or the Microsoft App Password do not contain valid values. 두 필드를 모두 입력해야 하고 각 필드에는 2단계에서 확인한 해당 값을 포함해야 합니다.Both fields should be populated and each field should contain the corresponding value that you verified in Step 2.
  • 봇의 보안이 사용하도록 설정되지 않았습니다.Security has not been enabled for the bot. 봇 구성 설정이 앱 ID 및 암호의 값을 둘 다 지정하는지 확인합니다.Verify that the bot configuration settings specify values for both app ID and password.

4단계: 클라우드에서 봇 테스트 Step 4: Test your bot in the cloud

현재 보안이 사용되지 않을 때 봇이 localhost에서 액세스 가능하고 작동함을 확인했고, 봇의 앱 ID 및 암호가 유효한 것을 확인했고, 보안이 사용될 때 봇이 localhost에서 액세스 가능하고 작동함을 확인했습니다.At this point, you have verified that your bot is accessible and functional on localhost when security is disabled, confirmed that your bot's app ID and password are valid, and verified that your bot is accessible and functional on localhost when security is enabled. 이 단계에서는 봇을 클라우드에 배포하고 보안이 사용될 경우 봇이 클라우드에서 액세스 가능하고 작동하는지 확인합니다.In this step, you will deploy your bot to the cloud and verify that it is accessible and functional there with security enabled.

클라우드에 봇 배포Deploy your bot to the cloud

Bot Framework에서는 봇이 인터넷에서 액세스 가능해야 하므로, 봇을 Azure와 같은 클라우드 호스팅 플랫폼에 배포해야 합니다.The Bot Framework requires that bots be accessible from the internet, so you must deploy your bot to a cloud hosting platform such as Azure. 3단계의 설명대로 배포하기 전에 봇에 대한 보안을 사용하도록 설정해야 합니다.Be sure to enable security for your bot prior to deployment, as described in Step 3.

참고

클라우드 호스팅 공급자가 아직 없는 경우 무료 계정에 등록할 수 있습니다.If you do not already have a cloud hosting provider, you can register for a free account.

Azure에 봇을 배포하면 애플리케이션에 대한 SSL이 자동으로 구성되므로 Bot Framework에서 요구하는 HTTPS 엔드포인트를 사용할 수 있습니다.If you deploy your bot to Azure, SSL will automatically be configured for your application, thereby enabling the HTTPS endpoint that the Bot Framework requires. 다른 클라우드 호스팅 공급자에 배포할 경우에는 봇에 HTTPS 엔드포인트가 포함되도록 애플리케이션에 대한 SSL이 구성되어 있는지 확인해야 합니다.If you deploy to another cloud hosting provider, be sure to verify that your application is configured for SSL so that the bot will have an HTTPS endpoint.

봇 테스트Test your bot

보안을 사용하도록 설정하고 클라우드에서 봇을 테스트하려면 다음 단계를 수행합니다.To test your bot in the cloud with security enabled, complete the following steps.

  1. 봇이 성공적으로 배포되었고 실행 중인지 확인합니다.Ensure that your bot has been successfully deployed and is running.
  2. Azure Portal에 로그인합니다.Sign in to the Azure portal.
  3. 포털 내 봇의 Bot 채널 등록 으로 이동합니다.Navigate to the Bot Channels Registration for your bot within the portal.
  4. 왼쪽에 있는 Bot 관리 창에서 웹 채팅에서 테스트 를 클릭합니다.Click Test in Web Chat in the Bot management pane on the left.
  5. 봇에 대한 연결을 테스트하려면 웹 채팅 컨트롤에 일부 텍스트를 입력하고 Enter 키를 누릅니다.To test connectivity to your bot, type some text into the web chat control and press Enter.

채팅 창에 오류가 표시되면 오류 메시지를 사용하여 오류의 원인을 확인합니다.If an error is indicated in the chat window, use the error message to determine the cause of the error. 일반적인 문제는 다음과 같습니다.Common issues include:

  • Bot Framework 포털에서 봇에 대한 설정 페이지에 지정된 메시징 엔드포인트 가 올바르지 않습니다.The Messaging endpoint specified on the Settings page for your bot in the Bot Framework Portal is incorrect. URL 끝에 적절한 경로를 포함했는지 확인합니다(예: /api/messages).Make sure you have included the proper path at the end of the URL (e.g., /api/messages).
  • Bot Framework 포털에서 봇에 대한 설정 페이지에 지정된 메시징 엔드포인트https로 시작되지 않거나 Bot Framework에서 신뢰하는 엔드포인트가 아닙니다.The Messaging endpoint specified on the Settings page for your bot in the Bot Framework Portal does not begin with https or is not trusted by the Bot Framework. 봇에는 유효한 체인에서 신뢰할 수 있는 인증서가 있어야 합니다.Your bot must have a valid, chain-trusted certificate.
  • 앱 ID 또는 암호의 값이 잘못되거나 누락된 상태로 봇이 구성되어 있습니다.The bot is configured with missing or incorrect values for app ID or password. 봇 구성 설정이 앱 ID 및 암호의 유효한 값을 지정하는지 확인합니다.Verify that the bot configuration settings specify valid values for app ID and password.

봇이 입력에 적절하게 응답하는 경우 보안을 사용하도록 설정하고 봇이 클라우드에서 액세스 가능하고 작동함을 확인했습니다.If the bot responds appropriately to the input, you have verified that your bot is accessible and functional in the cloud with security enabled. 이때 봇은 Facebook Messenger, Direct Line 등의 채널에 안전하게 연결할 수 있습니다.At this point, your bot is ready to securely connect to a channel such as Facebook Messenger, Direct Line, and others.

추가 리소스Additional resources

위의 단계를 완료한 후에도 문제가 계속 발생하는 경우, 다음을 수행할 수 있습니다.If you are still experiencing issues after completing the steps above, you can:

  • 봇을 디버그하는 방법 및 해당 섹션의 다른 디버깅 문서를 검토합니다.Review how-to debug a bot and the other debugging articles in that section.
  • Bot Framework Emulator 및 ngrok 터널링 소프트웨어를 사용하여 클라우드에서 봇을 디버그합니다.Debug your bot in the cloud using the Bot Framework Emulator and ngrok tunneling software. ngrok는 Microsoft 제품이 아닙니다.ngrok is not a Microsoft product.
  • Fiddler 같은 프록시 도구를 사용하여 봇에서 보내고 받는 HTTPS 트래픽을 검사합니다.Use a proxying tool like Fiddler to inspect HTTPS traffic to and from your bot. Fiddler는 Microsoft 제품이 아닙니다.Fiddler is not a Microsoft product.
  • Bot Framework가 사용하는 인증 기술을 알아보려면 Bot Connector 인증 가이드를 검토하세요.Review the Bot Connector authentication guide to learn about the authentication technologies that the Bot Framework uses.
  • Bot Framework 지원 리소스를 사용하여 다른 사용자에게 도움을 요청합니다.Solicit help from others by using the Bot Framework support resources.