자습서: Microsoft ID 플랫폼을 사용하여 ASP.NET Core Web API 빌드 및 보호
적용: 흰색 확인 표시 기호가 있는 녹색 원 
Workforce 테넌트는 흰색 확인 표시 기호가 있는 녹색 원을 외부 테넌트(자세한알아보기)
이 자습서 시리즈에서는 Microsoft ID 플랫폼으로 ASP.NET Core Web API를 보호하여 권한이 부여된 사용자 및 클라이언트 앱에만 액세스할 수 있도록 제한하는 방법을 보여 줍니다. 빌드하는 웹 API는 위임된 권한(범위) 및 애플리케이션 권한(앱 역할)을 모두 사용합니다.
이 자습서에서는 다음을 수행합니다.
- ASP.NET Core 웹 API 빌드
- Microsoft Entra 앱 등록 세부 정보를 사용하도록 웹 API 구성
- 웹 API 엔드포인트 보호
- 웹 API를 실행하여 HTTP 요청을 수신 대기하는지 확인합니다.
필수 구성 요소
- 아직 완료하지 않은 경우 빠른 시작의 단계를 완료합니다. 샘플 웹앱에서 사용자 로그인. 빠른 시작에서는 코드 샘플을 복제하고 실행할 필요가 없습니다.
- .NET 8.0 SDK 이상 또는 더 최신을 사용하십시오.
- Visual Studio Code 또는 다른 코드 편집기.
새 ASP.NET Core Web API 프로젝트 만들기
최소 ASP.NET Core Web API 프로젝트를 만들려면 다음 단계를 수행합니다.
Visual Studio Code 또는 다른 코드 편집기에서 터미널을 열고 프로젝트를 만들 디렉터리로 이동합니다.
.NET CLI 또는 다른 명령줄 도구에서 다음 명령을 실행합니다.
dotnet new webapi -n MyProtectedApi cd MyProtectedApi예를 선택합니다. 대화 상자가 작성자를 신뢰할지 묻는다면 그렇다고 대답하십시오.
예 프로젝트에 필요한 자산을 추가할지 묻는 대화 상자가 표시되면 선택합니다.
필수 패키지 설치
ASP.NET Core 웹 API를 보호하려면 Microsoft ID 플랫폼과 통합되는 웹앱 및 웹 API에 인증 및 권한 부여 지원을 추가하는 것을 간소화하는 ASP.NET Core 라이브러리 집합인 Microsoft.Identity.Web 패키지가 필요합니다.
패키지를 설치하려면 다음을 사용합니다.
dotnet add package Microsoft.Identity.Web
앱 등록 세부 정보 구성
앱 폴더에서 appsettings.json 파일을 열고 웹 API를 등록한 후 기록한 앱 등록 세부 정보를 추가합니다.
{
"AzureAd": {
"Instance": "Enter_the_Authority_URL_Here",
"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_Authority_URL_Here기관 URL로 바꿉습니다.
앱의 권한 URL
기관 URL은 MSAL(Microsoft 인증 라이브러리)에서 토큰을 요청할 수 있는 디렉터리를 지정합니다. 인력 및 외부 테넌트가 다음과 같이 다르게 구성되어 있음을 보여줍니다.
사용자 지정 URL 도메인 사용(선택 사항)
사용자 지정 URL 도메인은 조직 테넌트에서 지원되지 않습니다.
앱 역할 및 범위 추가
모든 API는 클라이언트 앱이 사용자의 액세스 토큰을 성공적으로 가져오려면 위임된 권한이라고도 하는 최소 하나의 범위를 게시해야 합니다. API는 또한 클라이언트 앱이 사용자 로그인을 하지 않을 때도 자체 액세스 토큰을 얻을 수 있도록, 애플리케이션 권한이라고도 하는 최소 하나의 앱 역할을 게시해야 합니다.
appsettings.json 파일에 이러한 권한을 지정합니다. 이 자습서에서는 "Forecast.Read" 범위에 위임된 권한과 애플리케이션 권한을 모두 등록합니다. 즉, "Forecast.Read" 범위를 포함하는 액세스 토큰을 사용하여 API를 호출하는 사용자 또는 클라이언트 애플리케이션만 보호된 엔드포인트에 액세스할 수 있는 권한이 부여됩니다.
{
"AzureAd": {
"Instance": "Enter_the_Authority_URL_Here",
"TenantId": "Enter_the_Tenant_Id_Here",
"ClientId": "Enter_the_Application_Id_Here",
"Scopes": {
"Read": "Forecast.Read",
},
"AppPermissions": {
"Read": ["Forecast.Read"],
}
},
"Logging": {...},
"AllowedHosts": "*"
}
API에서 인증 및 권한 부여 구현
인증 및 권한 부여를 구성하려면 program.cs 파일을 열고 해당 내용을 다음 코드 조각으로 바꿉니다.
인증 체계 추가
이 API에서는 JWT(JSON Web Token) 전달자 체계를 기본 인증 메커니즘으로 사용합니다.
AddAuthentication 메서드를 사용하여 JWT 전달자 체계를 등록합니다.
// Import the required packages
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;
var builder = WebApplication.CreateBuilder(args);
// Configure authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddMicrosoftIdentityWebApi(options =>
{
builder.Configuration.Bind("AzureAd", options);
options.TokenValidationParameters.NameClaimType = "name";
}, options => { builder.Configuration.Bind("AzureAd", options); });
권한 부여 구성
권한 부여는 인증된 사용자가 수행할 수 있는 작업을 결정합니다. API를 호출하는 클라이언트가 클라이언트 앱에 대한 Forecast.Read 역할 또는 로그인한 사용자의 Forecast.Read 범위를 갖도록 요구하는 AuthZPolicy이라는 정책을 정의합니다.
builder.Services.AddAuthorization(config =>
{
config.AddPolicy("AuthZPolicy", policy =>
policy.RequireRole("Forecast.Read"));
});
AddPolicy 메서드는 사용자의 토큰 클레임에 Forecast.Read 역할이 있는지 확인하는 명명된 정책(AuthZPolicy)을 만듭니다. 토큰에 roles 클레임이 없는 경우 이 정책이 필요한 엔드포인트에 대한 액세스가 거부됩니다.
HTTP 요청 파이프라인 빌드
이 자습서에서는 API 보호에 중점을 두기 때문에 컨트롤러 없이 최소 API를 사용합니다. 다음을 추가하여 API 미들웨어 파이프라인을 구성합니다.
- HTTPS 리디렉션: HTTP 요청을 HTTPS로 리디렉션하여 보안 통신을 적용합니다.
- 인증 미들웨어: 요청을 처리하기 전에 들어오는 토큰의 유효성을 검사합니다.
- 권한 부여 미들웨어: 인증 후에 정책을 적용하여 권한 있는 클라이언트만 보호된 엔드포인트에 액세스할 수 있도록 합니다.
var app = builder.Build();
// Configure the HTTP request pipeline
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
일기 예보 엔드포인트 정의
/weatherforecast 엔드포인트는 권한 부여 정책으로 보호되는 임의의 5일 예측을 생성합니다.
RequireAuthorization("AuthZPolicy")
Forecast.Read 역할이 있는 클라이언트만 액세스할 수 있도록 합니다.
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", () =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
Random.Shared.Next(-20, 55),
summaries[Random.Shared.Next(summaries.Length)]
))
.ToArray();
return forecast;
})
.WithName("weatherForecast")
.RequireAuthorization("AuthZPolicy"); // Protect this endpoint with the AuthZPolicy
app.Run();
record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
만든 샘플 웹 API의 인증 및 권한 부여 흐름은 다음과 같이 작동합니다.
- 클라이언트는
Authorization헤더에서 JWT를 사용하여/weatherforecastGET 요청을 보냅니다. -
UseAuthenticationMicrosoft Entra ID에 대해 토큰의 유효성을 검사합니다. -
UseAuthorization는 토큰의 주장에서Forecast.Read의 역할을 확인합니다. - 성공하면 엔드포인트는 예측을 반환합니다. 그렇지 않으면
401 Unauthorized(잘못된/아니요 토큰) 또는403 Forbidden(역할 누락)로 응답합니다.
API 실행
명령 dotnet run사용하여 오류 없이 실행되도록 API를 실행합니다. 테스트하는 동안에도 HTTPS 프로토콜을 사용하려는 경우 트러스트를 합니다. NET의 개발 인증서.
터미널에 다음을 입력하여 애플리케이션을 시작합니다.
dotnet run애플리케이션이
http://localhost:{port}실행 중이고 요청을 수신 대기 중임을 확인하는 다음과 유사한 출력이 터미널에 표시되어야 합니다.Building... info: Microsoft.Hosting.Lifetime[0] Now listening on: http://localhost:{port} info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. ...
웹 페이지 http://localhost:{host} 다음 이미지와 유사한 출력을 표시합니다. 이는 API가 인증 없이 호출되기 때문입니다. 권한 있는 호출을 수행하려면 다음 단계 참조하여 보호된 웹 API에 액세스하는 방법에 대한 지침을 참조하세요.
이 API 코드의 전체 예제는 샘플 파일참조하세요.