다음을 통해 공유

최소 API의 인증 및 권한 부여

  • 아티클

참고 항목

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Warning

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조 하세요. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Important

이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

최소 API는 ASP.NET Core 사용할 수 있는 모든 인증 및 권한 부여 옵션을 지원하고 인증 작업 환경을 개선하기 위한 몇 가지 추가 기능을 제공합니다.

인증 및 권한 부여의 주요 개념

인증은 사용자의 identity. 권한 부여는 사용자에게 리소스에 대한 액세스 권한이 있는지를 확인하는 프로세스입니다. 인증 및 권한 부여 시나리오는 모두 ASP.NET Core 유사한 구현 의미 체계를 공유합니다. 인증은 인증 미들웨어에서 사용되는 인증 서비스인 IAuthenticationService를 사용하여 처리됩니다. 권한 부여는 권한 부여 미들웨어에서 사용되는 권한 부여 서비스 IAuthorizationService에 의해 처리됩니다.

인증 서비스는 등록된 인증 처리기를 사용하여 인증 관련 작업을 완료합니다. 예를 들어 인증 관련 작업은 사용자를 인증하거나 사용자를 로그아웃하는 것입니다. 인증 체계는 인증 처리기 및 해당 구성 옵션을 고유하게 식별하는 데 사용되는 이름입니다. 인증 처리기는 인증 전략을 구현하고 OAuth 또는 OIDC와 같은 특정 인증 전략을 고려하여 사용자의 클레임을 생성합니다. 구성 옵션은 전략에서도 고유하며 리디렉션 URI와 같은 인증 동작에 영향을 주는 구성을 처리기에 제공합니다.

권한 부여 계층의 리소스에 대한 사용자 액세스를 결정하는 두 가지 전략이 있습니다.

  • 역할 기반 전략은 할당된 역할(예: Administrator 또는 User)에 따라 사용자의 액세스를 결정합니다. 역할 기반 권한 부여에 대한 자세한 내용은 역할 기반 권한 부여 설명서를 참조하세요.
  • 클레임 기반 전략은 중앙 기관에서 발급한 클레임에 따라 사용자의 액세스를 결정합니다. 클레임 기반 권한 부여에 대한 자세한 내용은 클레임 기반 권한 부여 설명서를 참조하세요.

ASP.NET Core 두 전략은 모두 권한 부여 요구 사항으로 캡처됩니다. 권한 부여 서비스는 권한 부여 처리기를 활용하여 특정 사용자가 리소스에 적용된 권한 부여 요구 사항을 충족하는지 여부를 결정합니다.

최소 앱에서 인증 사용

인증을 사용하도록 설정하려면 AddAuthentication를 호출하여 앱의 서비스 공급자에 필요한 인증 서비스를 등록합니다.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

일반적으로 특정 인증 전략이 사용됩니다. 다음 샘플에서 앱은 JWT 전달자 기반 인증을 지원하도록 구성됩니다. 이 예제에서는 NuGet 패키지에서 사용할 수 있는 API를 Microsoft.AspNetCore.Authentication.JwtBearer 사용합니다.

var builder = WebApplication.CreateBuilder(args);
// Requires Microsoft.AspNetCore.Authentication.JwtBearer
builder.Services.AddAuthentication().AddJwtBearer();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

기본적으로 WebApplication는 특정 인증 및 권한 부여 서비스를 사용하는 경우 인증 및 권한 부여 미들웨어를 자동으로 등록합니다. 다음 샘플에서는 AddAuthentication 또는 AddAuthorization가 호출된 후에 WebApplication이 자동으로 수행하므로 미들웨어 등록하기 위해 UseAuthentication 또는 UseAuthorization를 호출할 필요가 없습니다.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

미들웨어 순서 제어와 같은 경우에 인증 및 권한 부여를 명시적으로 등록해야 합니다. 다음 샘플에서는 CORS 미들웨어가 실행 된 후 인증 미들웨어가 실행됩니다. 미들웨어 및 이 자동 동작에 대한 자세한 내용은 최소 API 앱의 미들웨어를 참조하세요.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");
app.Run();

인증 전략 구성

인증 전략은 일반적으로 옵션을 통해 로드되는 다양한 구성을 지원합니다. 최소 앱은 다음 인증 전략에 대한 구성의 로딩 옵션을 지원합니다.

