봇에 인증 추가

아티클
10/27/2023

적용 대상: SDK v4

Azure AI Bot Service v4 SDK는 사용자 인증이 필요한 온라인 리소스에 액세스할 수 있는 봇의 개발을 용이하게 합니다. Azure에서 OAuth 2.0을 사용하여 각 사용자의 자격 증명에 따라 토큰을 생성하기 때문에 봇은 인증 토큰을 관리할 필요가 없습니다. 봇은 Azure에서 생성된 토큰을 사용하여 해당 리소스에 액세스합니다. 이러한 방식으로 사용자는 보안 리소스에 액세스하기 위해 봇에 ID와 암호를 제공할 필요가 없으며 신뢰할 수 있는 ID 공급자에게만 액세스할 수 있습니다.

Bot Framework에서 이러한 종류의 인증을 처리하는 방법에 대한 개요는 사용자 인증을 참조하세요.

이 문서에서는 두 가지 샘플을 참조합니다. 하나는 인증 토큰을 가져오는 방법을 보여줍니다. 다른 하나는 더 복잡하며 사용자를 대신하여 Microsoft Graph에 액세스하는 방법을 보여줍니다. 두 경우 모두 Azure AD v1 또는 v2를 ID 공급자로 사용하여 봇에 대한 OAuth 토큰을 가져올 수 있습니다. 이 문서에서는 다음 작업을 수행하는 방법을 설명합니다.

Azure Bot 리소스 만들기
Microsoft Entra ID ID 공급자 만들기
봇에 Microsoft Entra ID ID 공급자 등록
봇 코드 준비

이 문서를 마치면 몇 가지 간단한 작업에 응답할 수 있는 봇이 있습니다. Microsoft Graph 예제에서는 전자 메일을 보내고, 현재 사용자를 표시하고, 최근 전자 메일을 검사 수 있습니다. OAuth 기능을 테스트하기 위해 봇을 게시할 필요가 없습니다. 그러나 봇에는 유효한 Azure 앱 ID 및 암호가 필요합니다.

참고 항목

Bot Framework JavaScript, C#및 Python SDK는 계속 지원되지만 Java SDK는 2023년 11월에 종료되는 최종 장기 지원으로 사용 중지됩니다.

Java SDK를 사용하여 빌드된 기존 봇은 계속 작동합니다.

새 봇 빌드의 경우 Power Virtual Agents 사용을 고려하고 올바른 챗봇 솔루션을 선택하는 방법을 읽어 보세요.

자세한 내용은 봇 빌드의 미래를 참조 하세요.

웹 채팅 및 Direct Line 고려 사항

Important

웹 채팅 컨트롤을 사용하여 봇에 연결할 때 보안 위험을 완화하기 위해 향상된 인증을 사용하도록 설정된 Direct Line을 사용해야 합니다. 자세한 내용은 Direct Line 고급 인증을 참조하세요.

필수 조건

봇 기본 사항, 상태 관리, 대화 상자 라이브러리 및 순차적 대화 흐름을 구현하는 방법 및 대화 상자를 다시 사용하는 방법에 대한 지식
Azure 및 OAuth 2.0 개발에 대한 지식
.NET용 Visual Studio 2017 이상
JavaScript용 Node.js.
Python용 Python 3.8 이상

아래에 나열된 샘플 중 하나입니다.

예제	BotBuilder 버전	시연
C# 또는 JavaScript 또는 Java 또는 Python의 인증	v4	OAuthCard 지원
C# 또는 JavaScript 또는 Java 또는 Python에서 Microsoft Graph에 대한 인증	v4	OAuth 2.0을 사용한 Microsoft Graph API 지원
C# 또는 JavaScript 또는 Java 또는 Python에서 Microsoft Teams에 대한 인증	v4	OAuth 2.0을 사용한 Microsoft Graph API 지원

이 문서에서 참조하는 샘플을 실행하려면 다음이 필요합니다.

Azure에서 봇 리소스를 등록할 Microsoft Entra ID 애플리케이션입니다. 이 애플리케이션을 사용하면 봇에서 Microsoft Graph와 같은 외부 보안 리소스에 액세스할 수 있습니다. 또한 사용자가 웹 채팅 같은 여러 채널을 통해 봇과 통신할 수 있습니다.
ID 공급자로 작동하는 별도의 Microsoft Entra ID 애플리케이션입니다. 이 애플리케이션은 봇과 보안 리소스 간에 OAuth 연결을 설정하는 데 필요한 자격 증명을 제공합니다. 이 문서에서는 Active Directory를 ID 공급자로 사용합니다. 다른 많은 공급자도 지원됩니다.

Important

Azure에 봇을 등록할 때마다 Microsoft Entra ID 애플리케이션이 할당됩니다. 그러나 이 애플리케이션은 채널-봇 액세스를 보호합니다. 봇이 사용자를 대신하여 액세스하려는 각 외부 보안 리소스에 대한 추가 Microsoft Entra ID 애플리케이션이 필요합니다.

리소스 만들기

Azure AI Bot Service에 봇을 등록할 수 있는 Azure Bot 리소스를 만듭니다.

팁

