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 Teams
• Microsoft Teams Trigger
• Microsoft To Do

사전 요구 사항#

• 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 작업에서는 그룹, 플랜, 버킷, 멤버 선택기가 일반 ID 필드로 대체됩니다.
• 권한이 테넌트 전체에 적용됩니다. 애플리케이션 권한은 한 사용자로 범위가 제한되지 않습니다. 예를 들어 Mail.Send 애플리케이션 권한은 Exchange Online 애플리케이션 액세스 정책으로 제한하지 않는 한 앱이 테넌트의 모든 메일함으로 메일을 보낼 수 있게 합니다. n8n은 애플리케이션 액세스 정책으로 테넌트 전체 메일 권한의 범위를 제한할 것을 권장합니다.
• 선택기가 테넌트 전체를 봅니다. 예를 들어 Microsoft Teams의 Team 선택기는 앱이 참여한 팀만이 아니라 조직의 모든 팀을 나열합니다.
• 일부 작업을 사용할 수 없습니다. 노드는 드라이브 검색이나 Teams 채팅과 같이 로그인한 사용자에게만 존재하는 기능을 숨기거나 설명 오류로 차단합니다. 앱 전용 액세스에서 사용할 수 없는 작업을 참고하세요.

앱 등록 설정하기#

n8n에서 자격 증명을 생성하기 전에 Microsoft Entra 관리 센터에서 다음 단계를 완료하세요.

앱 등록하기#

1. Microsoft Entra 관리 센터를 열고 Entra ID > App registrations로 이동합니다.
2. New registration을 선택합니다.
3. 앱의 Name을 입력합니다. 예: n8n service principal.
4. Supported account types에서 Accounts in this organizational directory only를 선택합니다. 리디렉션 URI는 필요하지 않습니다.
5. Register를 선택합니다.
6. 앱의 Overview 페이지에서 Application (client) ID와 Directory (tenant) ID를 복사합니다. n8n에서 둘 다 필요합니다.

애플리케이션 권한 추가하기#

1. 앱 등록에서 API permissions > Add a permission > Microsoft Graph를 선택합니다.
2. Application permissions를 선택합니다. Delegated permissions는 선택하지 마세요: 앱 전용 액세스는 위임된 스코프를 무시하며, 두 유형 간 권한 이름도 다릅니다.
3. 사용할 노드에 필요한 권한을 추가합니다. 노드별 필수 애플리케이션 권한을 참고하세요.
4. Organization.Read.All(또는 더 넓은 범위의 Directory.Read.All)을 추가합니다. n8n 자격 증명 테스트는 Microsoft Graph에서 조직 정보를 읽으므로, 둘 중 하나가 없으면 실패합니다.
5. Add permissions를 선택합니다.

관리자 동의 부여하기#

1. API permissions 페이지에서 **Grant admin consent for <your tenant>**를 선택하고 확인합니다.
2. 모든 권한에 대해 Status 열이 Granted로 표시되는지 확인합니다.

클라이언트 시크릿 생성하기#

1. 앱 등록에서 Certificates & secrets > Client secrets > New client secret을 선택합니다.
2. Description을 입력합니다. 예: n8n credential. 그리고 만료 기간을 선택합니다.
3. Add를 선택합니다.
4. 시크릿의 Value를 즉시 복사하세요. Microsoft는 이를 한 번만 표시합니다.

n8n에서 자격 증명 생성하기#

n8n에서 새 Microsoft Entra Service Principal 자격 증명을 생성하고 다음 필드를 입력합니다:

1. Directory (Tenant) ID: 앱 등록의 Overview 페이지에 있는 Directory(테넌트) ID입니다. 검증된 도메인(예: contoso.onmicrosoft.com)을 대신 사용할 수도 있습니다.
2. Application (Client) ID: 앱 등록의 Overview 페이지에 있는 Application(클라이언트) ID입니다.
3. Client Secret: 복사한 클라이언트 시크릿 값입니다.
4. Microsoft Graph API Base URL: 테넌트가 소버린 클라우드에 있지 않은 한 Global을 유지하세요. 소버린 클라우드 환경을 참고하세요.

자격 증명을 저장하고 테스트하세요. 연결 테스트는 Microsoft Graph의 /v1.0/organization 엔드포인트를 호출하므로, 노드에 필요한 권한을 모두 부여했더라도 관리자 동의를 받은 Organization.Read.All(또는 Directory.Read.All) 애플리케이션 권한이 있어야 통과합니다.

노드별 필수 애플리케이션 권한#

사용할 모든 노드에 필요한 애플리케이션 권한을 추가한 다음 관리자 동의를 부여하세요. 이 표의 모든 권한은 Microsoft Graph Application 권한이며, Delegated 권한이 아닙니다.

Microsoft Teams 노드는 팀을 나열하기 위해 Team.ReadBasic.All이 필요하며, 작업별로 추가 권한이 필요합니다:

앱 전용 액세스에서 사용할 수 없는 작업#

일부 Microsoft Graph 작업은 로그인한 사용자에게만 존재합니다. 이 자격 증명을 선택하면, 노드는 이러한 작업을 숨기거나 설명 오류로 차단합니다. 이러한 작업이 필요하다면 OAuth2 자격 증명을 사용하세요:

• Microsoft OneDrive: File: Search와 Folder: Search. Microsoft Graph는 로그인한 사용자에게만 드라이브 검색을 제공합니다.
• Microsoft Excel (OneDrive): Workbook: Get Many, 그리고 Workbook 필드에서 이름으로 워크북을 검색하는 기능. 대신 필드를 By ID로 설정하세요.
• Microsoft Teams: Chat Message 리소스 전체, Channel Message: Create, Group Member 모드의 Task: Get Many.
• Microsoft Teams Trigger: New Chat 및 New Chat Message 이벤트, 그리고 전체 감시(watch-all) 옵션. 대신 특정 팀이나 채널을 선택하세요.

Microsoft Outlook, Microsoft Outlook Trigger, Microsoft To Do 노드에는 차단된 작업이 없습니다.

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 자격 증명에서 흔히 발생하는 오류와 문제입니다:

• 노드 권한을 부여했는데도 자격 증명 테스트가 실패합니다. 연결 테스트는 GET /v1.0/organization을 호출하며, 관리자 동의를 받은 Organization.Read.All(또는 Directory.Read.All) 애플리케이션 권한이 필요합니다. 이를 추가하고 관리자 동의를 부여하세요.
• 모든 작업이 일반적인 권한 오류로 실패합니다. 이는 거의 항상 애플리케이션 권한 누락이나 관리자 동의 누락을 의미합니다. 관리자 동의 부여하기의 경고를 참고하세요. Microsoft Teams 노드는 대신 더 명확한 메시지를 표시합니다: "The app registration is missing a consented application permission for this operation."
• 권한이나 시크릿 변경 사항이 즉시 적용되지 않습니다. n8n은 액세스 토큰을 캐시합니다. 동의를 부여하거나 시크릿을 교체한 후 자격 증명을 다시 테스트하고, 캐시된 토큰이 계속 실패한다면 다시 생성하세요.
• "Microsoft Entra tenant ID is not a valid GUID or domain." 앱 등록의 Overview 페이지에 있는 Directory(테넌트) ID GUID를 입력하거나, contoso.onmicrosoft.com과 같은 검증된 도메인을 입력하세요. URL은 입력하지 마세요.