ASP.NET Core 프레임워크는 구성의 Authentication:Schemes:{SchemeName} 섹션에서 이러한 옵션을 찾을 것으로 예상합니다. 다음 샘플에서는 두 개의 서로 다른 체계인 Bearer 및 LocalAuthIssuer가 해당 옵션으로 정의됩니다. Authentication:DefaultScheme 옵션은 사용되는 기본 인증 전략을 구성하는 데 사용할 수 있습니다.

{
  "Authentication": {
    "DefaultScheme":  "LocalAuthIssuer",
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      },
      "LocalAuthIssuer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "local-auth"
      }
    }
  }
}

Program.cs에서 다음을 사용하여 두 개의 JWT 전달자 기반 인증 전략이 등록됩니다.

  • "전달자" 체계 이름.
  • "LocalAuthIssuer" 체계 이름.

"전달자"는 JWT 전달자 기반 사용 앱의 일반적인 기본 체계이지만 이전 예제와 같이 DefaultScheme 속성을 설정하여 기본 체계를 재정의 할 수 있습니다.

체계 이름은 인증 전략을 고유하게 식별하는 데 사용되며 다음 예제와 같이 구성에서 인증 옵션을 확인할 때 조회 키로 사용됩니다.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
  .AddJwtBearer()
  .AddJwtBearer("LocalAuthIssuer");
  
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

최소 앱에서 권한 부여 정책 구성

인증은 API에 대해 사용자의 식별 및 유효성을 검사 identity 하는 데 사용됩니다. 권한 부여는 API의 리소스에 대한 액세스의 유효성을 검사하고 확인하는 데 사용되며 AddAuthorization 확장 메서드에 의해 등록된 IAuthorizationService에 의해 촉진됩니다. 다음 시나리오 /hello 에서는 사용자가 범위 클레임을 사용하여 역할 클레임을 제시 admin 해야 하는 리소스가 greetings_api 추가됩니다.

리소스에 대한 권한 부여 요구 사항을 구성하는 것은 다음이 필요한 2단계 프로세스입니다.

  1. 정책에서 권한 부여 요구 사항을 전역적으로 구성합니다.
  2. 리소스에 개별 정책 적용.

다음 코드에서 AddAuthorizationBuilder가 호출됩니다.

  • DI 컨테이너에 권한 부여 관련 서비스를 추가합니다.
  • AuthorizationBuilder 권한 부여 정책을 직접 등록하는 데 사용할 수 있는 값을 반환합니다.

이 코드는 두 가지 권한 부여 요구 사항을 캡슐화하는 admin_greetings로 명명된 새 권한 부여 정책을 만듭니다.

  • admin 역할이 있는 사용자를 위한 RequireRole를 통한 역할 기반 요구 사항.
  • 사용자가 범위 클레임을 제공해야 greetings_api 하는 클레임 기반 요구 사항 RequireClaim 입니다.

admin_greetings 정책은 /hello 엔드포인트에 필요한 정책으로 제공됩니다.

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
  .AddPolicy("admin_greetings", policy =>
        policy
            .RequireRole("admin")
            .RequireClaim("scope", "greetings_api"));

var app = builder.Build();

app.MapGet("/hello", () => "Hello world!")
  .RequireAuthorization("admin_greetings");

app.Run();

개발 테스트에 dotnet user-jwts 사용

이 문서 전체에서 JWT 전달자 기반 인증으로 구성된 앱이 사용됩니다. JWT 전달자 기반 인증을 사용하려면 클라이언트가 요청 헤더에 토큰을 제시하여 해당 identity 토큰과 클레임의 유효성을 검사해야 합니다. 일반적으로 이러한 토큰은 서버와 같은 identity 중앙 기관에서 발급합니다.

로컬 컴퓨터에서 개발할 때 dotnet user-jwts 도구를 사용하여 전달자 토큰을 만들 수 있습니다.

dotnet user-jwts create

참고 항목

프로젝트에서 호출될 때 도구는 생성된 토큰과 일치하는 인증 옵션을 appsettings.json에 자동으로 추가합니다.

토큰은 다양한 사용자 지정으로 구성할 수 있습니다. 예를 들어, 이전 코드에서 권한 부여 정책에 필요한 admin 역할 및 greetings_api 범위에 대한 토큰을 만들려면 다음을 수행합니다.

dotnet user-jwts create --scope "greetings_api" --role "admin"

생성된 토큰은 선택한 테스트 도구에서 헤더의 일부로 보낼 수 있습니다. 예를 들어 curl을 사용하면 다음과 같습니다.

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/hello

dotnet user-jwts 도구에 대한 자세한 내용은 전체 설명서를 참조하세요.