새 웹앱 봇 및 봇 채널 등록 리소스는 만들 수 없습니다. 그러나 구성되고 배포된 이러한 기존 리소스는 계속 작동합니다. SDK 버전 4.14.1.2 이상에서 VSIX 또는 Yeoman 템플릿에서 만든 봇에는 Azure Bot 리소스를 생성하는 ARM 템플릿이 포함되어 있습니다.

Azure Portal로 이동합니다.
오른쪽 창에서 리소스 만들기를 선택합니다.
검색 상자에 입력 bot한 다음 Enter 키를 누릅니 다.
Azure Bot 카드 선택합니다.
만들기를 실행합니다.
필수 필드에 값을 입력하고 설정을 검토하고 업데이트합니다.
1. 프로젝트 세부 정보 아래에 정보를 제공합니다. 봇에 전역 또는 로컬 데이터 상주 여부를 선택합니다. 현재 로컬 데이터 상주 기능은 "westeurope" 및 "centralindia" 지역의 리소스에 사용할 수 있습니다. 자세한 내용은 Azure AI Bot Service의 지역화를 참조 하세요.
2. Microsoft 앱 ID 아래에 정보를 제공합니다. Azure에서 봇 ID를 관리하는 방법과 새 ID를 만들거나 기존 ID를 사용할지 여부를 선택합니다.
검토 + 만들기를 선택합니다.
유효성 검사가 통과하면 만들기를 선택합니다.
배포가 완료되면 리소스로 이동을 선택합니다. 선택한 리소스 그룹에 나열된 봇 및 관련 리소스가 표시됩니다.
Bot Framework SDK가 아직 없는 경우 GitHub에서 다운로드를 선택하여 기본 설정 언어로 패키지를 사용하는 방법을 알아봅니다.

이제 Bot Framework SDK를 사용하여 봇을 빌드할 준비가 되었습니다.

팁

Azure에서 새 앱 ID를 사용하여 새 단일 테넌트 또는 다중 테넌트 Azure Bot 리소스를 만들면 암호도 생성됩니다.

봇 ID 정보

다음 단계에 따라 봇의 구성 파일에 ID 정보를 추가합니다. 파일은 봇을 만드는 데 사용하는 프로그래밍 언어에 따라 다릅니다.

Important

Java 버전의 Bot Framework SDK는 다중 테넌트 봇만 지원합니다. Bot Framework SDK의 Python 버전은 다중 테넌트 및 단일 테넌트 봇을 지원합니다. C# 및 JavaScript 버전은 봇의 ID를 관리하기 위한 세 가지 애플리케이션 유형을 모두 지원합니다.

언어	파일 이름	주의
C#	appsettings.json	봇의 ID를 관리하기 위한 세 가지 애플리케이션 유형을 모두 지원합니다.
JavaScript	.env	봇의 ID를 관리하기 위한 세 가지 애플리케이션 유형을 모두 지원합니다.
Java	application.properties	다중 테넌트 봇만 지원합니다.
Python	config.py	다중 테넌트 및 단일 테넌트 봇을 지원합니다. 메서드 호출에 대한 인수 `os.environ.get` 로 속성을 제공합니다.

추가해야 하는 ID 정보는 봇의 애플리케이션 유형에 따라 달라집니다. 구성 파일에 다음 값을 제공합니다.

C# 및 JavaScript 봇에만 사용할 수 있습니다.

속성	값
`MicrosoftAppType`	`UserAssignedMSI`
`MicrosoftAppId`	사용자 할당 관리 ID의 클라이언트 ID입니다.
`MicrosoftAppPassword`	해당 없음. 사용자가 할당한 관리 ID 봇에 대해 이 값을 비워 둡니다.
`MicrosoftAppTenantId`	사용자 할당 관리 ID의 테넌트 ID입니다.

C#, JavaScript 및 Python 봇에만 사용할 수 있습니다.

속성	값
`MicrosoftAppType`	`SingleTenant`
`MicrosoftAppId`	봇의 앱 ID입니다.
`MicrosoftAppPassword`	봇의 앱 암호입니다.
`MicrosoftAppTenantId`	봇의 앱 테넌트 ID입니다.

C#, JavaScript, Java 및 Python과 같은 모든 프로그래밍 언어의 봇에 사용할 수 있습니다.

속성	값
`MicrosoftAppType`	`MultiTenant`
`MicrosoftAppId`	봇의 앱 ID입니다.
`MicrosoftAppPassword`	봇의 앱 암호입니다.
`MicrosoftAppTenantId`	해당 없음. 다중 테넌트 봇의 경우 이 값을 비워 둡니다.

앱 서비스를 업데이트하려면

봇에 대한 기존 App Service 리소스(웹앱)가 있고 봇이 사용자 할당 관리 ID 애플리케이션인 경우 봇의 앱 서비스를 업데이트해야 할 수 있습니다.

봇의 웹앱에 대한 App Service 블레이드로 이동합니다.
설정에서 ID를 선택합니다.
ID 블레이드에서 사용자 할당 탭을 선택하고 추가(+)를 선택합니다.
사용자 할당 관리 ID 추가 블레이드에서 다음을 수행합니다 .
1. 구독을 선택합니다.
2. 사용자가 할당한 관리 ID의 경우 봇의 관리 ID를 선택합니다. 관리 ID가 자동으로 생성된 경우 봇과 동일한 이름을 갖습니다.
3. 추가를 선택하여 봇에 이 ID를 사용합니다.

