refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -0,0 +1,28 @@
+# Bearer JWT가 검증과 역할 변환을 지나 principal이 된다
+
+## Alternative text
+
+Bearer JWT 입력이 JwtDecoder, issuer·시간 검증, audience 검증, role converter를 거쳐 authenticated principal이 되는 검증 사슬.
+
+## Long description
+
+왼쪽의 raw Bearer JWT가 NimbusJwtDecoder에서 JWK 서명을 확인한 뒤 issuer와 timestamp validator, 프로젝트의 AudienceValidator를 통과해 validated Jwt가 된다. 이어서 KeycloakRealmRoleConverter가 realm_access.roles를 ROLE_* authority로 바꾸고 authenticated principal이 만들어진다.
+
+## Elements and evidence
+
+- **Bearer JWT** (data): Resource Server가 Authorization header에서 받은 raw Bearer JWT. Evidence: L354–L359.
+- **NimbusJwtDecoder** (service): JWK를 이용해 JWT 서명을 검증하는 decoder. Evidence: L359–L360.
+- **Issuer · Time validators** (service): Expected issuer와 timestamp 조건을 확인하는 default validators. Evidence: L361–L361.
+- **AudienceValidator** (service): keycloak-pattern-api audience 포함 여부를 확인하는 project validator. Evidence: L362–L370.
+- **Validated Jwt** (data): 서명, issuer·시간, audience 검증을 통과한 Jwt. Evidence: L363–L363.
+- **Realm role converter** (service): realm_access.roles 문자열에 ROLE_ prefix를 붙여 authority로 변환한다. Evidence: L364–L370.
+- **Authenticated principal** (actor): 검증된 JWT와 ROLE_* authorities를 가진 인증 결과. Evidence: L365–L365.
+
+## Relationships
+
+- **Bearer JWT → NimbusJwtDecoder:** decode. Evidence: L354–L360.
+- **NimbusJwtDecoder → Issuer · Time validators:** signature ok. Evidence: L360–L361.
+- **Issuer · Time validators → AudienceValidator:** claims. Evidence: L361–L362.
+- **AudienceValidator → Validated Jwt:** valid audience. Evidence: L362–L363.
+- **Validated Jwt → Realm role converter:** realm roles. Evidence: L363–L364.
+- **Realm role converter → Authenticated principal:** authorities. Evidence: L364–L365.