빠른 시작: Microsoft ID 플랫폼을 사용하여 ASP.NET Core 웹 API 보호

환영합니다! 아마도 기대했던 페이지는 아닐 것입니다. 수정 작업을 진행하는 동안 이 링크를 통해 올바른 문서로 이동해야 합니다.

빠른 시작: Microsoft ID 플랫폼 의해 보호되는 ASP.NET Core 웹 API 호출

이 문제를 해결하는 동안 불편을 끼쳐 드려 죄송하며 양해해 주셔서 감사합니다.

다음 빠른 시작에서는 ASP.NET Core 웹 API 코드 샘플을 사용하여 리소스 액세스를 권한 있는 계정으로 제한하는 방법을 보여 줍니다. 이 샘플은 모든 Microsoft Entra 조직에서 개인 Microsoft 계정 및 계정의 권한 부여를 지원합니다.

필수 조건

• 활성 구독이 있는 Azure 계정 체험 계정을 만듭니다.
• Microsoft Entra 테넌트
• .NET 6.0 SDK의 최소 요구 사항
• Visual Studio 2022 또는 Visual Studio Code

1단계: 애플리케이션 등록

먼저 Microsoft Entra 테넌트에 웹 API를 등록하고 다음 단계를 수행하여 범위를 추가합니다.

1. 최소한 애플리케이션 관리자로 Microsoft Entra 관리 센터에 로그인합니다.
2. ID>애플리케이션>앱 등록으로 이동합니다.
3. 새 등록을 선택합니다.
4. 이름에 애플리케이션의 이름을 입력합니다. 예를 들어 AspNetCoreWebApi-Quickstart를 입력합니다. 앱 사용자에게 이 이름이 표시되며 나중에 변경할 수 있습니다.
5. 등록을 선택합니다.
6. 관리에서 API 표시>범위 추가를 선택합니다. 애플리케이션 ID URI의 경우 저장 및 계속을 선택하여 기본값은 수락한 후, 다음 세부 정보를 입력합니다.

• 범위 이름: access_as_user
• 동의할 수 있는 사람은 누구인가요?: 관리자 및 사용자
• 관리자 동의 표시 이름: Access AspNetCoreWebApi-Quickstart
• 관리자 동의 설명: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
• 사용자 동의 표시 이름: Access AspNetCoreWebApi-Quickstart
• 사용자 동의 설명: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
• 상태: 사용

1. 범위 추가를 선택하여 범위 추가를 완료합니다.

2단계: ASP.NET Core 프로젝트 다운로드

GitHub에서 ASP.NET Core 솔루션을 다운로드합니다.

참고 항목

코드 샘플은 현재 ASP.NET Core 3.1을 대상으로 합니다. 이 샘플은 .NET Core 6.0을 사용하도록 업데이트할 수 있으며 샘플 코드를 ASP.NET Core 6.0으로 업데이트하는 단계에서 사용합니다. 이 빠른 시작은 가까운 장래에 더 이상 사용되지 않을 예정이며 .NET 6.0을 사용하도록 업데이트될 예정입니다.

3단계: ASP.NET Core 프로젝트 구성

이 단계에서는 이전에 만든 앱 등록을 사용하도록 샘플 코드를 구성합니다.

1. Windows의 경로 길이 제한으로 인한 오류를 방지하기 위해 디스크의 루트에 가까운 로컬 폴더에 .zip 파일의 압축을 풉니다. 예를 들어 파일의 압축을 C:\Azure-Samples에 풉니다.

2. 코드 편집기의 webapi 폴더에서 솔루션을 엽니다.

3. appsettings.json에서 ClientId 및 TenantId의 값을 바꿉니다.

   "ClientId": "Enter_the_Application_Id_here",
   "TenantId": "Enter_the_Tenant_Info_Here"
   

   • Enter_the_Application_Id_Here는 등록한 애플리케이션의 애플리케이션(클라이언트) ID입니다.
   • Enter_the_Tenant_Info_Here을 다음 중 하나로 바꿉니다.
     • 애플리케이션이 이 조직 디렉터리의 계정만을 지원하는 경우 이 값을 디렉터리(테넌트) ID(GUID) 또는 테넌트 이름(예: contoso.onmicrosoft.com)으로 바꿉니다. 디렉터리(테넌트) ID는 앱의 개요 페이지에서 찾을 수 있습니다.
     • 애플리케이션에서 모든 조직 디렉터리의 계정을 지원하는 경우 이 값을 organizations로 바꿉니다.
     • 애플리케이션에서 모든 Microsoft 계정 사용자를 지원하는 경우 이 값을 common으로 둡니다.