앱 또는 테넌트 ID를 가져오려면

봇의 앱 또는 테넌트 ID를 가져오려면 다음을 수행합니다.

봇에 대한 Azure Bot 리소스 블레이드로 이동합니다.
봇의 구성 블레이드로 이동합니다. 이 블레이드에서 봇의 Microsoft 앱 ID 또는 앱 테넌트 ID를 복사할 수 있습니다.

새 암호를 생성하려면

단일 테넌트 및 다중 테넌트 봇에는 일부 작업에 필요한 앱 비밀 또는 암호가 있습니다. Azure AI Bot Service는 봇 비밀을 숨깁니다. 그러나 봇의 App Service 리소스 소유자는 새 암호를 생성할 수 있습니다.

봇에 대한 Azure Bot 리소스 블레이드로 이동합니다.
봇의 구성 블레이드로 이동합니다.
Microsoft 앱 ID 옆에 있는 관리를 선택하여 앱 서비스에 대한 인증서 + 비밀 블레이드로 이동합니다.
블레이드의 지침에 따라 새 클라이언트 비밀을 만들고 안전한 장소에 값을 기록합니다.

Microsoft Entra ID ID 서비스

Microsoft Entra ID는 OAuth 2.0과 같은 업계 표준 프로토콜을 사용하여 사용자를 안전하게 로그인하는 애플리케이션을 빌드할 수 있는 클라우드 ID 서비스입니다.

다음 두 가지 ID 서비스 중 하나를 사용할 수 있습니다.

Microsoft Entra ID 개발자 플랫폼(v1.0). Microsoft 회사 또는 학교 계정으로 사용자를 안전하게 로그인하는 앱을 빌드할 수 있는 Azure AD v1 엔드포인트라고도 합니다. 자세한 내용은 개발자용 Microsoft Entra ID(v1.0) 개요를 참조하세요.
Microsoft ID 플랫폼(v2.0). Azure AD 플랫폼(v1.0)의 진화된 Microsoft Entra ID 엔드포인트라고도 합니다. 이를 통해 모든 Microsoft ID 공급자에 로그인하고 Microsoft API(예: Microsoft Graph) 또는 개발자가 빌드한 다른 API를 호출하는 토큰을 가져오는 애플리케이션을 빌드할 수 있습니다. 자세한 내용은 Microsoft ID 플랫폼(v2.0) 개요를 참조하세요.

v1 및 v2 엔드포인트의 차이점에 대한 자세한 내용은 Microsoft ID 플랫폼(v2.0)으로 업데이트하는 이유를 참조하세요. 자세한 내용은 Microsoft ID 플랫폼(이전의 개발자용 Microsoft Entra ID)를 참조하세요.

Microsoft Entra ID ID 공급자 만들기

이 섹션에서는 OAuth 2.0을 사용하여 봇을 인증하는 Microsoft Entra ID ID 공급자를 만드는 방법을 보여줍니다. Azure AD v1 또는 Microsoft Entra ID 엔드포인트를 사용할 수 있습니다.

팁

애플리케이션에서 요청한 권한을 위임하는 데 동의할 수 있는 테넌트에 Microsoft Entra ID 애플리케이션을 만들고 등록해야 합니다.

Azure Portal에서 Microsoft Entra ID 패널을 엽니다. 올바른 테넌트에 없는 경우 디렉터리 전환을 선택하여 올바른 테넌트로 전환합니다. (테넌트를 만드는 방법에 대한 자세한 내용은 다음을 참조하세요 .포털에 액세스하고 테넌트를 만듭니다.)
앱 등록 패널을 엽니다.
앱 등록 패널에서 새 등록을 선택합니다.
필수 필드를 입력하고 앱 등록을 만듭니다.
1. 애플리케이션의 이름을 지정합니다.
2. 애플리케이션에 대해 지원되는 계정 유형을 선택합니다. (옵션 중 하나는 이 샘플에서 작동합니다.)
3. 리디렉션 URI의 경우 웹을 선택하고 URL을 지원되는 OAuth 리디렉션 URL 중 하나로 설정합니다.
4. 등록을 선택합니다.
  - Azure가 만들어지면 앱의 개요 페이지가 표시됩니다.
  - 애플리케이션(클라이언트) ID 값을 기록해 둡니다. 이 값은 나중에 연결 문자열 만들고 Microsoft Entra ID 공급자를 봇 등록에 등록할 때 클라이언트 ID로 사용합니다.
  - 디렉터리(테넌트) ID 값을 기록합니다. 이 값을 사용하여 이 공급자 애플리케이션을 봇에 등록합니다.
