빠른 시작: ASP.NET Core 웹앱에서 사용자 로그인

빠른 시작 가이드에서는 Microsoft.Identity.Web을 사용하여 Microsoft Entra ID로 사용자를 로그인하는 ASP.NET Core 웹앱을 만듭니다. 템플릿에서 새 프로젝트를 스캐폴드하거나 기존 앱에 인증을 추가할 수 있습니다.

Microsoft Entra 테넌트가 없는 경우 시작하기 전에 free 계정을 만듭니다.

사전 요구 사항

• .NET 9 SDK
• Microsoft Entra ID 테넌트
• 사용자의 Microsoft Entra 테넌트 내에서 앱 등록 애플리케이션을 만들어야 하는 경우 애플리케이션 등록을 참조하세요.

템플릿에서 프로젝트 만들기

시작하는 가장 빠른 방법은 인증이 미리 구성된 새 프로젝트를 스캐폴드하는 것입니다.

다음 명령을 실행하여 단일 조직 인증을 사용하여 새 웹앱을 만들고 프로젝트 디렉터리로 이동합니다.

dotnet new webapp --auth SingleOrg --name MyWebApp
cd MyWebApp

템플릿은 이미 Microsoft.Identity.Web이 구성된 프로젝트를 생성합니다. 앱 등록 세부 정보만 제공해야 합니다.

appsettings.json 자리 표시자 값을 열고 앱 등록에서 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID로 바꿉니다.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc"
  }
}

애플리케이션을 시작하여 로그인이 작동하는지 확인합니다.

dotnet run

로그인으로 이동하여 https://localhost:5001선택합니다. Microsoft 로그인 프롬프트가 나타나면 구성이 올바릅니다.

기존 웹앱에 인증 추가

기존 ASP.NET Core 앱이 있는 경우 다음 단계에 따라 Microsoft Entra 로그인을 추가합니다.

NuGet 패키지 설치

Microsoft.Identity.Web 라이브러리를 추가하십시오. Microsoft.Identity.Web 패키지는 인증을 처리하고 Microsoft.Identity.Web.UI 미리 빌드된 로그인 및 로그아웃 UI 구성 요소를 제공합니다.

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI

인증 서비스 구성

Program.cs 인증 서비스를 열고 추가합니다. 다음 코드는 Microsoft Entra OpenID Connect 인증을 등록하고, 다운스트림 API 호출에 토큰 획득을 사용하도록 설정하고, 로그인/로그아웃 UI를 추가합니다.

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApp(builder.Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi() // Optional: if calling APIs
                .AddInMemoryTokenCaches(); // For production, use distributed cache

// Add Razor Pages or MVC
builder.Services.AddRazorPages()
    .AddMicrosoftIdentityUI(); // Adds sign-in/sign-out UI

var app = builder.Build();

// Configure middleware
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapRazorPages();
app.MapControllers();

app.Run();

Microsoft Entra 구성 추가

appsettings.json 섹션을 열고 추가합니다AzureAd. 자리 표시자 값을 앱 등록의 애플리케이션(클라이언트) ID로 바꿉니다. 앱에 적합한 대상 그룹으로 설정합니다 TenantId .

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-client-id-from-app-registration",
    "CallbackPath": "/signin-oidc"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

이 TenantId 값은 로그인할 수 있는 계정을 결정합니다.

페이지 보호

로그인이 필요한 페이지 또는 컨트롤러에 [Authorize] 특성을 추가합니다.

Razor Pages의 경우 특성은 [Authorize] 인증되지 않은 사용자를 로그인 페이지로 리디렉션합니다. 로그인 후, 사용자는 Name 및 preferred_username와 같은 클레임을 User 객체를 통해 사용할 수 있습니다.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc.RazorPages;

[Authorize] //  Require authentication
public class IndexModel : PageModel
{
    public void OnGet()
    {
        var userName = User.Identity?.Name;
        var userEmail = User.FindFirst("preferred_username")?.Value;
    }
}

MVC 컨트롤러의 경우 컨트롤러 또는 작업 수준에서 동일한 [Authorize] 특성이 적용됩니다.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require authentication
public class HomeController : Controller
{
    public IActionResult Index()
    {
        var userName = User.Identity?.Name;
        return View();
    }
}

로그인 및 로그아웃 링크 추가

사용자가 로그인하고 로그아웃할 수 있도록 레이아웃에 탐색 링크를 추가합니다. MicrosoftIdentity 영역 경로는 Microsoft.Identity.Web.UI 패키지에서 제공됩니다. 다음 Razor 태그는 사용자의 인증 상태에 따라 로그아웃 또는 로그인을 조건에 따라 렌더링합니다.

<ul class="navbar-nav">
    @if (User.Identity?.IsAuthenticated == true)
    {
        <li class="nav-item">
            <span class="nav-link">Hello @User.Identity.Name!</span>
        </li>
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a>
        </li>
    }
    else
    {
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a>
        </li>
    }
</ul>

실행 및 테스트

애플리케이션을 시작하여 인증이 작동하는지 확인합니다.

dotnet run

https://localhost:5001으로 이동합니다. 로그인 링크가 표시됩니다. Microsoft 로그인 흐름이 성공적으로 완료되었는지 확인하려면 선택합니다.

애플리케이션 등록

앱 등록이 아직 없는 경우 다음 단계에 따라 Azure 포털에서 만듭니다.

1. Azure Portal에 로그인합니다.
2. Microsoft Entra ID>앱 등록 새 등록으로> 이동합니다.
3. 표시 이름(예: "내 웹앱")을 입력합니다.
4. 지원되는 계정 유형을 선택합니다.
   • 단일 테넌트 - 조직의 사용자만
   • 다중 테넌트 - 모든 조직의 사용자
   • 멀티 테넌트 + 개인 — 모든 Microsoft 계정
5. 리디렉션 URI에서 플랫폼을 웹으로 설정하고 입력https://localhost:5001/signin-oidc합니다.
6. 등록을 선택합니다.
7. 개요 페이지에서 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID를 복사합니다. appsettings.json의 ClientId 및 TenantId 필드에는 이러한 값들이 필요합니다.

선택적 설정 구성

시나리오에 이러한 추가 설정이 필요할 수 있습니다.

ID 토큰 발급 사용 - 일부 하이브리드 인증 시나리오에서는 권한 부여 엔드포인트에서 직접 ID 토큰을 발급해야 합니다. 권한 부여 코드 흐름(Microsoft.Identity.Web 사용)이 권장되는 접근 방식입니다. 시나리오에 특별히 필요한 경우에만 이 설정을 사용하도록 설정합니다.

1. 앱 등록에서 인증으로 이동합니다.
2. 암시적 권한 부여 및 하이브리드 흐름에서 ID 토큰을 선택합니다.
3. 저장을 선택합니다.

프런트 채널 로그아웃 URL 구성 - 사용자가 Microsoft Entra 로그아웃할 때 앱에서 로그아웃되었는지 확인합니다.

1. 앱 등록에서 인증으로 이동합니다.
2. 프론트 채널 로그아웃 URL 아래에 값을 입력합니다https://localhost:5001/signout-oidc.
3. 저장을 선택합니다.

일반적인 오류 해결 방법

로그인하는 동안 문제가 발생하는 경우 이러한 일반적인 오류를 확인합니다.

관련 콘텐츠

• 웹앱에서 다운스트림 API 호출
• 승인
• 토큰 캐시 개요
• 빠른 시작: Web API