자습서: 외부 테넌트에 등록된 ASP.NET Core Web API 보호

이 자습서 시리즈에서는 외부 테넌트에서 등록된 웹 API를 보호하는 방법을 보여 줍니다. 이 자습서에서는 위임된 권한(범위) 및 애플리케이션 권한(앱 역할)을 모두 게시하는 ASP.NET Core Web API를 빌드합니다.

이 자습서에서는 다음을 수행합니다.

• 앱 등록 세부 정보를 사용하도록 웹 API 구성
• 앱 등록에 등록된 위임된 권한 및 애플리케이션 권한을 사용하도록 웹 API 구성
• 웹 API 엔드포인트 보호

필수 조건

• ToDoList.Read와 같이 하나 이상의 범위(위임된 권한)와 하나의 앱 역할(애플리케이션 권한)을 노출하는 API 등록입니다. 아직 API를 등록하지 않았다면 등록 단계에 따라 Microsoft Entra 관리 센터에 API를 등록합니다. 다음 사항이 있는지 확인합니다.

  • 웹 API의 애플리케이션(클라이언트) ID
  • 웹 API의 디렉터리(테넌트) ID가 등록됩니다.
  • 웹 API가 등록된 디렉터리(테넌트) 하위 도메인입니다. 예를 들어, 기본 도메인이 contoso.onmicrosoft.com인 경우 디렉터리(테넌트) 하위 도메인은 contoso입니다.
  • ToDoList.Read 및 ToDoList.ReadWrite는 웹 API에 의해 노출되는 위임된 권한(범위)입니다.
  • ToDoList.Read.All 및 ToDoList.ReadWrite.All은 웹 API에 의해 노출되는 애플리케이션 권한(앱 역할)입니다.

• .NET 7.0 SDK 이상.

• Visual Studio Code 또는 다른 코드 편집기

ASP.NET Core 웹 API 만들기

1. 터미널을 열고 프로젝트를 저장할 폴더로 이동합니다.

2. 다음 명령을 실행합니다.

   dotnet new webapi -o ToDoListAPI
   cd ToDoListAPI
   

3. 프로젝트에 필수 자산을 추가하려는지 묻는 대화 상자가 나타나면 예를 선택합니다.

패키지 설치

다음 패키지를 설치합니다.

• Entity Framework Core를 메모리 내 데이터베이스와 함께 사용할 수 있도록 하는 Microsoft.EntityFrameworkCore.InMemory입니다. 프로덕션 용도로 설계되지 않았습니다.
• Microsoft.Identity.Web은 Microsoft ID 플랫폼과 통합되는 웹앱 및 웹 API에 인증 및 권한 부여 지원 추가를 간소화합니다.

dotnet add package Microsoft.EntityFrameworkCore.InMemory
dotnet add package Microsoft.Identity.Web

앱 등록 세부 정보 구성

앱 폴더에서 appsettings.json 파일을 열고 웹 API 등록 후 기록한 앱 등록 세부 정보를 추가합니다.

{
    "AzureAd": {
        "Instance": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/",
        "TenantId": "Enter_the_Tenant_Id_Here",
        "ClientId": "Enter_the_Application_Id_Here",
    },
    "Logging": {...},
  "AllowedHosts": "*"
}

다음 자리 표시자를 그림과 같이 바꿉니다.

• Enter_the_Application_Id_Here를 애플리케이션(클라이언트) ID로 바꿉니다.
• Enter_the_Tenant_Id_Here를 디렉터리(테넌트) ID로 바꿉니다.
• Enter_the_Tenant_Subdomain_Here를 디렉터리(테넌트) 하위 도메인으로 바꿉니다.

앱 역할 및 범위 추가

클라이언트 앱이 사용자에 대한 액세스 토큰을 성공적으로 가져오려면 모든 API는 위임된 권한이라고도 하는 최소 하나의 범위를 게시해야 합니다. 또한 API는 클라이언트 앱이 사용자로 로그인하지 않을 때 액세스 토큰을 자체적으로 가져올 수 있도록 애플리케이션 권한이라고도 하는 애플리케이션에 대해 최소한 하나의 앱 역할을 게시해야 합니다.

이러한 권한은 appsettings.json 파일에 지정됩니다. 이 자습서에서는 네 가지 권한을 등록했습니다. 위임된 권한(ToDoList.ReadWrite 및 ToDoList.Read) 및 애플리케이션 권한(ToDoList.ReadWrite.All 및 ToDoList.Read.All).

{
  "AzureAd": {
    "Instance": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/",
    "TenantId": "Enter_the_Tenant_Id_Here",
    "ClientId": "Enter_the_Application_Id_Here",
    "Scopes": {
      "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
      "Write": ["ToDoList.ReadWrite"]
    },
    "AppPermissions": {
      "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
      "Write": ["ToDoList.ReadWrite.All"]
    }
  },
  "Logging": {...},
  "AllowedHosts": "*"
}

인증 체계 추가

인증 체계는 인증 중에 인증 서비스가 구성되면 이름이 지정됩니다. 이 문서에서는 JWT 전달자 인증 체계를 사용합니다. 인증 체계를 추가하려면 Programs.cs 파일에 다음 코드를 추가합니다.