탐색 창에서 인증서 및 비밀을 선택하여 애플리케이션에 대한 비밀을 만듭니다.
1. 클라이언트 암호 아래에서 새 클라이언트 암호를 선택합니다.
2. 이 앱에 대해 만들어야 할 수 있는 다른 사용자로부터 이 비밀을 식별하는 설명을 추가합니다(예: bot login.).
3. 만료의 경우 비밀이 만료되는 기간을 선택합니다.
4. 추가를 선택합니다.
5. 인증서 및 비밀을 떠나기 전에 비밀을 기록합니다. 나중에 봇에 Microsoft Entra ID 애플리케이션을 등록할 때 이 값을 클라이언트 비밀 로 사용합니다.
탐색 창에서 API 사용 권한을 선택하여 API 권한 패널을 엽니다. 앱에 대한 API 권한을 명시적으로 설정하는 것이 가장 좋습니다.
1. 권한 추가를 선택하여 요청 API 권한 창을 표시합니다.
2. 이 샘플에서는 Microsoft API 및 Microsoft Graph를 선택합니다.
3. 위임된 권한을 선택하고 필요한 사용 권한이 선택되어 있는지 확인합니다. 이 샘플에는 이러한 권한이 필요합니다.
  
  참고 항목
  
  ADMIN CONSENT REQUIRED로 표시된 모든 권한은 사용자와 테넌트 관리자가 모두 로그인해야 하므로 봇의 경우 이러한 권한에서 벗어나는 경향이 있습니다.
  - openid
  - profile
  - Mail.Read
  - Mail.Send
  - User.Read
  - User.ReadBasic.All
4. 권한 추가를 선택합니다. (사용자가 봇을 통해 이 앱에 처음 액세스할 때 동의를 부여해야 합니다.)

이제 Microsoft Entra ID 애플리케이션이 구성되었습니다.

참고 항목

연결 문자열 만들고 ID 공급자를 봇 등록에 등록할 때 애플리케이션(클라이언트) ID및 클라이언트 암호를 할당합니다. 다음 섹션을 참조하십시오.

봇에 Microsoft Entra ID ID 공급자 등록

다음 단계는 ID 공급자를 봇에 등록하는 것입니다.

Microsoft Entra ID
Azure AD v1

Azure Portal에서 봇의 Azure Bot 리소스 페이지를 엽니다.
설정을 선택합니다.
페이지 아래쪽의 OAuth 커넥트ion 설정 아래에서 설정 추가를 선택합니다.
다음과 같이 양식을 채웁니다.
1. 이름. 연결의 이름을 입력합니다. 봇 코드에서 사용합니다.
2. 서비스 공급자입니다. Microsoft Entra ID를 선택하여 Microsoft Entra ID 관련 필드를 표시합니다.
3. 클라이언트 ID입니다. Microsoft Entra ID ID 공급자에 대해 기록한 애플리케이션(클라이언트) ID를 입력합니다.
4. 클라이언트 암호입니다. Microsoft Entra ID ID 공급자에 대해 기록한 비밀을 입력합니다.
  
  팁
  
  인증서를 사용하려는 경우 인증서 공급자를 사용하여 AAD v2를 선택할 수 있습니다. Bot Service 토큰 저장소(appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921)에 인증서를 가져올 수 있는 권한을 부여해야 합니다.
