ASP.NET Core에서 JWT 전달자 인증 구성

2025-04-18

JWT(JSON 웹 토큰) 전달자 인증은 일반적으로 API에 사용됩니다. cookie 인증과 유사하게 작동하지만 ID 공급자는 성공적인 인증 시 JWT 또는 토큰을 발급합니다. 그런 다음, 발급 도메인으로만 다시 전송되는 쿠키와 달리 인증을 위해 이러한 토큰을 다른 서버로 보낼 수 있습니다. JWT는 API 리소스 또는 클라이언트에 대한 정보를 캡슐화하는 자체 포함 토큰입니다. JWT를 요청한 클라이언트는 권한 부여 헤더 및 전달자 토큰을 사용하여 API 리소스에서 데이터를 요청할 수 있습니다.

JWT 전달자 인증은 다음을 제공합니다.

인증: JwtBearerHandler사용하는 경우 전달자 토큰은 인증에 필수적입니다. JwtBearerHandler 토큰의 유효성을 검사하고 해당 클레임에서 사용자의 ID를 추출합니다.
권한 부여: cookie와 마찬가지로, 전달자 토큰은 사용자나 애플리케이션의 권한을 나타내는 클레임 모음을 제공하여 권한 부여를 가능하게 합니다.
위임된 권한 부여: 사용자별 액세스 토큰을 사용하여 애플리케이션 전체 액세스 토큰 대신 API 간에 인증하는 경우 이 프로세스를 위임된 권한 부여이라고 합니다.

JWT 전달자 인증에 대한 소개는 JSON 웹 토큰을 참조하세요.샘플 코드 보기 또는 다운로드

이 문서에서는 다음 영역을 다룹니다.

토큰 형식
JWT 토큰을 사용하여 API 보호
OIDC/OAuth가 이에 어떻게 부합하나요?
JWT 전달자 토큰 인증 구현
JWT를 만드는 권장 방법

토큰 형식

다양한 유형의 토큰과 형식이 있습니다. 테스트 용도를 제외하고 사용자 고유의 액세스 토큰 또는 ID 토큰을 생성하는 것은 권장되지 않습니다. 설정된 표준을 준수하지 않는 자체 생성 토큰:

보안 취약성으로 이어질 수 있습니다.
폐쇄형 시스템에만 적합합니다.

API 액세스를 위한 액세스 토큰을 만들기 위해 OpenID Connect 1.0 또는 OAuth 표준을 사용하는 것이 좋습니다.

액세스 토큰

액세스 토큰:

클라이언트 앱이 API를 구현하는 서버에 요청을 하는 데 사용하는 문자열입니다.
형식에 따라 달라질 수 있습니다. 다른 API는 토큰에 다른 형식을 사용할 수 있습니다.
암호화할 수 있습니다.
액세스 토큰을 보유하는 웹 클라이언트 또는 UI 앱에서 읽거나 해석해서는 안 됩니다.
API에 대한 요청만을 위한 것입니다.
일반적으로 Authorization 요청 헤더의 API에 전달자 토큰으로 전송됩니다.

OAuth 2.0 권한 부여 프레임워크 참조하세요.

애플리케이션 액세스 토큰 및 위임된 액세스 토큰

액세스 토큰은 애플리케이션 액세스 토큰 또는 위임된 액세스 토큰수 있습니다. 토큰은 클레임이 다르며 관리되고 다르게 저장됩니다. 애플리케이션 액세스 토큰 일반적으로 만료될 때까지 앱에 한 번 저장되지만 위임된 액세스 토큰 사용자별로 cookie 또는 보안 서버 캐시에 저장됩니다.

사용자가 참여할 때마다 위임된 사용자 액세스 토큰을 사용하는 것이 좋습니다. 다운스트림 API는 인증된 사용자를 대신하여 위임된 사용자 액세스 토큰을 요청할 수 있습니다.

발신자 제한 액세스 토큰