이 빠른 시작에서는 appsettings.json 파일에서 다른 값을 변경하지 마세요.

4단계: 샘플 코드를 ASP.NET Core 6.0으로 업데이트

이 코드 샘플을 ASP.NET Core 6.0을 대상으로 업데이트하려면 다음 단계를 수행합니다.

1. webapi.csproj 열기
2. 다음 줄을 제거합니다.

<TargetFramework>netcoreapp3.1</TargetFramework>

1. 원래 위치에 다음 줄을 추가합니다.

<TargetFramework>netcoreapp6.0</TargetFramework>

이 단계에서는 샘플이 .NET Core 6.0 프레임워크를 대상으로 하는지 확인합니다.

5단계: 샘플 실행

1. 터미널을 열고 디렉터리를 프로젝트 폴더로 변경합니다.

   cd webapi
   

2. 다음 명령을 실행하여 솔루션을 빌드합니다.

dotnet run

빌드에 성공하면 다음 출력이 표시됩니다.

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

샘플 작동 방법

시작 클래스

Microsoft.AspNetCore.Authentication 미들웨어는 호스팅 프로세스가 시작될 때 실행되는 Startup 클래스를 사용합니다. 해당 ConfigureServices 메서드에서는 Microsoft.Identity.Web에서 제공하는 AddMicrosoftIdentityWebApi 확장 메서드가 호출됩니다.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

AddAuthentication() 메서드는 JwtBearer 기반 인증을 추가하도록 서비스를 구성합니다.

.AddMicrosoftIdentityWebApi가 포함된 줄은 웹 API에 Microsoft ID 플랫폼 권한 부여를 추가합니다. 그런 다음, appsettings.json 구성 파일의 AzureAD 섹션에 있는 정보를 기반으로 Microsoft ID 플랫폼에서 발급한 액세스 토큰의 유효성을 검사하도록 구성됩니다.

appsettings.json 키	설명
ClientId	등록된 애플리케이션의 애플리케이션(클라이언트) ID입니다.
Instance	사용자가 인증하는 STS(보안 토큰 서비스) 엔드포인트입니다. 이 값은 일반적으로 https://login.microsoftonline.com/이며, Azure 퍼블릭 클라우드를 나타냅니다.
TenantId	회사 또는 학교 계정이나 Microsoft 개인 계정을 사용하여 사용자를 로그인하는 테넌트의 이름 또는 해당 테넌트 ID(GUID) 또는 common입니다.

Configure() 메서드에는 명명된 기능을 사용할 수 있도록 설정하는 두 가지 중요한 메서드인 app.UseAuthentication() 및 app.UseAuthorization()이 포함되어 있습니다.

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

컨트롤러, 컨트롤러의 메서드 또는 Razor 페이지 보호

컨트롤러 또는 컨트롤러 메서드는 [Authorize] 특성을 사용하여 보호할 수 있습니다. 이 특성은 인증된 사용자만 허용하여 컨트롤러 또는 메서드에 대한 액세스를 제한합니다. 사용자가 인증되지 않은 경우 컨트롤러에 액세스하기 위해 인증 챌린지를 시작할 수 있습니다.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

컨트롤러 범위 유효성 검사

API의 코드는 HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi);를 사용하여 필요한 범위가 토큰에 있는지 확인합니다.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

도움말 및 지원 

도움이 필요하거나, 문제를 보고하거나, 지원 옵션에 대해 알아보려면 개발자를 위한 도움말 및 지원을 참조하세요.

다음 단계

다음 GitHub 리포지토리에는 ASP.NET Core 웹 API 코드 샘플 지침과 다음을 수행하는 방법을 보여 주는 추가 샘플이 포함되어 있습니다.

• 새 ASP.NET Core 웹 API에 인증을 추가합니다.
• 데스크톱 애플리케이션에서 웹 API를 호출합니다.
• Microsoft Graph 및 기타 Microsoft API와 같은 다운스트림 API를 호출합니다.

GitHub의 ASP.NET Core 웹 API 자습서