5. 토큰 교환 URL입니다. Microsoft Entra ID에서만 SSO에 사용되므로 비워 둡니다.
6. 테넌트 ID입니다. Azure DD 앱을 만들 때 선택한 지원되는 계정 유형에 따라 이전에 Microsoft Entra ID 앱에 대해 기록한 디렉터리(테넌트) ID를 입력합니다. 할당할 값을 결정하려면 다음 조건을 따릅니다.
  - Microsoft Entra ID 앱을 만들 때 이 조직 디렉터리에서만 계정을 선택한 경우(Microsoft 전용 - 단일 테넌트) Microsoft Entra ID 앱에 대해 이전에 기록한 테넌트 ID를 입력합니다.
  - 그러나 조직 디렉터리(모든 Microsoft Entra ID 디렉터리 - 다중 테넌트 및 개인 Microsoft 계정(예: Xbox, Outlook.com) 또는 모든 조직 디렉터리의 계정(Microsoft Entra ID 디렉터리 - 다중 테넌트)에서 계정을 선택한 경우 테넌트 ID 대신 입력 common 합니다. 그렇지 않으면 Microsoft Entra ID 앱은 ID가 선택된 테넌트에서 확인하고 개인 Microsoft 계정을 제외합니다.
  인증할 수 있는 사용자와 연결된 테넌트가 됩니다. 자세한 내용은 Microsoft Entra ID의 테넌트를 참조하세요.
7. 범위의 경우 애플리케이션 등록에서 선택한 사용 권한의 이름을 입력합니다. 테스트를 위해 다음을 입력 openid profile하면 됩니다.
  
  참고 항목
  
  Microsoft Entra ID 의 경우 범위 필드는 대/소문자를 구분하고 공백으로 구분된 값 목록을 사용합니다.
저장을 선택합니다.

Azure Portal에서 봇의 리소스 페이지로 이동합니다.
설정을 선택합니다.
페이지 아래쪽의 OAuth 커넥트ion 설정 아래에서 설정 추가를 선택합니다.
다음과 같이 양식을 채웁니다.
1. 이름에 대해 연결의 이름을 입력합니다. 봇 코드에서 이 이름을 사용합니다.
2. 서비스 공급자의 경우 Microsoft Entra ID를 선택합니다. 이 항목을 선택하면 Microsoft Entra ID 관련 필드가 표시됩니다.
3. 클라이언트 ID의 경우 Azure AD v1 애플리케이션에 대해 기록한 애플리케이션(클라이언트) ID를 입력합니다.
4. 클라이언트 암호의 경우 Microsoft Entra ID 앱에 대한 봇 액세스 권한을 부여하기 위해 만든 비밀을 입력합니다.
5. 허용 유형에 대해 .를 입력합니다authorization_code.
6. 로그인 URL에 대해 .를 입력합니다https://login.microsoftonline.com.
7. 테넌트 ID의 경우 이전에 Microsoft Entra ID 앱에 대해 기록한 디렉터리(테넌트) ID를 입력하거나 ADD 앱을 만들 때 선택한 지원되는 계정 유형에 따라 공통을 입력합니다. 할당할 값을 결정하려면 다음 조건을 따릅니다.
  - Microsoft Entra ID 앱을 만들 때 이 조직 디렉터리에서만 계정을 선택한 경우(Microsoft 전용 - 단일 테넌트) Microsoft Entra ID 앱에 대해 이전에 기록한 테넌트 ID를 입력합니다.
  - 그러나 조직 디렉터리(모든 Microsoft Entra ID 디렉터리 - 다중 테넌트 및 개인 Microsoft 계정(예: Xbox, Outlook.com) 또는 모든 조직 디렉터리의 계정(Microsoft Entra ID 디렉터리 - 다중 테넌트)에서 계정을 선택한 경우 테넌트 ID 대신 입력 common 합니다. 그렇지 않으면 Microsoft Entra ID 앱은 ID가 선택된 테넌트에서 확인하고 개인 MS 계정을 제외합니다.
  인증할 수 있는 사용자와 연결된 테넌트가 됩니다. 자세한 내용은 Microsoft Entra ID의 테넌트를 참조하세요.
8. 리소스 URL에 대해 https://graph.microsoft.com/을 입력합니다.
9. 범위를 비워 둡 니다 .
저장을 선택합니다.

참고 항목

이러한 값을 사용하면 애플리케이션은 Microsoft Graph API를 통해 Office 365 데이터에 액세스할 수 있습니다. 또한 토큰 Exchange URL은 Microsoft Entra ID의 SSO에만 사용되므로 비워 두어야 합니다.

연결 테스트

연결 항목을 선택하여 만든 연결을 엽니다.
서비스 공급자 커넥트ion 설정 창의 맨 위에서 테스트 커넥트ion을 선택합니다.
처음으로 앱이 요청하는 권한을 나열하는 새 브라우저 탭이 열리고 수락하라는 메시지가 표시됩니다.
수락을 선택합니다.
그러면 연결 이름> 성공 페이지로 테스트 커넥트로 <리디렉션됩니다.

이제 봇 코드에서 이 연결 이름을 사용하여 사용자 토큰을 검색할 수 있습니다.

봇 코드 준비

이 프로세스를 완료하려면 봇의 앱 ID와 암호가 필요합니다.

작업하려는 샘플인 Microsoft Graph에 대한 봇 인증 또는 봇 인증을 GitHub 리포지토리에서 복제합니다.

appsettings.json 업데이트:

ConnectionName을 봇에 추가한 OAuth 연결 설정의 이름으로 설정합니다.
MicrosoftAppId 및 MicrosoftAppPassword를 봇의 앱 ID 및 앱 비밀로 설정합니다.

봇 비밀의 문자에 따라 암호를 XML로 이스케이프해야 할 수 있습니다. 예를 들어 앰퍼샌드(&A)를 로 인코딩 &해야 합니다.

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "ConnectionName": ""
}

퍼블릭 클라우드에서 데이터 상주와 함께 봇에서 OAuth를 사용하려면 appsettings에 다음 구성을 추가해야 합니다.

"OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

지역 </OAuth-Url> 은 다음 URI 중 하나입니다.

URI	설명
`https://europe.api.botframework.com`	유럽에 데이터가 상주하는 퍼블릭 클라우드 봇의 경우.
`https://unitedstates.api.botframework.com`	미국 데이터 상주가 있는 퍼블릭 클라우드 봇의 경우
`https://india.api.botframework.com`	인도에 데이터가 상주하는 퍼블릭 클라우드 봇의 경우.

업데이트 Startup.cs:

정부 클라우드와 같은 비공용 Azure 클라우드에서 OAuth를 사용하려면 Startup.cs 파일에 다음 코드를 추가해야 합니다.

string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

여기서 <uri-to-use> 는 다음 URI 중 하나입니다.

URI	설명
`https://api.botframework.azure.us`	데이터 보존이 없는 미국 정부-클라우드 봇의 경우
`https://api.botframework.com`	데이터 보존이 없는 퍼블릭 클라우드 봇의 경우 이는 기본 URI이며 Startup.cs 변경할 필요가 없습니다.

작업하려는 GitHub 리포지토리에서 복제: Microsoft Graph 에 대한 봇 인증 또는 봇 인증.
.env 업데이트:
- connectionName을 봇에 추가한 OAuth 연결 설정의 이름으로 설정합니다.
- MicrosoftAppPassword 값을 봇의 앱 ID 및 앱 비밀로 설정합니다MicrosoftAppId.
  
  봇 비밀의 문자에 따라 암호를 XML로 이스케이프해야 할 수 있습니다. 예를 들어 앰퍼샌드(&A)를 로 인코딩 &해야 합니다.
```
MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
connectionName=
```

작업하려는 샘플인 Microsoft Graph에 대한 봇 인증 또는 봇 인증을 GitHub 리포지토리에서 복제합니다.
application.properties 업데이트:
- ConnectionName을 봇에 추가한 OAuth 연결 설정의 이름으로 설정합니다.
- MicrosoftAppId 및 MicrosoftAppPassword를 봇의 앱 ID 및 앱 비밀로 설정합니다.
```
MicrosoftAppId=
MicrosoftAppPassword=
server.port=3978
ConnectionName=
```

작업하려는 샘플인 Microsoft Graph에 대한 봇 인증 또는 봇 인증을 GitHub 리포지토리를 복제합니다.

업데이트 config.py:

ConnectionName을 봇에 추가한 OAuth 연결 설정의 이름으로 설정합니다.
MicrosoftAppId 및 MicrosoftAppPassword를 봇의 앱 ID 및 앱 비밀로 설정합니다.

봇 비밀의 문자에 따라 암호를 XML로 이스케이프해야 할 수 있습니다. 예를 들어 앰퍼샌드(&A)를 로 인코딩 &해야 합니다.

#!/usr/bin/env python3
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License.

import os

""" Bot Configuration """


class DefaultConfig:
    """ Bot Configuration """

    PORT = 3978
    APP_ID = os.environ.get("MicrosoftAppId", "")
    APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
    APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
    APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
    CONNECTION_NAME = os.environ.get("ConnectionName", "")

Microsoft 앱 ID 및 Microsoft 앱 암호 값을 가져오려면 등록 암호 가져오기를 참조하세요.

참고 항목

이제 이 봇 코드를 Azure 구독에 게시할 수 있지만(프로젝트에서 오른쪽 선택 및 게시 선택) 이 문서에는 필요하지 않습니다. Azure Portal에서 봇을 구성할 때 사용한 애플리케이션 및 호스팅 계획을 사용하는 게시 구성을 설정해야 합니다.

에뮬레이터를 사용하여 봇 테스트

아직 설치하지 않은 경우 Bot Framework Emulator를 설치합니다. 에뮬레이터를 사용하여 디버그도 참조하세요.

봇 샘플 로그인이 작동하려면 인증을 위해 에뮬레이터 구성에 표시된 대로 에뮬레이터를 구성해야 합니다.

테스팅

인증 메커니즘을 구성한 후에는 실제 봇 샘플 테스트를 수행할 수 있습니다.

참고 항목

봇 샘플이 구현되는 방식이므로 매직 코드를 입력하라는 메시지가 표시될 수 있습니다. 이 매직 코드는 RFC#7636의 일부이며 추가 보안 요소를 추가할 수 있습니다. 매직 코드를 제거하면 보안 위험이 증가합니다. 향상된 인증을 사용하도록 설정된 Direct Line을 사용하여 이 문제를 완화할 수 있습니다. 자세한 내용은 Bot Framework 고급 인증을 참조하세요.

컴퓨터에서 로컬로 봇 샘플을 실행합니다.
에뮬레이터를 시작합니다.
봇에 연결할 때 봇의 앱 ID와 암호를 제공해야 합니다.
- Azure 앱 등록에서 앱 ID와 암호를 가져옵니다. 이러한 값은 또는 .env 파일의 봇 앱에 할당한 값과 appsettings.json 동일합니다. 에뮬레이터에서 구성 파일 또는 봇에 처음 연결할 때 이러한 값을 할당합니다.
- 봇 코드에서 암호를 XML로 이스케이프해야 하는 경우 여기에서도 이 작업을 수행해야 합니다.
help를 입력하여 봇에 사용 가능한 명령 목록을 보고 인증 기능을 테스트합니다.
로그인하면 로그아웃할 때까지 자격 증명을 다시 제공할 필요가 없습니다.
로그아웃하고 인증을 취소하려면 .를 입력 logout합니다.

참고 항목

봇 인증을 사용하려면 Bot 커넥트or 서비스를 사용해야 합니다. 서비스는 Azure Bot 리소스의 정보에 액세스합니다.

인증 예제

봇 인증 샘플에서 대화 상자는 사용자가 로그인한 후 사용자 토큰을 검색하도록 디자인됩니다.

인증 샘플 봇과의 샘플 대화입니다.

Microsoft Graph 인증 예제

Microsoft Graph용 봇 인증 샘플에서 대화 상자는 사용자가 로그인한 후 제한된 명령 집합을 허용하도록 설계되었습니다.

Microsoft Graph 인증 샘플 봇과의 샘플 대화입니다.

추가 정보

사용자가 봇에 사용자가 로그인해야 하는 작업을 수행하도록 요청하는 경우 봇은 지정된 연결에 대한 토큰 검색을 시작하는 데 사용할 OAuthPrompt 수 있습니다. 다음 OAuthPrompt 으로 구성된 토큰 검색 흐름을 만듭니다.

Azure AI Bot Service에 현재 사용자 및 연결에 대한 토큰이 이미 있는지 확인합니다. 토큰이 있으면 토큰이 반환됩니다.
Azure AI Bot Service에 캐시된 토큰이 없는 경우 사용자가 선택할 수 있는 로그인 단추인 토큰 OAuthCard 이 만들어집니다.
사용자가 로그인 단추를 선택하면 OAuthCard Azure AI Bot Service는 사용자의 토큰을 직접 봇에 보내거나 채팅 창에 입력할 6자리 인증 코드를 사용자에게 제공합니다.
사용자에게 인증 코드가 제공되면 봇이 이 인증 코드를 사용자의 토큰으로 교환합니다.

다음 섹션에서는 샘플에서 몇 가지 일반적인 인증 작업을 구현하는 방법을 설명합니다.

OAuth 프롬프트를 사용하여 사용자 로그인 및 토큰 가져오기

C# 샘플의 아키텍처 다이어그램.

Dialogs\MainDialog.cs

해당 생성자의 MainDialog에 OAuth 프롬프트를 추가합니다. 여기서 연결 이름 값은 appsettings.json 파일에서 검색되었습니다.

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

대화 상자 단계 내에서 BeginDialogAsync를 사용하여 사용자에게 로그인하라고 요청하는 OAuth 프롬프트를 시작합니다.

사용자가 이미 로그인한 경우 사용자에게 메시지를 표시하지 않고 토큰 응답 이벤트를 생성합니다.
사용자가 아직 로그인하지 않은 경우 사용자에게 로그인하라는 프롬프트를 표시합니다. Azure AI Bot Service는 사용자가 로그인을 시도한 후 토큰 응답 이벤트를 보냅니다.

return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

다음 대화 단계 내에서 이전 단계의 결과에 토큰이 있는지 검사. null이 아닌 경우 사용자가 성공적으로 로그인했습니다.

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There is an example of this in the next method.
var tokenResponse = (TokenResponse)stepContext.Result;

JavaScript 샘플에 대한 아키텍처 다이어그램.

dialogs/기본Dialog.js

해당 생성자의 MainDialog에 OAuth 프롬프트를 추가합니다. 여기서 연결 이름 값은 .env 파일에서 검색되었습니다.

this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
    this.promptStep.bind(this),
    this.loginStep.bind(this),
    this.displayTokenPhase1.bind(this),
    this.displayTokenPhase2.bind(this)
]));

