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

ปกป้อง API ASP.NET Core ของคุณด้วยการควบคุมการเข้าถึงตามบทบาท (RBAC) และการตรวจสอบ JWT

คู่มือนี้จะช่วยให้คุณนำการอนุญาต (Authorization) ไปใช้เพื่อรักษาความปลอดภัยให้กับ API ของ ASP.NET Core โดยใช้ การควบคุมการเข้าถึงตามบทบาท (RBAC) และ JSON Web Tokens (JWTs) ที่ออกโดย Logto

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

แอปพลิเคชันไคลเอนต์ของคุณจำเป็นต้องขอรับโทเค็นการเข้าถึง (Access tokens) จาก Logto หากคุณยังไม่ได้ตั้งค่าการเชื่อมต่อกับไคลเอนต์ โปรดดู เริ่มต้นอย่างรวดเร็ว สำหรับ React, Vue, Angular หรือเฟรมเวิร์กฝั่งไคลเอนต์อื่น ๆ หรือดู คู่มือเครื่องต่อเครื่อง สำหรับการเข้าถึงแบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์

คู่มือนี้เน้นที่ การตรวจสอบโทเค็นฝั่งเซิร์ฟเวอร์ ในแอป ASP.NET Core ของคุณ

A figure showing the focus of this guide

สิ่งที่คุณจะได้เรียนรู้​

  • การตรวจสอบ JWT: เรียนรู้วิธีตรวจสอบโทเค็นการเข้าถึง (Access tokens) และดึงข้อมูลการยืนยันตัวตน (Authentication)
  • การสร้าง Middleware: สร้าง middleware ที่นำกลับมาใช้ซ้ำได้สำหรับการปกป้อง API
  • โมเดลสิทธิ์ (Permission models): เข้าใจและนำรูปแบบการอนุญาต (Authorization) ที่แตกต่างกันไปใช้:
    • ทรัพยากร API ระดับโกลบอลสำหรับ endpoint ทั่วทั้งแอปพลิเคชัน
    • สิทธิ์ขององค์กรสำหรับควบคุมฟีเจอร์เฉพาะผู้เช่า (tenant)
    • ทรัพยากร API ระดับองค์กรสำหรับการเข้าถึงข้อมูลแบบหลายผู้เช่า (multi-tenant)
  • การผสาน RBAC: บังคับใช้สิทธิ์และขอบเขต (Scopes) ตามบทบาท (RBAC) ใน endpoint ของ API ของคุณ

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

  • ติดตั้ง .NET เวอร์ชันเสถียรล่าสุด
  • มีความเข้าใจพื้นฐานเกี่ยวกับ ASP.NET Core และการพัฒนาเว็บ API
  • ตั้งค่าแอป Logto เรียบร้อยแล้ว (ดู เริ่มต้นอย่างรวดเร็ว หากยังไม่ได้ตั้งค่า)

ภาพรวมของโมเดลสิทธิ์ (Permission models overview)​

ก่อนดำเนินการปกป้องทรัพยากร ให้เลือกโมเดลสิทธิ์ที่เหมาะสมกับสถาปัตยกรรมแอปพลิเคชันของคุณ ซึ่งสอดคล้องกับ สถานการณ์การอนุญาต (authorization scenarios) หลักสามแบบของ Logto:

Global API resources RBAC
  • กรณีการใช้งาน: ปกป้องทรัพยากร API ที่ใช้ร่วมกันทั่วทั้งแอปพลิเคชัน (ไม่เฉพาะองค์กร)
  • ประเภทโทเค็น: โทเค็นการเข้าถึง (Access token) ที่มีผู้รับ (audience) ระดับโกลบอล
  • ตัวอย่าง: Public APIs, บริการหลักของผลิตภัณฑ์, จุดเชื่อมต่อสำหรับผู้ดูแลระบบ
  • เหมาะสำหรับ: ผลิตภัณฑ์ SaaS ที่มี API ใช้ร่วมกันโดยลูกค้าทุกคน, microservices ที่ไม่มีการแยก tenant
  • เรียนรู้เพิ่มเติม: ปกป้องทรัพยากร API ระดับโกลบอล

💡 เลือกโมเดลของคุณก่อนดำเนินการต่อ - การนำไปใช้จะอ้างอิงแนวทางที่คุณเลือกตลอดคู่มือนี้

ขั้นตอนเตรียมความพร้อมอย่างรวดเร็ว​

