ตั้งค่าการเข้าสู่ระบบโซเชียลด้วย GitHub ผ่าน GitHub App (Set up social login with GitHub via GitHub App)

ผสานรวม GitHub App เพื่อเปิดใช้งานการลงชื่อเข้าใช้ด้วย GitHub, การเชื่อมโยงบัญชี, และการเข้าถึง GitHub API อย่างปลอดภัยด้วยสิทธิ์แบบละเอียดและโทเค็นรีเฟรช (refresh tokens)

เคล็ดลับ:

คู่มือนี้สมมติว่าคุณมีความเข้าใจพื้นฐานเกี่ยวกับ ตัวเชื่อมต่อ (Connectors) ของ Logto หากคุณยังไม่คุ้นเคย โปรดดูคู่มือ ตัวเชื่อมต่อ (Connectors) เพื่อเริ่มต้น

GitHub App กับ OAuth App

GitHub มีแอปสองประเภทสำหรับการยืนยันตัวตนและการเข้าถึง API: GitHub Apps และ OAuth Apps ตารางเปรียบเทียบนี้จะช่วยให้คุณเลือกได้ง่ายขึ้น:

ฟีเจอร์	GitHub App	OAuth App
สิทธิ์ (Permissions)	สิทธิ์แบบละเอียด — ขอเข้าถึงเฉพาะทรัพยากรที่ต้องการเท่านั้น	ขอบเขตกว้าง — มักให้สิทธิ์มากเกินความจำเป็น
การจัดการสิทธิ์	กำหนดในแดชบอร์ด GitHub เท่านั้น; ช่อง Scope ของ Logto สามารถเว้นว่างได้	กำหนดผ่าน scopes ในตัวเชื่อมต่อ Logto
โทเค็นรีเฟรช (Refresh tokens)	ออกให้เสมอระหว่าง OAuth flow	ไม่รองรับ — โทเค็นจะไม่มีวันหมดอายุหากไม่ถูกเพิกถอน
การหมดอายุของโทเค็น	โทเค็นการเข้าถึงหมดอายุหลัง 8 ชั่วโมง; โทเค็นรีเฟรชใช้ได้ 6 เดือน	โทเค็นการเข้าถึงไม่มีวันหมดอายุ
การควบคุมโดยผู้ใช้	ผู้ใช้เลือกได้ว่าแอปจะเข้าถึง repository ใดบ้าง	เข้าถึง repository ทั้งหมดที่ผู้ใช้เข้าถึงได้
ขีดจำกัดอัตรา (Rate limits)	ขีดจำกัดอัตราสูงขึ้นและปรับตามจำนวนการติดตั้ง	ขีดจำกัดอัตราต่ำกว่า (5,000 คำขอ/ชั่วโมง/ผู้ใช้)
การติดตั้ง	ติดตั้งบนบัญชี/องค์กร พร้อมการเข้าถึง repository แบบละเอียด	อนุญาตโดยผู้ใช้ด้วยสิทธิ์กว้าง
Webhooks	รองรับ webhook แบบศูนย์กลางในตัว	ต้องตั้งค่าแยกแต่ละ repository
การทำงานอิสระ	สามารถทำงานแทนตัวเอง (server-to-server) ได้	ทำงานแทนผู้ใช้เสมอ

ควรใช้ GitHub App เมื่อ:

• คุณต้องการควบคุมสิทธิ์และการเข้าถึง repository อย่างละเอียด
• คุณต้องการโทเค็นรีเฟรชสำหรับการเข้าถึง API ระยะยาวที่ปลอดภัยยิ่งขึ้น
• คุณต้องการขีดจำกัดอัตรา API ที่สูงขึ้น
• คุณต้องการทำงานอัตโนมัติที่ไม่ขึ้นกับเซสชันของผู้ใช้

ควรใช้ OAuth App เมื่อ:

