ข้ามไปยังเนื้อหาหลัก

วิธีตรวจสอบโทเค็นการเข้าถึง (Access tokens) ในบริการ API หรือ backend ของคุณ

การตรวจสอบโทเค็นการเข้าถึง (โทเค็นการเข้าถึง (Access tokens)) เป็นส่วนสำคัญของการบังคับใช้ การควบคุมการเข้าถึงตามบทบาท (RBAC) ใน Logto คู่มือนี้จะแนะนำขั้นตอนการตรวจสอบ JWT ที่ออกโดย Logto ใน backend / API ของคุณ โดยตรวจสอบลายเซ็น ผู้ออก (Issuer) ผู้รับ (Audience) วันหมดอายุ สิทธิ์ (ขอบเขต; scopes) และบริบทขององค์กร

ก่อนเริ่มต้น​

ขั้นตอนที่ 1: กำหนดค่าคงที่และยูทิลิตี้​

กำหนดค่าคงที่และยูทิลิตี้ที่จำเป็นในโค้ดของคุณเพื่อจัดการการดึงและตรวจสอบโทเค็น คำขอที่ถูกต้องต้องมี header Authorization ในรูปแบบ Bearer <access_token>

auth-middleware.ts
import { IncomingHttpHeaders } from 'http';

const JWKS_URI = 'https://your-tenant.logto.app/oidc/jwks';
const ISSUER = 'https://your-tenant.logto.app/oidc';

export class AuthInfo {
  constructor(
    public sub: string,
    public clientId?: string,
    public organizationId?: string,
    public scopes: string[] = [],
    public audience: string[] = []
  ) {}
}

export class AuthorizationError extends Error {
  name = 'AuthorizationError';
  constructor(
    message: string,
    public status = 403
  ) {
    super(message);
  }
}

export function extractBearerTokenFromHeaders({ authorization }: IncomingHttpHeaders): string {
  const bearerPrefix = 'Bearer ';

  if (!authorization) {
    // ส่วนหัว Authorization ไม่พบ (Authorization header is missing)
    throw new AuthorizationError('Authorization header is missing', 401);
  }

  if (!authorization.startsWith(bearerPrefix)) {
    // ส่วนหัว Authorization ต้องขึ้นต้นด้วย "Bearer " (Authorization header must start with "Bearer ")
    throw new AuthorizationError(`Authorization header must start with "${bearerPrefix}"`, 401);
  }

  return authorization.slice(bearerPrefix.length);
}

ขั้นตอนที่ 2: ดึงข้อมูลเกี่ยวกับ Logto tenant ของคุณ​

คุณจะต้องใช้ค่าต่อไปนี้เพื่อยืนยันโทเค็นที่ออกโดย Logto:

  • URI ของ JSON Web Key Set (JWKS): URL ไปยัง public keys ของ Logto ใช้สำหรับตรวจสอบลายเซ็นของ JWT
  • ผู้ออก (Issuer): ค่าผู้ออกที่คาดหวัง (OIDC URL ของ Logto)

ขั้นแรก ให้ค้นหา endpoint ของ Logto tenant ของคุณ คุณสามารถหาได้จากหลายที่:

  • ใน Logto Console ที่ Settings → Domains
  • ในการตั้งค่าแอปพลิเคชันใด ๆ ที่คุณตั้งค่าใน Logto, Settings → Endpoints & Credentials

ดึงค่าจาก OpenID Connect discovery endpoint​

ค่าทั้งหมดนี้สามารถดึงได้จาก OpenID Connect discovery endpoint ของ Logto:

https://<your-logto-endpoint>/oidc/.well-known/openid-configuration

ตัวอย่างการตอบกลับ (ละเว้นฟิลด์อื่นเพื่อความกระชับ):

{
  "jwks_uri": "https://your-tenant.logto.app/oidc/jwks",
  "issuer": "https://your-tenant.logto.app/oidc"
}

เนื่องจาก Logto ไม่อนุญาตให้ปรับแต่ง JWKS URI หรือผู้ออก (issuer) คุณสามารถเขียนค่าคงที่เหล่านี้ไว้ในโค้ดของคุณได้ อย่างไรก็ตาม ไม่แนะนำให้ใช้วิธีนี้ในแอปพลิเคชัน production เพราะอาจเพิ่มภาระในการดูแลรักษาหากมีการเปลี่ยนแปลงค่าคอนฟิกในอนาคต

  • JWKS URI: https://<your-logto-endpoint>/oidc/jwks
  • ผู้ออก (Issuer): https://<your-logto-endpoint>/oidc

ขั้นตอนที่ 3: ตรวจสอบโทเค็นและสิทธิ์ (permissions)​

