GN2.Business 3.0.0

GN2.Business

GN2 인증서버(OpenIddict)를 사용하는 클라이언트 측 라이브러리입니다. API 서버와 응용 프로그램이 인증·인가와 서비스 간 호출을 최소한의 코드로 구성하도록 돕습니다.

• Target Framework: net10.0 · Version: 3.0.0 · NuGet: GN2.Business
• 의존성: GN2.Core, Microsoft.AspNetCore.Authentication.JwtBearer

Swagger, API 버저닝, EF Core 감사 확장은 GN2.Common.Web 에 있습니다.

구성

Protocol/          OIDC 통신 — 디스커버리 조회, 토큰 요청
  ProtocolResponse.cs               응답 기반 (IsError, Error, Raw, Json)
  ProtocolRequest.cs                요청 기반 + 그랜트별 요청 타입
  TokenResponse.cs
  DiscoveryDocumentResponse.cs
  HttpClientProtocolExtensions.cs   HttpClient 확장 메서드

Authentications/   ASP.NET Core 구성
  ExtendAuthentication.cs           JwtBearer 등록, 프록시 헤더
  ExtendAuthorization.cs            정책 등록, RequireGn2Roles
  ExtendApiClient.cs                HttpClient 등록
  ExtendClaimsPrincipal.cs          클레임 조회
  ClientCredentialsTokenProvider.cs 토큰 발급 · 캐시
  IdentityClientCredentialHandler.cs 토큰 자동 부착
  RoleTypes.cs / AuthorizationConsts.cs / IdentityClientConsts.cs

설정

{
  "Identity": {
    "BaseUrl": "https://auth.example.com",     // Authority (토큰 발급자)
    "IdentityUrl": "https://auth.example.com", // 토큰 발급 요청 대상
    "Audience": "example-api",
    "Scope": "example-api",
    "ClientId": "example-service",
    "ClientSecret": "..."
  }
}

IdentityConfiguration(검증용)과 IdentityClientConfiguration(발급용) 모두 GN2.Core.Configurations 에 있습니다.

1. 인증 · 인가 등록

var identity = builder.Configuration.GetSection("Identity").Get<IdentityConfiguration>()!;

builder.Services.RegisterAuthentication(identity);
builder.Services.RegisterAuthorization(identity);

var app = builder.Build();

app.AddForwardHeaders();   // 리버스 프록시를 쓴다면 인증 미들웨어보다 먼저
app.UseAuthentication();
app.UseAuthorization();

RegisterAuthentication 이 하는 일:

• Authority 와 Audience 설정
• MapInboundClaims = false — 이걸 켜두면(ASP.NET Core 기본값) 토큰의 sub·role 이 WS-Federation URI 로 바뀌어 JwtClaimTypes 상수로 찾을 수 없게 됩니다
• NameClaimType = "sub", RoleClaimType = "role"
• Authority 가 https 면 메타데이터 HTTPS 요구, http 면 해제

세부 조정이 필요하면 세 번째 인자로 JwtBearerOptions 를 직접 손봅니다.

builder.Services.RegisterAuthentication(identity, options =>
{
    options.TokenValidationParameters.ClockSkew = TimeSpan.FromSeconds(30);
});

2. 정책 사용

[Authorize(Policy = AuthorizationConsts.ManagerPolicy)]   // Manager 또는 Admin
public class ProductController : ControllerBase { }

모든 정책은 scope 클레임에 Audience 가 포함되어 있는지 확인한 뒤, role · client_role · ClaimTypes.Role 중 하나가 요구 역할과 일치하는지 검사합니다.

역할 체계가 다르면 정책을 직접 정의합니다.

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("Billing",
        policy => policy.RequireGn2Roles(identity.Audience, "BillingAdmin", "Admin"));
});

3. 서비스 간 호출 (client_credentials)

var client = builder.Configuration.GetSection("Identity").Get<IdentityClientConfiguration>()!;

builder.Services.AddIdentityCredentialClient(client);