• ต้องการผสานรวมการลงชื่อเข้าใช้ง่าย ๆ โดยไม่ต้องเข้าถึง API มาก
• ต้องการโทเค็นที่ไม่มีวันหมดอายุ (สำหรับการผสานรวมแบบเก่า)
• ต้องการเข้าถึงทรัพยากรระดับองค์กร (GitHub Apps ยังไม่รองรับสิทธิ์ระดับองค์กร)

เคล็ดลับ:

GitHub แนะนำให้ใช้ GitHub Apps แทน OAuth Apps ในกรณีส่วนใหญ่ เนื่องจากมีความปลอดภัยสูงกว่าและสิทธิ์แบบละเอียด ศึกษาเพิ่มเติมเกี่ยวกับ ความแตกต่างระหว่าง GitHub Apps และ OAuth Apps

เริ่มต้นใช้งาน

ตัวเชื่อมต่อ GitHub App ช่วยให้ผสานรวม OAuth 2.0 เพื่อให้แอปของคุณสามารถ:

• เพิ่มการยืนยันตัวตน “Sign-in with GitHub”
• เชื่อมโยงบัญชีผู้ใช้กับเอกลักษณ์ GitHub
• ซิงค์ข้อมูลโปรไฟล์ผู้ใช้จาก GitHub
• เข้าถึง GitHub API ผ่านการจัดเก็บโทเค็นอย่างปลอดภัยใน Logto Secret Vault สำหรับงานอัตโนมัติ (เช่น สร้าง issue, จัดการ repository จากแอปของคุณ)
• ใช้ โทเค็นรีเฟรช (refresh tokens) (GitHub Apps ออกให้เสมอ) เพื่อรักษาการเข้าถึง API ระยะยาวโดยไม่ต้องให้ผู้ใช้ยืนยันตัวตนซ้ำ

ในการตั้งค่าฟีเจอร์การยืนยันตัวตนเหล่านี้ ให้สร้างตัวเชื่อมต่อ GitHub ใน Logto ก่อน:

1. ไปที่ Logto console > Connector > Social connector
2. คลิก Add social connector เลือก GitHub App คลิก Next และทำตามขั้นตอนในบทเรียนเพื่อผสานรวมให้สมบูรณ์

ขั้นตอนที่ 1: สร้าง GitHub App

ก่อนที่คุณจะใช้ GitHub เป็นผู้ให้บริการการยืนยันตัวตน คุณต้องสร้าง GitHub App บน GitHub เพื่อรับข้อมูลประจำตัว OAuth 2.0

1. ไปที่ GitHub และลงชื่อเข้าใช้ด้วยบัญชีของคุณ หรือสร้างบัญชีใหม่หากจำเป็น
2. ไปที่ Settings > Developer settings > GitHub Apps
3. คลิก New GitHub App เพื่อจดทะเบียนแอปใหม่:
   • GitHub App name: กรอกชื่อแอปของคุณที่ไม่ซ้ำกัน ชื่อไม่เกิน 34 ตัวอักษรและต้องไม่ซ้ำกับแอปอื่นใน GitHub
   • Homepage URL: กรอก URL หน้าแรกของแอปพลิเคชันของคุณ
   • Callback URL: คัดลอก Callback URI จากตัวเชื่อมต่อ GitHub ของคุณใน Logto แล้ววางที่นี่ คุณสามารถเพิ่ม Callback URL ได้หลายรายการหากต้องการ หลังจากผู้ใช้ลงชื่อเข้าใช้ด้วย GitHub แล้ว จะถูกเปลี่ยนเส้นทางมาที่นี่พร้อมรหัสการอนุญาตที่ Logto ใช้เพื่อดำเนินการยืนยันตัวตนให้เสร็จสมบูรณ์
   • Expire user authorization tokens: ให้ติ๊ก ถูก (แนะนำ) เพื่อเปิดใช้งานการหมดอายุของโทเค็นและโทเค็นรีเฟรชเพื่อความปลอดภัยที่มากขึ้น
   • Request user authorization (OAuth) during installation: เลือกตัวเลือกนี้หากต้องการให้ผู้ใช้อนุญาตแอประหว่างการติดตั้ง
   • Webhook: ยกเลิกการเลือก Active หากคุณไม่ต้องการรับเหตุการณ์ webhook สำหรับกรณีใช้งานเฉพาะการยืนยันตัวตน มักไม่จำเป็นต้องใช้ webhook
