Credentials สำหรับ Microsoft Entra Service Principal

การรับรองสำหรับ Microsoft Entra Service Principal ใช้รับรองเหล่านี้เพื่อรับรองบริการ Microsoft ใน n8n ซึ่งเป็นแพลตฟอร์มอัตโนมัติการทำงาน

Microsoft Entra Service Principal credential ให้ n8n app-only access to Microsoft Graph. แทนที่จะลงทะเบียนเป็นบุคคล, n8n authenticates เป็นแอปลงทะเบียนที่ผู้ดูแลระบบตั้งค่าครั้งเดียวในศูนย์บริหาร Microsoft Entra. นี้เหมาะกับการทำงานที่ไม่ได้คาดหวังและแบ่งปัน: ไม่มีเซสชั่นผู้ใช้ที่จะสิ้นสุดและไม่มีความยินยอมต่อผู้ใช้ที่จะจัดการ.

คุณสามารถใช้ credentials เหล่านี้เพื่อตรวจสอบสิทธิ์ node ต่อไปนี้:

• Microsoft Excel (OneDrive)
• Microsoft Excel (SharePoint)
• Microsoft OneDrive
• Microsoft OneDrive Trigger
• Microsoft Outlook
• Microsoft Outlook Trigger
• Microsoft SharePoint
• Microsoft Teams
• Microsoft Teams Trigger
• Microsoft To Do

ข้อกำหนดรุ่น Node (Node version requirements)

Microsoft Excel (OneDrive), Microsoft Outlook, Microsoft SharePoint, และ Microsoft Teams ปุ่มสนับสนุนการรับรองนี้จากรุ่น 2 ของปุ่ม Microsoft Excel (SharePoint) ปุ่มสนับสนุนจากรุ่น 1

ข้อกำหนดเบื้องต้น

• Microsoft 365 ผู้เช่าองค์กรบัญชี Microsoft ส่วนบุคคลไม่สนับสนุนอนุญาตการใช้งาน
• เข้าถึง ไมโครซอฟต์แวร์เข้าศูนย์ admin เป็นผู้ดูแลระบบที่สามารถสร้างการลงทะเบียนแอปและให้ความยินยอมของผู้ดูแลระบบหรือผู้ดูแลระบบที่สามารถให้ความยินยอมสำหรับคุณ

วิธีการรับรองความถูกต้องที่รองรับ

• OAuth2 การรับรองของลูกค้าโดยใช้ Client Secret หรือใบรับรอง (การยืนยันของลูกค้าที่ลงทะเบียน)

ทรัพยากรที่เกี่ยวข้อง

โปรดดูเอกสารของ Microsoft สำหรับข้อมูลเพิ่มเติม:

• ได้รับการเข้าถึงโดยไม่มีผู้ใช้ : วิธีการทำงาน app-only authentication
• การอ้างอิงของ Microsoft Graph permissions
• อนุญาตให้ผู้เชี่ยวชาญผู้เชี่ยวชาญเพื่อการสมัคร

วิธีการเข้าถึงแอปเพียงแตกต่างจาก OAuth2

ด้วยการรับรอง OAuth2 Microsoft nodes act as the user who signed in. ด้วยการรับรอง Service Principal จะไม่มีผู้ใช้ที่ลงชื่อเข้าใช้ จึงต้องใช้ node ต่างจากกรณีที่ทำงานในนามผู้ใช้ดังนี้:

• คุณเลือกว่าใครหรือสิ่งที่ต้องดำเนินการ (You choose who or what to act on.) แต่ละคอยแสดงให้เห็น parameter ที่ต้องการเพิ่มเติมเมื่อคุณเลือกใบรับรองนี้: Access As (ผู้ใช้หรือไดรฟ์) ใน Microsoft OneDrive, Microsoft OneDrive Trigger และ Microsoft Excel (OneDrive) Mailbox ใน Microsoft Outlook และ Microsoft Outlook Trigger และ User ใน Microsoft To Do. ใส่ชื่อผู้ใช้หลัก (UPN) ตัวอย่างเช่น jane@contoso.com , หรือ ID ของวัตถุผู้ใช้ ใน Access As โลกที่คุณสามารถเลือกได้ Drive และป้อน ID drive ไม่มีตัวเลือกรายการสำหรับฟิลด์เหล่านี้: ป้อนค่าโดยตรง ในคิวส์ของ Microsoft Teams Authentication ตัวเลือกที่ระบุไว้ Service Principal (App-Only) และ Task การดำเนินงานซ่อน Team คุกกี้และแทนที่ Plan, Bucket และ Assigned To พิกเกอร์ที่มีฟิลด์ ID ตรง
• ใบอนุญาตใช้ในเครือข่ายเช่า (Permissions apply tenant-wide.) ใบอนุญาตการใช้งานจะไม่ถูกกระจายไปยังผู้ใช้เดียว ตัวอย่างเช่นผู้ใช้ Mail.Send ใบอนุญาตการสมัครอนุญาตให้แอพพลิเคชันส่งเป็นกล่องอีเมลใด ๆ ในผู้เช่ายกเว้นถ้าคุณ จำกัด มันด้วย นโยบายการเข้าถึงแอพพลิเคชัน Exchange Online . n8n เสนอการลบอนุญาตทางอีเมลแบบครอบคลุมโดยใช้นโยบายการเข้าถึงการสมัคร
• ชิ๊กเกอร์เห็นผู้เช่าทั้งหมด (Pickers see the whole tenant.) ตัวอย่างเช่นทีม Microsoft Team picker รายการทุกทีมในองค์กรไม่เพียง แต่ทีมที่แอปได้เข้าร่วม
• การดำเนินงานบางอย่างไม่สามารถใช้ได้ (Some operations aren't available.) ปุ่มซ่อนสิ่งใดที่อยู่เฉพาะสำหรับผู้ใช้ที่ลงทะเบียนเช่นการค้นหาไดรฟ์หรือแชททีมหรือบล็อกมันด้วยข้อผิดพลาดในการอธิบาย การดำเนินงานที่ไม่สามารถเข้าถึงได้ด้วย app-only .

สร้างการลงทะเบียนแอป

เสร็จสมบูรณ์ขั้นตอนเหล่านี้ในศูนย์การจัดการ Microsoft Entra ก่อนที่คุณจะสร้างการรับรองใน n8n เพื่อตั้งค่าการลงทะเบียนแอปสำหรับ node Microsoft SharePoint จากเส้นคำสั่งในทางกลับกัน Provision a SharePoint app registration with the Azure CLI.

ลงทะเบียนแอป (Register an app)

1. เปิด ไมโครซอฟต์แวร์เข้าศูนย์ admin และไป Entra ID > การลงทะเบียน App (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 หน้า, copy the Application (client) ID และ Directory (tenant) ID . คุณจะต้องการทั้งสองใน n8n

เพิ่มใบอนุญาตการใช้งาน (Add application permissions)

1. ในการลงทะเบียนแอปของคุณเลือก ใบอนุญาต API (API permissions) > เพิ่มใบอนุญาต (Add a permission) > Microsoft Graph.
2. เลือก อนุญาตการใช้งาน (Application permissions) อย่าเลือก อนุญาตที่ได้รับอนุญาต (Delegated permissions) : app-only access ignores คู่มือที่ส่งมอบและชื่ออนุญาตแตกต่างกันระหว่างสองประเภท
3. เพิ่มอนุญาตสำหรับช่องที่คุณวางแผนที่จะใช้ ใบอนุญาตการสมัครที่จำเป็นโดย node .
4. เลือก เพิ่มอนุญาต (Add permissions).

ใบอนุญาต admin (Grant admin consent)

1. บน ใบอนุญาต API (API permissions) หน้าที่เลือก อนุญาตให้ admin <your-tenant> และยืนยัน
2. ตรวจสอบว่า Status แสดงคอลัมน์ Granted สำหรับอนุญาตใด ๆ

ความยินยอมของผู้ดูแลระบบที่หายไปล้มเหลวด้วยข้อผิดพลาดการอนุญาตทั่วไป (Missing admin consent fails with a generic permissions error)

หากไม่มีใครอนุญาตให้ผู้ดูแลระบบทุกอย่างดูดีในตอนแรก: การรับรองบันทึกและ Microsoft ยังคงส่ง token แต่ token ไม่มีการอนุญาตดังนั้นการดำเนินการแต่ละครั้งจะล้มเหลวด้วยข้อผิดพลาดอนุญาตทั่วไปของ Microsoft Graph เช่น HTTP 403 Authorization_RequestDenied ("ข้อดีที่ไม่เพียงพอที่จะเสร็จสิ้นการดำเนินงาน"). คะแนนการรับรองไม่ได้เป็นปัญหา

เพื่อแก้ไขมันเปิดการลงทะเบียนแอป ใบอนุญาต API (API permissions) หน้า, ตรวจสอบว่าอนุญาตแต่ละรายการแสดงให้เห็น Granted , และให้ความยินยอมของ admin ถ้าไม่. n8n caches the access token, ดังนั้น retest the credential หลังจากให้ความยินยอม. ถ้ามันยังคงล้มเหลว, recreate the credential to force a fresh token.

สร้าง Client Secret (Create a client secret)

1. ในการลงทะเบียนแอปของคุณเลือก ใบรับรองและความลับ (Certificates & secrets) > Client Secret (Client secrets) > ลูกค้าใหม่ความลับ (New client secret).
2. ป้อนก Description ตัวอย่างเช่น n8n credential , และเลือกการหมดอายุ
3. เลือก Add.
4. คัดลอกความลับ Value ตอนนี้ Microsoft แสดงมันเพียงครั้งเดียว

สร้างการรับรองใน n8n (Create the credential in n8n)

ใน n8n สร้างใหม่ Microsoft Entra Service Principal การรับรองและเติมในพื้นที่เหล่านี้:

1. Directory (Tenant) ID : ID ของไดเรกทอรี (เจ้าของ) จากการลงทะเบียนแอปของคุณ Overview หน้า. คุณยังสามารถใช้โดเมนที่ได้รับการตรวจสอบเช่น contoso.onmicrosoft.com.
2. Application (Client) ID : ID การใช้งาน (ลูกค้า) จากการลงทะเบียนแอปของคุณ Overview หน้า
3. Client Secret : ลูกค้าความลับค่าที่คุณคัดลอก
4. Microsoft Graph API Base URL : เก็บ Global ไม่ว่าผู้เช่าของคุณอยู่ในคลาวด์ของสวีเดน สภาพแวดล้อมคลาวด์ที่สอดคล้องกัน .

เพื่อรับรองด้วยใบรับรองแทนที่ Client Secret Authentication ถึง Certificate และใส่คีย์ส่วนตัวและใบรับรองของคุณ การรับรองจะต้องอัพโหลดไปยังแอปลงทะเบียนด้านล่าง ใบรับรองและความลับ (Certificates & secrets).

การบันทึกและการทดสอบการรับรอง จาก n8n 2.40.0 การทดสอบการเชื่อมต่อเพียงตรวจสอบว่าแอปสามารถลงทะเบียนได้ดังนั้นจึงไม่จำเป็นต้องมีใบอนุญาตการใช้งานของตัวเอง ความยินยอมของผู้ดูแลระบบที่หายไปหรือหายไปผ่านการทดสอบและล้มเหลวเมื่อจุดทำงานแทน ก่อน n8n 2.40.0 การทดสอบอ่านองค์กรของคุณจาก Microsoft Graph ดังนั้นจึงจำเป็นต้องมีใบอนุญาต Organization.Read.All (หรือ Directory.Read.All ) ใบอนุญาตการสมัคร

ใบอนุญาตการสมัครที่จำเป็นโดย node

เพิ่มใบอนุญาตการใช้งานสำหรับแต่ละช่องที่คุณวางแผนที่จะใช้แล้วให้ความยินยอมของผู้ดูแลระบบ ทั้งหมดใบอนุญาตในตารางนี้คือ Microsoft Graph Application อนุญาตและไม่อนุญาตที่ได้รับอนุญาต

Microsoft Teams Node ต้องการ Team.ReadBasic.All รายการทีมรวมถึงใบอนุญาตต่อการดำเนินงาน:

ให้สิทธิ์การเข้าถึงต่อไซต์

โลหะ Sites.Read.All หรือ Sites.ReadWrite.All ให้แอปเข้าถึงทุกเว็บไซต์ SharePoint ในองค์กรของคุณ หากทีมความปลอดภัยของคุณชอบที่จะให้เว็บไซต์เข้าถึงโดยเว็บไซต์ใช้ Sites.Selected ปุ่ม Microsoft SharePoint (จากรุ่น 2) และปุ่ม Microsoft Excel (SharePoint) สนับสนุนมัน

ขั้นตอนที่สองไม่มีหน้าในศูนย์บริหาร Enter หรือศูนย์บริหาร SharePoint ซึ่งเป็นเหตุผลที่การตั้งค่าจำนวนมากพลาดมัน:

1. เพิ่มอนุญาตและให้ความยินยอมของ admin (Add the permission and grant admin consent.) ในแอปลงทะเบียนเพิ่ม Sites.Selected ใบอนุญาตการสมัครในสถานที่ของผู้เช่า Sites.* การอนุญาตและให้ความยินยอมของ admin
2. ให้แอปเข้าถึงทุกเว็บไซต์ (Grant the app access to each site.) ผู้ดูแลระบบโทรหาจุดสิ้นสุดที่อนุญาตเว็บไซต์ของ 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 สำหรับการทำงานในการเขียน node. คุณสามารถส่งคำขอจาก เครื่องตรวจจับกราฟ หรือเครื่องมือใด ๆ ที่สามารถเรียก Microsoft Graph. ผู้ดูแลระบบ SharePoint สามารถใช้ PnP PowerShell Grant-PnPEntraIDAppSitePermission แทน. สำหรับเส้นทางทั้งหมดจากผู้เช่าที่ว่างเปล่าไปยังเว็บไซต์ที่ได้รับอนุญาตให้อ้างถึง Provision a SharePoint app registration with the Azure CLI.

ผู้ส่งคำขอต้องการอนุญาตในการจัดการอนุญาตเว็บไซต์: ใน Graph Explorer เปิด การเปลี่ยนแปลงอนุญาต (Modify permissions) และยินยอมที่จะ Sites.FullControl.All ก่อนที่จะส่ง A 403 Access denied การตอบสนองต่อคำขอนี้หมายความว่าบัญชีหรือเครื่องมือที่ส่งมันขาดอนุญาตนี้ไม่ใช่แอปที่คุณให้การเข้าถึง

ค้นหาเว็บไซต์ <site-id> , กรุณาใช้ชื่อโฮสต์และเส้นทาง: GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/mysite.

ด้วย Sites.Selected , nodes ไม่สามารถค้นหาหรือรายการเว็บไซต์เพราะ Microsoft Graph ไม่สนับสนุนการค้นพบเว็บไซต์โดยไม่ต้องได้รับอนุญาตอ่านที่ครอบคลุม เลือกเว็บไซต์โดยการวาง URL หรือ ID ของมันแทน A missing per site grant surfaces as a 403 error on the operation, naming the permission it needs.

การดำเนินงานที่ไม่สามารถเข้าถึงได้ด้วย app-only

บางการดำเนินงานของ Microsoft Graph มีเฉพาะสำหรับผู้ใช้ที่ลงทะเบียน เมื่อคุณเลือกใบรับรองนี้ nodes ซ่อนหรือบล็อกด้วยข้อผิดพลาดในการอธิบาย ใช้ใบรับรอง OAuth2 ถ้าคุณต้องการพวกเขา:

• Microsoft OneDrive : ไฟล์: ค้นหาและโฟลเดอร์: ค้นหา Microsoft Graph เท่านั้นให้การค้นหาไดรฟ์สำหรับผู้ใช้ที่ลงทะเบียน
• Microsoft Excel (OneDrive) : Workbook: รับจำนวนมากและค้นหาหนังสือทำงานตามชื่อใน Workbook field. set the field to By ID แทน
• Microsoft Teams : ทั้งหมดสมาชิกแชท, โพสต์แชท, และทรัพยากรการประชุมออนไลน์. โพสต์ช่อง: สร้างและตอบ. งาน: รับจำนวนมากในโหมดสมาชิกกลุ่ม.
• Microsoft Teams Trigger : กิจกรรมใหม่แชทและใหม่แชทข้อความและตัวเลือกทั้งหมด เลือกทีมหรือช่องเฉพาะแทน

Microsoft Outlook, Microsoft Outlook Trigger, Microsoft SharePoint, และ Microsoft To Do nodes ไม่มีการทำงานที่ถูกบล็อก ใน Microsoft SharePoint nodes การค้นหาเว็บไซต์ต้องใช้ Sites.Read.All ใบอนุญาตการสมัคร; ด้วยเพียง Sites.Selected , เลือกเว็บไซต์โดย URL หรือ ID แทน

ไฟล์: ส่วนแบ่งและโฟลเดอร์: ส่วนแบ่งใน Microsoft OneDrive จะยังคงมีอยู่ แต่การสร้างลิงค์การแบ่งปันแอปเท่านั้นที่อาจต้องการการกำหนดค่าผู้เช่าหรือผู้ดูแลระบบเพิ่มเติม ปุ่มแสดงการแจ้งเตือนเกี่ยวกับการดำเนินการเหล่านี้

สภาพแวดล้อมคลาวด์ที่สอดคล้องกัน

เลือก Microsoft Graph API Base URL ซึ่งตรงกับสภาพแวดล้อมคลาวด์ของเช่าของคุณ:

• ทั่วโลก ( เว็บไซต์ทางการของ www.microsoft.com ) (Global (https://graph.microsoft.com)) : ตัวแทนเช่ามาตรฐาน Microsoft 365 (เริ่มต้น)
• รัฐบาลสหรัฐอเมริกา ( https://graph.microsoft.us ) (US Government (https://graph.microsoft.us)) : Azure อเมริกันรัฐบาลเช่ารวมถึง GCC สูง
• สหรัฐอเมริกา DOD ( https://dod-graph.microsoft.us ) (US Government DOD (https://dod-graph.microsoft.us)) : Azure อเมริกันรัฐบาลของรัฐบาลของรัฐบาลของรัฐบาลของรัฐบาล
• ประเทศจีน ( https://microsoftgraph.chinacloudapi.cn ) (China (https://microsoftgraph.chinacloudapi.cn)) : Microsoft 365 ที่ดำเนินการโดย 21Vianet ในประเทศจีน

n8n นำไปสู่จุดหมายปลายที่ตรงกันข้ามโดยอัตโนมัติ ตัวอย่างเช่น login.microsoftonline.us สำหรับรัฐบาลสหรัฐอเมริกาคลาวด์และ login.partner.microsoftonline.cn สำหรับประเทศจีนดังนั้นคุณไม่จำเป็นต้องตั้งค่า token หรือ URL ที่ได้รับอนุญาต โปรดเสร็จสมบูรณ์การลงทะเบียนแอปในศูนย์การจัดการ Entra ของ Cloud ของคุณเองและ nodes route ทั้งหมดการโทรของ Microsoft Graph ผ่านจุดสิ้นสุดที่คุณเลือก

ปัญหาทั่วไป

นี่คือข้อผิดพลาดทั่วไปและปัญหาเกี่ยวกับการรับรองหลักของ Microsoft Entra Service:

• การทดสอบการรับรองผ่าน แต่ทุกการดำเนินงานผิดพลาด (The credential test passes but every operation fails.) จาก n8n 2.40.0 การทดสอบการเชื่อมต่อเพียงตรวจสอบว่าแอปสามารถลงชื่อเข้าได้ไม่ใช่อนุญาตที่มันถือได้ อนุญาตการใช้งานที่ขาดหายหายหายหายหายหายหายหายหายหายหายหายหายหายหายหายหายหายหายหายหายหายหาย
• การดำเนินงานแต่ละครั้งทำลายด้วยข้อผิดพลาดการอนุญาตทั่วไป (Every operation fails with a generic permissions error.) นี่มักหมายถึงการขาดอนุญาตการสมัครหรือการขาดความยินยอมของผู้ดูแลระบบ หมายถึงการแจ้งเตือน ใบอนุญาต admin คู่ Microsoft SharePoint (เวอร์ชัน 2) และ Microsoft Excel (SharePoint) แสดงข้อความที่ชัดเจนขึ้นแทนที่ชื่ออนุญาตการดำเนินงานที่ต้องการ: "การลงทะเบียนแอปขาดอนุญาตการใช้งานที่ได้รับอนุญาตสำหรับการดำเนินงานนี้"
• การรับรองผิดพลาดกับ "การรับรอง Microsoft Entra ไม่ได้คืน token การเข้าถึง" Microsoft ได้ปฏิเสธการแลกเปลี่ยน token เช่น AADSTS7000215 (Client Secret ที่ไม่ถูกต้อง), AADSTS7000222 (Client Secret ที่สิ้นสุด) หรือ AADSTS700027 (การยืนยันการรับรองที่ปฏิเสธ) ตรวจสอบว่าคุณได้ปฏิบัติตาม Client Secret Value แทนที่รหัสลับของมันที่รหัสลับไม่ได้หมดอายุและสำหรับใบรับรองการรับรองที่รหัสลับตรงกับใบรับรองที่อัปโหลดไปยังแอปลงทะเบียน
• การอนุญาตหรือการเปลี่ยนแปลงที่ลับไม่ได้มีผลทันที (Permission or secret changes don't take effect right away.) n8n cache the access token. ลบการรับรองหลังจากได้รับความยินยอมหรือหมุนความลับและรีไซเคิลมันถ้า token cache ยังคงขาด.
• "Microsoft Entra ID ผู้เช่าไม่ได้เป็น GUID หรือโดเมนที่ถูกต้อง" ("Microsoft Entra tenant ID is not a valid GUID or domain.") เข้าสู่ระบบ (ผู้ถือ) ID GUID จากการลงทะเบียนแอป Overview หน้าหรือโดเมนที่ได้รับการยืนยันเช่น contoso.onmicrosoft.com ไม่ใส่ URL