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

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

เคล็ดลับ:

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

GitHub App กับ OAuth App

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

คุณสมบัติ	GitHub App	OAuth App
สิทธิ์ (Permissions)	สิทธิ์แบบละเอียด — ขอเข้าถึงเฉพาะทรัพยากรที่ต้องการเท่านั้น	ขอบเขตกว้าง — มักให้สิทธิ์มากเกินความจำเป็น
การจัดการสิทธิ์ (Permission management)	กำหนดในแดชบอร์ด GitHub เท่านั้น; ช่อง Scope ของ Logto สามารถเว้นว่างได้	กำหนดผ่าน scopes ในตัวเชื่อมต่อ Logto
โทเค็นรีเฟรช (Refresh tokens)	ออกให้เสมอระหว่าง OAuth flow	ไม่รองรับ — โทเค็นจะไม่มีวันหมดอายุเว้นแต่จะถูกเพิกถอน
อายุโทเค็น (Token expiration)	โทเค็นการเข้าถึงหมดอายุหลัง 8 ชั่วโมง; โทเค็นรีเฟรชใช้ได้ 6 เดือน	โทเค็นการเข้าถึงไม่มีวันหมดอายุ
การควบคุมโดยผู้ใช้ (User control)	ผู้ใช้เลือกได้ว่าแอปจะเข้าถึง repository ใดบ้าง	เข้าถึง repository ทั้งหมดที่ผู้ใช้เข้าถึงได้
ขีดจำกัดอัตรา (Rate limits)	ขีดจำกัดอัตราสูงขึ้นและปรับตามจำนวนการติดตั้ง	ขีดจำกัดอัตราต่ำกว่า (5,000 คำขอ/ชั่วโมง/ผู้ใช้)
การติดตั้ง (Installation)	ติดตั้งบนบัญชี/องค์กรพร้อมการเข้าถึง repository แบบละเอียด	อนุญาตโดยผู้ใช้ด้วยการเข้าถึงแบบกว้าง
Webhooks	รองรับ webhook แบบศูนย์กลางในตัว	ต้องตั้งค่าแยกสำหรับแต่ละ repository
การทำงานอิสระ (Acting independently)	สามารถทำงานแทนตัวเอง (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 เพื่อให้แอปของคุณสามารถ:

• เพิ่มการยืนยันตัวตน “ลงชื่อเข้าใช้ด้วย GitHub”
• เชื่อมโยงบัญชีผู้ใช้กับตัวตน GitHub
• ซิงค์ข้อมูลโปรไฟล์ผู้ใช้จาก GitHub
• เข้าถึง GitHub API ผ่านการจัดเก็บโทเค็นอย่างปลอดภัยใน Logto Secret Vault สำหรับงานอัตโนมัติ (เช่น สร้าง issue บน GitHub, จัดการ 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 ของผู้ใช้ปลายทางได้ เลือกตัวเลือกที่ตรงกับความต้องการของคุณ:

เปิดใช้งาน “ลงชื่อเข้าใช้ด้วย GitHub”

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

เรียนรู้เพิ่มเติมเกี่ยวกับ ประสบการณ์การลงชื่อเข้าใช้โซเชียล

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

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

เคล็ดลับ:

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

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

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

เนื่องจาก GitHub Apps จะออกโทเค็นรีเฟรชเสมอระหว่าง OAuth flow Logto จะจัดเก็บทั้งโทเค็นการเข้าถึง (access tokens) และโทเค็นรีเฟรช (refresh tokens) โทเค็นการเข้าถึงจะหมดอายุหลัง 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