Keycloak 인증 패턴 기록
Tech Log Studio에 있는 18건이다. Studio의 working copy가 정본이고, 이 폴더의 세 형식은 모두 그 값을 받아 적은 것이다.
| 파일 | 무엇 |
|---|---|
<name>.md |
사람이 읽고 고치는 형식. 여기서 고친 뒤 Studio로 올린다 |
<name>.json |
같은 내용의 기계 판독 형식. Studio에서 받아 다시 만든다 |
case-*.body.md |
Case 본문만 따로 뺀 것. 파서 검사에 쓴다 |
셋은 같이 갱신한다. 하나만 고치면 다음 사람이 어느 쪽이 최신인지 알 수 없다. 마지막 동기화는 2026-08-26이고 그 시점에 세 형식과 Studio가 모두 같았다.
파일 형식
| 부분 | 담는 것 |
|---|---|
| front matter | id, kind, slug, title, topic, project, status, version, 검증일, Studio·공개 주소 |
# 제목 다음 문단 |
요약 |
## 관계 · ## 근거 |
대상 제목과 이유. Decision만 「근거」다 |
## 규칙 · ## 선택지 |
### N. 제목 다음에 본문 |
| 목록 칸 | - 항목. 적용 조건·예외·예시·사실·가정·미지수·제약·영향 |
## 본문 |
Case만. <!-- body:start -->와 <!-- body:end --> 사이가 Studio 본문 원문이다 |
Case 본문은 글자 단위로 Studio 값과 같다. Reference·Question·Decision의 칸은 평문으로
렌더링되므로 표와 코드블록을 넣지 않는다. 비교 축이 필요하면 이름 : 값 줄로 쓴다.
다이어그램 SVG와 record JSON은 같은 폴더에 있다. relation-plan.json은 18개 문서의 관계를
한 파일로 모은 색인이고 .md에서 다시 만든다.
목록
Case (4건)
| 파일 | 제목 | 상태 | 버전 |
|---|---|---|---|
| case-ap2-split-custody.md | Mediator가 Refresh Token을 관리하고 Access Token을 Browser에 전달하는 구조 | 게시 중 공개 | v20 |
| case-ap3-bff-session-csrf.md | BFF에서 OAuth Token을 관리할 때 Session과 CSRF를 처리한 과정 | 게시 중 공개 | v28 |
| case-ap4-identity-header-trust.md | Forward-Auth에서 Client가 보낸 Identity Header를 신뢰하면 안 되는 이유 | 게시 중 공개 | v37 |
| case-browser-credential-boundary.md | SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계 | 게시 중 공개 | v25 |
Reference (7건)
| 파일 | 제목 | 상태 | 버전 |
|---|---|---|---|
| reference-authorization-code-endpoints.md | Authorization Code Flow의 Endpoint와 Credential 이동 기준 | 게시 중 공개 | v32 |
| reference-bff-auth-design.md | BFF 인증 구조 설계 기준 | 게시 전 | v10 |
| reference-forward-auth-header-trust.md | Forward-Auth에서 Identity Header를 신뢰하기 위한 조건 | 게시 전 | v10 |
| reference-idp-federation-boundary.md | 외부 IdP Federation과 Application 인증 경계 | 게시 전 | v9 |
| reference-pattern-selection.md | OAuth/OIDC 인증 패턴 선택 기준 | 게시 전 | v10 |
| reference-public-confidential-client.md | Public Client와 Confidential Client 구분 기준 | 게시 전 | v12 |
| reference-token-vs-session.md | OAuth Token과 Application Session을 구분하는 기준 | 게시 전 | v11 |
Question (4건)
| 파일 | 제목 | 상태 | 버전 |
|---|---|---|---|
| question-bff-state-store.md | BFF의 Session과 OAuth2AuthorizedClient를 어디에 저장할 것인가 | 게시 전 | v8 |
| question-edge-authorization-scope.md | Forward-Auth 구조에서 Application Authorization을 어디까지 Edge에 둘 것인가 | 게시 전 | v9 |
| question-multi-instance-session.md | 서버 세션 기반 인증 구조는 다중 인스턴스에서 어떻게 운영할 것인가 | 게시 전 | v10 |
| question-refresh-rotation-replica.md | Refresh Token Rotation과 다중 Replica 경쟁을 어떻게 처리할 것인가 | 게시 전 | v10 |
Decision (3건)
| 파일 | 제목 | 상태 | 버전 |
|---|---|---|---|
| decision-bff-owns-token.md | BFF가 OAuth Token을 관리하는 조건 | 게시 전 | v11 |
| decision-federation-not-a-pattern.md | 외부 IdP Federation을 별도의 인증 구조로 세지 않는다 | 게시 전 | v9 |
| decision-not-maturity-ladder.md | 인증 구조를 보안 성숙도 단계로 취급하지 않는다 | 게시 전 | v11 |
주의
이미 게시된 문서는 Studio에서 저장하는 순간 공개 화면에 반영된다. 게시 기록에 새 이벤트가 남지 않아도 그렇다. 2026-08-25에 확인했다. 게시된 문서를 고칠 때는 먼저 Studio의 현재 값을 여기로 받아 온 다음 고친다. 로컬 파일이 오래됐으면 Studio에서 손댄 내용을 덮어쓰게 된다.
Studio 편집기에는 working copy 버전 이력이 없다. 게시 기록에서 볼 수 있는 것은 게시 시점의 Snapshot뿐이다.
문체 기준은 .claude/skills/writing-tech-log-records에 있다. 문서군 전체의 리듬은
references/ai-tells.md.