// Add the following to your imports
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

// Add authentication scheme
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration);

모델 만들기

프로젝트의 루트 폴더에 Models라는 폴더를 만듭니다. 폴더로 이동하여 ToDo.cs라는 파일을 만든 후 다음 코드를 추가합니다. 이 코드는 ToDo라는 모델을 만듭니다.

using System;

namespace ToDoListAPI.Models;

public class ToDo
{
    public int Id { get; set; }
    public Guid Owner { get; set; }
    public string Description { get; set; } = string.Empty;
}

데이터베이스 컨텍스트 추가

{b>데이터베이스 컨텍스트Microsoft.EntityFrameworkCore.DbContext 클래스에서 파생되어 만들어집니다. 이 자습서에서는 테스트 목적으로 메모리 내 데이터베이스를 사용합니다.

1. 프로젝트의 루트 폴더에 DbContext라는 폴더를 만듭니다.

2. 해당 폴더로 이동하여 ToDoContext.cs라는 파일을 만든 후 해당 파일에 다음 콘텐츠를 추가합니다.

   using Microsoft.EntityFrameworkCore;
   using ToDoListAPI.Models;
   
   namespace ToDoListAPI.Context;
   
   public class ToDoContext : DbContext
   {
       public ToDoContext(DbContextOptions<ToDoContext> options) : base(options)
       {
       }
   
       public DbSet<ToDo> ToDos { get; set; }
   }
   

3. 앱의 루트 폴더에서 Program.cs 파일을 열고 파일에 다음 코드를 추가합니다. 이 코드는 ASP.NET Core 애플리케이션 서비스 공급자(종속성 삽입 컨테이너라고도 함)에서 범위가 지정된 서비스로 ToDoContext라는 DbContext 하위 클래스를 등록합니다. 컨텍스트는 메모리 내 데이터베이스를 사용하도록 구성됩니다.

   // Add the following to your imports
   using ToDoListAPI.Context;
   using Microsoft.EntityFrameworkCore;
   
   builder.Services.AddDbContext<ToDoContext>(opt =>
       opt.UseInMemoryDatabase("ToDos"));
   

컨트롤러 추가

대부분의 경우 컨트롤러에는 둘 이상의 작업이 있습니다. 일반적으로 CRUD(만들기, 읽기, 업데이트 및 삭제) 작업을 수행합니다. 이 자습서에서는 두 개의 작업 항목만 만듭니다. 엔드포인트를 보호하는 방법을 보여 주는 모든 작업 항목 읽기 및 작업 항목 만들기.

1. 프로젝트 루트 폴더에 있는 Controllers 폴더로 이동합니다.

2. 이 폴더 안에 ToDoListController.cs라는 파일을 만듭니다. 파일을 열고 다음 상용구 코드를 추가합니다.

   using Microsoft.AspNetCore.Authorization;
   using Microsoft.AspNetCore.Mvc;
   using Microsoft.EntityFrameworkCore;
   using Microsoft.Identity.Web;
   using Microsoft.Identity.Web.Resource;
   using ToDoListAPI.Models;
   using ToDoListAPI.Context;
   
   namespace ToDoListAPI.Controllers;
   
   [Authorize]
   [Route("api/[controller]")]
   [ApiController]
   public class ToDoListController : ControllerBase
   {
       private readonly ToDoContext _toDoContext;
   
       public ToDoListController(ToDoContext toDoContext)
       {
           _toDoContext = toDoContext;
       }
   
       [HttpGet()]
       [RequiredScopeOrAppPermission()]
       public async Task<IActionResult> GetAsync(){...}
   
       [HttpPost]
       [RequiredScopeOrAppPermission()]
       public async Task<IActionResult> PostAsync([FromBody] ToDo toDo){...}
   
       private bool RequestCanAccessToDo(Guid userId){...}
   
       private Guid GetUserId(){...}
   
       private bool IsAppMakingRequest(){...}
   }
   

컨트롤러에 코드 추가

이 섹션에서는 Microsoft가 만든 자리 표시자에 코드를 추가합니다. 여기서 포커스는 API 빌드가 아니라 API 보호에 있습니다.

1. 필요한 패키지를 가져옵니다. Microsoft.Identity.Web 패키지는 예를 들어, 토큰 유효성 검사를 처리하여 인증 논리를 쉽게 처리하는 데 도움이 되는 MSAL 래퍼입니다. 엔드포인트에 권한 부여가 필요한지 확인하기 위해 내장된 Microsoft.AspNetCore.Authorization 패키지를 사용합니다.

2. 사용자를 대신하여 위임된 권한을 사용하거나 클라이언트가 사용자를 대신하지 않고 자체적으로 호출하는 애플리케이션 권한을 사용하여 이 API를 호출할 수 있는 권한을 부여했으므로 앱이 자체적으로 호출을 수행하는지 여부를 아는 것이 중요합니다. 이를 수행하는 가장 쉬운 방법은 액세스 토큰에 idtyp 선택적 클레임이 포함되어 있는지 확인하는 클레임입니다. 이 idtyp 클레임은 API가 토큰이 앱 토큰인지 아니면 앱 + 사용자 토큰인지 확인하는 가장 쉬운 방법입니다. idtyp 선택적 클레임을 사용하도록 설정하는 것이 좋습니다.

   idtyp 클레임이 사용하도록 설정되지 않은 경우 roles 및 scp 클레임을 사용하여 액세스 토큰이 앱 토큰인지 또는 앱 + 사용자 토큰인지 확인할 수 있습니다. Microsoft Entra 외부 ID에서 발급한 액세스 토큰에는 두 클레임 중 하나 이상이 있습니다. 사용자에게 발급된 액세스 토큰에는 scp 클레임이 있습니다. 애플리케이션에 발급된 액세스 토큰에는 roles 클레임이 있습니다. 두 클레임을 모두 포함하는 액세스 토큰은 사용자에게만 발급됩니다. 여기서 scp 클레임은 위임된 권한을 지정하고 roles 클레임은 사용자 역할을 지정합니다. 둘 다 없는 액세스 토큰은 인정되지 않습니다.

   private bool IsAppMakingRequest()
   {
       if (HttpContext.User.Claims.Any(c => c.Type == "idtyp"))
       {
           return HttpContext.User.Claims.Any(c => c.Type == "idtyp" && c.Value == "app");
       }
       else
       {
           return HttpContext.User.Claims.Any(c => c.Type == "roles") && !HttpContext.User.Claims.Any(c => c.Type == "scp");
       }
   }
   

3. 요청에 의도한 작업을 수행하기에 충분한 권한이 포함되어 있는지 확인하는 도우미 함수를 추가합니다. 사용자 ID의 유효성을 검사하여 앱이 자체적으로 요청을 수행하는지, 아니면 앱이 특정 리소스를 소유한 사용자를 대신하여 호출을 수행하는지 유효성을 검사합니다.

   private bool RequestCanAccessToDo(Guid userId)
       {
           return IsAppMakingRequest() || (userId == GetUserId());
       }
   
   private Guid GetUserId()
       {
           Guid userId;
           if (!Guid.TryParse(HttpContext.User.GetObjectId(), out userId))
           {
               throw new Exception("User ID is not valid.");
           }
           return userId;
       }
   

4. 경로를 보호하려면 권한 정의를 연결합니다. 컨트롤러 클래스에 [Authorize] 특성을 추가하여 API를 보호합니다. 이렇게 하면 권한 부여된 ID로 API를 호출하는 경우에만 컨트롤러 작업을 호출할 수 있습니다. 권한 정의는 이러한 작업을 수행하는 데 필요한 권한 종류를 정의합니다.

   [Authorize]
   [Route("api/[controller]")]
   [ApiController]
   public class ToDoListController: ControllerBase{...}
   

   GET 모든 엔드포인트와 POST 엔드포인트에 권한을 추가합니다. Microsoft.Identity.Web.Resource 네임스페이스의 일부인 RequiredScopeOrAppPermission 메서드를 사용하여 이 작업을 수행합니다. 그런 다음 RequiredScopesConfigurationKey 및 RequiredAppPermissionsConfigurationKey 특성을 통해 이 메서드에 범위와 권한을 전달합니다.

   [HttpGet]
   [RequiredScopeOrAppPermission(
       RequiredScopesConfigurationKey = "AzureAD:Scopes:Read",
       RequiredAppPermissionsConfigurationKey = "AzureAD:AppPermissions:Read"
   )]
   public async Task<IActionResult> GetAsync()
   {
       var toDos = await _toDoContext.ToDos!
           .Where(td => RequestCanAccessToDo(td.Owner))
           .ToListAsync();
   
       return Ok(toDos);
   }
   
   [HttpPost]
   [RequiredScopeOrAppPermission(
       RequiredScopesConfigurationKey = "AzureAD:Scopes:Write",
       RequiredAppPermissionsConfigurationKey = "AzureAD:AppPermissions:Write"
   )]
   public async Task<IActionResult> PostAsync([FromBody] ToDo toDo)
   {
       // Only let applications with global to-do access set the user ID or to-do's
       var ownerIdOfTodo = IsAppMakingRequest() ? toDo.Owner : GetUserId();
   
       var newToDo = new ToDo()
       {
           Owner = ownerIdOfTodo,
           Description = toDo.Description
       };
   
       await _toDoContext.ToDos!.AddAsync(newToDo);
       await _toDoContext.SaveChangesAsync();
   
       return Created($"/todo/{newToDo!.Id}", newToDo);
   }
   

API 실행

API를 실행하여 dotnet run 명령을 사용하여 오류 없이 잘 실행되는지 확인합니다. 테스트하는 동안에도 HTTPS 프로토콜을 사용하려는 경우 신뢰해야 합니다. NET의 개발 인증서입니다.

이 API 코드의 전체 예를 보려면 샘플 파일을 참조하세요.

다음 단계

2부: 보호된 ASP.NET Core Web API 테스트