Files
clean-architecture-backend-…/compose/keycloak
DongHyeonka af177de0aa docs(compose): Keycloak realm과 Redis ACL 안내를 한국어로 옮긴다
문제: `compose/keycloak/README.md`와 `compose/redis/acl/README.md`가 영어라 언어 검사
예외에 있다. ACL README의 파일 표에는 폴더에 있는 `sentinel-accounts.acl`이 없다.

고른 방법: 뜻을 그대로 옮긴다. 긴 문단은 목록으로 나눈다. 파일 표에
`sentinel-accounts.acl` 행을 더하고, 지금 이 파일을 `aclfile`로 읽는 compose 파일이
없다고 적는다(`git grep sentinel-accounts`가 이 README 밖에서 0건).

위험·한계: `sentinel-accounts.acl`을 지울지는 정하지 않았다.

검증: `python3 scripts/check-docs.py` rc=0(언어 예외 줄 둘을 지움).
2026-11-07 17:18:18 +09:00
..

Keycloak realm 파일

루트 compose.yaml의 keycloak 서비스가 realms/ca-skeleton-realm.json을 가져온다(import). 모든 GraphQL qualification lane이 인증하는 realm도 이 파일이다.

client secret은 값이 아니라 참조다

confidential client ca-skeleton-api는 "secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"를 가진다. entrypoint.sh가 /run/secrets/keycloak-graphql-smoke-client-secret에 마운트된 Compose secret에서 값을 읽어 export하고, kc.sh start-dev --import-realm을 exec한다. 그래서 값이 Git, 렌더링된 Compose 설정, 명령줄, 증거 파일 어디에도 닿지 않는다. 동작하는 자격 증명이 든 realm 파일은 저장소 안의 자격 증명이다. 「smoke 테스트에만 쓴다」는 사정은 스캐너도 fork도 알 수 없다.

realm JSON에 주석 키를 두지 않는다

Keycloak은 이 파일을 RealmRepresentation으로 역직렬화할 때 모르는 필드를 무시하지 않고 거절한다. "_comment" 키 하나가 Unrecognized field "_comment"로 import 전체를 실패시키고, 컨테이너가 1로 끝나고, lane은 시험하던 것이 아니라 Keycloak에서 실패한다. 그래서 이 근거를 파일 안이 아니라 옆의 Markdown에 둔다.

realm이 주는 권한

  • realm role user: 애플리케이션이 보통 호출을 허가하는 기본 role
  • client role ca-skeleton-api:graphql-query: GraphQL query를 실행할 권한
  • client role notification-submit, notification-template-publish, operation-submit: security.yml이 플랫폼 권한으로 바꾸는 role
  • client role ROLE_FILE_READ, ROLE_FILE_WRITE: 파일 서버의 읽기·쓰기 등급. security.yml이 각각 file:read와 file:upload·file:delete·file:copy·file:move로 바꾼다. ROLE_FILE_ADMIN (file:admin)은 정의만 하고 service account에 주지 않는다. 관리 기능은 기본으로 꺼져 있다
  • qualification lane이 쓰는 client credentials grant용 service account
  • audience mapper와 realm·client role mapper. 발급한 토큰에 resource server가 검증하는 값이 실린다

standard flow와 direct access grant는 꺼 두었다. lane은 서비스로 인증하고, 켜 둔 password grant는 아무도 시험하지 않는 두 번째 입구가 된다.