Teams 채널 설정
n8n v2.47요약
Microsoft Teams 채널은 다음 환경에서 사용할 수 있습니다. 에이전트용 Microsoft Teams 채널은 프리뷰 상태이며 이후 릴리즈에서 변경될 수 있습니다. 권장 설정 또는 수동 설정으로 n8n 에이전트를 Microsoft Teams에 연결합니다.
기능 제공 범위
Microsoft Teams 채널은 다음 환경에서 사용할 수 있습니다.
- n8n Cloud: 모든 플랜
- 셀프 호스팅: n8n 2.32.3 이후의 모든 플랜
프리뷰 상태
에이전트용 Microsoft Teams 채널은 프리뷰 상태이며 이후 릴리즈에서 변경될 수 있습니다. 프로덕션 환경에서는 이 기능에 의존하지 마세요.
권장 설정 또는 수동 설정으로 n8n 에이전트를 Microsoft Teams에 연결합니다. 채널이 동작하는 방식과 사람들이 에이전트를 사용할 수 있는 위치는 에이전트를 Microsoft Teams에 연결을 참고하세요.
사전 요구 사항#
시작하기 전에 다음을 준비하세요.
- 편집할 수 있고 한 번 이상 게시된 에이전트.
- Microsoft가 HTTPS로 접근할 수 있는 n8n 인스턴스. 셀프 호스팅 n8n에서는
N8N_WEBHOOK_URL을 인스턴스의 공개 HTTPS URL로 설정합니다. - 글로벌 Microsoft 클라우드의 Microsoft 365 회사 또는 학교 계정. 개인 계정과 GCC 또는 Microsoft Azure operated by 21Vianet 같은 소버린 클라우드는 지원되지 않습니다.
- Azure Bot용 Azure 구독.
- Teams에서 사용자 지정 앱을 추가할 수 있는 권한. Teams 정책이 사용자 지정 앱 업로드를 허용하거나, 관리자가 조직에 앱을 게시할 수 있어야 합니다.
권장 설정#
권장 설정은 Microsoft에 필요한 모든 리소스를 대신 생성합니다. n8n Cloud에서는 별도 작업 없이 사용할 수 있습니다. 셀프 호스팅 n8n에서는 인스턴스 소유자가 먼저 설정해야 합니다. 셀프 호스팅 n8n에서 권장 설정 사용을 참고하세요. 사용할 수 없는 경우 Teams 채널에는 Use your own Microsoft app이라는 라벨이 붙은 수동 설정만 표시됩니다.
Teams를 연결하려면 다음을 수행합니다.
- 에이전트를 열고 Channels로 이동한 다음 Microsoft Teams를 선택합니다. Recommended setup이 선택되어 있는지 확인합니다.
- Connect to Microsoft에서 Sign in with Microsoft를 선택하고, 사람들이 에이전트를 사용할 조직의 회사 또는 학교 계정으로 로그인합니다.
- Create Teams app에서 Create app을 선택합니다. n8n이 Microsoft Entra에 앱을 등록합니다. 최대 30초가 걸릴 수 있습니다.
- Deploy Azure Bot에서 Azure subscription을 선택하고 Create Azure Bot을 선택합니다. 최대 1분이 걸릴 수 있습니다.
- Choose where it works에서 사람들이 에이전트를 사용할 수 있는 위치의 옵션을 선택합니다.
- Install app에서 Install for me 또는 Publish to organization을 선택합니다. 앱을 업로드하거나 조직에 게시를 참고하세요.
- Approve access에서 Microsoft Graph 권한을 지금 승인하거나 나중에 채널 설정에서 승인합니다. 액세스 승인을 참고하세요.
- Connect Microsoft Teams에서 Teams에 앱 추가를 마친 다음 Done을 선택합니다.
n8n이 대신 생성하는 항목#
| 리소스 | 세부 정보 |
|---|---|
| 앱 등록 | 이름은 <agent-name> (n8n)이며 단일 테넌트이고, n8n agent channel이라는 클라이언트 시크릿이 있습니다. n8n은 해당 서비스 주체도 함께 생성합니다. |
| 리소스 그룹 | West Europe의 n8n-agents이며, 선택한 구독에 없으면 생성됩니다. |
| Azure Bot | 에이전트 이름을 따르며 무료 F0 티어를 사용하고 Microsoft Teams 채널이 켜져 있습니다. 채널 설정에 이 봇으로 연결되는 링크가 있습니다. |
| n8n 자격 증명 | 앱의 ID와 시크릿이 담긴 Microsoft Entra Service Principal 자격 증명입니다. 시크릿을 다른 곳에 복사할 필요가 없습니다. |
단계를 다시 실행하면 n8n은 새로 만들지 않고 같은 앱 등록과 봇을 재사용합니다.
권장 설정에 필요한 권한#
로그인하면 n8n이 Microsoft에 다음 위임된 권한을 요청합니다. n8n은 이 권한을 로그인한 사용자 자격으로 에이전트를 설정하는 데에만 사용합니다.
| 권한 | n8n이 사용하는 용도 |
|---|---|
User.Read |
프로필과 조직을 읽습니다. |
Application.ReadWrite.All |
앱 등록과 클라이언트 시크릿, 서비스 주체를 생성합니다. |
AppCatalog.ReadWrite.All |
Teams 앱을 조직의 앱 카탈로그에 게시합니다. |
AppCatalog.Submit |
직접 게시할 수 없을 때 관리자 승인을 받도록 Teams 앱을 제출합니다. |
Azure Service Management (user_impersonation) |
Azure 구독 목록을 조회하고 Azure Bot을 생성합니다. |
Application.ReadWrite.All과 AppCatalog.ReadWrite.All에는 관리자 동의가 필요합니다. Microsoft 조직의 관리자가 n8n을 한 번 승인하면, 이후에는 누구나 권한 화면 없이 로그인할 수 있습니다. 로그인할 때 Microsoft에 Need admin approval이 표시되면 관리자가 먼저 n8n을 승인해야 합니다. Copy link for an admin을 선택하고 링크를 관리자에게 보내세요.
이 권한은 n8n이 사용자 대신 동작하도록 허용할 뿐입니다. Microsoft에서 다음 권한도 필요합니다.
| 단계 | 계정에 필요한 권한 | 없는 경우 |
|---|---|---|
| Create Teams app | Microsoft Entra에서 애플리케이션을 등록할 수 있는 권한. 조직에서 특정 역할로 제한할 수 있습니다. | 관리자에게 앱 등록을 요청하거나, 설정 화면의 Use your own Microsoft app instead 링크를 선택해 수동 설정으로 전환합니다. |
| Deploy Azure Bot | Azure 구독의 Contributor 역할. | Azure 관리자에게 Contributor 액세스를 요청하거나, Use your own Microsoft app instead 링크를 선택해 수동 설정으로 전환합니다. |
| Publish to organization | 직접 게시하려면 Teams 관리자 역할. | n8n이 대신 승인 요청용으로 앱을 제출합니다. 조직에 게시를 참고하세요. |
수동 설정#
권장 설정을 사용할 수 없거나 조직에서 허용하지 않는 경우 수동 설정을 사용합니다. Microsoft에서 리소스를 직접 생성하고 자격 증명으로 연결합니다.
Teams 채널에서 Use your own Microsoft app을 선택합니다. 권장 설정에서는 Use your own Microsoft app instead 링크를 선택하면 같은 위치로 이동합니다. 다음 단계를 따릅니다.
- Microsoft Entra에 앱 등록.
- n8n에서 자격 증명 생성.
- Azure Bot 배포.
- 사용 위치 선택.
- 앱 패키지 다운로드.
- Graph 권한 승인 (선택 사항).
- Teams에 앱 추가.
Microsoft Entra에 앱 등록#
다른 에이전트가 사용하지 않는 앱 등록의 자격 증명이 이미 있다면 이 단계를 건너뜁니다.
- Open Microsoft Entra를 선택하거나 Microsoft Entra admin center > App registrations > New registration으로 이동합니다.
- 이름을 입력합니다. 예를 들어 에이전트의 이름을 입력합니다.
- Supported account types에서 Accounts in this organizational directory only(단일 테넌트)를 선택합니다.
- 리디렉션 URI는 필요하지 않습니다. Register를 선택합니다.
- Overview 페이지에서 Directory (tenant) ID와 Application (client) ID를 복사합니다.
- Certificates & secrets > Client secrets > New client secret으로 이동합니다. 설명과 만료일을 추가한 다음 Secret ID가 아닌 시크릿 Value를 복사합니다. Microsoft는 값을 한 번만 표시합니다.
메시지를 주고받는 데에는 봇에 API 권한이 필요하지 않습니다.
n8n에서 자격 증명 생성#
Create credential에서 새 자격 증명을 생성합니다.
- Authentication: Client Secret. Teams 채널은 인증서를 지원하지 않습니다.
- Directory (Tenant) ID: 복사한 테넌트 ID.
- Application (Client) ID: 복사한 클라이언트 ID.
- Client Secret: 복사한 시크릿 값.
- Microsoft Graph API Base URL: Global.
n8n이 Microsoft로 자격 증명을 확인합니다. 확인을 통과하면 n8n에 **Credential verified with Microsoft Entra.**가 표시됩니다. 각 자격 증명은 에이전트 하나만 Teams에 연결할 수 있습니다. 다른 에이전트가 이미 사용 중이면 이 에이전트용 앱을 새로 등록하세요.
이 자격 증명 유형에 대한 자세한 내용은 Microsoft Entra Service Principal 자격 증명을 참고하세요.
Azure Bot 배포#
다음 중 하나를 선택합니다.
- New bot: Deploy to Azure를 선택합니다. Azure 포털이 열리고, n8n이 봇 이름과 앱 ID, 메시징 엔드포인트를 채운 템플릿이 표시됩니다. Azure에서 템플릿이 Microsoft 제공이 아니라는 안내가 표시될 수 있습니다. 구독과 리소스 그룹을 선택한 다음 배포를 생성합니다. 구독에 대한 Contributor 역할이 필요합니다.
- Existing bot: Use an existing Azure Bot을 선택하고 Messaging endpoint를 복사합니다. Azure 포털에서 봇의 Configuration 페이지를 열고 Messaging endpoint에 붙여넣은 다음, 봇이 같은 앱 등록을 사용하는지 확인합니다. 그런 다음 Channels로 이동해 Microsoft Teams를 켭니다.
사용 위치 선택#
사람들이 에이전트를 사용할 위치와 에이전트가 메시지를 수신하는 방식을 선택합니다. 다이렉트 채팅은 항상 켜져 있습니다. Team channels 또는 Group and meeting chats를 켜면 사람들이 그곳에 에이전트를 추가하고 @멘션할 수 있습니다. 모든 메시지 읽기 옵션을 켜면 에이전트가 모든 메시지에 실행되므로 매번 모델 크레딧이 사용됩니다. 자세한 내용은 사람들이 에이전트를 사용할 수 있는 위치와 에이전트가 채널과 그룹 채팅에서 메시지를 수신하는 방식을 참고하세요.
앱 패키지 다운로드#
Download app package를 선택합니다. 이 작업은 채널을 에이전트에 연결하는 작업도 함께 수행합니다. 패키지는 에이전트의 이름과 아이콘을 사용합니다.
Graph 권한 승인#
에이전트가 사람과 채널을 찾고 첨부 파일을 읽을 수 있도록, 관리자가 Microsoft Graph 애플리케이션 권한을 추가하고 관리자 동의를 부여합니다. Approve access를 선택한 다음 Approve now 또는 Copy link for admin을 선택합니다. 액세스 승인을 참고하세요.
에이전트가 메시지를 받았을 때만 응답한다면 이 단계를 건너뜁니다. 나중에 채널 설정에서 승인할 수 있습니다.
Teams에 앱 추가#
- Teams에서 Apps > Manage your apps > Upload an app으로 이동해 zip 파일을 업로드합니다.
- 에이전트가 동작할 위치에 따라 Add to a team 또는 Add to a chat을 선택합니다.
- n8n에서 Done을 선택합니다.
Upload an app이 보이지 않으면 Teams 정책이 사용자 지정 앱을 허용하지 않는 것입니다. Teams 관리자에게 사용자 지정 앱 업로드를 허용해 달라고 요청하거나, 조직의 앱 카탈로그에 앱을 업로드해 달라고 요청하세요.
수동 설정에 필요한 권한#
| 권한 | 유형 | 부여하는 주체 | 필요한 용도 | 없는 경우 |
|---|---|---|---|---|
| Register applications | Microsoft Entra 설정 또는 역할 | Microsoft Entra 관리자 | 앱 등록 | 앱 등록을 생성할 수 없습니다. |
| Contributor | 구독의 Azure 역할 | Azure 관리자 | Azure Bot 배포 | 봇을 생성할 수 없습니다. |
| Upload custom apps | Teams 앱 설정 정책 | Teams 관리자 | 앱 패키지 업로드 | Teams 관리 센터를 통해서만 관리자가 앱을 추가할 수 있습니다. |
User.ReadBasic.All, Team.ReadBasic.All, Channel.ReadBasic.All, Files.Read.All |
Microsoft Graph 애플리케이션 권한 | Microsoft 관리자(관리자 동의 포함) | 사람과 채널 찾기, 채널과 그룹 채팅에 첨부된 파일 | 에이전트가 메시지를 받았을 때만 응답할 수 있으며 해당 파일을 읽을 수 없습니다. |
ChannelMessage.Read.Group |
RSC 권한, Team channels로 추가됨 | 앱을 추가할 때 팀 소유자 | 채널 메시지와 붙여넣은 이미지 읽기 | 에이전트가 채널에서 동작할 수 없습니다. |
ChatMessage.Read.Chat |
RSC 권한, Group and meeting chats로 추가됨 | 채팅에 앱을 추가하는 사람 | 채팅 메시지와 붙여넣은 이미지 읽기 | 에이전트가 그룹 채팅에서 동작할 수 없습니다. |
셀프 호스팅 n8n에서 권장 설정 사용#
셀프 호스팅 n8n에서 권장 설정을 쓰려면 설정을 위해 사용자를 로그인시키는 Microsoft 앱이 필요합니다. n8n Cloud는 이 앱을 제공합니다. 자체 인스턴스에서는 인스턴스 소유자가 이 앱을 제공합니다.
-
Microsoft Entra에서 멀티 테넌트 앱(Accounts in any organizational directory)을 등록합니다.
-
리디렉션 URI
<n8n-url>/rest/oauth2-credential/callback을 Web 플랫폼으로 추가합니다. -
다음 위임된 API 권한을 추가합니다.
- Microsoft Graph:
User.Read,Application.ReadWrite.All,AppCatalog.ReadWrite.All,AppCatalog.Submit,openid,profile,offline_access - Azure Service Management:
user_impersonation
- Microsoft Graph:
-
클라이언트 시크릿을 생성합니다.
-
클라이언트 ID와 시크릿을 자격 증명 유형
microsoftTeamsManagerOAuth2Api의 자격 증명 오버라이트로 제공합니다.{ "microsoftTeamsManagerOAuth2Api": { "clientId": "<client-id>", "clientSecret": "<client-secret>" } }
오버라이트가 적용되면 Teams 채널에 Recommended setup이 표시됩니다. 자격 증명 오버라이트를 설정하는 방법은 자격 증명 오버라이트와 Microsoft OAuth 자격 증명 사전 구성을 참고하세요.
Microsoft Graph 권한#
대화에서 응답하고 붙여넣은 이미지를 읽는 기능은 앱 패키지에 포함된 권한으로 동작합니다. 그 외의 기능에는 앱 등록에 Microsoft Graph 애플리케이션 권한 네 가지가 필요합니다.
| 권한 | 에이전트가 이 권한으로 할 수 있는 일 |
|---|---|
User.ReadBasic.All |
이메일로 사람을 찾아 다이렉트 메시지를 보내고 멘션할 수 있습니다. |
Team.ReadBasic.All |
이름으로 팀을 찾아 해당 팀의 채널에 게시할 수 있습니다. |
Channel.ReadBasic.All |
이름으로 채널을 찾아 해당 채널에 게시할 수 있습니다. |
Files.Read.All |
사람들이 채널과 그룹 채팅에 첨부한 파일을 읽습니다. |
Microsoft 조직의 관리자가 네 가지를 한 번에 승인합니다. 일부만 승인할 수는 없습니다. 이 권한이 없으면 에이전트는 누군가 메시지를 보냈을 때만 응답할 수 있습니다.
액세스 승인#
두 설정 모두 Approve access 단계가 표시됩니다. 이 단계의 설명에는 켜 둔 위치에서 승인하면 사용할 수 있게 되는 기능이 나열됩니다. 나중에 승인할 수도 있습니다. 관리자가 승인할 때까지 채널 설정의 Where it works 아래에 경고가 표시됩니다.
Approve access를 선택한 다음 다음 중 하나를 선택합니다.
- Approve now: 조직의 관리자라면 직접 승인 화면을 엽니다.
- Copy link for admin: 링크를 복사해 승인할 수 있는 관리자에게 보냅니다.
링크가 여는 화면은 설정에 따라 다릅니다.
- Recommended setup: Microsoft 관리자 동의 화면입니다. n8n이 이미 앱 등록에 권한을 추가했습니다. 관리자가 권한을 검토하고 수락합니다.
- Manual setup: Microsoft Entra의 앱 등록 API permissions 페이지입니다. 관리자가 여기서 권한을 추가합니다.
- Add a permission > Microsoft Graph > Application permissions를 선택합니다.
- 위 표의 각 권한을 검색해 추가합니다.
- Grant admin consent를 선택합니다.
애플리케이션 권한 사용
권한을 Delegated가 아닌 Application 권한으로 추가하세요. 에이전트는 로그인한 사용자가 아니라 앱으로 동작하므로 위임된 권한을 사용할 수 없습니다.
채널을 연결한 후에는 두 설정 모두 채널 설정이 상태를 대신 확인합니다. Microsoft가 승인을 확인하면 **Permissions approved.**가 표시됩니다. 에이전트가 권한을 사용할 수 있게 되기까지 최대 1시간이 걸릴 수 있습니다.