API 인증: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT는 복잡한 인증 (범위/역할/테넌트), SSO 및 짧은 TTL 토큰이있는 클라이언트 응용 프로그램 및 서버 통합을위한 표준입니다.
HMAC 서명은 결정 론적 검증과 재생에 대한 강력한 보호 기능을 갖춘 웹 후크 및 간단한 파트너 호출 "서버 → 서버" 에 가장 적합한 선택입니다.
보안 강화: mSL 또는 DPoP (발신자 제한 토큰), 짧은 TTL (5-15 분), 키 회전 (JWKS), 회전/재사용으로 토큰 새로 고침, 엄격한 검증 'aud/iss/exp/nbf/kid' 및 게이트웨이의 정책 코드.

1) 솔루션 맵: 적용 대상

2) OAuth2/OIDC: 흐름과 클라이언트

2. 1 흐름

인증 코드 + PKCE (웹/모바일) -인증 코드를 차단으로부터 보호합니다.
클라이언트 자격 증명: 사용자가없는 서버 서버; 스코프-최소한의 필요.
장치 코드: 브라우저가없는 장치의 경우.
토큰 새로 고침: 신뢰할 수있는 클라이언트 전용; 재사용 탐지를 회전하고 가능하게합니다.

2. 클라이언트 유형 2 개

기밀 (서버, BFF): 비밀 유지; mTLS를 사용하십시오.
공개 (용지/모바일): 비밀을 → PKCE, DPoP, 짧은 TTL 및 제한된 범위로 저장할 수 없습니다.

3) JWT: 구조, 타이밍, 검증

3. 1 필드 (청구)

필수: 'iss', 'sub', 'aud', 'exp', 'iat', 'nbf', 'jti', 'scope '/' rights', 'tentian' (다중 임대), 'kid'.

3. 2 평생

액세스 토큰: 5-15 분

토큰 새로 고침: 며칠/주, 각 교환으로 회전하십시오. 오래된 것을 다시 제출할 때 세션을 차단합니다.

시계 왜곡: 허용 오차가 6 초

3. 3 JWKS 및 키

KMS/Vault에 키를 저장하려면 'kid' 가 필요합니다.
60-90 일마다 한 번씩 또는 사고로 재발행 된 두 개의 활성 키 (롤링).
JWKS는 자동 장애가있는 5 분 동안 게이트웨이에 캐시합니다.

3. 4 게이트웨이/서비스 검증

체크: 서명, 'aud' (승인 된 서비스), 'iss', 'exp/nbf', 자물쇠 목록 (취소).
서명을 확인하지 않고 신체의 필드를 신뢰하지 마십시오. 'alg = none' 을 무시하십시오.

Authorization: Bearer <JWT>
X-Trace-Id: <uuid>

4) 클라이언트에 바인딩 토큰: mSL, DPoP

mTLS (SL 클라이언트 인증서): 클라이언트 인증서가있는 경우에만 토큰이 발행 및 검증됩니다. → 토큰은 키 + 인증서 조합 외부에서는 쓸모가 없습니다.
DPoP (소유 증명 데모): 클라이언트는 각 요청에 일회성 키 → 공개 클라이언트의 재생 및 토큰 도난으로부터 보호합니다.
중요한 경로 (지불 돌연변이) 의 경우-메커니즘 중 하나가 필요합니다.

5) 승인: 스코프, 역할, ABAC

스코프-최소 조치 ('지불: 쓰기', '지불: 상태: 읽기').
역할 - 관리자를위한 단위; 범위없이 직접 사용하지 마십시오.
ABAC-게이트웨이/OPA의 토큰 ('테넌트', '국가', 'kyc _ 레벨', '위험 _ 플래그') → 정책의 속성.
경로/필드 레벨 (GraphQL) 및 도메인 작동 레벨 (REST/gRPC) 의 정책.

6) HMAC 서명: 웹 후크 및 파트너

6. 1 개념

각 통합에는 고유 한 비밀이 있습니다.

표준 줄 위의 캡션: '타임 스탬프 + "\n "+ 방법 + "\n" + 경로 + "\n "+ sha256 (본문)'

X-Signature: v1=base64(hmac_sha256(secret, canonical_string))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF...

시간 창: λ300 초; 만료/미래 'X-Timestamp' 요청을 거부합니다.
Idempotence: TTL (24h) 에 'X-Event-ID' 를 저장하십시오-중복을 버립니다.

6. 2 가지 모범 사례

KMS/Vault의 비밀은 90 일마다 회전합니다.
공공 고객에게는 HMAC가 적합하지 않습니다 (비밀 누출). OAuth2/DPoP 사용.

7) 재생, 무차별 대입 및 누출 방지

민감한 작업을위한 Nonce/' jti '; 사용 된 식별자의 블랙리스트.
요율/할당량: 키/클라이언트/테넌트/경로 별; "비싼" 운영은 별도의 할당량입니다.
파트너 및 웹 후크에 대한 IP/ASN/Geo 허용 목록.
콘텐츠 유형 허용 ('응용 프로그램/json'), 신체 크기 제한.
로그에서 PII 마스킹; 토큰/비밀을 기록하는 것을 금지합니다.

8) 오류 및 답변 (단일 형식)

json
{
"error": "invalid_token",
"error_description": "expired",
"trace_id": "4e3f-..."
}