액세스 토큰은 전달자 토큰으로 사용하거나 보낸 사람 제한 토큰으로 사용하여 리소스에 액세스할 수 있습니다. 보낸 사람 제한 토큰을 사용하려면 요청 클라이언트가 토큰을 사용하기 위해 프라이빗 키의 소유를 증명해야 합니다. 프라이빗 키의 소유를 증명하면 토큰을 독립적으로 사용할 수 없습니다. 보낸 사람 제한 토큰은 다음 두 가지 방법으로 구현할 수 있습니다.

ID 토큰

ID 토큰은 사용자의 성공적인 인증을 확인하는 보안 토큰입니다. 토큰을 사용하면 클라이언트가 사용자의 ID를 확인할 수 있습니다. JWT 토큰 서버는 사용자 정보가 있는 클레임을 포함한 ID 토큰을 발급합니다. ID 토큰은 항상 JWT 형식입니다.

ID 토큰 은 API에 액세스하는 데 절대 사용되어서는 안 됩니다.

기타 토큰

OpenID Connect 및 OAuth 표준에 지정된 대로 액세스 및 ID 토큰을 비롯한 다양한 유형의 토큰이 있습니다. 새로 고침 토큰을 사용하여 사용자를 다시 인증하지 않고 UI 앱을 새로 고칠 수 있습니다. OAuth JAR 토큰 안전하게 권한 부여 요청을 보낼 수 있습니다. 확인 가능한 자격 증명 흐름은 자격 증명을 발급하거나 확인하는 데 JWT 형식을 활용합니다. 사양에 따라 토큰을 사용하는 것이 중요합니다. 자세한 내용은 이 문서의 뒷부분에 제공된 표준 링크를 참조하세요.

JWT 토큰을 사용하여 API 보호

API 권한 부여에 JWT 액세스 토큰을 사용하는 경우 API는 제공된 토큰에 따라 액세스를 부여하거나 거부합니다. 요청에 권한이 없는 경우 401 또는 403 응답이 반환됩니다. API는 사용자를 ID 공급자로 리디렉션하여 새 토큰을 가져오거나 추가 권한을 요청해서는 안 됩니다. API를 사용하는 앱은 적절한 토큰을 획득해야 합니다. 이렇게 하면 API(권한 부여)와 사용 중인 클라이언트 앱(인증) 간에 문제가 명확하게 분리됩니다.

메모

또한 HTTP를 사용하면 권한이 없는 클라이언트에 리소스의 존재에 대한 정보를 누출하지 않도록 권한이 없는 경우 404를 반환할 수 있습니다.

401 권한 없음

401 권한 없는 응답은 제공된 액세스 토큰이 필요한 표준을 충족하지 않음을 나타냅니다. 이는 다음을 비롯한 여러 가지 이유로 인해 발생할 수 있습니다.

잘못된 서명: 토큰의 서명이 일치하지 않아 변조 가능성이 있음을 시사합니다.
만료: 토큰이 만료되어 더 이상 유효하지 않습니다.
잘못된 클레임: 대상 그룹(aud) 또는 발급자(iss)와 같은 토큰 내의 중요한 클레임이 누락되었거나 잘못되었습니다.

메모

HTTP 의미 체계 RFC 9110: 401 응답을 생성하는 서버는 대상 리소스에 적용할 수 있는 하나 이상의 챌린지가 포함된 WWW-Authenticate 헤더 필드(섹션 11.6.1)를 보내야 합니다.

OAuth 사양은 필요한 클레임 및 검증에 대한 자세한 지침을 제공합니다.

403 금지됨

403 사용할 수 없음 응답은 일반적으로 인증된 사용자에게 요청된 리소스에 액세스하는 데 필요한 권한이 없음을 나타냅니다. 이는 인증 문제(예: 잘못된 토큰)와는 별개이며 액세스 토큰 내의 표준 클레임과 관련이 없습니다.

ASP.NET Core에서는 다음을 사용하여 권한 부여를 적용할 수 있습니다.

요구 사항 및 정책: 사용자 지정 요구 사항(예: "관리자여야 함")을 정의하고 정책과 연결합니다. 역할 기반 권한 부여: "관리자", "편집기"와 같은 역할에 사용자를 할당하고 해당 역할에 따라 액세스를 제한합니다.