หลังจากดึงโทเค็นและดึงข้อมูล OIDC config แล้ว ให้ตรวจสอบสิ่งต่อไปนี้:

  • ลายเซ็น (Signature): JWT ต้องถูกต้องและลงนามโดย Logto (ผ่าน JWKS)
  • ผู้ออก (Issuer): ต้องตรงกับผู้ออกของ Logto tenant ของคุณ
  • ผู้รับ (Audience): ต้องตรงกับตัวบ่งชี้ทรัพยากร API ที่ลงทะเบียนใน Logto หรือบริบทขององค์กรหากเกี่ยวข้อง
  • วันหมดอายุ (Expiration): โทเค็นต้องไม่หมดอายุ
  • สิทธิ์ (ขอบเขต) (Permissions (scopes)): โทเค็นต้องมีขอบเขตที่จำเป็นสำหรับ API / การกระทำของคุณ ขอบเขตจะเป็นสตริงที่คั่นด้วยช่องว่างใน scope การอ้างสิทธิ์ (claim)
  • บริบทองค์กร (Organization context): หากปกป้องทรัพยากร API ระดับองค์กร ให้ตรวจสอบการอ้างสิทธิ์ organization_id

ดู JSON Web Token เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับโครงสร้างและการอ้างสิทธิ์ของ JWT

สิ่งที่ต้องตรวจสอบสำหรับแต่ละโมเดลสิทธิ์ (What to check for each permission model)​

การอ้างสิทธิ์ (claims) และกฎการตรวจสอบจะแตกต่างกันไปตามโมเดลสิทธิ์:

  • การอ้างสิทธิ์ผู้รับ (aud): ตัวบ่งชี้ทรัพยากร API
  • การอ้างสิทธิ์องค์กร (organization_id): ไม่มี
  • ขอบเขต (สิทธิ์) ที่ต้องตรวจสอบ (scope): สิทธิ์ของทรัพยากร API

สำหรับสิทธิ์ขององค์กรที่ไม่ใช่ API บริบทขององค์กรจะแสดงโดยการอ้างสิทธิ์ aud (เช่น urn:logto:organization:abc123) การอ้างสิทธิ์ organization_id จะมีเฉพาะในโทเค็นทรัพยากร API ระดับองค์กรเท่านั้น
เคล็ดลับ:

ควรตรวจสอบทั้งสิทธิ์ (ขอบเขต) และบริบท (ผู้รับ, องค์กร) เสมอ เพื่อความปลอดภัยของ API แบบหลายผู้เช่า

เพิ่มตรรกะการตรวจสอบ​

เราใช้ jose ในตัวอย่างนี้เพื่อใช้ตรวจสอบความถูกต้องของ JWT หากคุณยังไม่ได้ติดตั้ง ให้ติดตั้งดังนี้:

npm install jose

หรือใช้ตัวจัดการแพ็กเกจที่คุณชื่นชอบ (เช่น pnpm หรือ yarn)

ก่อนอื่น เพิ่มยูทิลิตี้ที่ใช้ร่วมกันเหล่านี้เพื่อจัดการการตรวจสอบ JWT:

jwt-validator.ts
import { createRemoteJWKSet, jwtVerify, JWTPayload } from 'jose';
import { AuthInfo, AuthorizationError } from './auth-middleware.js';

const jwks = createRemoteJWKSet(new URL(JWKS_URI));

export async function validateJwt(token: string): Promise<JWTPayload> {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
  });

  verifyPayload(payload);
  return payload;
}

export function createAuthInfo(payload: JWTPayload): AuthInfo {
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  const audience = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];

  return new AuthInfo(
    payload.sub!,
    payload.client_id as string,
    payload.organization_id as string,
    scopes,
    audience
  );
}

function verifyPayload(payload: JWTPayload): void {
  // เพิ่มตรรกะการตรวจสอบของคุณที่นี่ตามโมเดลสิทธิ์ (permission model)
  // ตัวอย่างจะอธิบายในส่วนโมเดลสิทธิ์ด้านล่าง
}

จากนั้น ให้สร้าง middleware เพื่อตรวจสอบ access token:

auth-middleware.ts
import { Request, Response, NextFunction } from 'express';
import { validateJwt, createAuthInfo } from './jwt-validator.js';

// ขยายอินเทอร์เฟซ Request ของ Express เพื่อเพิ่ม auth
declare global {
  namespace Express {
    interface Request {
      auth?: AuthInfo;
    }
  }
}

export async function verifyAccessToken(req: Request, res: Response, next: NextFunction) {
  try {
    const token = extractBearerTokenFromHeaders(req.headers);
    const payload = await validateJwt(token);

    // เก็บข้อมูล auth ใน request เพื่อใช้งานทั่วไป
    req.auth = createAuthInfo(payload);

    next();
  } catch (err: any) {
    return res.status(err.status ?? 401).json({ error: err.message });
  }
}