• '401' - 아니오/유효하지 않은 토큰 (WWW- 바스 타르).
• '403' -불충분 한 권리 (범위/ABAC).
• '429' -제한/할당량.
• gRPC: 'UNAUTHENTICATED '/' PERMISSION _ DENIED '/' RESOURCE _ EXHAUSTED'.

9) 기간 및 세션 정책

액세스 10 분; 새로 고침-회전 + 재사용 탐지 (오래된 세션 제출-세션 리콜).
Webhooks HMAC: TTL 서명 지수 백오프와 함께 반복 전달.
세션/키 취소 → 취소 목록에 즉시 들어갑니다 (게이트웨이의 캐시 1 분).

10) 관찰 및 감사

'trace _ id '/' span _ id' 에 의한 상관 관계.
측정 항목: 성공률, '401/403/429', OIDC/JWKS 대기 시간, 회전 주파수, 재사용 새로 고침, DPoP/mSL 트래픽 공유.
감사 로그: "누가 '하위/테넌트/스코프' 로 인해 무엇이 발생했는지" 키/비밀 변경으로 인해 HMAC 서명이 실패했습니다.

11) 게이트웨이 API에 포함

게이트웨이의 JWT 검증 (JWKS 캐시) 및 OPA/ABAC

신뢰할 수있는 클라이언트/파트너를위한 mTLS 프

웹 후크의 HMAC 검증 (내부 서비스 이전).
평가/쿼터 정책, OIDC 제공 업체의 회로 차단기 (캐시 JWK).
기능 플래그: 클라이언트/키의 빠른 분리, 서명 알고리즘의 변경.

12) 미니 스 니펫

의사: JWT 검증

pseudo jwks = cache. getOrFetch(iss + "/.well-known/jwks. json")
key = jwks[kid]
assert verify_signature(jwt, key)
assert aud in ALLOWED_AUDIENCES and iss in TRUSTED_ISSUERS assert now in [nbf-60s, exp+60s]

의사: HMAC 웹 후크 확인

pseudo canonical = timestamp + "\n" + method + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
assert abs(now - timestamp) <= 300 assert not seen(event_id)
assert timingSafeEqual(sig, header["X-Signature"].split("v1=")[1])
markSeen(event_id, ttl=86400)

예 범위 정책 (OPA/Rego idea)

rego allow {
input. jwt. scope[_] == "payments:write"
input. jwt. tenant == input. route. tenant
}

13) 사건 플레이 북

개인 키 누출/JWT 서명자: 키 재발급, JWKS 업데이트, 기존 비활성화 ('kid' → 거부), 장애 새로 고침, 강제 로그아웃.
웹 후크의 대체: 비밀의 회전, IP 허용 목록, 'X-Timestamp' 창의 증폭, 누락 된 이벤트의 반복 전달.
재생/무차별 대응: 중요 경로에서 DPoP/mTLS를 활성화하고, 좁은 할당량, IP/ASN의 임시 블록을 사용하면 'jti' 블록 목록이 활성화됩니다.
중단 OIDC: 캐시 된 토큰 (그레이스) 의 저하, 회로 차단기 제공 업체, 고객 알림.

14) 구현 점검표

• OAuth2: 코드 + PKCE (웹/모바일), 클라이언트 자격 증명 (서버 간)
• TTL: X15 분 액세스, 회전 및 재사용 탐지로 새로 고침
• JWKS: 'kid' 라는 두 개의 활성 키를 캐시합니다
• 웹 후크: HMAC v1, 'X- 타임 스탬프', 'X- 이벤트-페이지', 창

[Sender] 제한: 중요한 경로의 mSL/DPoP

• ABAC/OPA: 게이트웨이 정책의 범위 + 테넌트/위험
• Rate/Quotes.com 429; 파트너를위한 IP/ASN 허용 목록
• 감사 및 경고 (401/403/429, 새로 고침 재사용, HMAC 서명)

• 토큰/비밀/전체 카드 본문을 기록하지 마십시오
• PII 마스킹; DSAR 지원; 통나무의 유통 기한이 제한되어 있습니다

15) 반 패턴

'alg = none' 또는 서명 확인/JWKS없이 토큰을 신뢰하십시오.
오래 지속되는 액세스 토큰 (시간/일).
모든 파트너를위한 하나의 일반적인 HMAC 비밀.
타임 스탬프/idempotency가없는 웹 후크.
회전없이 재사용 탐지없이 토큰을 새로 고칩니다.
'aud '/' iss' 유효성 검사 및 'kid' 회전 부족.
KMS/Vault없이 환경 변수에 비밀을 저장합니다.

16) NFT/SLO (랜드 마크)

OIDC/JWKS 가용성은 99 이상입니다. 95% (에지 캐시는 종속성을 줄입니다).
게이트웨이의 JWT 유효성 추가 기능 2-5 ms p95.
인증 오류 ('401') 전체 트래픽의 5% (봇 제외).

서명 된 웹 후크: 성공적으로 검증 된 공유 9%, 평균 배송 지연

요약

결합 메커니즘: 사용자 및 풍부한 서버 스크립트를위한 OAuth2/OIDC + JWT, 웹 후크/간단한 파트너를위한 HMAC 및 중요한 작업 (mSL/DPoP). 짧은 TTL, 주요 회전 (JWKS), 엄격한 ABAC/OPA 정책을 유지하고 루프를 재생 및 누출로부터 보호하며 API 게이트웨이 레벨에서 모든 것을 자동화하십시오. 따라서 인증은 UX 및 수익 창출에 대한 타협없이 예측 가능하고 확장 가능하며 안전합니다.