전달자 토큰을 사용할 때 OIDC 및/또는 OAuth가 있는 역할은 무엇인가요?

API가 권한 부여를 위해 JWT 액세스 토큰을 사용하는 경우 API는 토큰을 얻은 방법이 아니라 액세스 토큰의 유효성만 검사합니다.

OIDC(OpenID Connect) 및 OAuth 2.0은 토큰 획득을 위한 표준화된 보안 프레임워크를 제공합니다. 토큰 획득은 앱 유형에 따라 다릅니다. 보안 토큰 획득의 복잡성으로 인해 다음 표준을 사용하는 것이 좋습니다.

사용자 및 애플리케이션을 대신하여 작동하는 앱의 경우: OIDC는 위임된 사용자 액세스를 사용하도록 설정하는 기본 선택입니다. 웹앱에서 보안 강화를 위해 PKCE(코드 교환)에 대한
증명 키가 있는 기밀 코드 흐름이 권장됩니다.
- 호출 앱이 서버 쪽 OIDC 인증있는 ASP.NET Core 앱인 경우 SaveTokens 옵션을 사용하여 cookie통해 나중에 사용할 수 있도록 HttpContext.GetTokenAsync("access_token") 액세스 토큰을 저장할 수 있습니다.
앱에 사용자가 없는 경우: OAuth 2.0 클라이언트 자격 증명 흐름은 애플리케이션 액세스 토큰을 가져오는 데 적합합니다.

JWT 전달자 토큰 인증 구현

Microsoft.AspNetCore.Authentication.JwtBearer Nuget 패키지를 사용하여 JWT 전달자 토큰의 유효성을 검사할 수 있습니다.

JWT 전달자 토큰은 API에서 완전히 유효성을 검사해야 합니다. 다음의 유효성을 검사해야 합니다.

신뢰 및 무결성을 위한 서명입니다. 이렇게 하면 지정된 보안 토큰 서비스에서 토큰을 만들었으며 변조되지 않았습니다.
예상 값을 가진 발급자 클레임입니다.
청중은 예상 값을 사용하여 클레임합니다.
토큰 만료.

OAuth 2.0 액세스 토큰에는 iss, exp, aud, sub, client_id, iat및 jti클레임이 필요합니다.

이러한 클레임 또는 값이 잘못된 경우 API는 401 응답을 반환해야 합니다.

JWT 전달자 토큰 기본 유효성 검사

AddJwtBearer 기본 구현은 대상 그룹 및 발급자만 유효성을 검사할 수 있습니다. 토큰을 신뢰할 수 있고 변조되지 않도록 서명의 유효성을 검사해야 합니다.

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(jwtOptions =>
{
	jwtOptions.Authority = "https://{--your-authority--}";
	jwtOptions.Audience = "https://{--your-audience--}";
});

JWT 전달자 토큰 명시적 유효성 검사

AddJwtBearer 메서드는 여러 구성을 제공합니다. 일부 보안 토큰 공급자는 비표준 메타데이터 주소를 사용하며 매개 변수를 명시적으로 설정할 수 있습니다. API는 여러 발급자 또는 대상 그룹을 수락할 수 있습니다.

매개 변수를 명시적으로 정의할 필요는 없습니다. 정의는 액세스 토큰 클레임 값 및 액세스 토큰의 유효성을 검사하는 데 사용되는 보안 토큰 서버에 따라 달라집니다. 가능하면 기본값을 사용해야 합니다.

매핑 클레임을 보려면 MapInboundClaims 세부 정보를 참조하세요.

builder.Services.AddAuthentication()
.AddJwtBearer("some-scheme", jwtOptions =>
{
	jwtOptions.MetadataAddress = builder.Configuration["Api:MetadataAddress"];
	// Optional if the MetadataAddress is specified
	jwtOptions.Authority = builder.Configuration["Api:Authority"];
	jwtOptions.Audience = builder.Configuration["Api:Audience"];
	jwtOptions.TokenValidationParameters = new TokenValidationParameters
	{
		ValidateIssuer = true,
		ValidateAudience = true,
		ValidateIssuerSigningKey = true,
		ValidAudiences = builder.Configuration.GetSection("Api:ValidAudiences").Get<string[]>(),
		ValidIssuers = builder.Configuration.GetSection("Api:ValidIssuers").Get<string[]>()
	};

	jwtOptions.MapInboundClaims = false;
});