대화 상자 단계 내에서 beginDialog를 사용하여 사용자에게 로그인하라고 요청하는 OAuth 프롬프트를 시작합니다.

사용자가 이미 로그인한 경우 사용자에게 메시지를 표시하지 않고 토큰 응답 이벤트를 생성합니다.
사용자가 아직 로그인하지 않은 경우 사용자에게 로그인하라는 프롬프트를 표시합니다. Azure AI Bot Service는 사용자가 로그인을 시도한 후 토큰 응답 이벤트를 보냅니다.

const tokenResponse = stepContext.result;

다음 대화 단계 내에서 이전 단계의 결과에 토큰이 있는지 검사. null이 아닌 경우 사용자가 성공적으로 로그인했습니다.

await stepContext.context.sendActivity('Login was not successful please try again.');
return await stepContext.endDialog();

Java 샘플에 대한 아키텍처 다이어그램입니다.

MainDialog.java

해당 생성자의 MainDialog에 OAuth 프롬프트를 추가합니다. 여기서 연결 이름 값은 application.properties 파일에서 검색되었습니다.

OAuthPromptSettings settings = new OAuthPromptSettings();
settings.setText("Please Sign In");
settings.setTitle("Sign In");
settings.setConnectionName(configuration.getProperty("ConnectionName"));
settings.setTimeout(300000); // User has 5 minutes to login (1000 * 60 * 5)

