เครื่องต่อเครื่อง: การยืนยันตัวตนกับ Logto

บันทึก:

คู่มือนี้ถือว่าคุณได้สร้างแอปพลิเคชันประเภท "Machine-to-machine" ใน Admin Console แล้ว

แนะนำ

เครื่องต่อเครื่อง (Machine-to-machine; M2M) เป็นแนวปฏิบัติทั่วไปสำหรับการยืนยันตัวตนหากคุณมีแอป (ไม่ใช่ผู้ใช้) ที่ต้องสื่อสารกับทรัพยากรโดยตรง (โดยปกติแล้วแอป M2M ไม่ต้องมีการโต้ตอบกับผู้ใช้ จึงไม่มี UI) เช่น บริการ API ที่อัปเดตข้อมูลผู้ใช้แบบกำหนดเองใน Logto, บริการสถิติที่ดึงคำสั่งซื้อรายวัน ฯลฯ

เนื่องจาก Logto ใช้ RBAC เป็นนโยบายควบคุมการเข้าถึง การกำหนดบทบาท M2M ให้กับแอป M2M จึงเป็นสิ่งจำเป็นเพื่อปกป้อง API ของคุณที่ต้องการการสื่อสารโดยตรงระหว่างบริการ

ข้อมูล:

เพื่อเรียนรู้เกี่ยวกับ RBAC ปัจจุบันของเราและความแตกต่างระหว่างบทบาทผู้ใช้กับบทบาท M2M ดูที่ กำหนดค่าบทบาทระดับโกลบอล เพื่อศึกษารายละเอียดเพิ่มเติม

มีกรณีการใช้งานหลัก 2 แบบของแอปเครื่องต่อเครื่องใน Logto:

1. เข้าถึง Logto Management API: ในกรณีนี้ คุณต้องกำหนดบทบาท M2M ที่มีสิทธิ์ all จาก Logto Management API ที่มีมาให้กับแอป M2M ของคุณ
2. เข้าถึงทรัพยากร API ของคุณ: ในกรณีนี้ คุณต้องกำหนดบทบาท M2M ที่มีสิทธิ์จากทรัพยากร API ของคุณให้กับแอป M2M

ระหว่างกระบวนการสร้างแอป M2M คุณจะถูกนำไปยังหน้าที่คุณสามารถกำหนด บทบาท M2M ให้กับแอปพลิเคชันของคุณได้:

หรือคุณยังสามารถกำหนดบทบาทเหล่านี้ได้ที่หน้ารายละเอียดแอป M2M เมื่อคุณได้สร้างแอป M2M ไว้แล้ว:

ต่อไป เราจะพาคุณผ่านกระบวนการแบบ end-to-end เพื่อความชัดเจน เราจะแยกขั้นตอนสำหรับการเข้าถึง Logto Management API และทรัพยากร API อื่น ๆ และสมมติว่าคุณได้สร้างแอป M2M ใน Logto แล้ว

ดึงโทเค็นการเข้าถึง (Fetch an access token)

พื้นฐานเกี่ยวกับคำขอโทเค็นการเข้าถึง

แอป M2M จะส่งคำขอ POST ไปยัง token endpoint เพื่อดึงโทเค็นการเข้าถึง (Access token) โดยเพิ่มพารามิเตอร์ต่อไปนี้ในรูปแบบ application/x-www-form-urlencoded ใน entity-body ของ HTTP request:

• grant_type: ต้องตั้งค่าเป็น client_credentials
• resource: ทรัพยากรที่คุณต้องการเข้าถึง
• scope: ขอบเขต (Scope) ของคำขอการเข้าถึง

และคุณยังต้องแนบข้อมูลรับรองของแอป M2M ของคุณใน request header เพื่อให้ token endpoint ทำการยืนยันตัวตน (Authentication) ของแอป M2M ของคุณ