여러 체계가 있는 JWT

API는 종종 다양한 발급자의 액세스 토큰을 수용해야 합니다. API에서 여러 토큰 발급자를 지원하는 작업은 다음을 통해 수행할 수 있습니다.

별도의 API: 각 발급자마다 전용 인증 체계를 사용하여 고유한 API를 만듭니다.
AddPolicyScheme 이 메서드는 여러 인증 체계를 정의하고 토큰 속성(예: 발급자, 클레임)에 따라 적절한 체계를 선택하는 논리를 구현할 수 있습니다. 이 방법을 사용하면 단일 API 내에서 유연성이 향상됩니다.

전달자 인증 강제

SetDefaultPolicy 사용하여 [Authorize] 특성이 없는 엔드포인트에 대해서도 모든 요청에 대한 인증을 요구할 수 있습니다. SetDefaultPolicy는 [Authorize] 특성을 가진 엔드포인트에 사용되는 정책을 구성하며, 이미 인증된 사용자를 요구하는 것으로 기본적으로 설정되어 있습니다. 자세한 내용은 인증된 사용자 설명서을 참조하세요.

var requireAuthPolicy = new AuthorizationPolicyBuilder()
	.RequireAuthenticatedUser()
	.Build();

builder.Services.AddAuthorizationBuilder()
	.SetDefaultPolicy(requireAuthPolicy);

권한 부여 특성을 사용하여 인증을 강제 적용할 수도 있습니다. 여러 체계를 사용하는 경우 전달자 체계는 일반적으로 기본 인증 체계로 설정하거나 [Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme])통해 지정해야 합니다.

컨트롤러에서의 권한 부여