กำหนดค่าทรัพยากรและสิทธิ์ของ Logto​

  1. สร้างทรัพยากร API: ไปที่ Console → ทรัพยากร API และลงทะเบียน API ของคุณ (เช่น https://api.yourapp.com)
  2. กำหนดสิทธิ์: เพิ่มขอบเขต (scopes) เช่น read:products, write:orders – ดู กำหนดทรัพยากร API พร้อมสิทธิ์
  3. สร้างบทบาทระดับโกลบอล: ไปที่ Console → บทบาท และสร้างบทบาทที่รวมสิทธิ์ API ของคุณ – ดู กำหนดค่าบทบาทระดับโกลบอล
  4. กำหนดบทบาท: กำหนดบทบาทให้กับผู้ใช้หรือแอป M2M ที่ต้องการเข้าถึง API
ใหม่กับ RBAC?:

เริ่มต้นด้วย คู่มือการควบคุมการเข้าถึงตามบทบาท (RBAC) ของเรา สำหรับคำแนะนำการตั้งค่าแบบทีละขั้นตอน

อัปเดตแอปพลิเคชันฝั่งไคลเอนต์ของคุณ​

ร้องขอขอบเขต (scopes) ที่เหมาะสมในไคลเอนต์ของคุณ:

กระบวนการนี้มักเกี่ยวข้องกับการอัปเดตการกำหนดค่าไคลเอนต์ของคุณเพื่อรวมหนึ่งหรือมากกว่ารายการต่อไปนี้:

  • พารามิเตอร์ scope ในกระบวนการ OAuth
  • พารามิเตอร์ resource สำหรับการเข้าถึงทรัพยากร API
  • organization_id สำหรับบริบทขององค์กร
ก่อนเริ่มเขียนโค้ด:

ตรวจสอบให้แน่ใจว่าผู้ใช้หรือแอป M2M ที่คุณทดสอบได้รับการกำหนดบทบาทหรือบทบาทขององค์กรที่มีสิทธิ์ที่จำเป็นสำหรับ API ของคุณแล้ว

เริ่มต้นโปรเจกต์ API ของคุณ​

ในการเริ่มต้นโปรเจกต์ .NET Web API ใหม่ คุณสามารถใช้ .NET CLI ได้ดังนี้:

dotnet new webapi -n YourApiName
cd YourApiName

เพิ่มแพ็กเกจ NuGet ที่จำเป็นสำหรับการยืนยันตัวตนด้วย JWT:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

สร้าง API controller พื้นฐาน:

Controllers/ApiController.cs
using Microsoft.AspNetCore.Mvc;

namespace YourApiName.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class ApiController : ControllerBase
    {
        [HttpGet]
        public IActionResult Get()
        {
            return Ok(new { message = "Hello from .NET API" });
        }
    }
}

เริ่มต้นเซิร์ฟเวอร์สำหรับพัฒนา:

dotnet run
บันทึก:

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการตั้งค่า controller, middleware และฟีเจอร์อื่น ๆ ได้ที่เอกสารของ ASP.NET Core

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

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

AuthConstants.cs
namespace YourApiNamespace
{
    public static class AuthConstants
    {
        public const string Issuer = "https://your-tenant.logto.app/oidc";
    }
}
AuthenticationExceptions.cs
namespace YourApiNamespace.Exceptions
{
    public class AuthorizationException : Exception
    {
        public int StatusCode { get; }

        public AuthorizationException(string message, int statusCode = 403) : base(message)
        {
            StatusCode = statusCode;
        }
    }
}

ดึงข้อมูลเกี่ยวกับ 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

ตรวจสอบโทเค็นและสิทธิ์ (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 แบบหลายผู้เช่า

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

เพิ่มแพ็กเกจ NuGet ที่จำเป็นสำหรับการยืนยันตัวตนด้วย JWT:

<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.0" />

สร้างบริการสำหรับตรวจสอบความถูกต้องของโทเค็น:

JwtValidationService.cs
using System.Security.Claims;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using YourApiNamespace.Exceptions;

namespace YourApiNamespace.Services
{
    public interface IJwtValidationService
    {
        Task ValidateTokenAsync(TokenValidatedContext context);
    }

    public class JwtValidationService : IJwtValidationService
    {
        public async Task ValidateTokenAsync(TokenValidatedContext context)
        {
            var principal = context.Principal!;

            try
            {
                // เพิ่มตรรกะการตรวจสอบของคุณที่นี่ตามโมเดลสิทธิ์ (permission model)
                ValidatePayload(principal);
            }
            catch (AuthorizationException)
            {
                throw; // ส่งต่อข้อยกเว้นการอนุญาต
            }
            catch (Exception ex)
            {
                throw new AuthorizationException($"Token validation failed: {ex.Message}", 401);
            }
        }

        private void ValidatePayload(ClaimsPrincipal principal)
        {
            // นำตรรกะการตรวจสอบของคุณมาใช้ที่นี่ตามโมเดลสิทธิ์ (permission model)
            // ตัวอย่างจะอธิบายในส่วนโมเดลสิทธิ์ด้านล่าง
        }
    }
}

กำหนดค่า JWT authentication ใน Program.cs ของคุณ:

Program.cs
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using YourApiNamespace.Services;
using YourApiNamespace.Exceptions;

var builder = WebApplication.CreateBuilder(args);

// เพิ่มบริการลงใน container
builder.Services.AddControllers();
builder.Services.AddScoped<IJwtValidationService, JwtValidationService>();

// กำหนดค่า JWT authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = AuthConstants.Issuer;
        options.MetadataAddress = $"{AuthConstants.Issuer}/.well-known/openid-configuration";
        options.RequireHttpsMetadata = true;
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = AuthConstants.Issuer,
            ValidateAudience = false, // เราจะตรวจสอบ audience ด้วยตนเองตาม permission model
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromMinutes(5)
        };

        options.Events = new JwtBearerEvents
        {
            OnTokenValidated = async context =>
            {
                var validationService = context.HttpContext.RequestServices
                    .GetRequiredService<IJwtValidationService>();

                await validationService.ValidateTokenAsync(context);
            },
            OnAuthenticationFailed = context =>
            {
                // จัดการข้อผิดพลาดของ JWT library เป็น 401
                context.Response.StatusCode = 401;
                context.Response.ContentType = "application/json";
                context.Response.WriteAsync($"{{\"error\": \"Invalid token\"}}");
                context.HandleResponse();
                return Task.CompletedTask;
            }
        };
    });

