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(언어 예외 줄 둘을 지움).
This commit is contained in:
+25
-29
@@ -1,37 +1,33 @@
|
||||
# Keycloak realm artifact
|
||||
# Keycloak realm 파일
|
||||
|
||||
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in the root `compose.yaml`
|
||||
and is the same realm every GraphQL qualification lane authenticates against.
|
||||
루트 `compose.yaml`의 `keycloak` 서비스가 `realms/ca-skeleton-realm.json`을 가져온다(import). 모든 GraphQL
|
||||
qualification lane이 인증하는 realm도 이 파일이다.
|
||||
|
||||
## The client secret is a reference, never a value
|
||||
## client secret은 값이 아니라 참조다
|
||||
|
||||
The confidential client `ca-skeleton-api` carries `"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"`.
|
||||
`entrypoint.sh` reads the value from the Compose secret mounted at
|
||||
`/run/secrets/keycloak-graphql-smoke-client-secret`, exports it, and execs `kc.sh start-dev
|
||||
--import-realm`, so the value never reaches Git, a rendered Compose config, a command line, or an
|
||||
evidence file. A realm file with a working credential in it is a credential in the repository, and
|
||||
"it is only for smoke tests" is not something a scanner or a fork can tell.
|
||||
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도 알 수 없다.
|
||||
|
||||
## No comment keys in the realm JSON
|
||||
## realm JSON에 주석 키를 두지 않는다
|
||||
|
||||
Keycloak deserializes this file into `RealmRepresentation` with unknown fields **rejected**, not
|
||||
ignored. A `"_comment"` key here fails the whole import with `Unrecognized field "_comment"`, the
|
||||
container exits 1, and the lane fails on Keycloak rather than on anything it was testing. That is
|
||||
why this rationale lives in Markdown next to the artifact instead of inside it.
|
||||
Keycloak은 이 파일을 `RealmRepresentation`으로 역직렬화할 때 모르는 필드를 무시하지 않고 **거절한다**.
|
||||
`"_comment"` 키 하나가 `Unrecognized field "_comment"`로 import 전체를 실패시키고, 컨테이너가 1로 끝나고,
|
||||
lane은 시험하던 것이 아니라 Keycloak에서 실패한다. 그래서 이 근거를 파일 안이 아니라 옆의 Markdown에 둔다.
|
||||
|
||||
## What the realm grants
|
||||
## realm이 주는 권한
|
||||
|
||||
- realm role `user` — the baseline role the application authorizes ordinary calls on
|
||||
- client role `ca-skeleton-api:graphql-query` — permission to execute a GraphQL query
|
||||
- client roles `notification-submit`, `notification-template-publish`, `operation-submit` — the
|
||||
platform permissions `security.yml` maps them to
|
||||
- client roles `ROLE_FILE_READ` and `ROLE_FILE_WRITE` — the fileserver's read and write tiers, which
|
||||
`security.yml` also maps to `file:read` and to `file:upload`, `file:delete`, `file:copy`,
|
||||
`file:move`; `ROLE_FILE_ADMIN` (`file:admin`) is defined but not granted to the service account,
|
||||
since the management plane is off by default
|
||||
- a service account for the client-credentials grant the qualification lane uses
|
||||
- audience and realm/client role mappers, so the issued token carries what the resource server
|
||||
validates
|
||||
- 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 and direct access grants are disabled: the lane authenticates as a service, and an
|
||||
enabled password grant is a second way in that nothing tests.
|
||||
standard flow와 direct access grant는 꺼 두었다. lane은 서비스로 인증하고, 켜 둔 password grant는 아무도
|
||||
시험하지 않는 두 번째 입구가 된다.
|
||||
|
||||
+55
-49
@@ -1,58 +1,64 @@
|
||||
# ACL accounts — test fixtures, not a deployment file
|
||||
# ACL 계정 — 배포 파일이 아니라 시험용 fixture
|
||||
|
||||
**Nothing in this directory is loaded by a deployment.** Every file here is a fixture for the local
|
||||
and test lanes: its passwords are public (`fixture-*`, written in this repository), and
|
||||
`lane-fixture-accounts.acl` also provisions three accounts that only a lane topology needs — among
|
||||
them `ca-skeleton-cluster-bootstrap`, which has `~* &* +@all`, every command on every key. Loaded into
|
||||
a real Redis, that line alone gives anyone who can reach the server and read this repository full
|
||||
control of it (`CONFIG`, `MODULE`, every key). A deployment writes its own ACL file of the same
|
||||
shape: the application accounts it actually uses, passwords from its secret store, and none of the
|
||||
lane-only accounts (review 2026-11-03 RR-07-04). The application enforces its half of that: under
|
||||
the `prod` runtime profile it refuses to start while a secret holds a value beginning with
|
||||
`fixture-` (`SecretSourceValidator`): a key the secrets registry classifies `secret`, a variable a
|
||||
module's `RequiredProductionSecrets` bean names, or the variable a `secret://…/<VAR>` credential
|
||||
reference in the environment names. A reference held in code — the typed SDK's admin account,
|
||||
contributed as a `RedisAccountContribution` bean — is none of those: the composer names its variable
|
||||
in a `RequiredProductionSecrets` bean too (`src/adapter/outbound/redis-sdk/README.md`), or the
|
||||
`fixture-admin` password passes. A deployment that copied a lane's
|
||||
`APP_REDIS_AUTHENTICATION_*_REFERENCE` and `REDIS_LANE_*` values stops before it connects. Values
|
||||
that are not secrets — a pod's `HOSTNAME`, an application name — are not read, because `fixture-`
|
||||
is an ordinary word as well.
|
||||
**이 폴더의 어떤 파일도 배포에서 읽지 않는다.** 모든 파일이 로컬·테스트 lane용 fixture다.
|
||||
|
||||
One file per `CommandAccess` level. Each account is deliberately narrower than the SDK's own rules:
|
||||
the account is the last enforcement boundary and a permit issued inside the process never widens it,
|
||||
so a mistake in the SDK is still refused by the server.
|
||||
- 비밀번호가 공개돼 있다(`fixture-*`, 이 저장소에 적혀 있다).
|
||||
- `lane-fixture-accounts.acl`은 lane 구성에만 필요한 계정 셋도 만든다. 그중
|
||||
`ca-skeleton-cluster-bootstrap`은 `~* &* +@all`, 곧 모든 key에 모든 명령을 가진다.
|
||||
- 이 줄 하나를 실제 Redis에 올리면, 서버에 닿을 수 있고 이 저장소를 읽을 수 있는 누구나 서버 전체
|
||||
(`CONFIG`, `MODULE`, 모든 key)를 다룰 수 있다.
|
||||
|
||||
A Redis ACL file accepts nothing but complete `user` lines — no comments and no line continuations —
|
||||
which is why the rationale lives here instead of inline.
|
||||
배포는 같은 모양의 자기 ACL 파일을 쓴다. 실제로 쓰는 애플리케이션 계정만 두고, 비밀번호는 자기 secret
|
||||
store에서 가져오고, lane 전용 계정은 두지 않는다(review 2026-11-03 RR-07-04).
|
||||
|
||||
Every account here carries a **fixture** password (`fixture-*`). They are written down rather than
|
||||
left as `nopass` because an account that accepts any password makes every assertion about
|
||||
authentication pass for the same reason a typo would have — and because these files are what a fork
|
||||
copies. The four per-role files carried `nopass` long after the combined lane file had been fixed;
|
||||
a fork that copied one of them got an open account and a green lane.
|
||||
애플리케이션도 자기 몫을 강제한다. `prod` 런타임 profile에서 비밀값이 `fixture-`로 시작하면 기동을
|
||||
거부한다(`SecretSourceValidator`). 보는 비밀값은 셋이다.
|
||||
|
||||
| File | Account | Grants |
|
||||
- 비밀 레지스트리가 `secret`으로 분류한 키
|
||||
- 모듈의 `RequiredProductionSecrets` bean이 이름을 댄 변수
|
||||
- 환경 안의 `secret://…/<VAR>` 자격 증명 참조가 가리키는 변수
|
||||
|
||||
코드에 있는 참조(typed SDK의 admin 계정을 `RedisAccountContribution` bean으로 기여하는 경우)는 이 셋 중
|
||||
어디에도 들지 않는다. 조립하는 쪽이 그 변수도 `RequiredProductionSecrets` bean에 적어야 한다
|
||||
(`src/adapter/outbound/redis-sdk/README.md`). 그러지 않으면 `fixture-admin` 비밀번호가 통과한다.
|
||||
lane의 `APP_REDIS_AUTHENTICATION_*_REFERENCE`와 `REDIS_LANE_*` 값을 복사한 배포는 연결하기 전에 멈춘다.
|
||||
비밀이 아닌 값(pod의 `HOSTNAME`, 애플리케이션 이름)은 읽지 않는다. `fixture-`는 보통 낱말이기도 하다.
|
||||
|
||||
`CommandAccess` 등급마다 파일이 하나다. 각 계정은 SDK 자체 규칙보다 일부러 더 좁다. 계정이 마지막
|
||||
강제 경계이고 프로세스 안에서 내준 허가는 그 경계를 넓히지 못한다. 그래서 SDK에 실수가 있어도 서버가
|
||||
거절한다.
|
||||
|
||||
Redis ACL 파일은 완전한 `user` 줄만 받는다. 주석도, 줄 이어 쓰기도 안 된다. 그래서 근거를 파일 안이
|
||||
아니라 여기에 둔다.
|
||||
|
||||
여기의 모든 계정은 **fixture** 비밀번호(`fixture-*`)를 가진다. `nopass`로 두지 않고 적어 둔 이유는 둘이다.
|
||||
|
||||
- 아무 비밀번호나 받는 계정에서는 인증에 대한 모든 단언이 오타가 있어도 통과한다.
|
||||
- fork가 복사하는 것이 이 파일들이다. 역할별 파일 넷은 합친 lane 파일을 고친 뒤에도 오래 `nopass`였고,
|
||||
그중 하나를 복사한 fork는 열린 계정과 녹색 lane을 함께 얻었다.
|
||||
|
||||
| 파일 | 계정 | 주는 권한 |
|
||||
| --- | --- | --- |
|
||||
| `application.acl` | `CommandAccess.APPLICATION` | the typed data-structure commands over `prod:*`, with the dangerous and deprecated names denied |
|
||||
| `application-advanced.acl` | `APPLICATION_ADVANCED` | the above plus pub/sub, transactions, and the registered-script path. `EVAL` is absent: only `EVALSHA` of an already loaded digest is reachable. `+time` is granted because the rate-limit and idempotency scripts read the server clock with `redis.call('TIME')`, and `TIME` is in no data category (`@read`/`@write`): without it every such script fails with an ACL error. The startup SCRIPT probe runs `TIME` so a template missing it fails at boot |
|
||||
| `raw-gateway.acl` | `RAW_GATEWAY` | exactly the commands the catalog classifies `RAW_ONLY`, and nothing else |
|
||||
| `lane-fixture-accounts.acl` | – | what the lanes load (Redis takes one `aclfile`): `user default off`, the four per-role accounts of this table, and three lane-only accounts — `ca-skeleton-replication` (replica sync) and `ca-skeleton-sentinel` for the replicated and sentinel topologies, `ca-skeleton-cluster-bootstrap` (`+@all`) to create the cluster lane's slots. Never a deployment file |
|
||||
| `admin-readonly.acl` | `ADMIN_READONLY` | read-only diagnostics. Every destructive counterpart is denied here and blocked in the command policy catalog — two independent controls for the same rule |
|
||||
| `application.acl` | `CommandAccess.APPLICATION` | `prod:*` 위의 typed 자료구조 명령. 위험한 명령과 폐기된 명령 이름은 막는다 |
|
||||
| `application-advanced.acl` | `APPLICATION_ADVANCED` | 위 권한에 pub/sub, 트랜잭션, 등록된 script 경로를 더한다. `EVAL`은 없다: 이미 올린 digest의 `EVALSHA`만 닿는다. `+time`을 주는 이유: rate-limit·idempotency script가 `redis.call('TIME')`으로 서버 시계를 읽는데, `TIME`은 어떤 데이터 범주(`@read`/`@write`)에도 없다. 없으면 그런 script가 모두 ACL 오류로 실패한다. 기동 때의 SCRIPT 확인이 `TIME`을 돌려서, 이 권한이 빠진 템플릿은 기동에서 실패한다 |
|
||||
| `raw-gateway.acl` | `RAW_GATEWAY` | catalog가 `RAW_ONLY`로 분류한 명령만, 그 밖에는 없다 |
|
||||
| `lane-fixture-accounts.acl` | – | lane이 읽는 파일(Redis는 `aclfile` 하나만 받는다): `user default off`, 이 표의 역할별 계정 넷, lane 전용 계정 셋 — `ca-skeleton-replication`(replica 동기화)과 `ca-skeleton-sentinel`(replicated·sentinel 구성용), `ca-skeleton-cluster-bootstrap`(`+@all`, cluster lane의 slot을 만든다). 배포 파일이 아니다 |
|
||||
| `admin-readonly.acl` | `ADMIN_READONLY` | 읽기 전용 진단. 파괴적인 짝 명령은 모두 여기서 막고 명령 정책 catalog에서도 막는다 — 같은 규칙에 서로 독립인 통제 둘 |
|
||||
| `sentinel-accounts.acl` | – | sentinel 프로세스용 계정(`ca-skeleton-sentinel-client`, `ca-skeleton-sentinel-peer`, `ca-skeleton-sentinel-operator`). 지금 이 파일을 `aclfile`로 읽는 compose 파일은 없다 |
|
||||
|
||||
## Who loads `lane-fixture-accounts.acl`
|
||||
## 누가 `lane-fixture-accounts.acl`을 읽나
|
||||
|
||||
The Redis topology lanes (`src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`), the
|
||||
application's Compose lanes that switch Redis on (`local-redis`, `all-adapters` in
|
||||
`src/app-bootstrap/compose-lanes/compose-profile-contracts.json`), and the development stack's
|
||||
`redis` service (root `compose.yaml`). They all mount this directory read-only; neither
|
||||
keeps a copy, because a second copy of these lines is a second place for a password or a key
|
||||
pattern to drift.
|
||||
- Redis 구성(topology) lane: `src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`
|
||||
- Redis를 켜는 애플리케이션 Compose lane: `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의
|
||||
`local-redis`, `all-adapters`
|
||||
- 개발 환경의 `redis` 서비스(루트 `compose.yaml`)
|
||||
|
||||
The Compose lanes connect the application as `ca-skeleton-application` and
|
||||
`ca-skeleton-application-advanced`, through `secret://<account>@environment/<variable>` references
|
||||
whose variables carry the fixture passwords above. They run with the Redis namespace environment
|
||||
`prod`, because every account here is fenced to `~prod:*`. `scripts/verify-compose-profile-contracts.sh`
|
||||
compares each Redis lane's references, passwords and namespace with the account lines in this file,
|
||||
so changing a password or a key pattern here without the lanes fails that check rather than the
|
||||
lane's first command.
|
||||
모두 이 폴더를 읽기 전용으로 마운트한다. 복사본을 두지 않는다. 이 줄들의 두 번째 사본은 비밀번호나 key
|
||||
패턴이 따로 어긋날 두 번째 자리다.
|
||||
|
||||
Compose lane은 애플리케이션을 `ca-skeleton-application`과 `ca-skeleton-application-advanced`로 연결한다.
|
||||
연결은 `secret://<account>@environment/<variable>` 참조를 거치고, 그 변수가 위 fixture 비밀번호를 가진다.
|
||||
여기의 모든 계정이 `~prod:*`로 묶여 있어서, lane은 Redis namespace 환경을 `prod`로 두고 돈다.
|
||||
`scripts/verify-compose-profile-contracts.sh`가 Redis lane마다 참조·비밀번호·namespace를 이 파일의 계정 줄과
|
||||
비교한다. 그래서 lane을 고치지 않고 여기의 비밀번호나 key 패턴만 바꾸면, lane의 첫 명령이 아니라 그 검사가
|
||||
실패한다.
|
||||
|
||||
@@ -5,8 +5,6 @@
|
||||
# - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다.
|
||||
|
||||
# 언어: 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR. 다음 단계(살아 있는 문서 번역, ADR 번역)에서 지운다.
|
||||
language compose/keycloak/README.md
|
||||
language compose/redis/acl/README.md
|
||||
language docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md
|
||||
language docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md
|
||||
language docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md
|
||||
|
||||
Reference in New Issue
Block a user