이 문서는 ASP.NET Core 환경에서 Identity.API를 활용하여 사용자 인증 및 권한 부여 서비스를 구축하는 과정을 상세히 설명합니다. EF Core를 통한 데이터베이스 연동, 서비스 헬스 체크, 분산 추적을 위한 OpenTelemetry 통합, 서비스 디스커버리 구현, 그리고 OAuth2/OpenID Connect 기반의 IdentityServer 설정까지 다룹니다.
1. 프로젝트 시작 및 데이터베이스 구성
docker-compose를 이용하여 개발 환경을 구성하고 프로젝트의 데이터베이스 연결 문자열을 설정한 후 프로젝트를 시작합니다. 첫 실행 시 EF Core가 IdentityDB 데이터베이스에 연결을 시도하며, 데이터베이스가 존재하지 않으면 자동으로 생성하고 마이그레이션을 적용합니다. DBeaver와 같은 데이터베이스 관리 도구를 통해 Identity.API 서비스의 데이터베이스와 테이블이 정상적으로 생성되었는지 확인할 수 있습니다.
2. 헬스 체크 구현
서비스의 상태를 모니터링하기 위해 헬스 체크 서비스를 등록합니다. 이는 애플리케이션의 활성(Liveness) 및 준비(Readiness) 상태를 외부에 노출하는 중요한 기능입니다.
주요 설정:
self라는 이름의 헬스 체크 항목을 등록합니다.- 이 항목은 항상 건강(Healthy) 상태를 반환하여 서비스 프로세스 자체의 실행 여부를 나타냅니다.
"live"태그를 부여하여 활성 상태 체크에 사용될 수 있도록 합니다.
| 구성 요소 | 설명 |
|---|---|
builder.Services.AddHealthChecks() |
DI 컨테이너에 헬스 체크 서비스 등록 |
.AddCheck("self", ...) |
"self"라는 이름의 헬스 체크 항목 추가 |
() => HealthCheckResult.Healthy() |
항상 Healthy 결과 반환 (서비스 자체 실행 중) |
["live"] |
해당 체크 항목에 "live" 태그 부여 (활성 체크 구분) |
public static IHostApplicationBuilder AddDefaultHealthChecks(this IHostApplicationBuilder builder)
{
builder.Services.AddHealthChecks()
.AddCheck("self", () => HealthCheckResult.Healthy(), ["live"]);
return builder;
}
// 개발 환경에서 헬스 체크 엔드포인트 노출
if (app.Environment.IsDevelopment())
{
// /health: 서비스가 트래픽을 받을 준비가 되었는지 (의존성 포함)
app.MapHealthChecks("/health");
// /alive: 서비스 프로세스가 살아있는지 (자체 생존 여부)
app.MapHealthChecks("/alive", new HealthCheckOptions
{
Predicate = r => r.Tags.Contains("live")
});
}
/health엔드포인트는 모든 헬스 체크 항목(의존성 포함)이 통과해야 건강한 상태를 반환하여 서비스의 전반적인 준비 상태를 나타냅니다./alive엔드포인트는"live"태그가 있는 헬스 체크 항목만 검사하여 서비스 프로세스 자체의 활성 상태를 확인합니다. 데이터베이스 오류와 같은 외부 의존성 문제와 무관하게 서비스 프로세스만 실행 중이면 Healthy를 반환합니다.
이러한 헬스 체크는 Kubernetes나 Docker와 같은 컨테이너 오케스트레이션 플랫폼에서 서비스 상태를 자동 관리하고 장애 발생 시 서비스를 재시작하거나 제거하는 데 활용됩니다.
3. OpenTelemetry 통합
OpenTelemetry (OTel)는 애플리케이션의 관찰 가능성(Observability)을 제공하는 오픈 소스 프레임워크입니다. 이를 통해 분산 환경에서 애플리케이션의 동작을 효과적으로 모니터링하고 분석할 수 있습니다.
- Trace (분산 트레이싱): 요청의 흐름과 각 서비스 간의 지연 시간을 파악합니다.
- Metrics (메트릭): 요청 수, 응답 시간, CPU 사용량 등 애플리케이션 성능 지표를 수집합니다.
- Logs (로그): 구조화된 로그를 통해 이벤트 세부 정보를 기록합니다.
| 범주 | 지원 도구 |
|---|---|
| 시각화 플랫폼 | Jaeger, Zipkin, Grafana, Datadog, New Relic |
| 클라우드 플랫폼 | Azure Monitor, AWS CloudWatch, Google Cloud |
| 미들웨어 | ASP.NET Core, gRPC, EF Core, Redis, MongoDB |
| 에이전트 | OpenTelemetry Collector (데이터 수집 및 전송) |
3.1 로그 수집
로그가 OpenTelemetry를 통해 수집되도록 설정합니다. 구조화된 로그 형식을 지원하며, 특정 요청과 관련된 로그를 쉽게 찾을 수 있도록 스코프(Scope) 정보를 유지합니다.
// OpenTelemetry 로그 설정
builder.Logging.AddOpenTelemetry(logging =>
{
// 구조화된 로그 형식 지원
logging.IncludeFormattedMessage = true;
// 특정 요청 관련 로그를 쉽게 찾기 위한 스코프 유지
logging.IncludeScopes = true;
});
3.2 메트릭 수집
애플리케이션의 다양한 성능 지표(메트릭)를 자동으로 수집하도록 구성합니다.
// OpenTelemetry 메트릭 수집 설정
builder.Services.AddOpenTelemetry()
.WithMetrics(metrics =>
{
metrics.AddAspNetCoreInstrumentation() // ASP.NET Core 요청 메트릭
.AddHttpClientInstrumentation() // HttpClient 호출 메트릭
.AddRuntimeInstrumentation() // .NET CLR 런타임 메트릭
.AddMeter("Experimental.Microsoft.Extensions.AI"); // 사용자 정의 AI 컴포넌트 메트릭
});
3.3 트레이싱 설정
애플리케이션 내의 요청 흐름을 추적하여 분산 시스템의 동작을 시각화하고 병목 현상을 진단하는 데 사용됩니다.
// OpenTelemetry 트레이싱 설정
.WithTracing(tracing =>
{
if (builder.Environment.IsDevelopment())
{
// 개발 환경에서는 모든 트레이스를 샘플링
tracing.SetSampler(new AlwaysOnSampler());
}
tracing.AddAspNetCoreInstrumentation() // HTTP 요청 자동 추적
.AddGrpcClientInstrumentation() // gRPC 클라이언트 호출 자동 추적
.AddHttpClientInstrumentation() // HttpClient 요청 자동 추적
.AddSource("Experimental.Microsoft.Extensions.AI");
});
3.4 데이터 익스포터
수집된 로그, 메트릭, 트레이스 데이터를 Jaeger, Grafana, Zipkin 등 외부 관찰 가능성 플랫폼으로 전송하기 위한 익스포터를 설정합니다. OTLP (OpenTelemetry Protocol)는 OpenTelemetry가 권장하는 표준 데이터 형식입니다.
// 데이터 익스포터 설정
builder.AddOpenTelemetryExporters();
private static IHostApplicationBuilder AddOpenTelemetryExporters(this IHostApplicationBuilder builder)
{
// OTLP 익스포터 사용 여부 확인
var useOtlpExporter = !string.IsNullOrWhiteSpace(builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]);
if (useOtlpExporter)
{
// 로그 익스포터 설정
builder.Services.Configure<OpenTelemetryLoggerOptions>(logging => logging.AddOtlpExporter());
// 메트릭 익스포터 설정
builder.Services.ConfigureOpenTelemetryMeterProvider(metrics => metrics.AddOtlpExporter());
// 트레이싱 익스포터 설정
builder.Services.ConfigureOpenTelemetryTracerProvider(tracing => tracing.AddOtlpExporter());
}
return builder;
}
4. 서비스 등록 및 발견
.NET Aspire 생태계의 Service Discovery 모듈은 마이크로서비스 환경에서 서비스 자동 등록 및 검색을 위한 즉시 사용 가능한 인프라 컴포넌트입니다.
builder.Services.AddServiceDiscovery();
AddServiceDiscovery는 다음과 같은 내부 메서드를 호출합니다.
public static IServiceCollection AddServiceDiscovery(this IServiceCollection services)
=> AddServiceDiscoveryCore(services)
.AddConfigurationServiceEndpointProvider()
.AddPassThroughServiceEndpointProvider();
| 메서드 | 기능 |
|---|---|
AddServiceDiscoveryCore() |
핵심 서비스(선택기, 관찰자 등) 주입 |
AddConfigurationServiceEndpointProvider() |
설정 파일 기반 서비스 검색 구현 주입 |
AddPassThroughServiceEndpointProvider() |
사용자가 제공한 주소를 직접 사용하는(서비스 검색 건너뛰기) 구현 주입 |
4.1 핵심 서비스 구성
AddServiceDiscoveryCore는 서비스 발견의 핵심 기능을 DI 컨테이너에 등록합니다. AddOptions() 및 AddLogging()과 같은 기본 서비스는 ASP.NET Core Web 애플리케이션에서는 기본적으로 주입되지만, 이 메서드는 콘솔 애플리케이션이나 라이브러리 등 비-웹 환경에서도 서비스 발견 기능이 정상 작동하도록 명시적으로 주입합니다 (TryAdd* 메서드를 사용하여 중복 등록 방지).
| 기능 | 역할 |
|---|---|
| 매개변수 검증 | 견고성 보장 |
| Options 및 Logging 주입 | 설정 및 로깅 지원 |
| 설정 유효성 검사기 등록 | 시작 시 설정의 정확성 확인 |
| 시간 서비스 주입 | 테스트 용이성 및 제어 향상 |
| 서비스 엔드포인트 선택기 등록 | 로드 밸런싱 구현 (기본 라운드 로빈) |
| 관찰자 팩토리 주입 | 서비스 등록 변경(온/오프라인, 주소 목록 업데이트) 지원 |
| 메시지 핸들러 팩토리 주입 | 요청 가로채기 및 서비스 이름 해석 (서비스 이름 기반 주소 재작성) |
| 엔드포인트 해석기 등록 | 서비스 이름을 실제 IP:Port 주소로 변환 |
ServiceEndpointResolver는 서비스 발견의 핵심 실행자로, 서비스 이름을 실제 IP:Port 주소로 해석합니다. 이는 ServiceEndpointWatcherFactory를 통해 사용 가능한 서비스 인스턴스 목록을 얻고, 라운드 로빈과 같은 전략을 사용하여 주소를 선택합니다. 호출자는 서비스가 어떻게 등록되고 변경되는지에 대해 신경 쓸 필요 없이 바로 사용할 수 있습니다.
4.2 설정 파일 기반 서비스 탐색
AddConfigurationServiceEndpointProvider는 IConfiguration (예: appsettings.json)을 통해 서비스 주소를 지정할 수 있는 서비스 발견 제공자를 등록합니다. 이를 통해 설정 파일을 기반으로 서비스 엔드포인트를 해석하고, 관련 서비스(엔드포인트 팩토리, 설정 유효성 검사기)를 DI 컨테이너에 주입합니다.
# appsettings.json 예시
{
"ServiceDiscovery": {
"CatalogService": {
"Endpoints": [ "https://catalog.mycompany.com/api" ]
}
}
}
var provider = app.Services.GetRequiredService<IServiceEndpointProvider>();
var endpoint = await provider.GetEndpointAsync("CatalogService");
Console.WriteLine(endpoint);
4.3 직접 주소 사용
AddPassThroughServiceEndpointProvider는 "투과형(Pass-Through)" 서비스 발견 제공자를 등록합니다. 이 제공자는 입력된 서비스 주소를 그대로 사용하며, 별도의 해석이나 검색을 수행하지 않습니다. 이는 서비스 주소를 이미 알고 있어 동적 서비스 발견이 필요 없는 상황에 유용합니다.
var provider = app.Services.GetRequiredService<IServiceEndpointProvider>();
// 이미 상품 서비스의 전체 주소를 알고 있는 경우
var endpoint = await provider.GetEndpointAsync("https://localhost:5005/api");
Console.WriteLine(endpoint);
AddConfigurationServiceEndpointProvider와 AddPassThroughServiceEndpointProvider는 AddServiceDiscoveryCore를 중복 호출할 수 있지만, TryAdd* 계열 메서드를 사용하여 서비스가 이미 등록된 경우 건너뛰므로 실제로는 중복 등록 문제가 발생하지 않습니다. 이는 각 확장 메서드가 독립적으로 사용될 수 있도록 하는 방어적 프로그래밍 패턴입니다.
5. HttpClient 구성
HttpClientFactory를 통해 생성되는 모든 HttpClient 인스턴스에 대한 기본 동작을 설정합니다. 이는 재사용성, 탄력성(Resilience), 서비스 검색 통합을 위한 중요한 단계입니다.
// 모든 HttpClient에 대한 기본 동작 설정
builder.Services.ConfigureHttpClientDefaults(http =>
{
// 기본 탄력성 처리 (리트라이, 서킷 브레이커 등) 활성화
http.AddStandardResilienceHandler();
// 서비스 발견 기능 활성화 (Dapr, Consul, Kubernetes DNS 등과 통합)
http.AddServiceDiscovery();
});
5.1 HttpClientFactory 등록
ConfigureHttpClientDefaults는 내부적으로 HttpClientFactory를 등록하고, DefaultHttpClientBuilder를 생성하여 사용자 정의 설정 델리게이트를 적용합니다.
AddHttpClient는 DefaultHttpClientFactory를 IHttpClientFactory 및 IHttpMessageHandlerFactory 인터페이스로 여러 번 주입합니다. 이는 DefaultHttpClientFactory가 두 인터페이스를 모두 구현하므로 동일한 인스턴스를 여러 역할로 재사용하여 리소스 낭비를 줄이고 일관성을 유지하기 위함입니다.
IHttpClientFactory:HttpClient인스턴스 생성 및 수명 주기 관리, 소켓 고갈 방지, 명명된/유형화된 클라이언트 지원.IHttpMessageHandlerFactory:HttpClient의 파이프라인(DelegatingHandler) 생성 및 캐시 관리, 하위 수준에서 핸들러 파이프라인을 제어할 때 사용.
5.2 기본 탄력성 처리
AddStandardResilienceHandler는 .NET의 Polly 확장 라이브러리를 사용하여 HTTP 요청에 대한 탄력성 파이프라인을 구성합니다. 이 파이프라인은 요청 실패, 타임아웃, 과부하 등의 상황에서 자동 리트라이, 속도 제한, 서킷 브레이커, 타임아웃 처리 등을 수행합니다.
주요 기능:
HttpStandardResilienceOptions를 위한 강력한 유효성 검사 등록.- 속도 제한, 총 요청 타임아웃, 리트라이, 서킷 브레이커, 시도 타임아웃 등 여러 Polly 정책을 파이프라인에 추가.
HttpClient자체의Timeout속성을Timeout.InfiniteTimeSpan으로 설정하여 비활성화합니다. 이는 Polly 정책 파이프라인과의 충돌을 피하고 모든 타임아웃 제어를 Polly에게 위임하기 위함입니다.
5.3 HttpClient에 서비스 발견 활성화
HttpClientBuilder.AddServiceDiscovery()를 호출하여 HttpClient에 서비스 발견 기능을 통합합니다. HttpClient는 HTTP 요청을 보내는 도구이지만, 마이크로서비스 환경에서 대상 서비스의 주소는 동적으로 변할 수 있습니다. 서비스 발견 메커니즘은 요청이 전송되기 전에 요청을 가로채어 "논리적 서비스 이름"(예: http://order-service/api/xxx)을 실제 IP 주소와 포트로 대체합니다. 이를 통해 HttpClient는 하드 코딩된 주소 없이 투명하게 마이크로서비스를 호출할 수 있습니다.
주요 동작:
- 서비스 발견을 위한 핵심 서비스(서비스 주소 모니터링, 캐시 등) 등록.
ResolvingHttpDelegatingHandler라는 사용자 정의HttpMessageHandler를HttpClient에 추가. 이 핸들러는 요청을 보내기 전에 서비스 이름을 실제 서비스 주소로 해석하고 대체하는 역할을 수행합니다.- gRPC 클라이언트의 내장 로드 밸런싱을 비활성화하여 서비스 발견 메커니즘과의 충돌을 방지합니다.
6. MVC 컨트롤러 등록
Identity.API는 MVC 아키텍처를 사용하여 개발되었으므로, ASP.NET Core 애플리케이션에서 MVC 컨트롤러와 Razor 뷰 엔진을 지원하도록 등록합니다.
// MVC 컨트롤러(Controller) 및 뷰 엔진(Razor 뷰) 등록
builder.Services.AddControllersWithViews();
7. 데이터베이스 컨텍스트 구성
Identity.API는 PostgreSQL 데이터베이스를 사용하며, Entity Framework Core의 ApplicationDbContext를 통해 데이터베이스와 상호작용합니다. ApplicationDbContext는 IdentityDbContext<ApplicationUser>를 상속받아 ASP.NET Core Identity의 사용자 인증 관련 테이블 구조를 자동으로 제공합니다.
// Npgsql 데이터베이스 컨텍스트 설정. "identitydb"는 연결 문자열 이름.
builder.AddNpgsqlDbContext<ApplicationDbContext>("identitydb");
public class ApplicationDbContext : IdentityDbContext<ApplicationUser>
{
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
: base(options)
{
}
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
}
}
8. 데이터베이스 마이그레이션 및 초기 데이터 생성
애플리케이션 시작 시 데이터베이스 마이그레이션을 자동으로 실행하고, 필요한 초기 데이터를 삽입하는 시딩(Seeding) 작업을 수행합니다. 이 접근 방식은 개발 환경에서는 편리하지만, 프로덕션 환경에서는 SQL 스크립트 생성을 고려하는 것이 좋습니다.
// 데이터베이스 마이그레이션 및 초기 데이터 실행
// 프로덕션 환경에는 권장되지 않으며, SQL 스크립트 생성을 고려하십시오.
builder.Services.AddMigration<ApplicationDbContext, UsersSeed>();
UsersSeed 클래스는 IDbSeeder<ApplicationDbContext> 인터페이스를 구현하여 ApplicationDbContext에 초기 데이터를 제공합니다. 이 클래스는 ILogger<UsersSeed> (로그 기록)와 UserManager<ApplicationUser> (사용자 생성/조회)를 주입받아 사용합니다. SeedAsync 메서드에서는 FindByNameAsync를 통해 사용자가 존재하는지 확인하고, 존재하지 않으면 'alice'와 'bob' 두 명의 기본 사용자를 생성합니다.
public interface IDbSeeder<in TContext> where TContext : DbContext
{
Task SeedAsync(TContext context);
}
9. ASP.NET Core Identity 구성
ASP.NET Core Identity는 사용자 계정을 관리하고 인증 서비스를 제공하는 프레임워크입니다. 이 코드는 사용자 인증 시스템을 설정합니다.
// 사용자 정의 User 타입 ApplicationUser와 기본 Role 타입 IdentityRole을 사용하여
// Identity 인증 서비스를 등록합니다.
// 사용자 정보는 ApplicationDbContext에 연결된 데이터베이스에 저장되며,
// 기본 토큰 제공자를 활성화하여 인증 검증 등의 기능을 지원합니다.
builder.Services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();
9.1 Identity 서비스 등록
AddIdentity<TUser, TRole>()는 사용자 관리, 역할 관리, 비밀번호 검증, 로그인/로그아웃, 비밀번호 재설정 등 Identity가 필요로 하는 핵심 서비스를 등록합니다. 이는 일반적으로 데이터베이스 컨텍스트(EF Core)와 연동하여 사용자 및 역할 데이터를 영구 저장합니다.
AddIdentity는 UserManager<TUser>, RoleManager<TRole>, SignInManager<TUser>, IUserStore<TUser>, IRoleStore<TRole> 등 다양한 핵심 서비스를 DI 컨테이너에 등록합니다. TUser는 사용자 엔티티 클래스(예: ApplicationUser)를, TRole은 역할 엔티티 클래스(예: IdentityRole)를 정의합니다.
AddIdentity는 Authentication 및 Identity가 필요로 하는 여러 쿠키 스킴(주 로그인, 외부 로그인, 2단계 인증 등)을 설정합니다. 또한 IHttpContextAccessor를 명시적으로 등록하여 Identity 컴포넌트가 HttpContext에 접근할 수 있도록 보장합니다. 핵심 Identity 서비스들은 TryAddScoped를 사용하여 등록되므로, 사용자가 기본 구현을 필요에 따라 재정의할 수 있습니다.
9.2 사용자 엔티티 (IdentityUser)
IdentityUser는 ASP.NET Core Identity 프레임워크의 내장 사용자 엔티티 클래스로, 사용자 계정과 관련된 일반적인 필드를 캡슐화합니다. 이는 등록, 로그인, 비밀번호 관리, 계정 잠금, 보안 검증 등 완전한 사용자 기능을 지원합니다.
| 속성 | 타입 | 설명 |
|---|---|---|
Id |
string |
사용자 고유 식별자 (기본 Guid 문자열) |
UserName |
string |
사용자 이름 |
Email |
string |
사용자 이메일 |
PasswordHash |
string |
비밀번호 해시 값 (보안 저장) |
SecurityStamp |
string |
보안 스탬프 (비밀번호 변경 시 업데이트) |
PhoneNumber |
string |
전화번호 |
TwoFactorEnabled |
bool |
2단계 인증 활성화 여부 |
LockoutEnd |
DateTimeOffset? |
사용자 잠금 만료 시간 |
ApplicationUser 클래스는 IdentityUser를 상속받아 추가 필드를 정의하여 사용자 엔티티를 확장합니다. 이 필드들은 EF Core를 통해 데이터베이스 테이블에 자동으로 매핑됩니다.
9.3 역할 엔티티 (IdentityRole)
IdentityRole은 Identity 시스템에서 "역할"을 나타내는 내장 클래스입니다. 역할은 관리자(Admin), 일반 사용자(User) 등과 같은 권한 집합을 나타냅니다. Identity.API는 기본 IdentityRole을 사용하며, 필요시 IdentityRole을 상속받아 ApplicationRole과 같이 추가 필드를 정의하여 확장할 수 있습니다.
| 속성 | 타입 | 설명 |
|---|---|---|
Id |
string |
역할 고유 식별자 |
Name |
string |
역할 이름 (예: Admin, User) |
NormalizedName |
string |
표준화된 역할 이름 |
ConcurrencyStamp |
string |
동시성 제어용 식별자 |
9.4 사용자 정보 저장소 구성
AddEntityFrameworkStores는 Identity의 사용자/역할 데이터 저장 메커니즘을 Entity Framework Core와 연동하고, IUserStore<TUser> 및 IRoleStore<TRole> 구현체를 DI 컨테이너에 등록합니다. 이는 사용자 유형이 IdentityUser<TKey>를, 역할 유형이 IdentityRole<TKey>를 상속받았는지 확인하고, DbContext 유형에 따라 적절한 UserStore 및 RoleStore 구현체를 동적으로 생성하여 등록합니다.
IUserStore<TUser>: 사용자 CRUD 및 하위 수준의 데이터 접근 인터페이스 정의.UserStore<TUser,...>: EF Core를 사용하여IUserStore<TUser>인터페이스 구현.UserManager<TUser>: 비밀번호 검증, 계정 잠금 등 사용자 관련 고수준 비즈니스 로직 제공.
9.5 기본 토큰 제공자 활성화
AddDefaultTokenProviders()는 ASP.NET Core Identity에서 비밀번호 재설정, 이메일 변경, 전화번호 변경, 2단계 인증(2FA)과 같은 시나리오를 위한 기본 토큰 생성기(Token Providers)를 등록합니다.
주요 토큰 유형:
Default:DataProtectorTokenProvider<TUser>(비밀번호 재설정, 이메일 확인 등 일반 작업).DefaultEmailProvider:EmailTokenProvider<TUser>(이메일 인증 코드 전송).DefaultPhoneProvider:PhoneNumberTokenProvider<TUser>(SMS 인증 코드 전송).DefaultAuthenticatorProvider:AuthenticatorTokenProvider<TUser>(Google Authenticator와 같은 TOTP 기반 2FA 지원).
10. IdentityServer 인증 및 권한 부여
IdentityServer는 OpenID Connect 및 OAuth 2.0 프로토콜 기반의 인증 및 권한 부여 프레임워크입니다. 이는 마이크로서비스, 프론트엔드/백엔드 분리, BFF(Backend For Frontend) 패턴에서 통합 인증 센터(Identity Provider, IdP)를 구축하는 데 널리 사용됩니다.
- 인증(Authentication): 사용자 신원 확인 (계정/비밀번호 로그인, 소셜 로그인).
- 권한 부여(Authorization): 자원에 대한 사용자 접근 제어 (토큰 기반).
- Access Token 발행: OAuth2.0 권한 부여 서버의 핵심 기능.
- 다양한 클라이언트 유형 지원: 웹 앱, SPA, 네이티브 앱, API 게이트웨이 등.
- ASP.NET Identity 통합: 기존 사용자 테이블(예:
AspNetUsers) 직접 사용 가능.
10.1 기본 구성
이 코드는 테스트 목적의 IdentityServer 서비스를 구성하며, ASP.NET Identity 사용자를 인증에 활용합니다. IdentityResources, ApiScopes, ApiResources, Clients는 메모리 방식으로 설정되었으며, 개발용 서명 자격 증명을 사용합니다. 프로덕션 환경에서는 IssuerUri 설정, 키 관리 활성화, 리소스 영구 저장소 사용, X.509 인증서 사용 등 추가적인 보안 강화가 필요합니다.
// IdentityServer 구성
builder.Services.AddIdentityServer(options =>
{
// 발행자 URI 설정 (토큰의 `iss` 필드)
// options.IssuerUri = "null"; // 설정하지 않으면 요청 호스트 사용
// 인증 쿠키의 수명 주기 2시간으로 설정
options.Authentication.CookieLifetime = TimeSpan.FromHours(2);
// 감사 및 로깅을 위한 이벤트 활성화 (오류, 정보, 실패, 성공)
options.Events.RaiseErrorEvents = true;
options.Events.RaiseInformationEvents = true;
options.Events.RaiseFailureEvents = true;
options.Events.RaiseSuccessEvents = true;
// 키 관리 비활성화 (개발 테스트 전용, 프로덕션에서는 활성화 및 보안 저장 필요)
options.KeyManagement.Enabled = false;
})
// 메모리 기반 Identity 리소스 등록 (Config 클래스에서 로드)
.AddInMemoryIdentityResources(Config.GetResources())
// 메모리 기반 API 스코프 등록 (Config 클래스에서 로드)
.AddInMemoryApiScopes(Config.GetApiScopes())
// 메모리 기반 API 리소스 등록 (Config 클래스에서 로드)
.AddInMemoryApiResources(Config.GetApis())
// 메모리 기반 클라이언트 등록 (Config 클래스에서 로드)
.AddInMemoryClients(Config.GetClients(builder.Configuration))
// ASP.NET Core Identity 사용자 시스템과 연동 (UserManager, SignInManager 사용)
.AddAspNetIdentity<ApplicationUser>()
// 개발자 서명 자격 증명 사용 (임시 키 파일 자동 생성, 개발 전용)
.AddDeveloperSigningCredential();
Config 클래스는 IdentityServer4의 IdentityResources, ApiScopes, ApiResources, Clients를 중앙 집중식으로 관리하고 제공하는 역할을 합니다.
10.2 API 리소스 (ApiResource)
ApiResource는 클라이언트가 접근할 수 있는 구체적인 백엔드 서비스(예: 주문 서비스, 장바구니 서비스)를 정의합니다.
10.3 API 스코프 (ApiScope)
ApiScope는 클라이언트가 API에 접근할 수 있는 권한 "범위(Scope)"를 정의합니다. 일반적으로 하나의 ApiResource는 하나 이상의 ApiScope와 연결되며, 클라이언트는 토큰을 요청할 때 필요한 스코프를 명시해야 합니다.
10.4 신원 리소스 (IdentityResource)
IdentityResources는 OpenID Connect 프로토콜에서 ID 토큰 생성 시 반환될 사용자 신원 정보(Claims)를 제어합니다.
| 리소스 | 설명 |
|---|---|
openid |
OIDC 지원, 사용자 고유 식별자 sub 반환 |
profile |
사용자 기본 정보(이름, 성별, 아바타, 닉네임 등) 반환 |
10.5 클라이언트 (Client)
클라이언트는 API 또는 인증 서비스에 접근해야 하는 "외부 애플리케이션"을 의미합니다. IdentityServer는 다양한 유형의 클라이언트를 지원하며, 각 클라이언트에 대한 인증 및 권한 부여 설정을 정의합니다.
주요 클라이언트 설정 필드:
| 필드명 | 설명 |
|---|---|
ClientId |
클라이언트 고유 식별자 |
ClientName |
클라이언트 친숙한 이름 |
ClientSecrets |
클라이언트 비밀 (기밀 클라이언트에 필수) |
AllowedGrantTypes |
권한 부여 모드 (예: code, implicit 등) |
RequirePkce |
PKCE (Proof Key for Code Exchange) 활성화 여부 (권한 코드 가로채기 방지, 모바일 앱에 강력 권장) |
RedirectUris |
로그인 성공 후 리디렉션 URI (등록 필수) |
PostLogoutRedirectUris |
로그아웃 후 리디렉션 URI |
AllowedScopes |
클라이언트가 접근 가능한 리소스 범위 (Scope) |
AllowOfflineAccess |
refresh_token 획득 허용 여부 (장기 접근) |
AccessTokenLifetime |
Access Token 유효 기간 (초) | IdentityTokenLifetime |
Identity Token 유효 기간 (초) |
10.5.1 OAuth2/OpenID Connect 권한 부여 모드 (Grant Types)
OAuth2는 다양한 시나리오에 맞는 여러 권한 부여 모드(Grant Type)를 제공합니다. 하나의 클라이언트가 여러 권한 부여 모드를 동시에 가질 수 있습니다.
- Authorization Code (권한 코드 모드): 가장 안전하고 일반적으로 사용됩니다. 클라이언트가 먼저 권한 코드를 얻은 후, 백엔드 서버에서 클라이언트 비밀과 함께 이를 Access Token으로 교환합니다. 서버 측 웹 애플리케이션에 적합합니다.
- Implicit (암시적 흐름): 브라우저가 Access Token과 ID Token을 직접 획득합니다. SPA(Single Page Application)에 사용되었으나 보안 문제로 인해 현재는 권장되지 않습니다.
- Hybrid (하이브리드 흐름): 권한 코드 모드와 암시적 흐름을 결합합니다. ID Token을 즉시 얻으면서 Access Token은 백엔드에서 교환합니다. 사용자 신원 정보와 서버 측 API 호출이 모두 필요한 웹 애플리케이션에 적합합니다.
- Client Credentials (클라이언트 자격 증명 모드): 사용자 개입 없이 클라이언트 자체의 자격 증명(ClientId + ClientSecret)으로 Access Token을 직접 획득합니다. 서비스 간 API 호출(백그라운드 서비스)에 적합합니다.
- Resource Owner Password (자원 소유자 비밀번호 모드): 사용자가 직접 사용자 이름과 비밀번호를 클라이언트에 제공하고, 클라이언트가 이를 Access Token으로 교환합니다. 내부 또는 신뢰할 수 있는 클라이언트에서 빠르게 토큰을 얻을 때 사용되나, 보안 위험이 높아 권장되지 않습니다.
- Device Flow (기기 권한 부여 모드): 브라우저 입력 능력이 없는 기기(스마트 TV, IoT 기기)에서 사용됩니다. 사용자는 다른 기기에서 코드를 입력하여 권한을 부여하고, 기기는 Access Token을 폴링하여 획득합니다.
10.5.2 MAUI 클라이언트
MAUI 모바일 클라이언트를 위한 설정입니다. 권한 코드 + PKCE(Proof Key for Code Exchange) 흐름을 사용하며, 여러 API에 접근할 수 있도록 구성되었습니다. AllowedGrantTypes = GrantTypes.Code와 RequirePkce = true 설정이 핵심입니다.
new Client
{
ClientId = "maui",
ClientName = "eShop MAUI OpenId Client",
AllowedGrantTypes = GrantTypes.Code, // 권한 코드 모드
ClientSecrets = { new Secret("secret".Sha256()) },
RedirectUris = { configuration["MauiCallback"] },
RequireConsent = false,
RequirePkce = true, // PKCE 강제 적용
PostLogoutRedirectUris = { $"{configuration["MauiCallback"]}/Account/Redirecting" },
AllowedScopes = new List<string>
{
IdentityServerConstants.StandardScopes.OpenId,
IdentityServerConstants.StandardScopes.Profile,
IdentityServerConstants.StandardScopes.OfflineAccess, // Refresh Token 요청 허용
"orders", "basket", "mobileshoppingagg", "webhooks"
},
AllowOfflineAccess = true, // Refresh Token 허용
AllowAccessTokensViaBrowser = true,
AlwaysIncludeUserClaimsInIdToken = true,
AccessTokenLifetime = 60*60*2, // 2시간
IdentityTokenLifetime = 60*60*2 // 2시간
}
10.5.3 웹앱 클라이언트
웹 애플리케이션 클라이언트에 대한 설정입니다. 권한 코드 흐름을 사용하며, Refresh Token을 지원하고, 로그인/로그아웃 콜백 주소와 접근 가능한 API 리소스 범위를 지정합니다. 보안상 브라우저를 통한 Access Token 직접 전달 및 동의 페이지 표시는 비활성화됩니다.
new Client
{
ClientId = "webapp",
ClientName = "WebApp Client",
ClientSecrets = { new Secret("secret".Sha256()) },
ClientUri = $"{configuration["WebAppClient"]}",
AllowedGrantTypes = GrantTypes.Code, // 권한 코드 모드
AllowAccessTokensViaBrowser = false,
RequireConsent = false,
AllowOfflineAccess = true, // Refresh Token 허용
AlwaysIncludeUserClaimsInIdToken = true,
RequirePkce = false,
RedirectUris = { $"{configuration["WebAppClient"]}/signin-oidc" },
PostLogoutRedirectUris = { $"{configuration["WebAppClient"]}/signout-callback-oidc" },
AllowedScopes = new List<string>
{
IdentityServerConstants.StandardScopes.OpenId,
IdentityServerConstants.StandardScopes.Profile,
IdentityServerConstants.StandardScopes.OfflineAccess,
"orders", "basket", "webshoppingagg", "webhooks"
},
AccessTokenLifetime = 60*60*2, // 2시간
IdentityTokenLifetime = 60*60*2 // 2시간
}
10.5.4 Webhooks 클라이언트
백엔드 웹 애플리케이션 형태의 Webhooks 클라이언트 설정입니다. 권한 코드 흐름을 허용하며, Refresh Token을 사용하고 webhooks API에 접근할 수 있습니다. 클라이언트 비밀 관리와 정확한 콜백 주소 매칭이 중요합니다.
new Client
{
ClientId = "webhooksclient",
ClientName = "Webhooks Client",
ClientSecrets = { new Secret("secret".Sha256()) },
ClientUri = $"{configuration["WebhooksWebClient"]}",
AllowedGrantTypes = GrantTypes.Code, // 권한 코드 모드
AllowAccessTokensViaBrowser = false,
RequireConsent = false,
AllowOfflineAccess = true, // Refresh Token 허용
AlwaysIncludeUserClaimsInIdToken = true,
RedirectUris = { $"{configuration["WebhooksWebClient"]}/signin-oidc" },
PostLogoutRedirectUris = { $"{configuration["WebhooksWebClient"]}/signout-callback-oidc" },
AllowedScopes = new List<string>
{
IdentityServerConstants.StandardScopes.OpenId,
IdentityServerConstants.StandardScopes.Profile,
IdentityServerConstants.StandardScopes.OfflineAccess,
"webhooks"
},
AccessTokenLifetime = 60*60*2, // 2시간
IdentityTokenLifetime = 60*60*2 // 2시간
}
10.5.5 Basket Swagger UI
Swagger UI에서 OAuth2 클라이언트를 등록하여, Swagger 페이지에서 "Authorize" 버튼을 통해 로그인하고 basket API에 접근할 수 있는 Access Token을 획득하도록 합니다. 이를 통해 Swagger에서 보호된 API를 호출할 수 있습니다.
new Client
{
ClientId = "basketswaggerui",
ClientName = "Basket Swagger UI",
AllowedGrantTypes = GrantTypes.Implicit, // 암시적 흐름 (Swagger UI에 적합)
AllowAccessTokensViaBrowser = true,
RedirectUris = { $"{configuration["BasketApiClient"]}/swagger/oauth2-redirect.html" },
PostLogoutRedirectUris = { $"{configuration["BasketApiClient"]}/swagger/" },
AllowedScopes = { "basket" }
}
10.5.6 Ordering Swagger UI
Ordering API의 Swagger UI를 위한 클라이언트 설정입니다. Basket Swagger UI와 유사하게 암시적 흐름을 사용하며, orders API에 접근할 수 있는 권한을 부여합니다.
new Client
{
ClientId = "orderingswaggerui",
ClientName = "Ordering Swagger UI",
AllowedGrantTypes = GrantTypes.Implicit, // 암시적 흐름
AllowAccessTokensViaBrowser = true,
RedirectUris = { $"{configuration["OrderingApiClient"]}/swagger/oauth2-redirect.html" },
PostLogoutRedirectUris = { $"{configuration["OrderingApiClient"]}/swagger/" },
AllowedScopes = { "orders" }
}
10.5.7 Webhooks Swagger UI
Webhooks API의 Swagger UI를 위한 클라이언트 설정입니다. 암시적 흐름을 사용하여 webhooks API에 접근할 수 있도록 합니다.
new Client
{
ClientId = "webhooksswaggerui",
ClientName = "WebHooks Service Swagger UI",
AllowedGrantTypes = GrantTypes.Implicit, // 암시적 흐름
AllowAccessTokensViaBrowser = true,
RedirectUris = { $"{configuration["WebhooksApiClient"]}/swagger/oauth2-redirect.html" },
PostLogoutRedirectUris = { $"{configuration["WebhooksApiClient"]}/swagger/" },
AllowedScopes = { "webhooks" }
}
11. Claims 제공 및 활성화 체크 (ProfileService)
ProfileService 클래스는 IdentityServer (Duende/IdentityServer4)에 사용자 프로필(claims)과 "활성화 여부" 검사 기능을 제공하기 위해 IProfileService 인터페이스를 구현합니다.
GetProfileDataAsync: IdentityServer가 토큰(ID 토큰/Access 토큰)을 발행하거나 userinfo 요청에 응답할 때 호출되어 토큰/userinfo에 포함될 사용자 클레임(claims)을 수집합니다. 토큰에 어떤 사용자 정보가 포함될지 결정하는 역할을 합니다.IsActiveAsync: 토큰 검증 또는 갱신 시, 현재 사용자 계정이 여전히 "활성화" 상태인지(예: 잠금 여부, 보안 스탬프 변경 여부) 판단합니다.IsActive = false를 반환하면 IdentityServer는 토큰 발행을 거부하거나 사용자를 사용할 수 없는 상태로 간주합니다.
11.1 사용자 Claims 생성
GetProfileDataAsync 메서드는 context.Subject에서 사용자 ID를 가져와 UserManager를 통해 ApplicationUser를 조회합니다. 조회된 사용자의 관련 필드들을 Claim 목록으로 변환하여 context.IssuedClaims에 할당합니다. 이 클레임들은 클라이언트가 요청한 스코프/클레임에 따라 토큰 또는 userinfo 응답에 포함됩니다.
public async Task GetProfileDataAsync(ProfileDataRequestContext context)
{
var subjectId = context.Subject?.Claims.Where(x => x.Type == "sub").FirstOrDefault()?.Value;
var user = await _userManager.FindByIdAsync(subjectId);
if (user == null)
throw new ArgumentException("Invalid subject identifier");
var claims = GetClaimsFromUser(user); // ApplicationUser의 필드를 Claim 목록으로 변환
context.IssuedClaims = claims.ToList();
}
11.2 사용자 활성화 상태 확인
IsActiveAsync 메서드는 사용자의 존재 여부를 확인합니다. 또한, 토큰에 포함된 security_stamp가 데이터베이스의 값과 일치하는지 비교하여 사용자 정보(예: 비밀번호) 변경 여부를 확인하고, 불일치 시 토큰 무효화를 처리합니다. 사용자가 잠금 상태(Lockout)이고 만료되지 않았다면 IsActive = false를 반환합니다.
SecurityStamp는 사용자 계정의 보안 상태를 나타내는 임의의 문자열입니다. 사용자가 비밀번호를 변경하거나 보안 정보를 업데이트하면 SecurityStamp가 업데이트되며, 이전 토큰의 SecurityStamp와 불일치 시 토큰은 자동으로 무효화됩니다.
12. 사용자 로그인 서비스 (EFLoginService)
EFLoginService는 UserManager와 SignInManager를 캡슐화하여 사용자 조회, 비밀번호 검증, 로그인 작업 및 사용자 인증 티켓(사용자 정보, 권한/역할/클레임 포함) 처리를 수행합니다.
13. 리디렉션 주소 해석 (RedirectService)
RedirectService는 OAuth2/OpenID Connect 로그인 또는 외부 로그인 콜백 시 반환되는 returnUrl을 해석하여 사용자가 올바른 원본 요청 페이지로 리디렉션될 수 있도록 보장합니다. returnUrl에서 redirect_uri를 추출하고, URL을 디코딩하며, 특수 문자를 처리하여 실제 리디렉션 주소를 반환합니다.
14. 애플리케이션 빌드 및 미들웨어 파이프라인 구성
builder.Build()를 통해 WebApplication 인스턴스를 생성한 후, HTTP 요청 처리 미들웨어 파이프라인을 구성합니다.
// WebApplication 인스턴스 빌드
var app = builder.Build();
// IdentityServer 기본 엔드포인트 매핑 (OAuth2/OpenID Connect)
// /connect/authorize, /connect/token, /connect/userinfo, /connect/logout
app.MapDefaultEndpoints();
// 정적 파일 미들웨어 활성화 (wwwroot의 CSS, JS, 이미지 등 접근 허용)
app.UseStaticFiles();
// 쿠키 정책 구성 (Chrome 80+ HTTP SameSite 문제 해결)
// Lax 정책은 로그인 POST 제출 시 쿠키 전송 허용
app.UseCookiePolicy(new CookiePolicyOptions { MinimumSameSitePolicy = SameSiteMode.Lax });
// 라우팅 미들웨어 활성화 (요청 URL을 Controller 또는 IdentityServer 엔드포인트에 매핑)
// IdentityServer 또는 Authorization 미들웨어 이전에 호출해야 함
app.UseRouting();
// IdentityServer 미들웨어 활성화 (OAuth2/OpenID Connect 핵심 기능 제공)
// /connect/authorize, /connect/token, /connect/userinfo, /connect/logout
// UseAuthorization 미들웨어 이전에 위치해야 함
app.UseIdentityServer();
// 권한 부여 미들웨어 활성화 (요청에 대한 접근 권한 검사)
// IdentityServer 미들웨어 이후, 엔드포인트 매핑 이전에 위치
app.UseAuthorization();
// 기본 MVC 라우트 매핑 ({controller=Home}/{action=Index}/{id?})
// /Account/Login 또는 /Home/Index와 같은 Controller/Action 접근 허용
// UseRouting과 함께 사용
app.MapDefaultControllerRoute();
// 애플리케이션 시작 및 HTTP 요청 리스닝
// Run()은 파이프라인의 최종 엔드포인트여야 함
app.Run();