addDialog(new OAuthPrompt("OAuthPrompt", settings));

대화 상자 단계 내에서 beginDialog를 사용하여 사용자에게 로그인하라고 요청하는 OAuth 프롬프트를 시작합니다.

사용자가 이미 로그인한 경우 사용자에게 메시지를 표시하지 않고 토큰 응답 이벤트를 생성합니다.
사용자가 아직 로그인하지 않은 경우 사용자에게 로그인하라는 프롬프트를 표시합니다. Azure AI Bot Service는 사용자가 로그인을 시도한 후 토큰 응답 이벤트를 보냅니다.

return stepContext.beginDialog("OAuthPrompt");

다음 대화 단계 내에서 이전 단계의 결과에 토큰이 있는지 검사. null이 아닌 경우 사용자가 성공적으로 로그인했습니다.

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There instanceof an example of this in the next method.
TokenResponse tokenResponse = (TokenResponse) stepContext.getResult();

Python 샘플에 대한 아키텍처 다이어그램.

dialogs/main_dialog.py

해당 생성자의 MainDialog에 OAuth 프롬프트를 추가합니다. 여기서 연결 이름 값은 config.py 파일에서 검색되었습니다.

self.add_dialog(
    WaterfallDialog(
        "WFDialog",
        [
            self.prompt_step,
            self.login_step,
            self.display_token_phase1,
            self.display_token_phase2,
        ],
    )
)

대화 상자 단계 내에서 begin_dialog를 사용하여 사용자에게 로그인하라고 요청하는 OAuth 프롬프트를 시작합니다.