[Authorize]
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{

최소 API의 권한 부여:

app.MapGet("/hello", [Authorize] () => "Hi");

JWT를 만드는 권장 방법

취약한 인증 또는 취약한 클라이언트 쪽 스토리지에 토큰 저장과 같은 액세스 토큰의 안전하지 않은 처리로 인해 심각한 보안 취약성이 발생할 수 있습니다. 예를 들어 로컬 스토리지, 세션 스토리지 또는 웹 작업자를 사용하여 브라우저에 직접 액세스 토큰을 저장합니다. 다음 섹션에는 액세스 토큰을 사용하고 만드는 앱에 대한 모범 사례가 포함되어 있습니다.

표준 사용

OpenID Connect 또는 OAuth와 같은 표준은 액세스 토큰을 만들 때 항상 사용해야 . 프로덕션 앱에서 액세스 토큰을 만들 때 이 문서에 설명된 보안 예방 조치를 준수하지 않고서는 생성해서는 안 됩니다. 액세스 토큰 만들기는 테스트 시나리오로 제한되어야 합니다.

비대칭 키 사용

비대칭 키는 액세스 토큰을 만들 때 항상 사용해야 합니다. 공개 키는 잘 알려진 엔드포인트에서 사용할 수 있으며 API 클라이언트는 공개 키를 사용하여 액세스 토큰의 서명의 유효성을 검사할 수 있습니다.

사용자 이름/암호 요청에서 액세스 토큰을 만들지 마세요.

사용자 이름/암호 요청에서 액세스 토큰을 생성하지 마십시오. 사용자 이름/암호 요청은 인증되지 않으며 가장 및 피싱 공격에 취약합니다. 액세스 토큰은 OpenID Connect 흐름 또는 OAuth 표준 흐름을 사용하여 만들어야 합니다. 이러한 표준에서 벗어나면 안전하지 않은 앱이 발생할 수 있습니다.

쿠키 사용

보안 웹앱의 경우 신뢰할 수 있는 서버에 액세스 토큰을 저장하려면 백 엔드가 필요합니다. 클라이언트 브라우저에서 보안된 HTTP 전용 cookie만 공유됩니다. ASP.NET Core 웹앱에서 이 작업을 수행하는 방법은 OIDC 인증 설명서 참조하세요.

다운스트림 API

API는 호출 앱에서 인증된 사용자를 대신하여 다운스트림 API에서 사용자 데이터에 액세스해야 하는 경우도 있습니다. OAuth 클라이언트 자격 증명 흐름을 구현하는 것은 옵션이지만 두 API 앱 간에 완전 신뢰가 필요합니다. 보다 안전한 방법은 위임된 사용자 액세스 토큰과 함께 제로 트러스트 전략을 사용하는 것입니다. 이 방법은 다음과 같습니다.

API에 특정 사용자에 필요한 권한만 부여하여 보안을 강화합니다.
API가 앱 및 API를 호출하는 사용자에 대한 새 액세스 토큰을 만들어야 합니다.

위임된 사용자 액세스 토큰을 사용하여 제로 트러스트 전략을 구현하는 방법에는 여러 가지가 있습니다.

OAuth 2.0 토큰 교환을 사용하여 위임된 새 액세스 토큰을 요청하세요.

이 요구 사항을 구현하는 좋은 방법이지만 OAuth 흐름을 구현해야 하는 경우에는 복잡합니다.

OAuth 2.0 토큰 교환을 참조하세요.

Microsoft Identity Web을 사용하여 흐름을 대신하여 새로운 위임된 액세스 토큰을 요청합니다.

Microsoft Identity 웹 인증 라이브러리 사용하는 것이 가장 쉽고 안전한 방법입니다. Microsoft Entra ID 및 Microsoft Entra 외부 ID에서만 작동합니다.

자세한 내용은 Microsoft ID 플랫폼 및 OAuth 2.0 On-Behalf-Of 흐름을 참조하세요.

API에 전송된 동일한 위임된 액세스 토큰 사용

이 방법은 구현하기 어렵지 않지만 액세스 토큰은 모든 다운스트림 API에 액세스할 수 있습니다. Yarp 역방향 프록시를 사용하여 이를 구현할 수 있습니다.

OAuth 클라이언트 자격 증명 흐름 사용 및 애플리케이션 액세스 토큰 사용

구현하기 쉽지만 클라이언트 애플리케이션에는 위임된 액세스 토큰이 아닌 전체 애플리케이션 액세스 권한이 있습니다. 토큰은 클라이언트 API 애플리케이션에 캐시되어야 합니다.

메모

모든 앱 간 보안도 작동될 수 있습니다. 인증서 인증 또는 Azure에서 관리 ID를 사용할 수 있습니다.

액세스 토큰 처리

클라이언트 애플리케이션에서 액세스 토큰을 사용하는 경우 액세스 토큰을 순환, 유지 및 서버의 어딘가에 저장해야 합니다. 웹 애플리케이션에서 쿠키는 세션을 보호하는 데 사용되며 SaveTokens 옵션을 통해 토큰을 저장하는 데 사용할 수 있습니다.

SaveTokens 현재 액세스 토큰을 자동으로 새로 고치지 않지만 이 기능은 .NET 10용으로 계획되어 있습니다. 업데이트를 받으려면 https://github.com/dotnet/aspnetcore/issues/8175을(를) 팔로우하세요. 그 동안 OIDC 설명서 Blazor Web App 설명된 대로 액세스 토큰을 수동으로 새로 고치거나 Duende.AccessTokenManagement.OpenIdConnect 같은 타사 NuGet 패키지를 사용하여 클라이언트 앱에서 액세스 토큰을 처리하고 관리할 수 있습니다. 자세한 내용은 Duende 토큰 관리참조하세요.

메모

프로덕션에 배포하는 경우 캐시는 뮤틀리 인스턴스 배포에서 작동해야 합니다. 영구 캐시는 일반적으로 필요합니다.

일부 보안 토큰 서버는 액세스 토큰을 암호화합니다. 액세스 토큰에는 형식이 필요하지 않습니다. OAuth 내성 검사를 사용하는 경우 액세스 토큰 대신 참조 토큰이 사용됩니다. 클라이언트(UI) 애플리케이션은 액세스 토큰이 이를 위한 것이 아니기 때문에 액세스 토큰을 열지 않아야 합니다. 액세스 토큰을 만든 API만 액세스 토큰을 열어야 합니다.

UI 애플리케이션에서 액세스 토큰 열기 안 함
API에 ID 토큰을 보내지 마세요.
액세스 토큰은 모든 형식을 가질 수 있습니다.
액세스 토큰을 암호화할 수 있습니다.
액세스 토큰이 만료되며 재발급되어야 합니다.
액세스 토큰은 보안 백 엔드 서버에 유지됩니다.

YARP(또 다른 역방향 프록시)

YARP(Yet Another Reverse Proxy) 는 HTTP 요청을 처리하고 요청을 다른 API에 전달하는 데 유용한 기술입니다. YARP는 새 액세스 자격 증명을 획득하기 위한 보안 논리를 구현할 수 있습니다. YARP는 BFF(백 엔드 for Frontend) 보안 아키텍처를 채택할 때 자주 사용됩니다.

Blazor YARP를 사용하여 BFF 패턴을 구현하는 예제는 다음 문서를 참조하세요.

YARP를 Blazor 사용하여 BFF 패턴을 구현하는 예제는 OIDC(OpenID Connect)를 사용하여 ASP.NET Core Blazor Web App 보안을 참조하세요.

자세한 내용은 auth0: 프런트 엔드 패턴의 백 엔드를 참조하세요.

API 테스트

액세스 토큰이 있는 통합 테스트 및 컨테이너를 사용하여 보안 API를 테스트할 수 있습니다. dotnet user-jwts 도구사용하여 액세스 토큰을 만들 수 있습니다.

경고

테스트 목적으로 보안 문제가 API에 도입되지 않도록 확인합니다. 이러한 토큰은 UI 및 OpenID Connect 흐름을 통해서만 만들 수 있으므로 위임된 액세스 토큰을 사용하는 경우 테스트가 더 어려워집니다. 테스트 도구를 사용하여 위임된 액세스 토큰을 만드는 경우 테스트를 위해 보안 기능을 사용하지 않도록 설정해야 합니다. 이러한 기능은 테스트 환경에서만 사용하지 않도록 설정해야 합니다.

보안 기능을 안전하게 사용하지 않도록 설정하거나 수정할 수 있는 격리된 전용 테스트 환경을 만듭니다. 이러한 변경 내용이 테스트 환경으로 엄격하게 제한되는지 확인합니다.

Swagger UI, Curl 및 기타 API UI 도구 사용

Swagger UI 및 Curl은 API를 테스트하기 위한 훌륭한 UI 도구입니다. 도구가 작동하려면 API에서 OpenAPI 문서를 생성할 수 있으며 클라이언트 테스트 도구에 로드할 수 있습니다. 새 액세스 토큰을 획득하는 보안 흐름을 API OpenAPI 파일에 추가할 수 있습니다.

경고

안전하지 않은 보안 테스트 흐름을 프로덕션에 배포하지 마세요.

API에 대한 Swagger UI를 구현할 때, 보안을 약화해야 하므로 해당 UI를 프로덕션에 일반적으로 배포하지 않아야 합니다.

OpenID Connect에서 클레임 매핑

다음 문서를 참조하세요.

ASP.NET Core 클레임 매핑, 사용자 지정 및 변환

표준

JWT (JSON 웹 토큰)

OAuth 2.0 권한 부여 프레임워크

OAuth 2.0 소유 증명 시연 DPoP

OAuth 2.0 JWT-Secured JAR(권한 부여 요청) RFC 9101

OAuth 2.0 Mutual-TLS 클라이언트 인증 및 Certificate-Bound 액세스 토큰

오픈ID 커넥트 1.0

Microsoft ID 플랫폼 및 OAuth 2.0 온플로우Behalf-Of

OAuth 2.0 토큰 교환

OAuth 2.0 액세스 토큰을 위한 JSON Web Token(JWT) 프로필

HTTP 의미 체계 RFC 9110