4. ในส่วน Permissions กำหนดสิทธิ์ที่แอปของคุณต้องการ (ดูรายละเอียดในขั้นตอนที่ 2 ด้านล่าง)
5. ในส่วน Where can this GitHub App be installed? เลือก Any account หากคุณต้องการให้ผู้ใช้จากบัญชี GitHub ใดก็ได้ใช้แอปของคุณเพื่อการยืนยันตัวตน
6. คลิก Create GitHub App เพื่อสร้าง GitHub App

บันทึก:

แตกต่างจาก OAuth Apps, GitHub Apps ใช้สิทธิ์แบบละเอียด (fine-grained permissions) แทนขอบเขต (scopes) แบบกว้าง คุณกำหนดสิทธิ์ในแดชบอร์ด GitHub ระหว่างการสร้างแอป และผู้ใช้จะอนุญาตการเข้าถึง repository เฉพาะระหว่างการอนุญาต

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการตั้งค่า GitHub Apps ได้ที่ Registering a GitHub App

ขั้นตอนที่ 2: กำหนดสิทธิ์ใน GitHub

GitHub Apps ใช้สิทธิ์แบบละเอียด (fine-grained permissions) แทน OAuth scopes คุณต้องกำหนดสิทธิ์ ในแดชบอร์ด GitHub ขณะสร้างหรือแก้ไข GitHub App ของคุณ สิทธิ์เหล่านี้จะกำหนดว่าแอปของคุณสามารถเข้าถึงข้อมูลใดได้บ้าง

ทำความเข้าใจสิทธิ์ของ GitHub App

สิทธิ์แบ่งออกเป็น 3 ประเภท:

• Repository permissions: เข้าถึงทรัพยากรระดับ repository (โค้ด, issues, pull requests ฯลฯ)
• Organization permissions: เข้าถึงทรัพยากรระดับองค์กร (สมาชิก, ทีม, โปรเจกต์ ฯลฯ)
• Account permissions: เข้าถึงข้อมูลบัญชีผู้ใช้ (อีเมล, โปรไฟล์, ผู้ติดตาม ฯลฯ)

สำหรับแต่ละสิทธิ์ คุณสามารถเลือกได้ว่า:

• No access: แอปไม่สามารถเข้าถึงทรัพยากรนี้
• Read-only: แอปอ่านได้แต่ไม่สามารถแก้ไขทรัพยากรนี้
• Read & write: แอปอ่านและแก้ไขทรัพยากรนี้ได้

สิทธิ์ที่แนะนำสำหรับการยืนยันตัวตน

สำหรับฟังก์ชัน "Sign in with GitHub" พื้นฐาน ให้กำหนด Account permissions ขั้นต่ำดังนี้:

Permission	Access level	Purpose
Email addresses	Read-only	รับอีเมลของผู้ใช้เพื่อสร้างบัญชีผู้ใช้

เคล็ดลับ:

GitHub Apps สามารถอ่านข้อมูลโปรไฟล์สาธารณะของผู้ใช้ได้โดยอัตโนมัติเมื่อดำเนินการในนามของผู้ใช้ คุณไม่จำเป็นต้องขอสิทธิ์สำหรับข้อมูลโปรไฟล์พื้นฐาน เช่น ชื่อผู้ใช้, รูปโปรไฟล์, และ URL โปรไฟล์สาธารณะ