사용자가 이미 로그인한 경우 사용자에게 메시지를 표시하지 않고 토큰 응답 이벤트를 생성합니다.
사용자가 아직 로그인하지 않은 경우 사용자에게 로그인하라는 프롬프트를 표시합니다. Azure AI Bot Service는 사용자가 로그인을 시도한 후 토큰 응답 이벤트를 보냅니다.

return await step_context.begin_dialog(OAuthPrompt.__name__)

다음 대화 단계 내에서 이전 단계의 결과에 토큰이 있는지 검사. null이 아닌 경우 사용자가 성공적으로 로그인했습니다.

if step_context.result:
    await step_context.context.send_activity("You are now logged in.")
    return await step_context.prompt(
        ConfirmPrompt.__name__,
        PromptOptions(
            prompt=MessageFactory.text("Would you like to view your token?")
        ),
    )

await step_context.context.send_activity(
    "Login was not successful please try again."
)

TokenResponseEvent 대기

OAuth 프롬프트를 시작할 때 사용자의 토큰을 검색하는 토큰 응답 이벤트를 기다립니다.

Bots\AuthBot.cs

AuthBot 은 토큰 응답 이벤트 활동에서 ActivityHandler 파생되고 명시적으로 처리됩니다. 여기서는 OAuth 프롬프트가 이벤트를 처리하고 토큰을 검색할 수 있도록 하는 활성 대화 상자를 계속 진행합니다.

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

봇/authBot.js

await this.dialog.run(context, this.dialogState);

await next();

AuthBot.java

AuthBot 은 토큰 응답 이벤트 활동에서 Dialog 파생되고 명시적으로 처리됩니다. 여기서는 OAuth 프롬프트가 이벤트를 처리하고 토큰을 검색할 수 있도록 하는 활성 대화 상자를 계속 진행합니다.

@Override
protected CompletableFuture<Void> onTokenResponseEvent(TurnContext turnContext) {
    LoggerFactory.getLogger(AuthBot.class).info("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

bots/auth_bot.py

AuthBot 은 토큰 응답 이벤트 활동을 명시적으로 처리합니다. 여기서는 OAuth 프롬프트가 이벤트를 처리하고 토큰을 검색할 수 있도록 하는 활성 대화 상자를 계속 진행합니다.

async def on_token_response_event(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

사용자 로그아웃

시간 초과를 위해 연결에 의존하는 대신 사용자가 명시적으로 로그아웃하도록 하는 것이 가장 좋습니다.

Dialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

dialogs/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }
    }

LogoutDialog.java

private CompletableFuture<DialogTurnResult> interrupt(DialogContext innerDc) {
    if (innerDc.getContext().getActivity().getType().equals(ActivityTypes.MESSAGE)) {
        String text = innerDc.getContext().getActivity().getText().toLowerCase();

        if (text.equals("logout")) {
            // The bot adapter encapsulates the authentication processes.
            BotFrameworkAdapter botAdapter = (BotFrameworkAdapter) innerDc.getContext().getAdapter();
            botAdapter.signOutUser(
                innerDc.getContext(),
                getConnectionName(),
                innerDc.getContext().getActivity().getFrom().getId())
                    .thenApply(result -> innerDc.getContext().sendActivity(MessageFactory.text("You have been signed out."))
                    .thenApply(sendResult -> null));
            return innerDc.cancelAllDialogs();
        }
    }

    return CompletableFuture.completedFuture(null);
}

dialogs/logout_dialog.py

async def _interrupt(self, inner_dc: DialogContext):
    if inner_dc.context.activity.type == ActivityTypes.message:
        text = inner_dc.context.activity.text.lower()
        if text == "logout":
            bot_adapter: BotFrameworkAdapter = inner_dc.context.adapter
            await bot_adapter.sign_out_user(inner_dc.context, self.connection_name)
            await inner_dc.context.send_activity("You have been signed out.")
            return await inner_dc.cancel_all_dialogs()

Teams 인증 추가

OAuth는 Teams에서 다른 채널과 다르게 처리됩니다. Teams 인증 봇 샘플( C#, JavaScript, Java 또는 Python)에서는 Teams에 대한 인증을 올바르게 구현하는 방법을 보여 줍니다.

추가 참고 자료

Bot Framework 추가 리소스에는 추가 지원을 위한 링크가 포함되어 있습니다.
Bot Framework SDK 리포지토리에는 Bot Builder SDK와 연결된 리포지토리, 샘플, 도구 및 사양에 대한 자세한 정보가 있습니다.

다음을 통해 공유

봇에 인증 추가

웹 채팅 및 Direct Line 고려 사항

필수 조건

리소스 만들기

봇 ID 정보

앱 서비스를 업데이트하려면

앱 또는 테넌트 ID를 가져오려면

새 암호를 생성하려면

Microsoft Entra ID ID 서비스

Microsoft Entra ID ID 공급자 만들기

봇에 Microsoft Entra ID ID 공급자 등록

연결 테스트

봇 코드 준비

에뮬레이터를 사용하여 봇 테스트

테스팅

인증 예제

Microsoft Graph 인증 예제

추가 정보

OAuth 프롬프트를 사용하여 사용자 로그인 및 토큰 가져오기

TokenResponseEvent 대기

사용자 로그아웃

Teams 인증 추가

추가 참고 자료

추가 리소스