วิธีนี้ทำได้โดยการแนบข้อมูลรับรองของแอปในรูปแบบ Basic authentication ใน request Authorization header: ให้ base64-encode {App ID}:{App Secret} และตั้งค่าเป็นค่าหลัง prefix Basic

คุณสามารถดู App ID และ App Secret ได้จากหน้ารายละเอียดของแอป M2M ของคุณ:

ตัวอย่างคำขอโทเค็นการเข้าถึง:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&resource=https://shopping.api
&scope=read:products write:products

ขอรับโทเค็นการเข้าถึง

บันทึก:

ในการสาธิตต่อไปนี้ ให้แทนที่ https://your.logto.endpoint ด้วย Logto endpoint ที่คุณต้องการใช้งาน สำหรับ Logto Cloud จะเป็น https://{your-tenant-id}.logto.app

สำหรับ Logto Management API

Logto มี “Logto Management API” เป็นทรัพยากรในตัว ซึ่งเป็นทรัพยากรแบบอ่านอย่างเดียว (readonly) พร้อมสิทธิ์ all สำหรับเข้าถึง Logto Management API คุณสามารถดูได้จากรายการทรัพยากร API ของคุณ ตัวบ่งชี้ API ของทรัพยากรนี้จะอยู่ในรูปแบบ https://{your-tenant-id}.logto.app/api และนี่จะเป็นค่าทรัพยากรที่ใช้ใน request body ของการขอโทเค็นการเข้าถึง (access token)

ก่อนเข้าถึง Logto Management API ให้แน่ใจว่าแอป M2M ของคุณได้รับมอบหมายบทบาท M2M ที่มีสิทธิ์ all จากทรัพยากร “Logto Management API” ที่มีมาให้ในตัวนี้แล้ว

ข้อมูล:

Logto ยังมีบทบาท M2M ที่ตั้งค่าล่วงหน้าไว้ชื่อ “Logto Management API access” สำหรับ tenant ที่สร้างใหม่ ซึ่งได้มอบหมายสิทธิ์ all ของ Logto Management API resource ไว้แล้ว คุณสามารถใช้งานได้ทันทีโดยไม่ต้องตั้งค่าสิทธิ์เอง บทบาทที่ตั้งค่านี้สามารถแก้ไขหรือลบได้ตามต้องการ

ตอนนี้ รวบรวมทุกอย่างที่เรามีและส่งคำขอ:

ข้อมูล:

ตั้งแต่เวอร์ชัน v1.30.1 เป็นต้นไป Logto มี SDK Node.js อย่างเป็นทางการ @logto/api เพื่อช่วยให้คุณโต้ตอบกับ Logto Management API ได้ง่ายขึ้น

Node.js with `@logto/api` SDK

Logto Cloud

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// หรือคุณสามารถข้ามขั้นตอนการขอโทเค็นการเข้าถึงและเรียก API ได้โดยตรง
const response = await apiClient.GET('/api/users');
console.log(response.data);

Self-hosted / OSS

ผู้ใช้ OSS ควรใช้ default เป็น tenant ID และต้องกำหนดค่า baseUrl และ apiIndicator ด้วย

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/api',
});

Node.js

const logtoEndpoint = 'https://your.logto.endpoint'; // แทนที่ด้วย Logto endpoint ของคุณ
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};

ข้อควรระวัง:

สำหรับผู้ใช้ Logto Cloud: เมื่อคุณโต้ตอบกับ Logto Management API คุณไม่สามารถใช้โดเมนแบบกำหนดเองได้ ให้ใช้ Logto endpoint เริ่มต้น https://{your_tenant_id}.logto.app/oidc/token เพื่อขอโทเค็นการเข้าถึง

ตัวอย่างการตอบกลับของโทเค็นการเข้าถึง (Access token response)

ตัวอย่างเนื้อหาการตอบกลับเมื่อสำเร็จจะมีลักษณะดังนี้:

{
  "access_token": "eyJhbG...2g", // ใช้โทเค็นนี้เพื่อเข้าถึง Logto Management API
  "expires_in": 3600, // เวลาหมดอายุของโทเค็น (วินาที)
  "token_type": "Bearer", // ประเภทการยืนยันตัวตนสำหรับคำขอเมื่อใช้โทเค็นการเข้าถึง
  "scope": "all" // ขอบเขต `all` สำหรับ Logto Management API
}

บันทึก:

ขณะนี้ Logto ยังไม่รองรับการใช้แอป M2M เพื่อแทนผู้ใช้ sub ใน payload ของโทเค็นการเข้าถึง (access token) จะเป็น App ID

cURL

curl --location \
  --request POST 'https://your.logto.endpoint' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://${tenantId}.logto.app/api' \
  --data-urlencode 'scope=all'

อย่าลืมแทนที่ค่าต่าง ๆ ด้วยค่าของคุณเอง

ข้อควรระวัง:

สำหรับผู้ใช้ Logto Cloud: เมื่อคุณโต้ตอบกับ Logto Management API คุณไม่สามารถใช้โดเมนแบบกำหนดเองได้ ให้ใช้ Logto endpoint เริ่มต้น https://{your_tenant_id}.logto.app/oidc/token เพื่อขอโทเค็นการเข้าถึง

ตัวอย่างการตอบกลับของโทเค็นการเข้าถึง (Access token response)

ตัวอย่างเนื้อหาการตอบกลับเมื่อสำเร็จจะมีลักษณะดังนี้:

{
  "access_token": "eyJhbG...2g", // ใช้โทเค็นนี้เพื่อเข้าถึง Logto Management API
  "expires_in": 3600, // เวลาหมดอายุของโทเค็น (วินาที)
  "token_type": "Bearer", // ประเภทการยืนยันตัวตนสำหรับคำขอเมื่อใช้โทเค็นการเข้าถึง
  "scope": "all" // ขอบเขต `all` สำหรับ Logto Management API
}

บันทึก:

ขณะนี้ Logto ยังไม่รองรับการใช้แอป M2M เพื่อแทนผู้ใช้ sub ใน payload ของโทเค็นการเข้าถึง (access token) จะเป็น App ID

สำหรับทรัพยากร API ของคุณ

ในรายการ API Resource ของคุณ ให้ค้นหา API identifier ที่แอปต้องเข้าถึง หากคุณยังไม่ได้เพิ่ม API Resource ใน Logto หรือไม่ทราบว่า API Resource คืออะไร ดูที่ การอนุญาต (Authorization)

สมมติว่าเรามีสิทธิ์ read:products และ write:products อยู่ภายใต้ทรัพยากร API “Online Shopping” นี้

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

ตอนนี้ รวบรวมทุกอย่างที่เรามีและส่งคำขอ:

Node.js

const logtoEndpoint = 'https://your.logto.endpoint';
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: 'https://shopping.api',
      scope: 'read:products write:products',
    }).toString(),
  });
};

cURL

curl --location \
  --request POST 'https://your.logto.endpoint/oidc/token' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://shopping.api' \
  --data-urlencode 'scope=read:products write:products'

การตอบกลับโทเค็นการเข้าถึง

ตัวอย่าง response ที่สำเร็จจะมีลักษณะดังนี้:

{
  "access_token": "eyJhbG...2g", // ใช้โทเค็นนี้สำหรับเข้าถึง Logto Management API
  "expires_in": 3600, // อายุโทเค็นเป็นวินาที
  "token_type": "Bearer", // ประเภทการยืนยันตัวตนสำหรับคำขอเมื่อใช้โทเค็นการเข้าถึง
  "scope": "all" // scope `all` สำหรับ Logto Management API
}

บันทึก:

ขณะนี้ Logto ยังไม่รองรับการใช้แอป M2M เพื่อแทนผู้ใช้ sub ใน payload ของโทเค็นการเข้าถึง (access token) จะเป็น App ID

เข้าถึงทรัพยากรโดยใช้โทเค็นการเข้าถึง