ตามโมเดลสิทธิ์ของคุณ ให้เพิ่มตรรกะการตรวจสอบที่เหมาะสมใน jwt-validator.ts:

jwt-validator.ts
function verifyPayload(payload: JWTPayload): void {
  // ตรวจสอบว่า audience claim ตรงกับตัวบ่งชี้ทรัพยากร API ของคุณ
  const audiences = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
  if (!audiences.includes('https://your-api-resource-indicator')) {
    throw new AuthorizationError('Invalid audience');
  }

  // ตรวจสอบขอบเขต (scopes) ที่จำเป็นสำหรับทรัพยากร API ระดับโกลบอล
  const requiredScopes = ['api:read', 'api:write']; // แทนที่ด้วยขอบเขตที่คุณต้องการจริง
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  if (!requiredScopes.every((scope) => scopes.includes(scope))) {
    throw new AuthorizationError('Insufficient scope');
  }
}

ขั้นตอนที่ 4: นำ middleware ไปใช้กับ API ของคุณ​

นำ middleware ไปใช้กับเส้นทาง API ที่คุณต้องการปกป้อง

app.ts
import { verifyAccessToken } from './auth-middleware.js';

app.get('/api/protected', verifyAccessToken, (req, res) => {
  // เข้าถึงข้อมูลการยืนยันตัวตน (auth) ได้โดยตรงจาก req.auth
  res.json({ auth: req.auth });
});

ขั้นตอนที่ 5: ทดสอบการใช้งานของคุณ​

รับโทเค็นการเข้าถึง (Access tokens)​

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

สำหรับการทดสอบด้วย curl / Postman:

  1. โทเค็นผู้ใช้: ใช้เครื่องมือสำหรับนักพัฒนาของแอปไคลเอนต์ของคุณเพื่อคัดลอกโทเค็นการเข้าถึงจาก localStorage หรือแท็บ network

  2. โทเค็นเครื่องต่อเครื่อง: ใช้ client credentials flow ตัวอย่างที่ไม่เป็นทางการโดยใช้ curl:

    curl -X POST https://your-tenant.logto.app/oidc/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=your-m2m-client-id" \
      -d "client_secret=your-m2m-client-secret" \
      -d "resource=https://your-api-resource-indicator" \
      -d "scope=api:read api:write"

    คุณอาจต้องปรับพารามิเตอร์ resource และ scope ให้ตรงกับทรัพยากร API และสิทธิ์ของคุณ; อาจต้องใช้พารามิเตอร์ organization_id หาก API ของคุณอยู่ในขอบเขตองค์กร

เคล็ดลับ:

ต้องการตรวจสอบเนื้อหาโทเค็นใช่ไหม? ใช้ JWT decoder ของเราเพื่อถอดรหัสและตรวจสอบ JWT ของคุณ

ทดสอบ endpoint ที่ได้รับการป้องกัน​

คำขอที่มีโทเค็นถูกต้อง
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/api/protected

ผลลัพธ์ที่คาดหวัง:

{
  "auth": {
    "sub": "user123",
    "clientId": "app456",
    "organizationId": "org789",
    "scopes": ["api:read", "api:write"],
    "audience": ["https://your-api-resource-indicator"]
  }
}
ไม่มีโทเค็น
curl http://localhost:3000/api/protected

ผลลัพธ์ที่คาดหวัง (401):

{
  "error": "Authorization header is missing"
}
โทเค็นไม่ถูกต้อง
curl -H "Authorization: Bearer invalid-token" \
  http://localhost:3000/api/protected

ผลลัพธ์ที่คาดหวัง (401):

{
  "error": "Invalid token"
}

การทดสอบเฉพาะโมเดลสิทธิ์ (Permission model-specific testing)​

กรณีทดสอบสำหรับ API ที่ได้รับการป้องกันด้วย global scopes:

  • ขอบเขตถูกต้อง: ทดสอบด้วยโทเค็นที่มีขอบเขต API ที่ต้องการ (เช่น api:read, api:write)
  • ขาดขอบเขต: คาดหวัง 403 Forbidden เมื่อโทเค็นไม่มีขอบเขตที่จำเป็น
  • audience ไม่ถูกต้อง: คาดหวัง 403 Forbidden เมื่อ audience ไม่ตรงกับทรัพยากร API
# โทเค็นที่ขาดขอบเขต - คาดหวัง 403
curl -H "Authorization: Bearer token-without-required-scopes" \
  http://localhost:3000/api/protected
การปรับแต่งการอ้างสิทธิ์ (claims) ในโทเค็น JSON Web Token (JWT)

OpenID Connect Discovery

RFC 8707: ตัวบ่งชี้ทรัพยากร (Resource Indicators)