สิทธิ์เพิ่มเติมสำหรับการเข้าถึง API

หากแอปของคุณต้องการเข้าถึง GitHub API มากกว่าการยืนยันตัวตน ให้เพิ่มสิทธิ์ที่เกี่ยวข้องในแดชบอร์ด GitHub ตัวอย่างที่พบบ่อย:

Permission type	Permission	Access level	Use case
Repository	Contents	Read-only / Read & write	เข้าถึงไฟล์และโค้ดใน repository
Repository	Issues	Read & write	สร้างและจัดการ issues
Repository	Pull requests	Read & write	สร้างและจัดการ pull requests
Repository	Metadata	Read-only	เข้าถึง metadata ของ repository (จำเป็นสำหรับหลายกรณี)
Organization	Members	Read-only	แสดงรายชื่อสมาชิกองค์กร
Account	Followers	Read-only	เข้าถึงผู้ติดตามและการติดตามของผู้ใช้

นี่ไม่ใช่รายการทั้งหมด — GitHub Apps รองรับสิทธิ์แบบละเอียดอีกมากมาย ดู Permissions required for GitHub Apps สำหรับรายการทั้งหมด

ความแตกต่างสำคัญจาก OAuth Apps:

แตกต่างจาก OAuth Apps ที่คุณกำหนด scopes ในตัวเชื่อมต่อ Logto, สิทธิ์ของ GitHub App จะถูกจัดการทั้งหมดในแดชบอร์ด GitHub คุณสามารถเว้นว่างช่อง Scope ในตัวเชื่อมต่อ GitHub ของ Logto ได้เลย — ไม่จำเป็นต้องใช้ เพราะ GitHub Apps ไม่ใช้ OAuth scopes แบบเดิม

เพียงกำหนดสิทธิ์ที่คุณต้องการใน GitHub และผู้ใช้จะได้รับแจ้งให้อนุญาตระหว่างการอนุญาต

ขั้นตอนที่ 3: กำหนดค่าตัวเชื่อมต่อ Logto ของคุณ

หลังจากสร้าง GitHub App แล้ว คุณจะถูกเปลี่ยนเส้นทางไปยังหน้าตั้งค่าซึ่งคุณสามารถรับข้อมูลประจำตัวได้

1. ในหน้าตั้งค่าของ GitHub App ของคุณ คัดลอก Client ID แล้ววางลงในช่อง clientId ใน Logto
2. ในส่วน Client secrets คลิก Generate a new client secret คัดลอกรหัสลับที่สร้างขึ้นแล้ววางลงในช่อง clientSecret ใน Logto
3. คลิก Save and Done ใน Logto เพื่อเชื่อมต่อระบบข้อมูลระบุตัวตนของคุณกับ GitHub

คำเตือน:

เก็บรักษา Client secret ของคุณให้ปลอดภัยและอย่าเปิดเผยในโค้ดฝั่งไคลเอนต์ หากคุณทำ Client secret หายจะไม่สามารถกู้คืนได้ — คุณต้องสร้างใหม่เท่านั้น

บันทึก:

Client ID สำหรับ GitHub App แตกต่างจาก App ID โปรดใช้ Client ID (แสดงเป็น "Client ID" ในหน้าตั้งค่า) ไม่ใช่ App ID

ขั้นตอนที่ 4: การตั้งค่าทั่วไป

นี่คือการตั้งค่าทั่วไปบางอย่างที่แม้จะไม่ขัดขวางการเชื่อมต่อกับ GitHub แต่ก็อาจมีผลต่อประสบการณ์การยืนยันตัวตนของผู้ใช้ปลายทาง

ซิงค์ข้อมูลโปรไฟล์

ในตัวเชื่อมต่อ GitHub คุณสามารถกำหนดวิธีซิงค์ข้อมูลโปรไฟล์จากข้อมูลผู้ใช้ GitHub ไปยังโปรไฟล์ผู้ใช้ใน Logto เช่น name, avatar, และ email โดยเลือกได้ดังนี้:

• ซิงค์เฉพาะตอนสมัครสมาชิก: ดึงข้อมูลโปรไฟล์ครั้งเดียวเมื่อผู้ใช้ลงชื่อเข้าใช้ครั้งแรก
• ซิงค์ทุกครั้งที่ลงชื่อเข้าใช้: อัปเดตข้อมูลโปรไฟล์ทุกครั้งที่ผู้ใช้ลงชื่อเข้าใช้

เก็บโทเค็นเพื่อเข้าถึง GitHub APIs (ไม่บังคับ)

หากคุณต้องการเข้าถึง GitHub APIs และดำเนินการต่าง ๆ ด้วยการอนุญาตของผู้ใช้ (ไม่ว่าจะผ่าน social sign-in หรือ account linking) ให้เปิดใช้งานการเก็บโทเค็นใน Logto:

1. กำหนดสิทธิ์ที่ต้องการในหน้าตั้งค่า GitHub App ของคุณ (ขั้นตอนที่ 2)
2. เปิดใช้งาน Store tokens for persistent API access ในตัวเชื่อมต่อ GitHub ของ Logto Logto จะเก็บทั้งโทเค็นการเข้าถึง (access token) และโทเค็นรีเฟรช (refresh token) ไว้อย่างปลอดภัยใน Secret Vault

บันทึก:

เนื่องจาก GitHub Apps ออกโทเค็นรีเฟรชเสมอ Logto จะเก็บทั้งสองโทเค็นโดยอัตโนมัติ โทเค็นการเข้าถึงจะหมดอายุหลัง 8 ชั่วโมง แต่ Logto สามารถใช้โทเค็นรีเฟรชเพื่อขอโทเค็นใหม่ได้ ทำให้เข้าถึง API ได้ต่อเนื่องสูงสุด 6 เดือน

ขั้นตอนที่ 5: ทดสอบการเชื่อมต่อของคุณ (ไม่บังคับ)

ก่อนเปิดใช้งานจริง ให้ทดสอบการเชื่อมต่อ GitHub App ของคุณ:

1. ใช้ตัวเชื่อมต่อใน Logto tenant สำหรับการพัฒนา
2. ตรวจสอบว่าผู้ใช้สามารถลงชื่อเข้าใช้ด้วย GitHub ได้
3. ตรวจสอบว่าผู้ใช้ได้รับแจ้งขอสิทธิ์ที่ถูกต้องระหว่างการอนุญาต
4. หากคุณเปิดใช้งานการเก็บโทเค็น ให้ตรวจสอบว่า access token (และ refresh token) ถูกเก็บไว้อย่างถูกต้อง
5. ทดสอบเรียก API โดยใช้โทเค็นที่เก็บไว้เพื่อให้แน่ใจว่าสิทธิ์ทำงานถูกต้อง

GitHub Apps สามารถใช้งานได้กับบัญชีผู้ใช้ GitHub ใด ๆ ทันที — ไม่จำเป็นต้องมีผู้ใช้ทดสอบหรือขออนุมัติแอปเหมือนบางแพลตฟอร์ม อย่างไรก็ตาม หากแอปของคุณถูกติดตั้งในองค์กร เจ้าขององค์กรอาจต้องอนุมัติการติดตั้ง

ใช้งานตัวเชื่อมต่อ GitHub

เมื่อคุณสร้างตัวเชื่อมต่อ GitHub และเชื่อมต่อกับ GitHub แล้ว คุณสามารถนำไปใช้ใน flow สำหรับผู้ใช้ปลายทางได้ เลือกตัวเลือกที่ตรงกับความต้องการของคุณ:

เปิดใช้งาน “Sign-in with GitHub”

