이 페이지에서는 새 Microsoft 365 테넌트에서 시작해 Microsoft Entra Service Principal 자격 증명을 사용하여 Microsoft SharePoint node가 로그인할 수 있는 앱 등록을 만드는 과정을 안내합니다. 붙여넣을 권한 매니페스트 조각, 실행할 스크립트, 대부분의 설정에서 놓치는 사이트별 권한 부여 방법을 제공합니다.

이 페이지는 앱 등록을 승인하고 생성하는 관리자를 대상으로 합니다. 보안팀이 권한 요청을 검토하는 경우 매니페스트 조각과 권한 표를 확인하면 됩니다.

Microsoft SharePoint node는 node 버전 2부터 앱 전용 액세스를 지원합니다.

시작하기 전에#

다음이 필요합니다.

• 설치되어 있고 az login --tenant <your-tenant-id>로 로그인된 Azure CLI.
• 앱 등록을 만들고 관리자 동의를 부여할 수 있는 계정. 관리자 동의에는 Global Administrator 또는 Privileged Role Administrator 역할이 필요합니다.
• 워크플로에서 사용할 각 SharePoint 사이트의 주소(예: https://contoso.sharepoint.com/sites/mysite).

권한 수준 선택#

세 가지 옵션은 모두 Microsoft Graph Application 권한입니다. 이름이 같은 Delegated 권한은 다른 권한이며 앱 전용 액세스에는 적용되지 않습니다.

Sites.Selected에서는 읽기와 쓰기를 매니페스트에서 선택하지 않습니다. 앱 등록은 하나의 권한만 요청하며, 읽기 또는 쓰기는 앱에 사이트 액세스 권한을 부여할 때 사이트별로 결정합니다.

사이트 검색(Site 필드의 node From List 옵션)에는 테넌트 전체 읽기 권한이 필요합니다. Sites.Selected를 사용한다면 Site 필드를 By URL 또는 By ID로 설정하세요. 둘 다 검색이 필요하지 않습니다.

권한 매니페스트 조각#

이 내용을 n8n-sharepoint-permissions.json으로 저장하세요. Microsoft Graph의 Sites.Selected만 요청하며 다른 권한은 요청하지 않습니다.

[
	{
		"resourceAppId": "00000003-0000-0000-c000-000000000000",
		"resourceAccess": [
			{
				"id": "883ea226-0bf2-4a8f-9f9d-92c9162a727d",
				"type": "Role"
			}
		]
	}
]

테넌트 전체 권한이 필요하다면 id 값 하나만 바꾸세요.

resourceAppId는 Microsoft Graph입니다. SharePoint node는 Microsoft Graph를 호출하므로, 이전 SharePoint Online API(00000003-0000-0ff1-ce00-000000000000)를 대상으로 하는 조각은 node가 사용할 수 있는 권한을 앱에 부여하지 않습니다. type은 항상 Role입니다. Role은 Application 권한을, Scope는 Delegated 권한을 뜻합니다.

이 파일은 두 가지 방법으로 사용할 수 있습니다.

• Azure CLI: 아래 스크립트처럼 --required-resource-accesses @n8n-sharepoint-permissions.json으로 전달합니다.
• Microsoft Entra 관리 센터: 앱 등록을 열고 Manifest를 선택한 다음 배열을 requiredResourceAccess 값으로 붙여넣습니다.

Azure CLI로 앱 등록 프로비저닝#

n8n-sharepoint-permissions.json이 있는 폴더에서 다음 명령을 실행하세요. 앱 등록과 클라이언트 시크릿을 만든 다음 관리자 동의를 부여하며, 이때 앱의 서비스 주체도 함께 생성됩니다.

# Create the app registration for this tenant only, with the permission already requested
APP_ID=$(az ad app create \
	--display-name "n8n SharePoint" \
	--sign-in-audience AzureADMyOrg \
	--required-resource-accesses @n8n-sharepoint-permissions.json \
	--query appId --output tsv)

# Create a client secret valid for one year, and print it once
az ad app credential reset \
	--id "$APP_ID" \
	--display-name "n8n credential" \
	--years 1 \
	--query password --output tsv

# Grant admin consent. This also creates the app's service principal in the tenant
az ad app permission admin-consent --id "$APP_ID"

# Print the two IDs you enter in n8n
echo "Application (client) ID: $APP_ID"
echo "Directory (tenant) ID: $(az account show --query tenantId --output tsv)"

두 번째 명령의 출력에서 시크릿을 복사하세요. Microsoft는 시크릿을 한 번만 표시합니다.

주의할 점은 다음과 같습니다.

• 기존 앱 등록에서는 az ad app credential reset에 --append를 추가하세요. 추가하지 않으면 명령이 앱에 이미 있는 시크릿과 인증서를 제거하여, 이를 사용하는 서비스가 작동을 멈춥니다.
• 동의를 부여하기 전에 az ad sp create를 실행하지 마세요. az ad app permission admin-consent가 서비스 주체를 직접 생성합니다. 이미 서비스 주체가 있으면 동의가 Request_BadRequest 오류와 함께 "The <application-client-id> service principal name is already present for the tenant" 메시지로 실패합니다.
• 관리자 동의가 처음 실행할 때 실패할 수 있습니다. Microsoft Entra가 새 앱 등록을 복제하는 데 몇 초가 필요합니다. 이때 명령이 "Unable to read the company information from the directory"라는 메시지와 함께 Directory_ObjectNotFound를 보고합니다. 잠시 기다린 뒤 다시 실행하세요.
• 관리자 동의가 계속 실패하면 포털에서 부여하세요. az ad app permission admin-consent는 모든 계정에서 작동하지는 않는 레거시 Azure 엔드포인트를 호출합니다. Microsoft Entra 관리 센터에서 앱 등록의 API permissions 페이지를 열고 **Grant admin consent for <your-tenant>**를 선택하세요.

앱에 사이트 액세스 권한 부여#

테넌트 전체 권한을 선택했다면 이 섹션은 건너뛰세요. Sites.Selected 권한만 있는 앱은 관리자가 사이트별로 액세스 권한을 부여하기 전까지 어떤 사이트에도 접근할 수 없습니다. 이 단계는 Microsoft Entra 관리 센터와 SharePoint 관리 센터 어디에도 페이지가 없어서 설정에서 자주 누락됩니다. 이 단계를 완료하기 전에는 모든 작업이 403 오류로 실패합니다.

읽기 전용 워크플로에는 read를, 파일을 업로드하거나 목록 항목을 변경하는 워크플로에는 write를 부여하세요.

사이트 ID가 필요합니다. 주소로 요청해 가져오세요.

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/mysite

PnP PowerShell#

SharePoint 관리자는 PnP PowerShell을 사용할 수 있습니다. 사이트에 연결한 다음 앱에 액세스 권한을 부여하세요.

Connect-PnPOnline -Url "https://contoso.sharepoint.com/sites/mysite" -Interactive -ClientId <pnp-app-client-id>

Grant-PnPEntraIDAppSitePermission -AppId <application-client-id> -DisplayName "n8n SharePoint" -Permissions Write

-Permissions에는 Read, Write, Manage, FullControl을 사용할 수 있습니다. node에는 Read 또는 Write가 필요합니다.

대화형 로그인에는 PnP PowerShell용 별도의 앱 등록이 필요하며, Register-PnPEntraIDAppForInteractiveLogin으로 만들 수 있습니다. 해당 앱의 클라이언트 ID를 -ClientId로 전달하세요.

Microsoft Graph#

Sites.FullControl.All 권한이 있는 관리자로서 사이트마다 요청을 하나씩 보내세요.

POST https://graph.microsoft.com/v1.0/sites/<site-id>/permissions
Content-Type: application/json

{
	"roles": ["write"],
	"grantedToIdentities": [
		{
			"application": {
				"id": "<application-client-id>",
				"displayName": "n8n SharePoint"
			}
		}
	]
}

Graph Explorer에서 이 요청을 보낼 수 있습니다. 먼저 Modify permissions를 열고 Sites.FullControl.All에 동의하세요. 이 요청에서 403 오류가 발생하는 경우의 의미는 사이트별 액세스 권한 부여를 참조하세요.

Azure CLI로 이 단계를 수행할 수 없는 이유#

같은 엔드포인트에 az rest --method POST를 보내면 Global Administrator에게도 403이 반환됩니다. Azure CLI는 Microsoft 소유의 자체 애플리케이션으로 로그인하는데, 이 애플리케이션에는 Sites.FullControl.All 권한이 없습니다. 자신의 앱 등록에서 해당 권한에 동의해도 Azure CLI 토큰이 가진 권한은 바뀌지 않습니다. 대신 PnP PowerShell 또는 Graph Explorer를 사용하세요.

n8n에서 설정 완료#

1. Microsoft Entra Service Principal 자격 증명을 만듭니다. Directory (tenant) ID, Application (client) ID, 스크립트가 출력한 클라이언트 시크릿을 입력합니다. 인증서 옵션과 소버린 클라우드에 대해서는 Microsoft Entra Service Principal 자격 증명을 참조하세요.
2. Microsoft SharePoint node에서 Authentication을 **Microsoft Entra Service Principal (App-Only)**로 설정하고 자격 증명을 선택합니다.
3. Site 필드를 By URL로 설정하고 앱에 액세스 권한을 부여한 사이트 주소를 붙여넣습니다.
4. node를 실행합니다.

n8n 2.40.0부터 자격 증명의 연결 테스트는 앱이 로그인할 수 있는지만 확인합니다. 권한 누락, 관리자 동의 누락, 사이트별 권한 부여 누락은 테스트를 통과하고 node를 실행할 때 작업에 필요한 권한을 명시한 403 오류와 함께 실패합니다.

관련 리소스#

• Microsoft Entra Service Principal 자격 증명
• Microsoft SharePoint node
• Microsoft 자격 증명
• Sites.Selected 개요
• 사이트에 권한 만들기
• Grant-PnPEntraIDAppSitePermission