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

아티클
2024. 11. 23.

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

빠른 시작: 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를 등록하고 다음 단계를 수행하여 범위를 추가합니다.

최소한 애플리케이션 관리자 자격으로 Microsoft Entra 관리 센터에 로그인합니다.
ID>애플리케이션>앱 등록으로 이동합니다.
새 등록을 선택합니다.
이름에 애플리케이션의 이름을 입력합니다. 예를 들어 AspNetCoreWebApi-Quickstart를 입력합니다. 앱 사용자에게 이 이름이 표시되며 나중에 변경할 수 있습니다.
등록을 선택합니다.
관리에서 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.
상태: 사용

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

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 프로젝트 구성

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

Windows의 경로 길이 제한으로 인한 오류를 방지하기 위해 디스크의 루트에 가까운 로컬 폴더에 .zip 파일의 압축을 풉니다. 예를 들어 파일의 압축을 C:\Azure-Samples에 풉니다.
코드 편집기의 webapi 폴더에서 솔루션을 엽니다.
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을 대상으로 업데이트하려면 다음 단계를 수행합니다.

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

<TargetFramework>netcoreapp3.1</TargetFramework>

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

<TargetFramework>netcoreapp6.0</TargetFramework>

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

5단계: 샘플 실행

터미널을 열고 디렉터리를 프로젝트 폴더로 변경합니다.
```
cd webapi
```
다음 명령을 실행하여 솔루션을 빌드합니다.

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 자습서

다음을 통해 공유