Microsoft Entra Service Principal 자격 증명
n8n v2.47요약
Microsoft Entra Service Principal 자격 증명은 n8n에 Microsoft Graph에 대한 앱 전용 액세스를 제공합니다. 이 자격 증명을 사용해 다음 노드를 인증할 수 있습니다: Microsoft Excel (OneDrive), Microsoft Outlook, Microsoft SharePoint, Microsoft Teams 노드는 노드 버전 2부터 이 자격 증명을 지원합니다.
Microsoft Entra Service Principal 자격 증명은 n8n에 Microsoft Graph에 대한 앱 전용 액세스를 제공합니다. 사람으로 로그인하는 대신, n8n은 관리자가 Microsoft Entra 관리 센터에서 한 번 설정한 앱 등록으로 인증합니다. 이는 무인 및 공유 워크플로에 적합합니다: 만료될 사용자 세션이 없고 관리해야 할 사용자별 동의도 없습니다.
이 자격 증명을 사용해 다음 노드를 인증할 수 있습니다:
- Microsoft Excel (OneDrive)
- Microsoft Excel (SharePoint)
- Microsoft OneDrive
- Microsoft OneDrive Trigger
- Microsoft Outlook
- Microsoft Outlook Trigger
- Microsoft SharePoint
- Microsoft SharePoint Trigger
- Microsoft Teams
- Microsoft Teams Trigger
- Microsoft To Do
노드 버전 요구 사항
Microsoft Excel (OneDrive), Microsoft Outlook, Microsoft SharePoint, Microsoft Teams 노드는 노드 버전 2부터 이 자격 증명을 지원합니다. Microsoft Excel (SharePoint) 노드는 버전 1부터 지원합니다.
사전 요구 사항#
- Microsoft 365 조직 테넌트. 개인 Microsoft 계정은 애플리케이션 권한을 지원하지 않습니다.
- 앱 등록을 생성하고 관리자 동의를 부여할 수 있는 관리자로서, 또는 대신 동의를 부여해 줄 수 있는 관리자를 통해 Microsoft Entra 관리 센터에 접근할 수 있어야 합니다.
지원되는 인증 방법#
- 클라이언트 시크릿 또는 인증서(서명된 클라이언트 어설션)를 사용하는 OAuth2 클라이언트 자격 증명
관련 자료#
자세한 내용은 Microsoft의 문서를 참조하세요:
- 사용자 없이 액세스 얻기: 앱 전용 인증이 작동하는 방식
- Microsoft Graph 권한 참조
- 애플리케이션에 테넌트 전체 관리자 동의 부여하기
앱 전용 액세스가 OAuth2와 다른 점#
OAuth2 Microsoft 자격 증명을 사용하면 노드는 로그인한 사용자로 동작합니다. Service Principal 자격 증명을 사용하면 로그인한 사용자가 없으므로, 노드를 사용하는 방식이 달라집니다:
- 누구 또는 무엇을 대상으로 작동할지 직접 선택합니다. 이 자격 증명을 선택하면 각 노드에 추가 필수 매개변수가 표시됩니다: Microsoft OneDrive, Microsoft OneDrive Trigger, Microsoft Excel (OneDrive)에서는 Access As(사용자 또는 드라이브), Microsoft Outlook과 Microsoft Outlook Trigger에서는 Mailbox, Microsoft To Do에서는 User입니다. 사용자 계정 이름(UPN), 예를 들어
jane@contoso.com또는 사용자 객체 ID를 입력하세요. Access As 필드에서는 대신 Drive를 선택하고 드라이브 ID를 입력할 수도 있습니다. 이 필드들에는 목록 선택기가 없습니다: 값을 직접 붙여넣으세요. Microsoft Teams 노드에서는 Authentication 옵션이 **Service Principal (App-Only)**로 표시되며, Task 작업에서는 Team 선택기가 숨겨지고 Plan, Bucket, Assigned To 선택기가 일반 ID 필드로 대체되며, Online Meeting 작업에는 앱이 회의를 관리할 대상 사용자를 지정하는 Organizer 필드가 추가됩니다. - 권한이 테넌트 전체에 적용됩니다. 애플리케이션 권한은 한 사용자로 범위가 제한되지 않습니다. 예를 들어
Mail.Send애플리케이션 권한은 Exchange Online 애플리케이션 액세스 정책으로 제한하지 않는 한 앱이 테넌트의 모든 메일함으로 메일을 보낼 수 있게 합니다. n8n은 애플리케이션 액세스 정책으로 테넌트 전체 메일 권한의 범위를 제한할 것을 권장합니다. - 선택기가 테넌트 전체를 봅니다. 예를 들어 Microsoft Teams의 Team 선택기는 앱이 참여한 팀만이 아니라 조직의 모든 팀을 나열합니다.
- 일부 작업을 사용할 수 없습니다. 노드는 드라이브 검색이나 Teams 채팅과 같이 로그인한 사용자에게만 존재하는 기능을 숨기거나 설명 오류로 차단합니다. 앱 전용 액세스에서 사용할 수 없는 작업을 참고하세요.
앱 등록 설정하기#
n8n에서 자격 증명을 생성하기 전에 Microsoft Entra 관리 센터에서 다음 단계를 완료하세요. 명령줄에서 Microsoft SharePoint 노드용 앱 등록을 설정하려면 Azure CLI로 SharePoint 앱 등록 프로비저닝하기를 참고하세요.
앱 등록하기#
- Microsoft Entra 관리 센터를 열고 Entra ID > App registrations로 이동합니다.
- New registration을 선택합니다.
- 앱의 Name을 입력합니다. 예:
n8n service principal. - Supported account types에서 Accounts in this organizational directory only를 선택합니다. 리디렉션 URI는 필요하지 않습니다.
- Register를 선택합니다.
- 앱의 Overview 페이지에서 Application (client) ID와 Directory (tenant) ID를 복사합니다. n8n에서 둘 다 필요합니다.
애플리케이션 권한 추가하기#
- 앱 등록에서 API permissions > Add a permission > Microsoft Graph를 선택합니다.
- Application permissions를 선택합니다. Delegated permissions는 선택하지 마세요: 앱 전용 액세스는 위임된 스코프를 무시하며, 두 유형 간 권한 이름도 다릅니다.
- 사용할 노드에 필요한 권한을 추가합니다. 노드별 필수 애플리케이션 권한을 참고하세요.
- Add permissions를 선택합니다.
관리자 동의 부여하기#
- API permissions 페이지에서 **Grant admin consent for
<your-tenant>**를 선택하고 확인합니다. - 모든 권한에 대해 Status 열이 Granted로 표시되는지 확인합니다.
관리자 동의가 없으면 일반적인 권한 오류로 실패합니다
아무도 관리자 동의를 부여하지 않으면, 처음에는 모든 것이 정상으로 보입니다: 자격 증명이 저장되고 Microsoft는 여전히 토큰을 발급합니다. 하지만 토큰에는 권한이 전혀 포함되지 않으므로, 모든 작업이 HTTP 403 Authorization_RequestDenied("Insufficient privileges to complete the operation")와 같은 일반적인 Microsoft Graph 권한 오류로 실패합니다. 자격 증명 값이 문제가 아닙니다.
이를 해결하려면 앱 등록의 API permissions 페이지를 열어 모든 권한이 Granted로 표시되는지 확인하고, 그렇지 않다면 관리자 동의를 부여하세요. n8n은 액세스 토큰을 캐시하므로, 동의를 부여한 후 자격 증명을 다시 테스트하세요. 그래도 계속 실패한다면 자격 증명을 다시 생성해 새 토큰을 강제로 발급받으세요.
클라이언트 시크릿 생성하기#
- 앱 등록에서 Certificates & secrets > Client secrets > New client secret을 선택합니다.
- Description을 입력합니다. 예:
n8n credential. 그리고 만료 기간을 선택합니다. - Add를 선택합니다.
- 시크릿의 Value를 즉시 복사하세요. Microsoft는 이를 한 번만 표시합니다.
n8n에서 자격 증명 생성하기#
n8n에서 새 Microsoft Entra Service Principal 자격 증명을 생성하고 다음 필드를 입력합니다:
- Directory (Tenant) ID: 앱 등록의 Overview 페이지에 있는 Directory(테넌트) ID입니다. 검증된 도메인(예:
contoso.onmicrosoft.com)을 대신 사용할 수도 있습니다. - Application (Client) ID: 앱 등록의 Overview 페이지에 있는 Application(클라이언트) ID입니다.
- Client Secret: 복사한 클라이언트 시크릿 값입니다.
- Microsoft Graph API Base URL: 테넌트가 소버린 클라우드에 있지 않은 한 Global을 유지하세요. 소버린 클라우드 환경을 참고하세요.
인증서 인증을 클라이언트 시크릿 대신 사용하려면 Authentication을 Certificate로 설정하고 개인 키와 인증서를 붙여넣으세요. 인증서는 Certificates & secrets 아래의 앱 등록에 업로드되어 있어야 합니다.
자격 증명을 저장하고 테스트하세요. n8n 2.40.0부터 연결 테스트는 앱이 로그인할 수 있는지만 확인하므로 자체적으로 필요한 애플리케이션 권한이 없습니다. 권한이나 관리자 동의가 누락되어도 테스트는 통과하고, 대신 노드를 실행할 때 실패합니다. n8n 2.40.0 이전에는 테스트가 Microsoft Graph에서 조직 정보를 읽었으므로 Organization.Read.All(또는 Directory.Read.All) 애플리케이션 권한도 필요했습니다.
노드별 필수 애플리케이션 권한#
사용할 모든 노드에 필요한 애플리케이션 권한을 추가한 다음 관리자 동의를 부여하세요. 이 표의 모든 권한은 Microsoft Graph Application 권한이며, Delegated 권한이 아닙니다.
| 노드 | 필요한 애플리케이션 권한 |
|---|---|
| n8n 2.40.0 이전의 모든 노드(자격 증명 테스트) | Organization.Read.All 또는 Directory.Read.All. n8n 2.40.0부터 자격 증명 테스트에는 애플리케이션 권한이 필요하지 않습니다. |
| Microsoft OneDrive 및 Microsoft OneDrive Trigger | Files.ReadWrite.All(읽기 전용 작업과 트리거에는 Files.Read.All로 충분) |
| Microsoft Excel (OneDrive) | Files.ReadWrite.All |
| Microsoft Outlook | Mail.ReadWrite(메시지, 임시 보관함, 폴더, 첨부 파일. 전송 전에 임시 보관함을 생성하거나 업데이트하는 Reply와 Draft: Send에도 필요), Mail.Send(전송 및 회신), Calendars.ReadWrite(캘린더 및 일정), Contacts.ReadWrite(연락처), MailboxSettings.Read(Categories 드롭다운을 불러옴). 사용하는 작업에 필요한 것만 추가하세요. |
| Microsoft Outlook Trigger | Mail.Read |
| Microsoft SharePoint | 읽기 작업에는 Sites.Read.All, 쓰기 작업에는 Sites.ReadWrite.All. 문서 라이브러리의 항목에는 Files.Read.All(Item: Get) 또는 Files.ReadWrite.All(Item: Delete)도 사용할 수 있습니다. 앱을 선택한 사이트로 제한하려면 대신 Sites.Selected를 부여하고 사이트별 액세스 부여하기를 참고하세요. |
| Microsoft SharePoint Trigger | Sites.Read.All. 앱을 선택한 사이트로 제한하려면 대신 Sites.Selected를 부여하고 사이트별 액세스 부여하기를 참고하세요. |
| Microsoft Teams 및 Microsoft Teams Trigger | Team.ReadBasic.All, 그리고 아래 표에서 사용하는 작업에 필요한 권한 |
| Microsoft To Do | Tasks.ReadWrite.All |
Microsoft Teams 노드는 팀을 나열하기 위해 Team.ReadBasic.All이 필요하며, 작업별로 추가 권한이 필요합니다:
| Teams 작업 | 애플리케이션 권한 |
|---|---|
| Activity Notification: Send | TeamsActivity.Send, 그리고 목록에서 수신자를 선택하려면 User.Read.All. 수신자에게는 보조 Teams 앱도 설치되어 있어야 합니다. 활동 알림 보내기를 참고하세요. |
| Channel: Get, Get Many | Channel.ReadBasic.All |
| Channel: Create | Channel.Create |
| Channel: Update | ChannelSettings.ReadWrite.All |
| Channel: Delete | Channel.Delete.All |
| Channel Message: Get, Get Many, Get Many Replies | ChannelMessage.Read.All |
| Online Meeting: Create, Create or Get, Update, Delete | OnlineMeetings.ReadWrite.All, 그리고 organizer에 대한 애플리케이션 액세스 정책. 앱 전용 온라인 회의 허용하기를 참고하세요. |
| Online Meeting: Get | OnlineMeetings.Read.All(또는 OnlineMeetings.ReadWrite.All), 그리고 organizer에 대한 애플리케이션 액세스 정책 |
| Online Meeting: 목록에서 선택하거나 사용자 계정 이름으로 지정한 Organizer | User.Read.All. organizer의 객체 ID를 입력하는 경우에는 필요하지 않습니다. |
| Task: all operations | Tasks.ReadWrite.All |
| Trigger: New Channel | Channel.ReadBasic.All |
| Trigger: New Channel Message | ChannelMessage.Read.All |
| Trigger: New Team Member | TeamMember.Read.All |
사이트별 액세스 부여하기#
테넌트 전체 Sites.Read.All 또는 Sites.ReadWrite.All은 앱에 조직의 모든 SharePoint 사이트에 대한 액세스를 부여합니다. 보안팀이 사이트별로 액세스를 부여하기를 원한다면 대신 Sites.Selected 권한을 사용하세요. Microsoft SharePoint 노드(버전 2부터), Microsoft SharePoint Trigger 노드, Microsoft Excel (SharePoint) 노드가 이를 지원합니다.
사이트별 액세스는 두 단계로 이루어집니다. 두 번째 단계는 Entra 관리 센터나 SharePoint 관리 센터에 해당 페이지가 없어서 많은 설정에서 누락됩니다.
- 권한을 추가하고 관리자 동의를 부여합니다. 앱 등록에서 테넌트 전체
Sites.*권한 대신Sites.Selected애플리케이션 권한을 추가하고 관리자 동의를 부여합니다. - 앱에 각 사이트에 대한 액세스를 부여합니다. 관리자가 앱이 접근해야 하는 사이트마다 한 번씩 Microsoft Graph의 사이트 권한 엔드포인트를 호출합니다.
POST https://graph.microsoft.com/v1.0/sites/<site-id>/permissions
Content-Type: application/json
{
"roles": ["write"],
"grantedToIdentities": [
{
"application": {
"id": "<application-client-id>",
"displayName": "<app-registration-name>"
}
}
]
}
읽기 전용 액세스에는 read 역할을, 노드의 쓰기 작업에는 write 역할을 사용하세요. Graph Explorer 또는 Microsoft Graph를 호출할 수 있는 모든 도구에서 요청을 보낼 수 있습니다. SharePoint 관리자는 대신 PnP PowerShell의 Grant-PnPEntraIDAppSitePermission을 사용할 수 있습니다. 빈 테넌트에서 사이트 액세스 부여까지의 전체 과정은 Azure CLI로 SharePoint 앱 등록 프로비저닝하기를 참고하세요.
요청을 보내는 주체에게는 사이트 권한을 관리할 권한이 필요합니다. Graph Explorer에서는 Modify permissions를 열고 요청을 보내기 전에 Sites.FullControl.All에 동의하세요. 이 요청에 대해 403 Access denied 응답이 오면, 액세스를 부여받는 앱이 아니라 요청을 보내는 계정이나 도구에 해당 권한이 없다는 뜻입니다.
사이트의 <site-id>를 찾으려면 호스트 이름과 경로로 요청하세요: GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/mysite.
Sites.Selected를 사용하면 Microsoft Graph가 테넌트 전체 읽기 권한 없이는 사이트 검색을 지원하지 않으므로 노드가 사이트를 검색하거나 나열할 수 없습니다. 대신 사이트의 URL이나 ID를 붙여넣어 사이트를 선택하세요. 사이트별 권한 부여가 누락되면 작업에서 필요한 권한을 명시한 403 오류로 나타납니다.
앱 전용 온라인 회의 허용하기#
이 자격 증명을 사용하면 Microsoft Teams 노드의 Online Meeting 작업은 노드의 Organizer 필드에서 선택한 사용자를 대신하여 동작합니다. Microsoft Teams 노드는 n8n 2.40.0부터 이를 지원합니다. Microsoft Graph는 Teams 관리자가 해당 사용자에 대한 애플리케이션 액세스 정책을 앱에 부여한 경우에만 이를 허용합니다. 정책이 없으면 모든 Online Meeting 작업이 403 오류로 실패하며, n8n은 요청에 OnlineMeetings.ReadWrite.All 권한과 organizer에 대한 애플리케이션 액세스 정책이 필요하다고 알려 줍니다.
설정 방법은 다음과 같습니다.
-
앱 등록에서
OnlineMeetings.ReadWrite.All애플리케이션 권한을 추가하고 관리자 동의를 부여합니다. Get 작업만 사용한다면OnlineMeetings.Read.All로 충분합니다. 목록에서 organizer를 선택하거나 객체 ID 대신 사용자 계정 이름을 입력하려면User.Read.All도 추가하세요. -
Microsoft Teams PowerShell 모듈을 설치하고 Teams 관리자로 로그인합니다.
Connect-MicrosoftTeams -
앱 등록의 Application (client) ID를 나열하는 애플리케이션 액세스 정책을 생성합니다.
New-CsApplicationAccessPolicy -Identity n8n-online-meetings -AppIds "<application-client-id>" -Description "Lets n8n manage online meetings" -
노드가 대신 동작해야 하는 각 사용자에게 사용자 객체 ID로 정책을 부여합니다.
Grant-CsApplicationAccessPolicy -PolicyName n8n-online-meetings -Identity "<user-object-id>"자체 정책이 없는 테넌트의 모든 사용자를 포함하려면 대신 테넌트 전체에 부여하세요.
Grant-CsApplicationAccessPolicy -PolicyName n8n-online-meetings -Global
정책 변경이 적용되기까지 최대 30분이 걸릴 수 있습니다. 사용자는 한 번에 하나의 애플리케이션 액세스 정책만 가질 수 있으므로, 새 정책을 부여하면 기존 정책이 대체됩니다. 여러 앱이 액세스해야 한다면 모든 앱의 ID를 같은 정책에 나열하세요.
앱 전용 액세스에서 사용할 수 없는 작업#
일부 Microsoft Graph 작업은 로그인한 사용자에게만 존재합니다. 이 자격 증명을 선택하면, 노드는 이러한 작업을 숨기거나 설명 오류로 차단합니다. 이러한 작업이 필요하다면 OAuth2 자격 증명을 사용하세요:
- Microsoft OneDrive: File: Search와 Folder: Search. Microsoft Graph는 로그인한 사용자에게만 드라이브 검색을 제공합니다.
- Microsoft Excel (OneDrive): Workbook: Get Many, 그리고 Workbook 필드에서 이름으로 워크북을 검색하는 기능. 대신 필드를 By ID로 설정하세요.
- Microsoft Teams: Chat, Chat Member, Chat Message 리소스 전체. Channel Message: Create, Reply, Delete, Undo Delete. Group Member 모드의 Task: Get Many. Online Meeting 작업은 사용할 수 있지만 애플리케이션 액세스 정책이 필요합니다. 앱 전용 온라인 회의 허용하기를 참고하세요.
- Microsoft Teams Trigger: New Chat 및 New Chat Message 이벤트, 그리고 전체 감시(watch-all) 옵션. 대신 특정 팀이나 채널을 선택하세요.
Microsoft Outlook, Microsoft Outlook Trigger, Microsoft SharePoint, Microsoft SharePoint Trigger, Microsoft To Do 노드에는 차단된 작업이 없습니다. Microsoft SharePoint 노드에서 사이트 검색에는 Sites.Read.All 애플리케이션 권한이 필요합니다. Sites.Selected만 있는 경우에는 대신 URL이나 ID로 사이트를 선택하세요.
Microsoft OneDrive의 File: Share와 Folder: Share는 계속 사용할 수 있지만, 앱 전용으로 공유 링크를 생성하려면 추가 테넌트 또는 관리자 설정이 필요할 수 있습니다. 노드는 이러한 작업에 대해 알림을 표시합니다.
소버린 클라우드 환경#
테넌트의 클라우드 환경에 맞는 Microsoft Graph API Base URL을 선택하세요:
- Global (
https://graph.microsoft.com): 표준 Microsoft 365 테넌트(기본값) - US Government (
https://graph.microsoft.us): GCC High를 포함한 Azure US Government 테넌트 - US Government DOD (
https://dod-graph.microsoft.us): Azure US Government 국방부(Department of Defense) 테넌트 - China (
https://microsoftgraph.chinacloudapi.cn): 중국의 21Vianet이 운영하는 Microsoft 365
n8n은 일치하는 로그인 엔드포인트를 자동으로 결정합니다. 예를 들어 US Government 클라우드는 login.microsoftonline.us, China는 login.partner.microsoftonline.cn을 사용하므로, 토큰이나 권한 부여 URL을 별도로 설정할 필요가 없습니다. 해당 클라우드의 Entra 관리 센터에서 앱 등록을 완료하면, 노드는 선택한 엔드포인트를 통해 모든 Microsoft Graph 호출을 라우팅합니다.
일반적인 문제#
Microsoft Entra Service Principal 자격 증명에서 흔히 발생하는 오류와 문제입니다:
- 자격 증명 테스트는 통과하지만 모든 작업이 실패합니다. n8n 2.40.0부터 연결 테스트는 앱이 로그인할 수 있는지만 확인하며, 앱이 어떤 권한을 가졌는지는 확인하지 않습니다. 애플리케이션 권한 누락, 관리자 동의 누락, 사이트별 권한 부여 누락은 노드를 실행할 때에야 나타납니다.
- 모든 작업이 일반적인 권한 오류로 실패합니다. 이는 거의 항상 애플리케이션 권한 누락이나 관리자 동의 누락을 의미합니다. 관리자 동의 부여하기의 경고를 참고하세요. Microsoft SharePoint(버전 2) 노드와 Microsoft Excel (SharePoint) 노드는 대신 해당 작업에 필요한 권한을 명시한 더 명확한 메시지를 표시합니다: "The app registration is missing a consented application permission for this operation."
- "Microsoft Entra authentication did not return an access token"과 함께 인증이 실패합니다. Microsoft가 토큰 교환을 거부한 것으로, 예를 들어 AADSTS7000215(잘못된 클라이언트 시크릿), AADSTS7000222(만료된 클라이언트 시크릿), AADSTS700027(거부된 인증서 어설션)이 있습니다. 시크릿의 Secret ID가 아니라 Value를 붙여넣었는지, 시크릿이 만료되지 않았는지, 인증서 인증의 경우 개인 키가 앱 등록에 업로드한 인증서와 일치하는지 확인하세요.
- 권한이나 시크릿 변경 사항이 즉시 적용되지 않습니다. n8n은 액세스 토큰을 캐시합니다. 동의를 부여하거나 시크릿을 교체한 후 자격 증명을 다시 테스트하고, 캐시된 토큰이 계속 실패한다면 다시 생성하세요.
- "Microsoft Entra tenant ID is not a valid GUID or domain." 앱 등록의 Overview 페이지에 있는 Directory(테넌트) ID GUID를 입력하거나,
contoso.onmicrosoft.com과 같은 검증된 도메인을 입력하세요. URL은 입력하지 마세요. - Microsoft Teams 노드의 Online Meeting 작업이 403 오류로 실패합니다. 앱 등록에는
OnlineMeetings.ReadWrite.All애플리케이션 권한과 organizer에 대한 Microsoft Teams 애플리케이션 액세스 정책이 필요합니다. 앱 전용 온라인 회의 허용하기를 참고하세요. 정책 변경이 적용되기까지 최대 30분이 걸릴 수 있습니다.