คุณอาจสังเกตเห็นว่าการตอบกลับโทเค็นมีฟิลด์ token_type ซึ่งถูกกำหนดไว้เป็น Bearer เสมอ

ดังนั้น คุณควรใส่โทเค็นการเข้าถึง (Access token) ลงในฟิลด์ Authorization ของ HTTP headers โดยใช้รูปแบบ Bearer (Bearer YOUR_TOKEN) เมื่อคุณโต้ตอบกับเซิร์ฟเวอร์ทรัพยากร API ของคุณ

โต้ตอบกับ Logto Management API

Node.js with `@logto/api` SDK

ด้วย @logto/api SDK คุณสามารถโต้ตอบกับ Management API ใด ๆ ได้โดยตรงโดยใช้โค้ดตัวอย่างด้านล่าง โทเค็นการเข้าถึง (Access token) จะถูกแคชภายในและรีเฟรชโดยอัตโนติหากจำเป็น

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

Node.js

คุณอาจสังเกตเห็นว่าการตอบกลับโทเค็นมีฟิลด์ token_type ซึ่งถูกกำหนดไว้เป็น Bearer เสมอ

ดังนั้น คุณควรใส่โทเค็นการเข้าถึง (Access token) ลงในฟิลด์ Authorization ของ HTTP headers โดยใช้รูปแบบ Bearer (Bearer YOUR_TOKEN) เมื่อคุณโต้ตอบกับเซิร์ฟเวอร์ทรัพยากร API ของคุณ

const logtoEndpoint = 'https://your.logto.endpoint'; // แทนที่ด้วย Logto endpoint ของคุณ
const accessToken = 'eyJhb...2g'; // โทเค็นการเข้าถึง (Access Token)

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

cURL

คุณอาจสังเกตเห็นว่าการตอบกลับโทเค็นมีฟิลด์ token_type ซึ่งถูกกำหนดไว้เป็น Bearer เสมอ

ดังนั้น คุณควรใส่โทเค็นการเข้าถึง (Access token) ลงในฟิลด์ Authorization ของ HTTP headers โดยใช้รูปแบบ Bearer (Bearer YOUR_TOKEN) เมื่อคุณโต้ตอบกับเซิร์ฟเวอร์ทรัพยากร API ของคุณ

curl --location \
  --request GET 'https://your.logto.endpoint/api/applications' \
  --header 'Authorization: Bearer eyJhbG...2g'

อย่าลืมแทนที่ค่าต่าง ๆ ด้วยค่าของคุณเอง ค่าหลัง Bearer ควรเป็นโทเค็นการเข้าถึง (JWT) ที่คุณได้รับ

โต้ตอบกับทรัพยากร API ของคุณ

ใช้โทเค็นการเข้าถึงที่ขอมากับทรัพยากร API https://shopping.api เพื่อดึงสินค้าทั้งหมดใน shopping API:

Node.js

const apiEndpoint = 'https://your.api.endpoint';
const accessToken = 'eyJhb...2g'; // โทเค็นการเข้าถึง

const fetchProducts = async () => {
  return await fetch(`${apiEndpoint}/products`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

cURL

curl --location \
  --request GET 'https://your.api.endpoint/products' \
  --header 'Authorization: Bearer eyJhbG...2 # โทเค็นการเข้าถึง

การอนุญาต (Authorization)

หากคุณปกป้องทรัพยากร API ของคุณเองที่ไม่ใช่ Logto Management API คุณต้องพัฒนา logic การอนุญาตในบริการ API ของคุณเพื่อยืนยันโทเค็นการเข้าถึงและตรวจสอบว่าแอป M2M มีสิทธิ์ที่จำเป็นในการเข้าถึงทรัพยากรหรือไม่

ดูรายละเอียดเพิ่มเติมได้ที่ การอนุญาต (Authorization) และ ตรวจสอบความถูกต้องของโทเค็นการเข้าถึง