public class OrderService(IHttpClientFactory factory)
{
    private readonly HttpClient _http = factory.CreateClient(IdentityClientConsts.ClientCredentialName);

    public Task<HttpResponseMessage> GetAsync() => _http.GetAsync("/api/v1/orders");
}

• 토큰과 디스커버리 결과를 만료 60초 전까지 캐시합니다. 요청마다 인증서버를 부르지 않습니다.
• 동시 요청이 몰려도 발급은 한 번만 일어납니다.
• 401 을 받으면 캐시를 버리고 재전송이 안전한 요청에 한해 한 번 재시도합니다. 스트리밍 본문처럼 다시 읽을 수 없는 요청은 캐시만 비우고 401 을 그대로 돌려줍니다.

인증서버나 대상 API 가 여러 개인 경우

clientName 을 다르게 주면 각각 독립된 토큰 캐시를 가집니다.

builder.Services.AddIdentityCredentialClient(orderConfig, "order-api");
builder.Services.AddIdentityCredentialClient(billingConfig, "billing-api");

var http = factory.CreateClient("order-api");

만료 여유 시간과 시각 고정

builder.Services.AddIdentityCredentialClient(client, expirationSkew: TimeSpan.FromSeconds(120));

// 테스트에서는 TimeProvider 를 DI 에 등록하면 토큰 캐시가 그것을 사용합니다.
services.AddSingleton<TimeProvider>(fakeTimeProvider);

4. 사용자 토큰 전달 (on-behalf-of)

현재 요청의 Bearer 토큰을 그대로 하위 API 로 넘깁니다.

builder.Services.AddApiClient(new ExternalApiConfiguration { BaseUrl = "https://inner-api.example.com" });

var http = factory.CreateClient(IdentityClientConsts.ClientAuthenticationName);

5. 클레임 조회

ClaimsPrincipal 확장이므로 HTTP 컨텍스트 없이도 씁니다.

var userId = User.GetUserId();          // sub
var roles  = User.GetRoles();
var ok     = User.HasAnyRole("Admin", "Manager");
var scoped = User.HasScope("example-api");

IHttpContextAccessor 오버로드도 그대로 있습니다.

accessor.GetCurrentUserId();
accessor.GetCurrentRoles();

6. 프로토콜 직접 사용

등록 확장을 쓰지 않고 디스커버리·토큰을 직접 다룰 때 사용합니다.

using GN2.Business.Protocol;

using var discovery = await http.GetDiscoveryDocumentAsync("https://auth.example.com");

if (discovery.IsError)
{
    logger.LogError("디스커버리 실패: {Error}", discovery.Error);
    return;
}

using var token = await http.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
{
    Address      = discovery.TokenEndpoint,
    ClientId     = "example-service",
    ClientSecret = secret,
    Scope        = "example-api"
});

if (!token.IsError)
{
    Console.WriteLine(token.AccessToken);
}

• 예외를 던지지 않습니다. 네트워크 오류든 프로토콜 오류든 IsError 로 판정합니다.
• 응답은 IDisposable 이므로 using 으로 받으세요. 본문은 이미 읽어두었으므로 폐기 후에도 속성은 읽을 수 있습니다.
• HTTPS 를 기본 요구합니다. 루프백은 허용하며, 사설망이라면 요청의 RequireHttps = false 로 해제합니다.

제공 요청 타입: ClientCredentialsTokenRequest, AuthorizationCodeTokenRequest, RefreshTokenRequest, PasswordTokenRequest

2.x → 3.0.0 마이그레이션

동작 변경:

• AddApiClient · AddIdentityCredentialClient 가 IHttpClientBuilder 를 반환합니다. 핸들러를 추가로 체이닝할 수 있습니다.
• 두 메서드 모두 잘못된 주소를 등록 시점에 ArgumentException 으로 거부합니다.
• 디스커버리·토큰 요청이 HTTPS 를 요구합니다 (루프백 예외).
• ProtocolResponse 가 IDisposable 입니다.

라이선스

Apache License 2.0