1. ใน Logto Console ไปที่ Sign-in & account > Sign-up and sign-in
2. เพิ่มตัวเชื่อมต่อ GitHub ในส่วน Social sign-in เพื่อให้ผู้ใช้ยืนยันตัวตนด้วย GitHub

ศึกษาข้อมูลเพิ่มเติมเกี่ยวกับ ประสบการณ์การเข้าสู่ระบบโซเชียล

เชื่อมโยงหรือยกเลิกการเชื่อมโยงบัญชี GitHub

ใช้ Account API เพื่อสร้างศูนย์บัญชี (Account Center) แบบกำหนดเองในแอปของคุณ ให้ผู้ใช้ที่ลงชื่อเข้าใช้เชื่อมโยงหรือยกเลิกการเชื่อมโยงบัญชี GitHub ของตน ดูบทเรียน Account API

เคล็ดลับ:

สามารถเปิดใช้งานตัวเชื่อมต่อ GitHub เฉพาะสำหรับการเชื่อมโยงบัญชีและการเข้าถึง API โดยไม่ต้องเปิดใช้งานสำหรับ social sign-in ก็ได้

เข้าถึง GitHub API และดำเนินการต่าง ๆ

แอปของคุณสามารถดึงโทเค็น GitHub ที่จัดเก็บไว้จาก Secret Vault เพื่อเรียกใช้ GitHub API และทำงาน backend อัตโนมัติ (เช่น สร้าง issue, จัดการ repository หรือ workflow อัตโนมัติ) ดูคู่มือการดึงโทเค็นที่จัดเก็บไว้เพื่อเข้าถึง API

เนื่องจาก GitHub Apps ออกโทเค็นรีเฟรชเสมอระหว่าง OAuth flow Logto จะจัดเก็บทั้งโทเค็นการเข้าถึงและโทเค็นรีเฟรช โทเค็นการเข้าถึงหมดอายุหลัง 8 ชั่วโมง แต่ Logto จะใช้โทเค็นรีเฟรช (ใช้ได้ 6 เดือน) เพื่อขอโทเค็นใหม่โดยอัตโนมัติ ทำให้การเข้าถึง API ต่อเนื่องไม่สะดุด

จัดการเอกลักษณ์ GitHub ของผู้ใช้

หลังจากผู้ใช้เชื่อมโยงบัญชี GitHub แล้ว ผู้ดูแลระบบสามารถจัดการการเชื่อมต่อนี้ใน Logto Console ได้ดังนี้:

1. ไปที่ Logto console > User management และเปิดโปรไฟล์ของผู้ใช้
2. ในส่วน Social connections ค้นหารายการ GitHub แล้วคลิก Manage
3. ในหน้านี้ ผู้ดูแลระบบสามารถจัดการการเชื่อมต่อ GitHub ของผู้ใช้ ดูข้อมูลโปรไฟล์ทั้งหมดที่ได้รับและซิงค์จากบัญชี GitHub และตรวจสอบสถานะโทเค็นการเข้าถึงและโทเค็นรีเฟรช

บันทึก:

ต่างจาก OAuth Apps ที่ใช้ scopes, GitHub Apps ใช้สิทธิ์แบบละเอียดที่กำหนดในแดชบอร์ด GitHub โทเค็นการเข้าถึงของผู้ใช้จะถูกจำกัดตามสิทธิ์ที่ทั้งแอปและผู้ใช้มี Logto ไม่สามารถแสดงรายการสิทธิ์ได้โดยตรง แต่แอปของคุณจะเข้าถึงได้ตามที่กำหนดไว้ใน GitHub App settings

อ้างอิง

เอกสารนักพัฒนา GitHub - เกี่ยวกับ GitHub Apps

เอกสารนักพัฒนา GitHub - การลงทะเบียน GitHub App

เอกสารนักพัฒนา GitHub - การสร้าง user access tokens

เอกสารนักพัฒนา GitHub - การรีเฟรช user access tokens

GitHub Apps vs OAuth Apps