builder.Services.AddAuthorization();

var app = builder.Build();

// การจัดการข้อผิดพลาดแบบ global สำหรับการยืนยันตัวตน / การอนุญาตที่ล้มเหลว
app.Use(async (context, next) =>
{
    try
    {
        await next();
    }
    catch (AuthorizationException ex)
    {
        context.Response.StatusCode = ex.StatusCode;
        context.Response.ContentType = "application/json";
        await context.Response.WriteAsync($"{{\"error\": \"{ex.Message}\"}}");
    }
});

// กำหนด HTTP request pipeline
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();

ตามโมเดลสิทธิ์ (permission model) ของคุณ ให้นำตรรกะการตรวจสอบที่เหมาะสมมาใช้ใน JwtValidationService:

JwtValidationService.cs
private void ValidatePayload(ClaimsPrincipal principal)
{
    // ตรวจสอบว่า audience claim ตรงกับตัวบ่งชี้ทรัพยากร API ของคุณ
    var audiences = principal.FindAll("aud").Select(c => c.Value).ToList();
    if (!audiences.Contains("https://your-api-resource-indicator"))
    {
        throw new AuthorizationException("Invalid audience");
    }

    // ตรวจสอบ scope ที่จำเป็นสำหรับทรัพยากร API ระดับโกลบอล
    var requiredScopes = new[] { "api:read", "api:write" }; // แทนที่ด้วย scope ที่คุณต้องการจริง
    var tokenScopes = principal.FindFirst("scope")?.Value?.Split(' ') ?? Array.Empty<string>();

    if (!requiredScopes.All(scope => tokenScopes.Contains(scope)))
    {
        throw new AuthorizationException("Insufficient scope");
    }
}

นำ middleware ไปใช้กับ API ของคุณ​

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

เราได้ตั้งค่า middleware สำหรับการยืนยันตัวตน (Authentication) และการอนุญาต (Authorization) ไว้แล้วในส่วนก่อนหน้านี้ ตอนนี้เราสามารถสร้าง controller ที่ได้รับการป้องกัน ซึ่งจะตรวจสอบโทเค็นการเข้าถึง (Access token) และดึงการอ้างสิทธิ์ (Claims) จากคำขอที่ได้รับการยืนยันตัวตน

ProtectedController.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;

namespace YourApiNamespace.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    [Authorize] // ต้องมีการยืนยันตัวตนสำหรับทุก action ใน controller นี้
    public class ProtectedController : ControllerBase
    {
        [HttpGet]
        public IActionResult GetProtectedData()
        {
            // ข้อมูลโทเค็นการเข้าถึงสามารถเข้าถึงได้โดยตรงจาก User claims
            var sub = User.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? User.FindFirst("sub")?.Value;
            var clientId = User.FindFirst("client_id")?.Value;
            var organizationId = User.FindFirst("organization_id")?.Value;
            var scopes = User.FindFirst("scope")?.Value?.Split(' ') ?? Array.Empty<string>();
            var audience = User.FindAll("aud").Select(c => c.Value).ToArray();

            return Ok(new {
                sub,
                client_id = clientId,
                organization_id = organizationId,
                scopes,
                audience
            });
        }

        [HttpGet("claims")]
        public IActionResult GetAllClaims()
        {
            // ส่งคืนการอ้างสิทธิ์ทั้งหมดเพื่อการดีบัก/ตรวจสอบ
            var claims = User.Claims.Select(c => new { c.Type, c.Value }).ToList();
            return Ok(new { claims });
        }
    }
}

ทดสอบ API ที่ได้รับการป้องกันของคุณ​

รับโทเค็นการเข้าถึง (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

อ่านเพิ่มเติม​

RBAC ในทางปฏิบัติ: การนำการอนุญาต (Authorization) ที่ปลอดภัยมาใช้กับแอปพลิเคชันของคุณ

สร้างแอปพลิเคชัน SaaS แบบหลายผู้เช่า: คู่มือฉบับสมบูรณ์ตั้งแต่การออกแบบจนถึงการนำไปใช้