From 8f518175f6fe9ae3c1ac25af7e28f546d9837574 Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Tue, 22 Sep 2026 16:53:27 +0900 Subject: [PATCH] =?UTF-8?q?refactor:=20=EB=AC=B8=EC=84=9C=20=EC=82=AC?= =?UTF-8?q?=EB=9E=8C=EC=B2=98=EB=9F=BC=20=EC=9E=91=EC=84=B1=ED=95=98?= =?UTF-8?q?=EA=B8=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../a2-11-readiness-timeline.txt | 5 + .../a3-01-kcadm-speed.txt | 1 + .../a3-03-preflight.txt | 16 +++ .../a3-04-single-session-crash-loop.txt | 7 + .../a3-05-race-window.txt | 23 +++ .../a3-06-race-window-bash.txt | 61 ++++++++ .../a3-07-cleanup.txt | 9 ++ .../a4-00-baseline.txt | 28 ++++ .../a4-01-worker-loss.txt | 136 ++++++++++++++++++ .../setup/setup-reproduce-a2-database-loss.md | 4 + .../setup-reproduce-a3-database-crash.md | 4 +- .../case/case-ap2-split-custody.md | 20 +-- .../case/case-ap3-bff-session-csrf.md | 20 +-- .../case/case-ap4-identity-header-trust.md | 16 +-- .../case/case-browser-credential-boundary.md | 18 +-- .../concept-authorization-code-and-pkce.md | 6 +- .../concept-bearer-jwt-validation-chain.md | 8 +- .../concept-browser-credential-storage.md | 6 +- .../concept/concept-cookie-auth-csrf.md | 4 +- .../concept-forward-auth-and-auth-request.md | 6 +- .../concept/concept-idp-brokering.md | 6 +- .../decision/decision-bff-owns-token.md | 10 +- .../decision-federation-not-a-pattern.md | 14 +- .../question/question-bff-state-store.md | 18 +-- .../question-edge-authorization-scope.md | 18 +-- .../question-multi-instance-session.md | 22 +-- .../question-refresh-rotation-replica.md | 20 +-- .../reference-authorization-code-endpoints.md | 12 +- .../reference/reference-bff-auth-design.md | 26 ++-- .../reference-forward-auth-header-trust.md | 14 +- .../reference-idp-federation-boundary.md | 16 +-- .../reference/reference-pattern-selection.md | 16 +-- .../reference-public-confidential-client.md | 12 +- .../reference-runtime-verification-order.md | 14 +- .../reference/reference-token-vs-session.md | 12 +- .../tech-log-studio/tech-log-tree.json | 8 +- 36 files changed, 464 insertions(+), 172 deletions(-) create mode 100644 docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-01-kcadm-speed.txt create mode 100644 docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-03-preflight.txt create mode 100644 docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-04-single-session-crash-loop.txt create mode 100644 docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-05-race-window.txt create mode 100644 docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-06-race-window-bash.txt create mode 100644 docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-07-cleanup.txt create mode 100644 docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-00-baseline.txt create mode 100644 docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-01-worker-loss.txt diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a2-11-readiness-timeline.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a2-11-readiness-timeline.txt index 2037905..5305f87 100644 --- a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a2-11-readiness-timeline.txt +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a2-11-readiness-timeline.txt @@ -9,3 +9,8 @@ POLL i=7 ready=false,false external=503 POLL i=8 ready=false,false external=503 POLL i=9 ready=false,false external=503 POLL i=10 ready=false,false external=503 +POLL i=11 ready=false,false external=503 +POLL i=12 ready=false,false external=503 +POLL i=13 ready=false,false external=503 +RECOVERY i=1 ready=false,false external=503 +RECOVERY i=2 ready=true,true external=200 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-01-kcadm-speed.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-01-kcadm-speed.txt new file mode 100644 index 0000000..05a8d1e --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-01-kcadm-speed.txt @@ -0,0 +1 @@ +before=2 after=7 delta=5 elapsed_ms=5684 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-03-preflight.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-03-preflight.txt new file mode 100644 index 0000000..b450270 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-03-preflight.txt @@ -0,0 +1,16 @@ +LOGGING +none +WAL +commit_delay=0 +synchronous_commit=on +wal_writer_delay=200ms +wal_writer_flush_after=1288kB +ROWS +0 +CLUSTER +vendor_cluster_size{cache_manager="keycloak",node="keycloak-0-3135"} 2.0 +vendor_cluster_size{cache_manager="keycloak",node="keycloak-1-42489"} 2.0 +RESTARTS +keycloak-0 0 +keycloak-1 0 +postgres-7b474b88c8-rdxlv 0 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-04-single-session-crash-loop.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-04-single-session-crash-loop.txt new file mode 100644 index 0000000..ff9cbc6 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-04-single-session-crash-loop.txt @@ -0,0 +1,7 @@ +ATTEMPT=1 +SID=P2cCynldow2mfJXsB1xGURnc +KILL_AT=16:34:46.677 +BACKEND_PID=649 +PRESENT=1 +ATTEMPT=2 +LOGIN_FAILED diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-05-race-window.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-05-race-window.txt new file mode 100644 index 0000000..394b930 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-05-race-window.txt @@ -0,0 +1,23 @@ +ATTEMPT=1 delay=0.75 0.85 0.95 1.00 1.05 1.10 1.15 1.20 1.30 +KILL_AT=16:35:54.650 +sleep: invalid time interval '0.75 0.85 0.95 1.00 1.05 1.10 1.15 1.20 1.30' +Try 'sleep --help' for more information. +BACKEND_PID=868 +CLIENT_RC=0 SID=TSVnv0baKrz9WfCs9CPGjudW +PRESENT=1 +CRASH_MARKERS +2026-09-22 07:33:17.228 UTC [1] LOG: server process (PID 649) was terminated by signal 9: Killed +2026-09-22 07:33:17.231 UTC [1] LOG: all server processes terminated; reinitializing +2026-09-22 07:33:17.337 UTC [821] LOG: database system was not properly shut down; automatic recovery in progress +2026-09-22 07:33:17.342 UTC [821] LOG: redo starts at 0/2B22018 +2026-09-22 07:33:17.343 UTC [821] LOG: redo done at 0/2B31190 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s +2026-09-22 07:33:17.398 UTC [1] LOG: database system is ready to accept connections +2026-09-22 07:34:25.210 UTC [1] LOG: server process (PID 868) was terminated by signal 9: Killed +2026-09-22 07:34:25.214 UTC [1] LOG: all server processes terminated; reinitializing +2026-09-22 07:34:25.293 UTC [979] LOG: database system was not properly shut down; automatic recovery in progress +2026-09-22 07:34:25.299 UTC [979] LOG: redo starts at 0/2B31230 +2026-09-22 07:34:25.299 UTC [979] LOG: redo done at 0/2B3D898 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s +2026-09-22 07:34:25.391 UTC [1] LOG: database system is ready to accept connections +RESTARTS +NAME RESTARTS +postgres-7b474b88c8-rdxlv 0 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-06-race-window-bash.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-06-race-window-bash.txt new file mode 100644 index 0000000..829bb64 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-06-race-window-bash.txt @@ -0,0 +1,61 @@ +ATTEMPT=1 delay=0.75 +KILL_AT=16:36:34.971 +BACKEND_PID=985 +CLIENT_RC=0 SID=efQaDb2SWla3rKfQWG17bUdI +PRESENT=1 +ATTEMPT=2 delay=0.85 +KILL_AT=16:36:39.076 +BACKEND_PID=1086 +CLIENT_RC=1 SID= +PRESENT=NA +ATTEMPT=3 delay=0.95 +KILL_AT=16:36:41.800 +BACKEND_PID=1146 +CLIENT_RC=1 SID= +PRESENT=NA +ATTEMPT=4 delay=1.00 +KILL_AT=16:36:45.084 +BACKEND_PID=1184 +CLIENT_RC=0 SID=MH7o1pr5R8Yv6-y4dAnL9lCv +PRESENT=0 +LOSS_CONFIRMED attempt=4 delay=1.00 sid=MH7o1pr5R8Yv6-y4dAnL9lCv +CRASH_MARKERS +2026-09-22 07:33:17.228 UTC [1] LOG: server process (PID 649) was terminated by signal 9: Killed +2026-09-22 07:33:17.231 UTC [1] LOG: all server processes terminated; reinitializing +2026-09-22 07:33:17.337 UTC [821] LOG: database system was not properly shut down; automatic recovery in progress +2026-09-22 07:33:17.342 UTC [821] LOG: redo starts at 0/2B22018 +2026-09-22 07:33:17.343 UTC [821] LOG: redo done at 0/2B31190 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s +2026-09-22 07:33:17.398 UTC [1] LOG: database system is ready to accept connections +2026-09-22 07:34:25.210 UTC [1] LOG: server process (PID 868) was terminated by signal 9: Killed +2026-09-22 07:34:25.214 UTC [1] LOG: all server processes terminated; reinitializing +2026-09-22 07:34:25.293 UTC [979] LOG: database system was not properly shut down; automatic recovery in progress +2026-09-22 07:34:25.299 UTC [979] LOG: redo starts at 0/2B31230 +2026-09-22 07:34:25.299 UTC [979] LOG: redo done at 0/2B3D898 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s +2026-09-22 07:34:25.391 UTC [1] LOG: database system is ready to accept connections +2026-09-22 07:35:05.585 UTC [1] LOG: server process (PID 985) was terminated by signal 9: Killed +2026-09-22 07:35:05.587 UTC [1] LOG: all server processes terminated; reinitializing +2026-09-22 07:35:05.749 UTC [1079] LOG: database system was not properly shut down; automatic recovery in progress +2026-09-22 07:35:05.767 UTC [1079] LOG: redo starts at 0/2B3D938 +2026-09-22 07:35:05.768 UTC [1079] LOG: redo done at 0/2B4C668 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s +2026-09-22 07:35:05.872 UTC [1] LOG: database system is ready to accept connections +2026-09-22 07:35:09.668 UTC [1] LOG: server process (PID 1086) was terminated by signal 9: Killed +2026-09-22 07:35:09.669 UTC [1] LOG: all server processes terminated; reinitializing +2026-09-22 07:35:09.775 UTC [1126] LOG: database system was not properly shut down; automatic recovery in progress +2026-09-22 07:35:09.781 UTC [1126] LOG: redo starts at 0/2B4C708 +2026-09-22 07:35:09.782 UTC [1126] LOG: redo done at 0/2B5A380 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s +2026-09-22 07:35:09.851 UTC [1] LOG: database system is ready to accept connections +2026-09-22 07:35:12.388 UTC [1] LOG: server process (PID 1146) was terminated by signal 9: Killed +2026-09-22 07:35:12.392 UTC [1] LOG: all server processes terminated; reinitializing +2026-09-22 07:35:12.509 UTC [1163] LOG: database system was not properly shut down; automatic recovery in progress +2026-09-22 07:35:12.515 UTC [1163] LOG: redo starts at 0/2B5A420 +2026-09-22 07:35:12.516 UTC [1163] LOG: redo done at 0/2B64B90 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s +2026-09-22 07:35:12.578 UTC [1] LOG: database system is ready to accept connections +2026-09-22 07:35:15.685 UTC [1] LOG: server process (PID 1184) was terminated by signal 9: Killed +2026-09-22 07:35:15.687 UTC [1] LOG: all server processes terminated; reinitializing +2026-09-22 07:35:15.779 UTC [1203] LOG: database system was not properly shut down; automatic recovery in progress +2026-09-22 07:35:15.784 UTC [1203] LOG: redo starts at 0/2B64C30 +2026-09-22 07:35:15.785 UTC [1203] LOG: redo done at 0/2B73558 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s +2026-09-22 07:35:15.851 UTC [1] LOG: database system is ready to accept connections +RESTARTS +NAME RESTARTS +postgres-7b474b88c8-rdxlv 0 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-07-cleanup.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-07-cleanup.txt new file mode 100644 index 0000000..ab4b9a5 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a3-07-cleanup.txt @@ -0,0 +1,9 @@ +DB +0 +LOG +none +CLUSTER +vendor_cluster_size{cache_manager="keycloak",node="keycloak-0-22712"} 2.0 +vendor_cluster_size{cache_manager="keycloak",node="keycloak-1-49037"} 2.0 +HTTP +200 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-00-baseline.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-00-baseline.txt new file mode 100644 index 0000000..4e3baa5 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-00-baseline.txt @@ -0,0 +1,28 @@ +URI +qemu:///system + +VMS + Id Name State +----------------------------- + 24 kc-lab-1 running + 25 kc-lab-edge running + 26 kc-lab-2 running + +NODES +NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME +kc-lab-1 Ready control-plane 24h v1.36.4+k3s1 192.168.122.11 Debian GNU/Linux 12 (bookworm) 6.1.0-53-cloud-amd64 (amd64) containerd://2.3.4-k3s1.36 +kc-lab-2 Ready 23h v1.36.4+k3s1 192.168.122.12 Debian GNU/Linux 12 (bookworm) 6.1.0-53-cloud-amd64 (amd64) containerd://2.3.4-k3s1.36 +LAB_PODS +NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES +keycloak-0 1/1 Running 0 2m46s 10.42.1.58 kc-lab-2 +keycloak-1 1/1 Running 0 3m20s 10.42.0.48 kc-lab-1 +postgres-7b474b88c8-rdxlv 1/1 Running 0 14m 10.42.1.56 kc-lab-2 +TRAEFIK +NAME READY UP-TO-DATE AVAILABLE AGE +traefik 1/1 1 1 24h +PVC +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE VOLUMEMODE +postgres-data Bound pvc-6ba2a481-a230-429b-8451-bd6c6b2bbd49 5Gi RWO local-path 23h Filesystem +PV +PV=pvc-6ba2a481-a230-429b-8451-bd6c6b2bbd49 +error: error parsing jsonpath nodeAffinity={.spec.nodeAffinity.required.nodeSelectorTerms[*].matchExpressions[*].values}{\n}, unrecognized character in action: U+005C '\' diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-01-worker-loss.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-01-worker-loss.txt new file mode 100644 index 0000000..aaf57b4 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-01-worker-loss.txt @@ -0,0 +1,136 @@ +A4_4A_BEGIN 2026-09-22T16:42:07+09:00 +BASE_VM=running +NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME +kc-lab-1 Ready control-plane 24h v1.36.4+k3s1 192.168.122.11 Debian GNU/Linux 12 (bookworm) 6.1.0-53-cloud-amd64 (amd64) containerd://2.3.4-k3s1.36 +kc-lab-2 Ready 23h v1.36.4+k3s1 192.168.122.12 Debian GNU/Linux 12 (bookworm) 6.1.0-53-cloud-amd64 (amd64) containerd://2.3.4-k3s1.36 +NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES +keycloak-0 1/1 Running 0 3m51s 10.42.1.58 kc-lab-2 +keycloak-1 1/1 Running 0 4m25s 10.42.0.48 kc-lab-1 +postgres-7b474b88c8-rdxlv 1/1 Running 0 15m 10.42.1.56 kc-lab-2 +BASE_AUTH=200 +DESTROY_AT=2026-09-22T16:42:07+09:00 +Domain 'kc-lab-2' destroyed + +VM_AFTER_DESTROY=shut off +SAMPLE i=0 at=2026-09-22T16:42:07+09:00 +kc-lab-2 True +keycloak-0 true Running kc-lab-2 +keycloak-1 true Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=000 +SAMPLE i=1 at=2026-09-22T16:42:42+09:00 +kc-lab-2 True +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=000 +SAMPLE i=2 at=2026-09-22T16:43:17+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=3 at=2026-09-22T16:43:51+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=4 at=2026-09-22T16:44:24+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=5 at=2026-09-22T16:44:58+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=6 at=2026-09-22T16:45:32+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=7 at=2026-09-22T16:46:05+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=8 at=2026-09-22T16:46:38+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=9 at=2026-09-22T16:47:11+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=10 at=2026-09-22T16:47:45+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 +AUTH=502 +SAMPLE i=11 at=2026-09-22T16:48:18+09:00 +kc-lab-2 Unknown node.kubernetes.io/unreachable,node.kubernetes.io/unreachable +keycloak-0 true Running kc-lab-2 2026-09-22T07:46:54Z +keycloak-1 false Running kc-lab-1 +postgres-7b474b88c8-rdxlv true Running kc-lab-2 2026-09-22T07:46:54Z +postgres-7b474b88c8-vxpvn Pending +AUTH=503 +AFTER_5MIN +NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR +postgres 0/1 1 0 23h postgres postgres:16-alpine app=postgres +NAME READY AGE CONTAINERS IMAGES +keycloak 0/2 23h keycloak quay.io/keycloak/keycloak:26.7.0 +keycloak-0 1/1 Terminating 0 10m 10.42.1.58 kc-lab-2 +keycloak-1 0/1 Running 0 10m 10.42.0.48 kc-lab-1 +postgres-7b474b88c8-rdxlv 1/1 Terminating 0 21m 10.42.1.56 kc-lab-2 +postgres-7b474b88c8-vxpvn 0/1 Pending 0 25s +[{"effect":"NoSchedule","key":"node.kubernetes.io/unreachable","timeAdded":"2026-09-22T07:41:23Z"},{"effect":"NoExecute","key":"node.kubernetes.io/unreachable","timeAdded":"2026-09-22T07:41:23Z"}] +PV=pvc-6ba2a481-a230-429b-8451-bd6c6b2bbd49 +kc-lab-2 +RESTORE_AT=2026-09-22T16:48:18+09:00 +Domain 'kc-lab-2' started + +VM_AFTER_START=running +RECOVERY i=1 node=Unknown k0=true k1=false pg=true auth=503 +RECOVERY i=2 node=Unknown k0=true k1=false pg=true auth=503 +RECOVERY i=3 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=4 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=5 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=6 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=7 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=8 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=9 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=10 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=11 node=True k0=false k1=false pg=false auth=503 +RECOVERY i=12 node=True k0=false k1=false pg=true auth=503 +RECOVERY i=13 node=True k0=false k1=true pg=true auth=200 +RECOVERY i=14 node=True k0=false k1=true pg=true auth=200 +RECOVERY i=15 node=True k0=false k1=true pg=true auth=200 +RECOVERY i=16 node=True k0=true k1=true pg=true auth=200 +RECOVERY_CONFIRMED +FINAL + Id Name State +----------------------------- + 24 kc-lab-1 running + 25 kc-lab-edge running + 27 kc-lab-2 running + +NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME +kc-lab-1 Ready control-plane 24h v1.36.4+k3s1 192.168.122.11 Debian GNU/Linux 12 (bookworm) 6.1.0-53-cloud-amd64 (amd64) containerd://2.3.4-k3s1.36 +kc-lab-2 Ready 23h v1.36.4+k3s1 192.168.122.12 Debian GNU/Linux 12 (bookworm) 6.1.0-53-cloud-amd64 (amd64) containerd://2.3.4-k3s1.36 +NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES +keycloak-0 1/1 Running 1 (118s ago) 2m22s 10.42.1.61 kc-lab-2 +keycloak-1 1/1 Running 0 13m 10.42.0.48 kc-lab-1 +postgres-7b474b88c8-vxpvn 1/1 Running 0 3m1s 10.42.1.60 kc-lab-2 +FINAL_AUTH=200 +A4_4A_CONFIRMED diff --git a/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a2-database-loss.md b/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a2-database-loss.md index 1445355..b5fdcdc 100644 --- a/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a2-database-loss.md +++ b/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a2-database-loss.md @@ -403,6 +403,8 @@ kubectl -n keycloak-lab get pods -o "custom-columns=NAME:.metadata.name,READY:.s 약 50초 뒤 ready false,false · 엔드포인트 false,false · 정문 503 ``` +2026-09-22 현재 실험대에서 다시 5초 간격으로 재보니 DB 파드가 사라진 뒤 약 20초까지는 `ready=true,true / 외부 200`이었고, 약 25초 시점에 한 파드가 먼저 `false`, 약 30초 시점에 `false,false / 외부 503`으로 바뀌었다. 따라서 `50초`를 고정된 장애 전환 시간으로 읽지 않는다. 실제 전환 시각은 readiness probe 주기와 실패 누적 시점에 따라 달라진다. 원본은 `final/evidence/raw/2026-09-22-test-server-revalidation/a2-11-readiness-timeline.txt`다. + **그 50초 사이의 화면을 보고 「DB 가 없어도 멀쩡하다」로 읽지 않는다.** 이미 500 인데 아직 트래픽에서 안 빠졌을 뿐이다. 이 편이 잡으려는 것도 그 어긋남이다 — 되는 것과 Ready 인 것은 다르다. `READY=false`인데 `RESTARTS`가 주입 전보다 늘지 않았다면 프로세스는 살아 있고 트래픽에서만 빠진 것이다. 2026-09-22에는 두 파드가 `false`, restart count는 둘 다 그대로 `0`이었다. restart count가 증가하면 DB 장애 외에 컨테이너 재시작이 섞인 것이므로 별도로 기록한다. @@ -441,6 +443,8 @@ curl -s -o /dev/null -w '④ %{http_code}\n' --max-time 10 -H "Authorization: Be 2026-09-22 수정 재검증에서도 네 경로가 모두 `500`이었다. 이 회차는 ②를 실제 cross-node/no-local-cache 경로로 바로잡고 다시 실행한 결과다. 원본은 `final/evidence/raw/2026-09-22-test-server-revalidation/a2-07-corrected-control-refreshes.txt`, `a2-08-corrected-control-four-paths.txt`, `a2-09-corrected-outage-and-recovery.txt`에 남겼다. +같은 날 현재 lab에서 독립적으로 다시 실행한 원자 재검증에서도 두 Keycloak 모두 `refresh=500`, `login=500`, `admin=500`, `JWKS=200`, `well-known=200`이었고 PostgreSQL 복구 뒤 Keycloak 재시작 없이 양쪽 Ready와 외부 `200`이 돌아왔다. 세션 행 수와 restart count도 주입 전후 `2 → 2`, `0,0 → 0,0`으로 유지됐다. 원본은 `a2-10-atomic-revalidation.txt`다. + 본문도 한 번 그대로 본다. ```sh label="[탐침 파드] 500 의 본문을 본다" diff --git a/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a3-database-crash.md b/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a3-database-crash.md index 88c465b..3b31e09 100644 --- a/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a3-database-crash.md +++ b/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a3-database-crash.md @@ -601,7 +601,7 @@ wc -l /tmp/db-sids.txt 실측은 `DB 전체 온라인 세션 : 150 건` 이다(observed). `psql` 의 두 얼굴을 가른다 — `-c` 는 표를 그려서 사람이 읽기 좋고 `-tAc` 는 값만 줘서 파이프에 넣기 좋으므로, 한 번은 `-c` 로 눈으로 보고 셀 때만 `-tAc` 를 쓴다. -차집합은 `comm` 으로 낸다. 정렬부터 한다 — 이 세 줄은 미검증이다(unknown). +차집합은 `comm` 으로 낸다. 정렬부터 한다. 2026-09-22 재검증에서 이 세 줄을 실제로 실행해 클라이언트 SID와 DB SID의 차집합을 확인했다. ```bash label="[lab host] ④ 같은 정렬 순서로 맞춘 뒤 왼쪽 전용만 낸다" LC_ALL=C sort -u /tmp/client-sids.txt > /tmp/a.txt @@ -815,6 +815,7 @@ rm -f /tmp/client-sids.txt /tmp/db-sids.txt /tmp/a.txt /tmp/b.txt /tmp/a3-login- | `a3-probe` 를 다시 못 만든다 | 옛 파드가 `Completed` 로 남아 있다 | `delete pod a3-probe --ignore-not-found` | | `pgrep` 이 아무것도 못 찾는다 | Keycloak 이 아직 연결을 안 만들었다 | `ps -ef` 로 먼저 본다 | | 손실 건수를 시간으로 환산했더니 문서와 다르다 | **원래 문서가 속도를 잘못 썼다가 정정했다** | 초당 14건이 실측이다 | +| `for D in $delays`가 한 번만 돌고 `sleep: invalid time interval`이 난다 | **zsh는 Bash처럼 scalar를 공백으로 자동 분리하지 않는다** | 반복 실험은 `bash`로 실행하거나 Bash 배열을 쓴다 | ## 무엇이 관측이고 무엇이 아닌가 @@ -825,6 +826,7 @@ rm -f /tmp/client-sids.txt /tmp/db-sids.txt /tmp/a.txt /tmp/b.txt /tmp/a3-login- - (observed) `offline_user_session` 의 시각 컬럼이 `integer`, 로그인 트랜잭션에도 붙은 `SET LOCAL synchronous_commit TO OFF`, WAL 설정 네 줄(`wal_writer_delay 200 ms default` 포함), 시도 ①·②·③ 의 시각 `12:00:26.511`·`12:03:21.441`·`12:04:22.063`, crash recovery 로그 여섯 줄, `153 / 149 / 4`, 유실 sid 네 개, 초당 14건, `DELETE 375`, 비밀번호 길이 `19`. - (observed, 2026-09-22) 재검증에서는 backend PID 하나를 골라 `kubectl ... exec deploy/postgres -- kill -9 ` 형태로 SIGKILL 했고 실제 crash recovery가 돌았다. 성공 응답 SID `504`, 복구 후 DB SID `500`, `LC_ALL=C sort` + `comm -23` 으로 유실 `4`건을 다시 확인했다. 증거는 `final/evidence/raw/2026-09-22-test-server-revalidation/a3-05-load-console.txt`, `a3-06-backend-kill.txt`, `a3-07-client-sids.sorted.txt`, `a3-08-db-sids.sorted.txt`, `a3-09-lost-sids.txt`다. - (observed, 2026-09-22) 로그인 루프를 foreground `kubectl exec` 세션으로 유지하는 방식이 실제로 동작했고, `curlimages/curl:8.11.1` 에 `/bin/tar` 가 있어 `kubectl cp` 를 사용할 수 있다. +- (observed, 2026-09-22, 독립 재검증) 고부하 루프와 별도로 한 로그인과 backend SIGKILL의 타이밍을 겹쳐 재봤다. 4번째 회차(`delay=1.00s`)에서 클라이언트가 SID `MH7o1pr5R8Yv6-y4dAnL9lCv`를 받은 뒤 crash recovery가 수행됐고, 복구 후 해당 SID의 DB 행은 `0`이었다. PostgreSQL Pod restart count는 계속 `0`이었다. 전체 증거는 `final/evidence/raw/2026-09-22-test-server-revalidation/a3-06-race-window-bash.txt`다. 이 값의 `1.00s`는 환경별 타이밍일 뿐 고정 손실 창으로 일반화하지 않는다. - (unknown) 게스트 노드에서 컨테이너의 host PID 를 찾아 직접 죽이는 (b) 갈래는 이번 재검증에서도 실행하지 않았다. - 이 실험이 두 번 틀렸다가 고친 것 — 「`--force` 로 죽였다」와 「`kill -9 1` 로 죽였다」가 둘 다 유실 0건이라는 깨끗한 결과를 냈다. 주입 성공 신호를 미리 정해 두지 않았다면 결론은 「Keycloak 은 DB 크래시에도 데이터를 잃지 않는다」가 됐을 것이다. - 추정이었다가 나중에 잰 값 — `wal_writer_delay` 200ms. 원래 문서는 결과를 먼저 쓰고 그 값과 맞는다고 주장했는데 그때는 조회한 적이 없었고, 로그인 속도도 초당 19건으로 잘못 적었다가 14건으로 정정했다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap2-split-custody.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap2-split-custody.md index c427c4d..aebaf5c 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap2-split-custody.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap2-split-custody.md @@ -2,7 +2,7 @@ id: 488ce49b-afa4-42a5-a2ce-de2e0653cd82 kind: CASE slug: split-custody-access-token -title: Refresh Token 관리만 서버로 이전, Access Token은 여전히 Browser에 노출 +title: Mediator에서는 Refresh Token만 서버에 남고 Access Token은 브라우저로 돌아온다 topic: oauth-oidc-auth-boundary topicName: OAuth/OIDC 인증 경계 project: KeyCloak Patterns @@ -25,11 +25,11 @@ source: - final/document.md#얻은-것-잃은-것-적용하지-않을-때-ap2 --- -# Refresh Token 관리만 서버로 이전, Access Token은 여전히 Browser에 노출 +# Mediator에서는 Refresh Token만 서버에 남고 Access Token은 브라우저로 돌아온다 -confidential client인 mediator가 authorization code를 교환하고, 받은 두 토큰을 서버 쪽 authorized client에 넣는다. 그런데 보호 자원 서버(Resource Server)를 부르는 쪽은 브라우저라서 액세스 토큰이 브라우저에도 있어야 하고, 그 값은 JSON 응답으로 다시 내려온다. 그래서 이 구조가 브라우저 밖으로 옮긴 것은 client secret과 리프레시 토큰까지이고, 액세스 토큰을 다루는 일은 브라우저가 계속 한다. +Mediator가 authorization code를 교환하고 access token과 refresh token을 서버의 Authorized Client에 저장한다. 다만 Resource Server를 직접 호출하는 쪽은 브라우저이므로 access token은 다시 브라우저로 내려간다. client secret과 refresh token은 서버에 남고, access token은 브라우저 JavaScript가 계속 사용한다. -## 관계 +## Mediator에서 토큰을 나누어 보관하는 이유 - **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계** SPA에서는 브라우저가 코드 교환과 토큰 보관을 모두 맡는데, 여기서는 그중 리프레시 토큰을 서버로 옮겼다. @@ -42,7 +42,7 @@ confidential client인 mediator가 authorization code를 교환하고, 받은 - **Refresh Token Rotation과 다중 Replica 경쟁을 어떻게 처리할 것인가** 여기서는 리프레시 토큰 rotation과 재사용 0회로 설정했다. 여러 replica에서 갱신이 겹치는 경우는 이 구성으로 확인하지 못해 그 질문에서 따로 다룬다. -## 문제 +## Refresh Token만 서버에 둬도 Access Token은 브라우저에 남는다 Spring mediator가 confidential client가 되어 code를 교환한다. 받은 액세스 토큰과 리프레시 토큰은 server-side authorized-client service에 저장하고, 브라우저가 로그인 상태로 들고 있는 것은 HttpOnly가 붙은 AP2_SESSION뿐이다. @@ -50,7 +50,7 @@ Spring mediator가 confidential client가 되어 code를 교환한다. 받은 /token/access 응답부터 보호 자원 서버 요청까지 따라가면 서버가 가져간 것은 리프레시 토큰까지였고 액세스 토큰을 다루는 일은 브라우저가 계속 하고 있었다. -## 결론 +## AP2는 토큰 보관 경계를 둘로 나눈다 서버로 옮긴 것은 client secret과 리프레시 토큰이다. 액세스 토큰은 브라우저에서 다음 세 곳을 지나간다. @@ -62,7 +62,7 @@ JavaScript 지역 변수 : o 서버 상태 : mediator의 session과 authorized-client 저장소를 운영해야 한다. 브라우저 노출 : 액세스 토큰이 브라우저 실행 영역 안에서 쓰이는 것은 막지 못했다. -## 검증 환경 +## AP2를 확인한 실행 환경 Keycloak 26.7.0 @@ -87,7 +87,7 @@ header : Authorization, Content-Type HTTPS : x HTTP : o -## 재현 조건 +## 같은 흐름을 다시 확인하려면 1. Mediator UI에서 로그인한 뒤 /token/boundary를 호출한다. @@ -109,7 +109,7 @@ HTTP : o 7. Local Storage와 Session Storage에 액세스 토큰 원문이나 refresh_token 문자열이 없는지 확인한다. -## 본문 +## Mediator가 code를 교환한 뒤 일어나는 일 @@ -246,7 +246,7 @@ mediator를 넣은 이유는 하나다. 리프레시 토큰은 브라우저 Java - 서버 상태 : mediator의 HttpSession과 authorized-client 저장소를 운영해야 한다 - 브라우저 노출 : 액세스 토큰이 응답 본문과 `Authorization` 헤더를 지나가는 것은 막지 못했다 -브라우저가 보호 자원 서버를 직접 불러야 한다는 요구가 분명하면 이 구조를 고를 수 있다. 이 구조는 두 구조의 비용을 함께 갖는다 — mediator 상태를 확장하고 복구해야 하는데 액세스 토큰은 여전히 XSS에 노출된다. 브라우저에서 액세스 토큰까지 없애야 한다면 이 구조로는 답이 되지 않고, 서버 상태 자체를 둘 수 없다면 SPA 구성이 더 단순하다. +브라우저가 Resource Server를 직접 호출해야 한다면 이 구조를 선택할 수 있다. 다만 Mediator의 서버 상태를 운영하면서도 access token은 브라우저 JavaScript에 남는다. 브라우저에서 access token까지 없애야 한다면 BFF가 더 맞고, 서버 상태를 두지 않으려면 SPA가 더 단순하다. ## 현재 자동 테스트로 확인한 범위 diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap3-bff-session-csrf.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap3-bff-session-csrf.md index 3e7bc22..66491b3 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap3-bff-session-csrf.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap3-bff-session-csrf.md @@ -2,7 +2,7 @@ id: d85bd6af-7599-4ef7-9407-6609927d5b5c kind: CASE slug: bff-session-csrf-responsibility -title: BFF에서 Browser Token을 제거하고 Session과 CSRF를 처리한 방식 +title: BFF에서 OAuth Token을 브라우저 밖으로 옮기고 Session과 CSRF를 처리한 방식 topic: oauth-oidc-auth-boundary topicName: OAuth/OIDC 인증 경계 project: KeyCloak Patterns @@ -27,11 +27,11 @@ source: - final/document.md#얻은-것-잃은-것-적용하지-않을-때-ap3 --- -# BFF에서 Browser Token을 제거하고 Session과 CSRF를 처리한 방식 +# BFF에서 OAuth Token을 브라우저 밖으로 옮기고 Session과 CSRF를 처리한 방식 BFF 구조에서는 브라우저가 access token도 refresh token도 받지 않는다. confidential client인 BFF 서버가 code를 교환해 두 토큰을 server-side authorized client에 넣어 두고, 로그인이 끝난 브라우저는 HttpOnly가 붙은 AP3_SESSION 쿠키 하나로 BFF를 부른다. -## 관계 +## BFF가 브라우저 대신 OAuth 토큰을 보관한다 - **BFF 인증 구조 설계 기준** 그 기준이 함께 설계하라고 적은 항목 가운데 지금 구현에 들어가 있는 것은 CSRF 검증 하나이고, 나머지는 아직 없다. @@ -46,7 +46,7 @@ BFF 구조에서는 브라우저가 access token도 refresh token도 받지 않 - **BFF의 Session과 OAuth2AuthorizedClient를 어디에 저장할 것인가** HttpSession은 session ID로 찾고 authorized client는 client registration 이름과 principal name으로 찾아서, 두 상태를 꼭 같은 저장소에 둬야 하는 것은 아니다. -## 문제 +## 브라우저 토큰을 없애도 세션과 CSRF 책임은 남는다 브라우저에 OAuth token을 두지 않으려면 code 교환과 token 보관을 서버가 맡아야 한다. BFF 구조에서는 confidential client인 BFF 서버가 code를 교환하고, access token과 refresh token을 server-side authorized client에 넣는다. 브라우저가 받는 것은 HttpOnly가 붙은 AP3_SESSION 쿠키다. @@ -54,7 +54,7 @@ BFF 구조에서는 브라우저가 access token도 refresh token도 받지 않 서버가 들고 있게 된 상태에도 둘 곳이 필요하다. 지금 session과 authorized client는 모두 memory에 있어서, BFF를 재시작하거나 요청이 다른 replica로 가는 경우까지 처리하려면 이 상태를 어디에 저장할지 따로 정해야 한다. -## 결론 +## 브라우저는 세션 쿠키와 CSRF 토큰으로 BFF를 호출한다 브라우저가 들고 있는 자격 증명은 cookie 2개다. @@ -75,7 +75,7 @@ downstream 오류 변환 : x timeout : x 경로별 인가 : x -## 검증 환경 +## AP3를 확인한 실행 환경 Keycloak 26.7.0 @@ -88,7 +88,7 @@ store : memory CSRF : o HTTP : o -## 재현 조건 +## BFF 경계를 다시 확인하는 조건 1. UI에서 로그인하고 authorization request를 확인한다. @@ -116,7 +116,7 @@ HTTP : o 9. 127.0.0.1에서 localhost로 보내는 cross-site POST에서 AP3_SESSION이 요청에 실리지 않는지 확인한다. -## 본문 +## 로그인 뒤 브라우저와 BFF가 나누어 맡는 일 BFF(Backend For Frontend)는 화면에 필요한 API를 브라우저 대신 호출하고 결과만 돌려주는 서버이고, 여기서는 로그인과 토큰 보관까지 이 서버가 맡는다. 브라우저에서 OAuth 토큰을 걷어내면 브라우저가 무엇을 들고 있게 되고 서버는 무엇을 더 맡게 되는지 확인했다. 그다음 상태를 바꾸는 요청에서 새로 필요해진 검사와 아직 구현하지 않은 항목을 적는다. @@ -206,7 +206,7 @@ external observation 브라우저 network → token endpoint 없음 앞의 것은 서버가 자기 상태를 스스로 보고한 값이고 뒤의 것은 브라우저에서 관찰한 값이다. 이 엔드포인트는 `OAuth2AuthorizedClientManager.authorize()`를 부르지 않고 `OAuth2AuthorizedClientService`에서 저장된 항목을 직접 조회한다. 그래서 여기를 호출하는 것만으로 액세스 토큰이 갱신되지는 않고, 인증된 세션인데 그 항목이 없으면 서버 보관 여부를 알리는 값 2개가 false인 200이 나올 수도 있다. 어느 경우에도 토큰 원문은 이 응답에 들어가지 않는다. -## 쿠키가 자동으로 붙는 요청을 CSRF 토큰으로 가른다 +## 쿠키 인증 요청에는 CSRF 토큰을 함께 검증한다 브라우저는 BFF로 가는 요청마다 세션 쿠키를 자동으로 붙이고 상태를 바꾸는 POST에서도 마찬가지라서, 세션 쿠키만 확인해서는 그 요청이 사용자가 보던 화면에서 시작한 것인지 알 수 없다. CSRF(Cross-Site Request Forgery) 토큰은 그 요청을 받아들일지 서버가 판단하려고 상태 변경 요청에서만 따로 대조하는 값이다. @@ -291,7 +291,7 @@ CSRF 검증을 눈으로 보려고 둔 `theme` 값도 사용자별 저장소에 ### 커밋된 테스트가 확인하도록 정의한 17개 -이 기록에서 확인했다고 적은 것은 마지막 실행 결과가 아니라 커밋된 자동 테스트가 확인하도록 정의한 계약이다. 항목은 17개이고 그중 10개를 확인했다. +자동 테스트에는 BFF 경계를 확인하는 17개 조건이 정의돼 있고, 현재 그중 10개가 구현과 함께 확인돼 있다. 나머지 조건은 실제 동작을 확인하기 전까지 완료로 보지 않는다. 인가 요청에는 `bff-confidential` 클라이언트와 `S256` challenge가 있어야 하고, 로그인 뒤 브라우저 요청 목록에는 Keycloak 토큰 엔드포인트 호출과 8081 직접 호출이 없어야 한다. 쿠키는 `AP3_SESSION`이고 `HttpOnly`와 `SameSite=Lax`가 붙어 있어야 하며 Web Storage는 비어 있어야 한다. `/bff/token-boundary`의 서버 보관 값 2개는 true여야 하고 `/bff/api/me`는 200과 함께 `username`과 기대한 audience를 돌려줘야 한다. CSRF 헤더가 없는 POST는 403, 쿠키에서 읽은 값을 헤더에 넣은 POST는 200, cross-site POST에서는 쿠키가 빠져야 한다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap4-identity-header-trust.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap4-identity-header-trust.md index 61de03c..c412556 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap4-identity-header-trust.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-ap4-identity-header-trust.md @@ -29,7 +29,7 @@ source: 앞단에 세운 프록시가 로그인을 대신 받으면, 업스트림은 요청에 붙어 온 X-Auth-Request-User 헤더 하나만 보고 누가 보낸 요청인지 정한다. 이 헤더는 인증을 마친 프록시가 붙일 수도 있고 브라우저가 직접 적어 보낼 수도 있는데, 업스트림에 도착한 요청만으로는 둘을 가려낼 수 없다. -## 관계 +## Forward-Auth는 신원 정보를 헤더로 전달한다 - **Forward-Auth에서 Identity Header를 신뢰하기 위한 조건** 그 기준이 세운 다섯 조건이 Nginx 설정과 업스트림 코드의 어디에 들어가 있는지 하나씩 확인했다. @@ -40,7 +40,7 @@ source: - **Forward-Auth 구조에서 Application Authorization을 어디까지 Edge에 둘 것인가** 지금 엣지는 사용자와 이메일만 넘기고 role은 넘기지 않는데, 그러면 인가를 어디서 판단할지 정해야 한다. -## 문제 +## 같은 이름의 헤더를 클라이언트도 만들 수 있다 앞단 프록시가 로그인을 맡으면 업스트림은 OAuth를 몰라도 되고, 대신 요청에 붙어 온 X-Auth-Request-User 하나로 사용자를 판단한다. 그러려면 업스트림은 이 헤더를 인증을 마친 엣지가 붙였는지 브라우저가 직접 적어 넣었는지 가릴 수 있어야 한다. @@ -48,7 +48,7 @@ source: 그래서 백엔드 포트가 외부에 열려 있거나 Nginx가 브라우저의 동명 헤더를 그대로 넘기면, 공격자가 원하는 이름을 적어 인증된 사용자처럼 요청을 보낼 수 있다. -## 결론 +## 프록시 경계에서 identity header를 다시 만든다 헤더를 인증 근거로 쓰려면 세 곳에서 막아야 한다. @@ -60,7 +60,7 @@ Nginx 헤더 덮어쓰기 : 클라이언트가 보낸 동명 헤더를 합치지 이렇게 네트워크를 나눠 두는 것만으로는 내부 서비스가 보낸 요청도, Nginx가 잘못 넘긴 헤더도 걸러 내지 못한다. 공유 토큰만 두고 포트를 열어 두면, 그 토큰을 얻은 쪽이 Nginx를 건너뛰고 업스트림에 바로 붙을 수 있다. -## 검증 환경 +## AP4를 확인한 실행 환경 Keycloak 26.7.0, oauth2-proxy 7.15.2 @@ -96,7 +96,7 @@ login, token, JWKS, userinfo URL : 각각 따로 관리 HTTP : o -## 재현 조건 +## spoofed header를 다시 확인하는 조건 1. 쿠키 없이 GET /를 부르면 /oauth2/start로 302가 되는지 확인한다. @@ -122,7 +122,7 @@ X-Internal-Auth-Token : attacker-controlled-token 8. 내부에서 /edge/me를 부를 때 사용자 정보 헤더만 있거나 내부 토큰이 없거나 틀리면 401이고, 둘 다 맞으면 200인지 확인한다. -## 본문 +## 인증 프록시가 신원 헤더를 만드는 과정 forward-auth는 실제 요청을 업스트림으로 넘기기 전에 별도의 인증 엔드포인트에 허용 여부를 묻는 방식이고, Nginx에서는 `auth_request` 디렉티브가 그 질문을 하위 요청(subrequest)으로 만든다. @@ -151,7 +151,7 @@ X-Internal-Auth-Token: attacker-controlled-token 세션 자체는 유효해서 이 요청이 200으로 처리되는 것은 정상이다. 볼 값은 응답의 `user`이고, 여기에 `spoofed-admin`이 아니라 실제로 인증된 사용자가 들어 있어야 이 검사를 통과한다. 「로그인이 성공한다」를 성공 기준으로 삼으면 이 경계는 재지 못한다. 위조 헤더가 통과해도 정상 사용자는 자기 이름을 보기 때문이다. -## 세 곳에서 나눠 막는다 +## 클라이언트 헤더를 제거하고 프록시가 값을 다시 만든다 ![브라우저, Nginx, oauth2-proxy, Spring upstream 사이에서 AP4_SESSION 검증, identity header 덮어쓰기, internal token 검증과 JSON 응답이 이어지는 순서도.](../../../final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.svg) @@ -290,7 +290,7 @@ issuer는 요청을 보내기 위한 주소가 아니라 Keycloak이 발급한 ### 커밋된 테스트가 확인하도록 정의한 계약 -이 기록에서 확인했다고 적은 것은 마지막 실행 성적표가 아니다. +여기서 확인된 항목은 자동 테스트와 현재 구성으로 재현 가능한 조건만 포함한다. 쿠키 없는 `/`는 302를 받고 쿠키 없는 `/api/edge`는 401을 받는다. authorization request에는 `edge-proxy` 클라이언트와 PKCE(Proof Key for Code Exchange) S256 challenge가 들어 있어야 한다. 로그인 뒤 쿠키는 `AP4_SESSION`이고 `HttpOnly`와 `SameSite=Lax`가 붙어 있어야 한다. 브라우저 요청 목록에는 Keycloak 토큰 엔드포인트가 없어야 하고, Web Storage는 비어 있어야 하며 `document.cookie`로는 세션 쿠키를 읽을 수 없어야 한다. 위조 헤더를 얹은 요청은 실제 사용자로 200을 받고, 외부에서 부른 `/oauth2/auth`는 404, 호스트의 4180과 8081은 접근 불가여야 한다. 사용자 정보 헤더가 없거나 내부 토큰이 없거나 틀리면 401이다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-browser-credential-boundary.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-browser-credential-boundary.md index 4649f73..398809a 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-browser-credential-boundary.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/case/case-browser-credential-boundary.md @@ -2,7 +2,7 @@ id: bf675775-4f3e-4744-8014-f0efff51422a kind: CASE slug: spa-browser-credential-boundary -title: SPA에서 OAuth Token을 JavaScript Memory에 보관한 경우 +title: SPA에서 OAuth Token을 JavaScript 메모리에만 보관한 방식 topic: oauth-oidc-auth-boundary topicName: OAuth/OIDC 인증 경계 project: KeyCloak Patterns @@ -25,11 +25,11 @@ source: - final/document.md#얻은-것-잃은-것-적용하지-않을-때-ap1 --- -# SPA에서 OAuth Token을 JavaScript Memory에 보관한 경우 +# SPA에서 OAuth Token을 JavaScript 메모리에만 보관한 방식 AP1에서는 SPA(Single Page Application)를 public OAuth client로 구성하고 authorization code도 브라우저에서 직접 교환한다. 발급받은 액세스 토큰, 리프레시 토큰, ID 토큰은 Web Storage에 저장하지 않고 JavaScript 메모리에만 둔다. -## 관계 +## SPA에서는 브라우저가 OAuth client가 된다 - **Authorization Code Flow의 Endpoint와 Credential 이동 기준** SPA에서 authorization request를 보내고 authorization code를 받은 뒤 토큰을 교환하는 과정을 직접 확인한 내용이다. @@ -38,7 +38,7 @@ AP1에서는 SPA(Single Page Application)를 public OAuth client로 구성하고 - **OAuth Token과 Application Session을 구분하는 기준** JavaScript 메모리에 있는 토큰과 Keycloak의 SSO 쿠키는 서로 다른 상태여서, 새로고침으로 SPA의 토큰이 없어져도 Keycloak의 SSO까지 끝나는 것은 아니다. -## 문제 +## 발급된 토큰을 브라우저가 직접 보관한다 AP1에서는 토큰을 Local Storage나 Session Storage에 저장하지 않고 JavaScript 메모리에만 둔다. @@ -46,7 +46,7 @@ AP1에서는 토큰을 Local Storage나 Session Storage에 저장하지 않고 J 그래서 SPA가 authorization code를 직접 교환한 뒤 토큰을 어디에 들고 있는지, API를 부를 때 액세스 토큰이 어느 곳을 지나는지 따라갔다. PKCE가 실제로 어느 구간에 적용되는지도 같이 봤다. -## 결론 +## Web Storage 대신 JavaScript 메모리만 사용한다 memory-only로 보관하면 새로고침 뒤에는 액세스·리프레시·ID 토큰이 모두 사라진다. @@ -58,7 +58,7 @@ Resource Server는 SessionCreationPolicy.STATELESS로 동작해 서버에서 지 PKCE는 authorization code를 토큰으로 교환하는 구간에 쓰는 것이지, 이미 발급된 액세스 토큰을 브라우저에서 숨겨 주는 기능은 아니다. -## 검증 환경 +## AP1을 확인한 실행 환경 Keycloak 26.7.0 @@ -80,7 +80,7 @@ CORS allowlist : localhost:8088, 127.0.0.1:8088, GET·OPTIONS, Authorization·Co HTTPS : x HTTP : o -## 재현 조건 +## 새로고침 전후 토큰 상태를 다시 확인하는 조건 1. SPA를 열고 로그인한 뒤 Keycloak authorization request에서 response_type=code, code_challenge_method=S256, 비어 있지 않은 code_challenge를 확인한다. @@ -94,7 +94,7 @@ HTTP : o 6. 리프레시 토큰으로 새 토큰을 받은 뒤 이전 리프레시 토큰이 거부되는지 확인한다. revocation 뒤에는 갱신이 실패하는지, 이미 발급된 access JWT는 만료 전까지 200을 받는지도 확인한다. -## 본문 +## SPA에서 code 교환부터 API 호출까지 @@ -162,7 +162,7 @@ issuer·audience : 검증 PKCE(Proof Key for Code Exchange)를 쓰면 authorization request에는 `code_challenge`가 들어가고, authorization code를 토큰으로 교환할 때는 원본인 `code_verifier`를 함께 보낸다. 두 값이 맞아야 code를 교환할 수 있다. -```text label="oidc-client-ts가 만드는 authorization request의 핵심 query" +```text label="oidc-client-ts가 만드는 authorization request의 주요 query parameter" response_type=code client_id=spa-public redirect_uri=http://localhost:8088/callback.html diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-authorization-code-and-pkce.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-authorization-code-and-pkce.md index d9a6230..b129785 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-authorization-code-and-pkce.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-authorization-code-and-pkce.md @@ -22,7 +22,7 @@ source: authorization code는 로그인을 마친 사용자가 애플리케이션으로 돌아올 때 잠시 들고 오는 교환용 값이다. 이 code를 액세스 토큰으로 바꾸는 구간을 PKCE가 보호한다. authorization request에는 code_challenge를 담아 보내고, token request에는 그 원본인 code_verifier를 보내 두 값이 대응하는지 확인한다. 두 값이 맞아야 교환이 끝난다. -## 관계 +## Authorization Code Flow에서 PKCE가 들어가는 위치 - **Authorization Code Flow의 Endpoint와 Credential 이동 기준** 이 개념을 endpoint별 기준으로 정리한 기록이다. @@ -31,7 +31,7 @@ authorization code는 로그인을 마친 사용자가 애플리케이션으로 - **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계** 브라우저가 code를 직접 교환한 구성이다. -## 본문 +## code와 verifier가 교환되는 순서 @@ -45,7 +45,7 @@ PKCE 값이 어디서 만들어져 어디서 확인되는지, 두 요청을 순 ## authorization request에 들어가는 challenge -oidc-client-ts가 만드는 요청의 핵심 모양은 다음과 같다. +oidc-client-ts가 만드는 authorization request의 주요 query parameter는 다음과 같다. ```http label="authorization request" GET http://localhost:8080/realms/keycloak-patterns/protocol/openid-connect/auth diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-bearer-jwt-validation-chain.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-bearer-jwt-validation-chain.md index 68c019d..3dd7f13 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-bearer-jwt-validation-chain.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-bearer-jwt-validation-chain.md @@ -21,9 +21,9 @@ source: # Bearer JWT가 인증된 principal이 되기까지 -Resource Server가 받는 입력은 `Authorization` 헤더에 실려 온 문자열 하나다. 이 문자열은 서명 검증, issuer와 시간 검증, audience 검증, 역할 변환을 차례로 지나야 인증된 요청 주체(principal)가 된다. OAuth 2.0과 JWT를 한 번이라도 다뤄 본 사람을 대상으로, 먼저 Resource Server가 받는 입력부터 이 사슬이 단계마다 무엇을 확인하고 무엇을 다음 단계로 넘기는지 따라간다. 서명 검증을 통과했다고 이 API를 위해 발급된 토큰인 것은 아니고, 그 확인은 audience 검증이 따로 맡는다. +Resource Server가 받는 입력은 `Authorization` 헤더에 실린 bearer token이다. 이 값은 서명 검증, issuer와 시간 검증, audience 검증, 역할 변환을 차례로 지나 인증된 principal이 된다. 서명 검증에 성공했다고 해서 그 토큰이 이 API를 대상으로 발급됐다는 뜻은 아니며, 그 조건은 audience 검증에서 따로 확인한다. -## 관계 +## Resource Server가 bearer token을 받는 위치 - **OAuth Token과 Application Session을 구분하는 기준** 이 검증을 통과한 JWT와 애플리케이션 세션은 다른 상태다. @@ -32,7 +32,7 @@ Resource Server가 받는 입력은 `Authorization` 헤더에 실려 온 문자 - **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계** 브라우저가 이 헤더를 직접 만든 구성이다. -## 본문 +## bearer token이 principal이 되기까지의 검증 순서 @@ -101,7 +101,7 @@ realm_access.roles: ["user-role"] Spring Security의 `hasRole("user-role")`이 `ROLE_user-role`이라는 이름의 권한을 찾기 때문에 이 접두사가 필요하다. -## 인증과 인가는 다른 endpoint에서 갈린다 +## 인증과 인가는 서로 다른 단계에서 확인한다 `/api/me`는 특정 역할을 요구하지 않고 `.authenticated()`만 요구한다. 그래서 역할 클레임이 없어 변환 결과가 빈 목록이어도, JWT가 유효하기만 하면 `/api/me`는 통과한다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-browser-credential-storage.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-browser-credential-storage.md index e6fddf0..bc930c1 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-browser-credential-storage.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-browser-credential-storage.md @@ -19,7 +19,7 @@ source: 브라우저에는 JavaScript 메모리, Session Storage, Local Storage, 쿠키가 있고 각각 수명과 접근 경로가 다르다. 자격 증명(credential)을 어디에 두느냐에 따라 새로고침 뒤에 무엇이 유지되는지, JavaScript가 무엇을 읽을 수 있는지, 어떤 값이 요청에 자동으로 실리는지가 갈린다. -## 관계 +## 토큰 보관 위치가 브라우저 인증 경계를 바꾼다 - **OAuth Token과 Application Session을 구분하는 기준** 여기 있는 값들을 어떤 이름으로 갈라 부르는지 정한 기록이다. @@ -28,7 +28,7 @@ source: - **BFF 인증 구조 설계 기준** 브라우저에 세션 쿠키만 두는 구조의 설계 항목이다. -## 본문 +## JavaScript 메모리와 Storage, Cookie의 차이 @@ -82,7 +82,7 @@ AP2에도 같은 구분이 필요하다. `/token/access` 응답의 access token `HttpOnly` 쿠키는 `document.cookie`로 조회되지 않지만, 브라우저는 요청마다 이 값을 자동으로 붙여 보낸다. -AP2의 `AP2_SESSION`, AP3의 `AP3_SESSION`, AP4의 `AP4_SESSION`이 모두 HttpOnly다. AP3와 AP4는 브라우저 JavaScript에 OAuth 토큰을 넘기지 않는다. 브라우저를 확인하면 HttpOnly 세션 쿠키가 남아 있고 요청할 때마다 자동으로 붙는다. 그래서 이 기록에서 「브라우저에 없다」는 말은 애플리케이션이 쓰는 OAuth 토큰에만 쓴다. 인증 상태 자체는 이 쿠키가 들고 있다. +AP2의 `AP2_SESSION`, AP3의 `AP3_SESSION`, AP4의 `AP4_SESSION`은 모두 HttpOnly 쿠키다. AP3와 AP4에서는 브라우저 JavaScript가 OAuth 토큰을 받지 않지만 인증 상태 자체는 세션 쿠키로 유지된다. 따라서 「브라우저에 토큰이 없다」는 표현은 OAuth access token과 refresh token이 JavaScript에 노출되지 않는다는 뜻으로 한정한다. Keycloak 도메인의 SSO 쿠키도 별도로 존재할 수 있다. 애플리케이션 메모리의 `User`가 사라진 것과 IdP(Identity Provider) 세션이 끝난 것은 다른 사건이다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-cookie-auth-csrf.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-cookie-auth-csrf.md index 6ce3681..8deed26 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-cookie-auth-csrf.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-cookie-auth-csrf.md @@ -22,7 +22,7 @@ source: 세션 쿠키는 브라우저가 요청마다 자동으로 붙이기 때문에, 상태를 바꾸는 요청에는 쿠키만으로 만든 cross-site forged request를 구분할 별도 검증 값이 필요하다. CSRF(Cross-Site Request Forgery, 사이트 간 요청 위조) 토큰은 예상한 anti-CSRF token이 함께 온 요청인지 검사하고, SameSite는 브라우저가 쿠키를 언제 보낼지 정하는 별도의 정책이다. -## 관계 +## 세션 쿠키를 쓰면 CSRF 검증이 필요하다 - **BFF 인증 구조 설계 기준** 이 확인이 필요한 구조의 설계 항목이다. @@ -31,7 +31,7 @@ source: - **OAuth Token과 Application Session을 구분하는 기준** 세션 쿠키와 CSRF 토큰은 서로 다른 값이다. -## 본문 +## 쿠키와 CSRF token이 함께 검증되는 과정 diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-forward-auth-and-auth-request.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-forward-auth-and-auth-request.md index 76b737d..a777d7a 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-forward-auth-and-auth-request.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-forward-auth-and-auth-request.md @@ -22,7 +22,7 @@ source: forward-auth는 실제 요청을 업스트림으로 넘기기 전에 별도의 인증 엔드포인트에 허용 여부를 먼저 묻는 방식이다. Nginx에서는 `auth_request` 지시어가 그 질문을 하위 요청(subrequest)으로 만든다. 인증 결과는 업스트림으로 나가는 요청의 헤더로 바뀌기 때문에, 업스트림은 JWT 대신 그 헤더를 입력으로 받는다. -## 관계 +## upstream에 도달하기 전에 인증을 끝낸다 - **Forward-Auth에서 Identity Header를 신뢰하기 위한 조건** 이 동작을 운영에서 신뢰하려면 무엇이 갖춰져야 하는지 적은 기록이다. @@ -31,7 +31,7 @@ forward-auth는 실제 요청을 업스트림으로 넘기기 전에 별도의 - **OAuth/OIDC 인증 패턴 선택 기준** 이 구조를 언제 고르는지 다른 패턴과 비교한 기록이다. -## 본문 +## auth_request subrequest와 identity header 전달 과정 @@ -110,7 +110,7 @@ X-Internal-Auth-Token: 업스트림에 도착한 요청만 봐서는 브라우저가 보낸 헤더와 바깥과 맞닿은 Nginx, 즉 엣지가 만든 헤더를 구분할 수 없다. 덮어쓰기를 엣지에서 끝내야 하는 이유가 여기에 있다. -## upstream은 두 겹을 확인한다 +## upstream은 사용자 정보와 내부 요청 자격 증명을 함께 확인한다 Spring 컨트롤러는 헤더 두 개를 함께 본다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-idp-brokering.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-idp-brokering.md index c8921e5..02c445a 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-idp-brokering.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/concept/concept-idp-brokering.md @@ -22,7 +22,7 @@ source: 브로커링(brokering)은 브로커가 외부 IdP(Identity Provider)의 인증 결과를 대신 받아 검증하고, 자기 realm 안의 사용자와 연결하는 동작이다. 연결이 끝나면 브로커는 자기가 만든 authorization code를 애플리케이션으로 보낸다. 애플리케이션이 받는 코드와 토큰은 언제나 브로커가 발급한 것이라, 외부 IdP를 붙여도 애플리케이션이 상대하는 issuer, 곧 그 토큰을 발급한 주체는 바뀌지 않는다. -## 관계 +## 외부 IdP와 애플리케이션 issuer는 서로 다른 경계다 - **외부 IdP 연동과 Application 인증 구조의 경계** 이 동작을 경계 기준으로 정리한 기록이다. @@ -31,7 +31,7 @@ source: - **Authorization Code Flow의 Endpoint와 Credential 이동 기준** 브로커가 발급하는 코드가 지나는 endpoint다. -## 본문 +## Google에서 Keycloak을 거쳐 애플리케이션으로 돌아오는 흐름 @@ -64,7 +64,7 @@ AP1의 Resource Server가 검증하는 issuer도 브로커이고, AP2와 AP3가 ## 경계를 섞으면 생기는 일 -외부 IdP 연동을 다섯 번째 애플리케이션 인증 구조로 세면 upstream IdP 경계와 애플리케이션 OAuth 경계를 같은 기준으로 묶게 되는데, 두 경계는 검증 방법이 다르다. 그러면 비교표에 성격이 다른 항목이 끼어들고, 계정 연결 규칙도 인증 구조 이야기에 섞여서 따로 설계하지 않고 넘어가게 된다. +외부 IdP 연동은 애플리케이션의 토큰 보관 방식이나 API 호출 경계를 바꾸는 선택이 아니다. 바뀌는 것은 사용자를 처음 인증하는 upstream IdP이며, 애플리케이션은 계속 Keycloak을 issuer로 상대한다. 계정 연결과 브로커 검증은 애플리케이션 인증 패턴과 분리해서 다룬다. 화면에서 어느 외부 IdP로 로그인할지 고르게 하거나 IdP마다 계정 연결을 다루는 것은 브로커가 하는 일이라 경계를 넘지 않는다. Resource Server의 토큰 검증이나 애플리케이션 인가가 외부 IdP별로 갈리기 시작하면, 브로커 경계가 애플리케이션까지 샜는지 확인한다. 외부 IdP의 토큰을 애플리케이션이 직접 받아 검증하는 경로를 만들면 브로커가 하던 계정 연결과 정책 판단도 함께 빠진다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/decision/decision-bff-owns-token.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/decision/decision-bff-owns-token.md index a9a9aed..c709d5f 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/decision/decision-bff-owns-token.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/decision/decision-bff-owns-token.md @@ -20,9 +20,9 @@ source: # BFF가 OAuth Token을 관리하는 조건 -BFF(Backend for Frontend)는 화면에 필요한 API를 브라우저 대신 호출하고 결과만 돌려주는 백엔드다. 애플리케이션 계층에서 API 응답 조합과 인가를 처리하면서도 브라우저 JavaScript에는 OAuth 토큰을 노출하지 않아야 한다면 이 구조를 선택할 수 있다. +BFF(Backend for Frontend)는 화면에 필요한 API를 브라우저 대신 호출하고 결과만 돌려주는 백엔드다. 애플리케이션 계층에서 API 응답 조합과 인가를 처리하면서 브라우저 JavaScript에는 OAuth 토큰을 노출하지 않아야 한다면 BFF가 그 조건을 만족한다. -## 근거 +## 브라우저 JavaScript에 OAuth 토큰을 두지 않으려면 - **Browser Token을 없애면서 BFF에 Session과 CSRF 책임이 생긴 과정** 이 결정대로 만든 구조를 실제로 실행해 본 기록이다. @@ -33,13 +33,13 @@ BFF(Backend for Frontend)는 화면에 필요한 API를 브라우저 대신 호 - **Refresh Token 관리만 서버로 이전, Access Token은 여전히 Browser에 노출** 액세스 토큰이 브라우저로 나가서 이 요구를 만족하지 못한 경우다. -## 결정문 +## BFF가 OAuth 토큰과 Resource Server 호출을 소유한다 브라우저에 OAuth 토큰을 노출하지 않으면서 애플리케이션이 Resource Server 호출을 중계하고 조합해야 하는 경우, BFF가 authorization code 교환과 토큰 보관, downstream API 호출을 소유한다. 브라우저에는 애플리케이션 세션만 제공한다. -## 판단 이유 +## API 호출을 서버로 옮기면 브라우저에 토큰을 내려줄 필요가 없다 브라우저에 OAuth 토큰을 전달하지 않으려면 서버가 authorization code를 교환하고 액세스 토큰으로 downstream API를 호출해야 한다. @@ -54,7 +54,7 @@ Forward-Auth 구조도 이 요구는 만족할 수 있지만, 업스트림은 JW 처리량과 장애 복구 시간, session failover, secret rotation 절차는 확인하지 못해서 이 판단의 근거가 아니다. -## 영향 +## 세션과 CSRF, Authorized Client 저장소를 서버가 운영해야 한다 - BFF가 로그인 상태와 액세스 토큰, 리프레시 토큰을 보관하는 보안 구성요소가 되므로, 요청을 그대로 넘기는 프록시처럼 다루지 않는다. - 상태를 바꾸는 요청마다 CSRF 검증이 붙는다. 클라이언트에 내려가는 값과 실제로 제출해야 하는 값이 다를 수 있어서 클라이언트 코드도 그 차이를 알아야 한다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/decision/decision-federation-not-a-pattern.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/decision/decision-federation-not-a-pattern.md index d0180b7..1545912 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/decision/decision-federation-not-a-pattern.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/decision/decision-federation-not-a-pattern.md @@ -2,7 +2,7 @@ id: 8c1ebea7-204e-445c-9812-0421d9eb0e9c kind: PROJECT_DECISION slug: federation-is-not-an-application-pattern -title: 외부 IdP와의 연동이라도 별도의 인증 방식이 아니다. +title: 외부 IdP 연동은 별도의 애플리케이션 인증 패턴이 아니다 topic: oauth-oidc-auth-boundary topicName: OAuth/OIDC 인증 경계 project: KeyCloak Patterns @@ -17,7 +17,7 @@ source: - final/document.md#선택이-코드와-흐름에-반영되는-방식-google-login --- -# 외부 IdP와의 연동이라도 별도의 인증 방식이 아니다. +# 외부 IdP 연동은 별도의 애플리케이션 인증 패턴이 아니다 외부 IdP(Identity Provider, 인증 제공자)는 사용자 인증을 실제로 수행하는 쪽이고, Google이 그중 하나다. Keycloak은 Google의 인증 결과를 받아 애플리케이션이 사용할 토큰을 발급한다. @@ -25,7 +25,7 @@ Keycloak은 Google의 인증 결과를 받아 애플리케이션이 사용할 SPA(Single Page Application)나 BFF(Backend for Frontend) 같은 구조는 로그인한 사용자의 토큰과 세션을 어디에서 관리할지 정한다. 그래서 외부 IdP가 붙어도 애플리케이션의 인증 구조는 바뀌지 않는다. -## 근거 +## Google 로그인을 붙여도 issuer는 Keycloak으로 유지된다 - **외부 IdP 연동과 Application 인증 구조의 경계** 이 결정을 규칙 문장으로 적어 둔 기준이다. @@ -34,7 +34,7 @@ SPA(Single Page Application)나 BFF(Backend for Frontend) 같은 구조는 로 - **OAuth Token과 Application Session을 구분하는 기준** upstream IdP 상태와 애플리케이션 상태를 같은 이름으로 부르지 않는다고 갈라 둔 기준이다. -## 결정문 +## 외부 IdP 연동은 애플리케이션 인증 패턴과 분리한다 외부 IdP 연동은 별도의 인증 구조가 아니다. @@ -42,7 +42,7 @@ Google과 같은 외부 IdP는 사용자의 인증을 담당한다. Keycloak은 그 인증 결과를 받아 애플리케이션이 신뢰할 수 있는 토큰을 발급한다. SPA, Mediator, BFF, OAuth2-proxy와 같은 4가지 구조는 이렇게 발급된 토큰이나 세션을 애플리케이션에서 어디까지 노출하고 관리할지를 구분한다. -## 판단 이유 +## upstream 인증과 애플리케이션 토큰 경계는 검증 대상이 다르다 사용자가 Keycloak 로그인 화면에서 Google 로그인을 선택하면 브라우저는 Google의 Authorization Endpoint로 이동한다. Google에서 인증이 끝나면 그 결과는 Keycloak으로 돌아오고, Keycloak은 이 응답을 검증해 자신의 사용자 정보와 연결한다. @@ -56,12 +56,12 @@ Resource Server가 검증하는 발급자(issuer)도 Google이 아니라 Keycloa 애플리케이션이 다루는 토큰을 Keycloak이 발급하기 때문에, Google 로그인을 추가해도 애플리케이션이 토큰을 관리하는 방식은 달라지지 않는다. SPA라면 여전히 브라우저에서 토큰을 관리하고, BFF라면 서버가 토큰을 관리하면서 API를 대신 호출한다. -Google을 다섯 번째 구조로 세면 upstream IdP 경계와 애플리케이션 OAuth 경계를 같은 기준으로 묶게 되는데, 두 경계는 검증하는 방법이 서로 다르다. +Google 연동은 upstream IdP 선택에 해당하며 SPA, Mediator, BFF, Forward-Auth처럼 애플리케이션의 토큰 보관·API 호출 경계를 정하는 패턴과는 구분한다. 그래서 외부 IdP 연동과 애플리케이션 인증 구조는 별도의 경계로 나누어 설계하고 검증한다. 그 비교표도 처음에는 다른 모양이었다. 네 구조를 설명하는 용어부터 나란히 놓고 견주었는데, 용어만으로는 어느 계층이 Authorization Code를 교환하고 어느 계층이 API를 부르는지 보이지 않아 로그인과 API 요청을 맡는 구성요소를 같은 표에 놓았다. -## 영향 +## 계정 연결과 callback은 별도 항목으로 관리한다 - Google을 추가해도 애플리케이션이 신뢰하고 토큰을 검증하는 대상은 계속 Keycloak이다. 토큰을 브라우저와 서버 중 어디에서 관리하고 어느 계층에서 API를 호출할지는 기존 4가지 구조가 그대로 정한다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-bff-state-store.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-bff-state-store.md index 0507ed1..87e4d84 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-bff-state-store.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-bff-state-store.md @@ -22,18 +22,18 @@ source: 현재 BFF(Backend for Frontend)의 세션과 Authorized Client는 프로세스 메모리에 저장된다. 재시작과 레플리카 이동 뒤에도 로그인 상태를 유지하려면 두 상태를 어디에 저장할지 정해야 한다. -## 관계 +## BFF가 서버에 보관하는 두 상태 - **서버 세션 기반 인증 구조는 다중 인스턴스에서 어떻게 운영할 것인가** - 이 질문에서 저장소 부분만 떼어 낸 것이다. + 여기서는 BFF 상태 가운데 세션과 Authorized Client를 어느 저장소에 둘지만 다룬다. - **Browser Token을 없애면서 BFF에 Session과 CSRF 책임이 생긴 과정** 세션과 Authorized Client를 찾는 열쇠가 다르다는 사실의 출처다. - **BFF 인증 구조 설계 기준** - 이 기준의 저장소 항목은 여기에 답이 나와야 채울 수 있다. + 재시작과 replica 이동 뒤에도 로그인 상태를 유지하려면 두 저장소의 수명과 공유 방식을 먼저 정해야 한다. - **Refresh Token Rotation과 다중 Replica 경쟁을 어떻게 처리할 것인가** 저장소를 공유한 다음에야 레플리카 경쟁을 재현할 수 있다. -## 사실 +## 현재 세션과 Authorized Client는 프로세스 메모리에 있다 - BFF가 서버에 들고 있는 상태는 둘이다. 하나는 브라우저의 로그인 세션이고, 다른 하나는 Keycloak에서 받은 액세스 토큰과 리프레시 토큰을 담아 두는 Authorized Client다. @@ -49,14 +49,14 @@ source: - 현재 확인 범위는 한 대에서 실행한 학습 환경의 코드와 테스트다. 여러 인스턴스가 세션과 Authorized Client를 공유하는지는 실행해 확인하지 못했다. -## 가정 +## 저장소를 고를 때 지켜야 할 조건 - 두 상태를 같은 저장소에 둘 필요는 없다. - 저장한 리프레시 토큰을 평문으로 두면 안 된다. - 세션 만료와 토큰 만료 중 하나가 먼저 오면 그 순간에 무엇이 일어날지 정해 두어야 한다. 토큰이 만료됐을 때 사용자의 로그인 상태가 유지되는지가 그런 예다. -## 미지수 +## 아직 정하지 않은 저장 방식 - Redis와 JDBC 중 어느 쪽이 이 상태의 접근 패턴에 맞는가. 요청마다 읽는 값과 가끔 읽는 값이 섞여 있다. @@ -66,14 +66,14 @@ source: - 로그아웃 한 번으로 세션과 Authorized Client 두 저장소를 어떻게 같이 지우는가. - 스티키 세션이 영속 저장소의 대안인가 보완인가. -## 제약 +## 현재 구현에서 확인된 제약 - Authorized Client를 찾을 때는 session ID를 쓰지 않아서, 세션만 공유해도 같은 사용자의 여러 세션이 같은 토큰을 본다. - 현재 테스트에는 저장소 계약이 없다. - 모든 화면 요청이 BFF를 지나기 때문에 저장소가 느려지면 화면도 바로 느려진다. 다만 이 학습 환경에서는 처리량을 재지 못해서, 어느 지점부터 느려지는지는 숫자로 말할 수 없다. -## 선택지 +## Redis와 JDBC를 어떻게 나눌 것인가 ### 1. 세션과 Authorized Client를 모두 Redis에 둔다 @@ -121,7 +121,7 @@ Authorized Client가 여전히 특정 애플리케이션 인스턴스의 메모 Redis와 관계형 DB를 둘 다 인증 경로에서 쓰게 되므로 모니터링, 장애 대응, 백업까지 운영할 저장소가 늘어난다. -## 다음 검증 +## 저장소 후보를 같은 조건으로 비교한다 후보마다 같은 입력으로 비교한다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-edge-authorization-scope.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-edge-authorization-scope.md index f4ca8fa..914d211 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-edge-authorization-scope.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-edge-authorization-scope.md @@ -21,16 +21,16 @@ source: 지금 엣지는 인증된 사용자의 `user`와 `email`만 헤더로 넘기고, 업스트림 애플리케이션은 역할(role)을 보고 인가를 판단하지 않는다. -## 관계 +## 현재 Forward-Auth가 upstream으로 넘기는 정보 - **Forward-Auth에서 Client가 보낸 Identity Header를 신뢰하면 안 되는 이유** 엣지가 user와 email만 넘긴다는 사실을 여기서 가져왔다. - **Forward-Auth에서 Identity Header를 신뢰하기 위한 조건** - 넘길 헤더를 허용 목록(allowlist)으로 두는 기준과 검증 조건이 이 기록에 있다. + Edge가 upstream으로 전달하는 identity header는 allowlist로 제한하고, 클라이언트가 같은 이름의 헤더를 보냈을 때 제거되거나 덮어써지는지 확인해야 한다. - **BFF 인증 구조 설계 기준** - 네 번째 선택지로 되돌아갈 때 따를 기준이 이 기록이다. + 인가 정보를 Edge까지 확장한다면 어떤 claim을 헤더로 넘길지와 upstream이 그 헤더를 신뢰할 조건을 함께 정해야 한다. -## 사실 +## 지금은 user와 email만 전달한다 - 지금 엣지 응답은 user와 email만 넘긴다. 역할과 그룹, 테넌트, 인증 방식, 토큰 만료는 넘기지 않는다. - 업스트림의 신원 응답 엔드포인트는 역할을 확인하지 않고 누가 왔는지만 돌려준다. @@ -38,12 +38,12 @@ source: - Nginx는 클라이언트가 보낸 같은 이름의 헤더를 합치지 않고 덮어쓴다. 헤더를 늘리면 늘어난 헤더도 똑같이 덮어쓰게 해야 한다. - 업스트림은 JWT를 입력으로 받지 않아서 헤더로 넘어온 값이 맞는지 확인할 방법이 없다. -## 가정 +## 인가 정보를 헤더에 추가하면 달라지는 점 - 헤더 종류가 늘어나면 그만큼 정해야 할 계약도 늘어난다. - 역할이 바뀌는 시각과 요청이 들어오는 시각이 달라서, 그 사이에 들어온 요청은 바뀌기 전 값을 볼 수도 있다. -## 미지수 +## 역할과 권한을 어디에서 판단할 것인가 - 역할 기반 인가가 필요한 요구가 들어왔을 때 어떻게 처리할지. 엣지가 사용자의 역할까지 확인해 헤더로 넘길지, 애플리케이션이 역할과 권한을 직접 조회해 인가를 판단할지. - 역할이 여러 개일 때 어떤 구분자와 이스케이프 규칙으로 보낼지. 값 안에 그 구분자가 들어오면 어떻게 되는지. @@ -52,12 +52,12 @@ source: - 역할이 바뀌었을 때 프록시 세션과 다운스트림 인가에 언제 반영되는지. 권한을 바꾸고 몇 분 뒤에 반영되는지. - 업스트림이 헤더가 있는지만 볼지, 값과 내부 서비스 식별값(service identity)까지 함께 볼지. -## 제약 +## identity header에 필요한 신뢰 조건 - 넘길 헤더는 허용 목록으로 정해야 하고, 클라이언트가 보낸 같은 이름의 헤더는 언제나 덮어써야 한다. - 내부 토큰 검사가 컨트롤러 한 곳에만 있다. 헤더를 늘리기 전에 이 검사를 공통 경계로 옮겨야 한다. -## 선택지 +## 인증만 Edge에 둘지 인가까지 올릴지 ### 1. 인증만 엣지에 둔다 @@ -97,7 +97,7 @@ source: 이 구조를 골랐다가 다시 엣지 쪽으로 되돌린다면 BFF가 맡던 사용자별 인가를 업스트림이나 별도 정책 서비스로 다시 옮겨야 한다. -## 다음 검증 +## 애플리케이션이 실제로 필요한 claim부터 확인한다 업스트림이 실제로 요구하는 사용자 속성(claim)부터 적는다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-multi-instance-session.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-multi-instance-session.md index 1715031..82cc64a 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-multi-instance-session.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-multi-instance-session.md @@ -21,18 +21,18 @@ source: Mediator와 BFF(Backend for Frontend)는 브라우저의 로그인 세션과 OAuth 토큰을 서로 다른 저장소에 둔다. 지금 구현은 두 저장소를 모두 애플리케이션 서버의 메모리에 두기 때문에, 서버 프로세스가 끝나면 담아 둔 상태도 같이 사라진다. -## 관계 +## Mediator와 BFF가 지금 상태를 보관하는 방식 - **Browser Token을 없애면서 BFF에 Session과 CSRF 책임이 생긴 과정** - 두 상태가 모두 인스턴스 하나의 메모리에 있다는 사실을 이 기록에서 가져왔다. + 현재 Mediator와 BFF는 세션과 Authorized Client를 모두 단일 애플리케이션 인스턴스의 메모리에 저장한다. - **Refresh Token 관리만 서버로 이전, Access Token은 여전히 Browser에 노출** 이 패턴도 세션과 토큰을 같은 방식으로 저장한다. - **BFF 인증 구조 설계 기준** - 이 질문에 답하면 그 기준에서 비어 있는 항목이 채워진다. + 다중 인스턴스 운영을 하려면 두 상태를 공유할지, sticky session으로 묶을지, 각각 어떤 장애 복구 수준을 요구할지 정해야 한다. - **BFF의 Session과 OAuth2AuthorizedClient를 어디에 저장할 것인가** 저장소 후보를 견주는 일만 따로 떼어 낸 질문이다. -## 사실 +## 세션과 Authorized Client는 서로 다른 키로 조회한다 - Mediator와 BFF는 로그인 상태와 OAuth 토큰을 서로 다른 저장소에 둔다. 로그인 상태는 HttpSession에 담고 세션 ID로 찾는다. OAuth 토큰은 OAuth2AuthorizedClientService에 담고, client registration 이름과 principal name으로 찾는다. - 세션과 OAuth 토큰을 담을 저장소를 따로 설정하지 않아서, Spring Boot 자동 구성이 고르는 메모리 기반 기본 구현이 쓰인다. 다만 저장소를 직접 만드는 Bean이 코드에 없으므로, 어떤 구현체가 실제로 올라오는지는 자동 구성 결과까지 열어 봐야 정확히 알 수 있다. @@ -41,13 +41,13 @@ Mediator와 BFF(Backend for Frontend)는 브라우저의 로그인 세션과 OAu - OAuth2-Proxy 구조는 로그인 상태를 서버 저장소에 두지 않고, 필요한 최소한의 정보만 브라우저의 세션 쿠키에 담는다. 지금 설정에서 이 쿠키의 유효 시간은 1시간이다. - 지금 테스트에는 서버를 재시작하거나 요청이 다른 인스턴스로 갔을 때 로그인 상태와 OAuth 토큰을 그대로 쓸 수 있는지 확인하는 항목이 없다. 그래서 세션이나 토큰의 저장 방식을 바꿔도 기존 동작이 깨지지 않는지는 따로 확인해야 한다. -## 가정 +## 다중 인스턴스에서 유지해야 할 조건 - 운영에서는 인스턴스가 둘 이상이다. - 재시작과 배포가 로그인 상태를 끊어서는 안 된다. 지금 구조에서는 끊긴다. - 같은 사용자가 여러 브라우저에서 로그인해도, 한쪽 세션이 다른 쪽의 토큰 항목을 덮어써서는 안 된다. -## 미지수 +## 재시작과 replica 이동 뒤 무엇이 남는가 - 재시작한 뒤에 로그인이 유지되는가. 지금은 유지되지 않는다는 것까지만 확인했고, 무엇을 바꿀지는 아직 정하지 않았다. - 요청이 다른 인스턴스로 가도 같은 세션을 찾는가. @@ -57,19 +57,19 @@ Mediator와 BFF(Backend for Frontend)는 브라우저의 로그인 세션과 OAu - 세션 만료와 토큰 만료가 어긋나면 무엇이 먼저 실패하고 사용자 화면에는 무엇이 보이는가. - OAuth2-Proxy 구조의 레플리카들은 같은 Cookie Secret을 어떻게 나눠 갖고 어떻게 바꾸는가. 바꾸는 동안 이미 로그인해 있던 사람은 어떻게 되는가. -## 제약 +## 세션 저장소만 공유해서는 부족하다 - 지금은 인스턴스 하나로만 실행하는 학습 환경이어서 레플리카 사이의 세션 조회나 장애 조치(failover) 동작은 아직 만들지 않았다. 장애 복구에 걸리는 시간과 비밀값 교체 절차도 확인한 범위에 넣지 못했다. - Authorized Client는 세션 ID로 저장하지도 조회하지도 않는다. 그래서 여러 인스턴스가 같은 세션을 쓰도록 세션 저장소만 공유 저장소로 바꿔서는 부족하다. 로그인 세션을 여러 인스턴스가 나눠 쓰는 방법과, OAuth 토큰이 들어 있는 Authorized Client를 어디에 어떻게 저장할지는 각각 따로 설계해야 한다. - Resource Server의 8081이 호스트에도 열려 있어서, 모든 클라이언트가 BFF만 거치도록 네트워크가 강제하고 있지는 않다. -## 선택지 +## 공유 저장소와 sticky session을 비교한다 ### 1. 공유 저장소 — 상태 일관성과 저장소 가용성 HttpSession과 Authorized Client를 외부 공유 저장소에 두면 요청이 다른 인스턴스로 이동해도 같은 로그인 상태와 OAuth 토큰을 조회할 수 있다. 인스턴스 재시작과 라우팅 변경에서 상태를 이어 가는 대신 인증 경로가 그 저장소의 가용성에 의존한다. -이 선택의 핵심은 두 상태의 수명과 보호 방식이다. 세션과 토큰의 만료 시점, 로그아웃 때 지우는 순서, 저장 token 보호가 맞지 않으면 한쪽 상태만 남을 수 있다. +두 상태는 수명과 보호 방식이 다르다. 세션 만료와 토큰 만료 시점, 로그아웃 때 삭제 순서, 저장된 token 보호 방식이 어긋나면 세션과 Authorized Client 중 하나만 남을 수 있다. ### 2. session affinity — 라우팅은 고정하지만 node loss는 남는다 @@ -87,9 +87,9 @@ SPA(Single Page Application)처럼 브라우저가 OAuth 토큰을 들고 Resour Forward-Auth의 최소 client-side cookie는 공유 저장소나 Sticky Session과 같은 층의 선택지가 아니다. 서버에 application-owned OAuth 상태를 두는 구조를 줄이고 인증 프록시가 cookie를 검증한 결과를 upstream identity로 전달한다. -레플리카는 같은 Cookie Secret을 검증할 수 있어야 하고, upstream은 프록시가 전달한 사용자 정보를 신뢰한다. 그래서 이 구조의 핵심 문제는 세션 저장소 일관성보다 secret 배포·교체, 직접 접근 차단, client-supplied identity header 제거 또는 덮어쓰기다. +Forward-Auth에서는 replica가 같은 Cookie Secret을 검증할 수 있어야 하고 upstream은 프록시가 전달한 사용자 정보를 신뢰한다. 따라서 세션 저장소 일관성뿐 아니라 secret 배포·교체, 프록시 우회 차단, 클라이언트가 보낸 identity header 제거 또는 덮어쓰기까지 함께 확인해야 한다. -## 다음 검증 +## 두 인스턴스로 로그인 상태 이동을 재현한다 인스턴스를 둘로 띄우고 순서대로 확인한다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-refresh-rotation-replica.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-refresh-rotation-replica.md index 9712bf1..ab451a9 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-refresh-rotation-replica.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/question/question-refresh-rotation-replica.md @@ -23,18 +23,18 @@ realm은 refresh token rotation과 최대 재사용 횟수 0회를 쓴다. `refr 무효가 되기 때문에, 두 replica가 같은 refresh token으로 동시에 갱신하면 두 번째 사용이 거부될 수 있다. 실제 Keycloak 응답과 session에 미치는 영향은 아직 재현하지 않았다. -## 관계 +## rotation 경쟁은 Authorized Client를 공유할 때 생긴다 - **BFF의 Session과 OAuth2AuthorizedClient를 어디에 저장할 것인가** - 이 질문에 답하기 전에 저장소부터 정해야 한다. + 동일 refresh token이 여러 replica에서 동시에 사용될 수 있는지 판단하려면 Authorized Client를 어디에 저장하고 어떻게 공유하는지 먼저 정해야 한다. - **Refresh Token 관리만 서버로 이전, Access Token은 여전히 Browser에 노출** rotation과 최대 재사용 횟수 0회를 쓰는 구성이 여기서 나왔다. - **서버 세션 기반 인증 구조는 다중 인스턴스에서 어떻게 운영할 것인가** 인스턴스를 여러 대 띄워야 이 경쟁이 생긴다. - **BFF 인증 구조 설계 기준** - 갱신 실패를 화면 오류로 바꾸는 규칙이 이 기준에 들어 있다. + refresh 실패가 발생했을 때 재로그인으로 전환할지 401을 반환할지 등 브라우저 응답 규칙도 함께 정해야 한다. -## 사실 +## realm은 rotation과 max reuse 0을 사용한다 - realm에는 refresh token rotation과 최대 재사용 횟수 0회가 설정되어 있다. - 커밋된 테스트는 새 refresh token이 발급되는지, 이전 token이 거부되는지, revocation 뒤 refresh가 @@ -42,19 +42,19 @@ realm은 refresh token rotation과 최대 재사용 횟수 0회를 쓴다. `refr 갱신할 때도 같은 결과가 나온다고 보지 않는다. - authorized client manager에는 refresh-token provider가 구성되어 있어, access token이 만료되면 refresh를 시도할 수 있다. -- `refreshTokenMaxReuse`는 재사용 횟수 설정이고 refresh token lifespan은 별도의 시간 설정이다. 이 문서에서는 둘을 같은 허용 시간으로 취급하지 않는다. +- `refreshTokenMaxReuse`는 재사용 횟수 설정이고 refresh token lifespan은 별도의 시간 설정이다. 두 값을 같은 허용 시간으로 해석하지 않는다. - access token이 만료될 때까지 기다려 실제로 갱신이 성공하고 새 token이 저장되는지까지는 확인하지 않았다. - 현재 authorized client 저장소는 프로세스 안에만 있어서(process-local) replica끼리 같은 refresh token 상태를 공유하지 않는다. 그래서 이번 단일 인스턴스 검증에서는 동시 refresh 경쟁을 재현하지 않았다. - 이미 발급된 access token은 만료 전까지 API에서 계속 통하기 때문에, 갱신이 실패해도 그동안 화면은 정상으로 보인다. -## 가정 +## 두 replica가 같은 refresh token을 읽는 상황 - 운영에서는 replica를 둘 이상 띄우고 저장소를 공유하므로, 두 replica가 같은 authorized client 항목을 읽는다. - 두 replica의 access token이 비슷한 시각에 만료되면 각 replica가 따로 갱신을 시도한다. -## 미지수 +## 동시 refresh에서 두 번째 요청은 어떻게 실패하는가 - 같은 refresh token으로 두 replica가 동시에 갱신하면 각 replica가 어떻게 동작하는가. - 최대 재사용 횟수 0회에서 두 번째 사용이 거부되면 사용자 화면에 무엇이 보이는가. @@ -64,14 +64,14 @@ realm은 refresh token rotation과 최대 재사용 횟수 0회를 쓴다. `refr - lock을 쓴다면 어디에 두고 얼마나 잡는가. 잡은 채로 프로세스가 내려가면 어떻게 푸는가. - 갱신 실패를 로그인 만료와 구분해 표시할 수 있는가. -## 제약 +## access token 만료 직후에 재현해야 한다 - rotation과 최대 재사용 횟수 0회는 이미 realm에 설정했다. 이 전제는 바꾸지 않고 답한다. - 이미 발급된 access token은 만료 전까지 쓸 수 있으므로 refresh 실패가 곧바로 드러나지 않을 수 있다. 재현 테스트는 access token 만료 직후에 맞춰 실행한다. - 이 경쟁은 저장소를 공유한 뒤에야 재현되므로 저장소를 정한 다음에 이어서 푼다. -## 선택지 +## 직렬화와 재시도 전략을 비교한다 ### 1. 분산 lock으로 갱신을 직렬화한다 @@ -101,7 +101,7 @@ refresh를 전담하는 구성요소 하나만 refresh token을 쓰고, 다른 r 최대 재사용 횟수를 늘리면 동일 refresh token의 추가 사용을 일정 횟수 받아들이도록 구성할 수 있다. 그만큼 탈취된 refresh token의 replay를 허용할 여지도 커진다. 현재 실험은 rotation과 최대 재사용 횟수 0회를 전제로 하므로 이 선택지는 제외한다. -## 다음 검증 +## 두 replica에서 동시에 refresh를 일으킨다 저장소를 공유한 뒤에 재현한다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-authorization-code-endpoints.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-authorization-code-endpoints.md index eb126fd..ddf513c 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-authorization-code-endpoints.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-authorization-code-endpoints.md @@ -21,7 +21,7 @@ source: Authorization Endpoint에서 리다이렉트, Token Endpoint, JWK(JSON Web Key) 검증, Resource API까지 지점마다 무엇이 이동하고 무엇이 이동하지 않는지 확인한다. 먼저 client_secret이 가는 곳과 가지 않는 곳을 나눈다. -## 관계 +## Authorization Code Flow에서 credential이 이동하는 지점 - **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계** 브라우저가 code를 직접 교환하는 흐름에서 엔드포인트마다 무엇이 오가는지 확인했다. @@ -30,7 +30,7 @@ Authorization Endpoint에서 리다이렉트, Token Endpoint, JWK(JSON Web Key) - **Public Client와 Confidential Client 구분 기준** 현재 네 패턴에서 client type, callback/code-exchange ownership, PKCE와 client authentication이 어떻게 배치됐는지 함께 본다. -## 목적 +## client secret과 code가 어디로 가는지 구분한다 Authorization Endpoint와 Token Endpoint는 하는 일도 다르고 요청이 나가는 방식도 다르다. @@ -39,7 +39,7 @@ Authorization Endpoint와 Token Endpoint는 하는 일도 다르고 요청이 Authorization Endpoint 요청 URL은 브라우저 주소창과 히스토리, Authorization Server의 접근 로그에 남을 수 있다. 다른 문서나 origin으로 이동할 때 referrer에 어느 범위까지 전달되는지는 브라우저의 Referrer-Policy와 이동 대상의 관계에 따라 달라진다. 이 요청에서는 client authentication을 수행하지 않는다. Token Endpoint 요청은 값을 요청 본문과 Authorization 헤더에 싣는다. 이 프로젝트에서는 AP1 public SPA가 브라우저에서 이 endpoint를 호출하고 AP2~AP4의 server-side component가 code를 교환한다. 이 호출 위치는 public/confidential client type 자체가 강제하는 것이 아니라 callback과 code exchange를 어느 구성요소가 소유하는지, 그리고 배포 구조를 어떻게 잡았는지에 따라 정해진다. -## 규칙 +## Endpoint마다 전달되는 값이 다르다 ### 1. Authorization Endpoint에는 client_secret을 보내지 않는다 @@ -92,19 +92,19 @@ issuer 검증값과 엔드포인트에 연결하는 주소는 따로 구성한 두 구간을 한 줄로 이어 그리면 누가 code를 바꾸고 누가 API를 부르는지가 겹쳐 보인다. 네 가지 구조는 여기서 갈리므로 나눠서 그린다. -## 적용 조건 +## 브라우저와 서버가 code exchange를 나누어 맡는 경우 - Authorization Code Flow를 쓰는 클라이언트를 설정하거나 문서로 설명할 때 - 브라우저 요청과 서버끼리 주고받는 요청이 한 흐름에 섞여 있을 때 - 엔드포인트마다 무엇이 드러나는지 나눠야 할 때 - PKCE와 클라이언트 인증을 어디에 걸지 정할 때 -## 예외 +## client type만으로 Token Endpoint 호출 위치를 정하지 않는다 - Client Credentials처럼 사용자 없이 토큰을 받는 흐름은 Authorization Endpoint를 지나지 않는다. - Device Authorization Grant는 브라우저 리다이렉트 대신 별도의 사용자 code 단계를 쓰기 때문에 redirect_uri 항목이 그대로 적용되지 않는다. -## 예시 +## AP1부터 AP4까지의 Endpoint 호출 위치 - authorization request에는 code_challenge_method=S256이 있고 클라이언트 시크릿은 없다 - token request에는 code_verifier가 있다. 시크릿을 가진 클라이언트는 이 요청에서 자기를 인증한다 diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-bff-auth-design.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-bff-auth-design.md index 65a4cd5..15fca52 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-bff-auth-design.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-bff-auth-design.md @@ -20,20 +20,20 @@ source: # BFF 인증 구조 설계 기준 -BFF(Backend For Frontend)는 화면에 필요한 API를 브라우저 대신 호출해 주는 백엔드다. 이 구조에서는 OAuth 토큰을 서버가 보관하고, 브라우저는 토큰 대신 세션 쿠키로 BFF에 요청한다. +BFF(Backend For Frontend)는 화면에 필요한 API를 브라우저 대신 호출해 주는 백엔드다. BFF가 OAuth 토큰을 서버에 보관하고, 브라우저는 토큰 대신 세션 쿠키로 BFF에 요청한다. -## 관계 +## BFF는 브라우저 대신 OAuth 토큰을 보관한다 - **Browser Token을 없애면서 BFF에 Session과 CSRF 책임이 생긴 과정** - 이 기준의 항목 중 무엇이 실제로 구현되었고 무엇이 비어 있는지 센 기록이다. + 현재 BFF 구현에서 어느 조건까지 충족했는지는 자동 테스트와 실제 구성으로 따로 확인한다. - **서버 세션 기반 인증 구조는 다중 인스턴스에서 어떻게 운영할 것인가** - 이 기준의 저장소 항목에 아직 답을 주지 못한 질문이다. + 세션과 Authorized Client의 공유 저장소 선택은 아직 확정하지 않았다. - **BFF의 Session과 OAuth2AuthorizedClient를 어디에 저장할 것인가** - 세션과 토큰을 어느 저장소에 둘지는 이 기준에서 아직 정하지 않았다. + 세션과 Authorized Client를 메모리, Redis, JDBC 가운데 어디에 둘지는 별도 결정이 필요하다. - **BFF가 OAuth Token을 관리하는 조건** - 그 결정이 PROPOSED인 동안에는 이 문서가 실제 적용 기준이다. + 공유 저장소 결정이 확정되기 전까지는 현재 단일 인스턴스 메모리 구성을 기준으로 동작을 확인한다. -## 목적 +## 브라우저 token exposure를 없애고 API 호출을 서버로 옮긴다 BFF 구조에서는 BFF가 authorization code를 토큰으로 교환하고 그 액세스 토큰으로 Resource Server를 호출한다. 브라우저의 로그인 상태는 세션이 담고 OAuth 토큰은 인가된 클라이언트(authorized client)가 보관하므로, 이 둘을 함께 관리해야 한다. 브라우저 응답에서 토큰이 보이지 않는다고 토큰을 다루는 일까지 없어지지는 않는다. BFF는 요청을 넘겨 주는 프록시가 아니라 로그인 상태와 토큰을 가진 보안 구성요소가 된다. @@ -41,7 +41,7 @@ BFF 구조에서는 BFF가 authorization code를 토큰으로 교환하고 그 쿠키로 인증하는 요청을 지킬 CSRF 검증, OAuth 토큰을 보관할 인가된 클라이언트 저장소, 로그아웃할 때 세션과 토큰을 함께 지우는 방법을 같이 설계해야 한다. BFF가 호출한 Resource Server에서 오류가 났을 때 이를 브라우저에 무엇으로 바꿔 돌려줄지도 함께 정해야 한다. -## 규칙 +## 세션과 Authorized Client를 서버가 함께 관리한다 ### 1. 브라우저에는 OAuth 토큰을 전달하지 않는다 @@ -77,7 +77,7 @@ Resource Server가 응답하지 않거나 처리가 늦어지는 경우에도 화면의 모든 요청이 BFF를 지나는 구조라면 이런 오류 처리 규칙도 BFF에서 일관되게 적용하는 편이 낫다. 그렇지 않으면 같은 종류의 오류를 화면마다 서로 다르게 판단하고 처리할 수 있다. -이 규칙이 정하는 것은 Resource Server가 돌려준 오류를 무엇으로 바꿔 내보낼지까지다. 토큰 갱신이 실패했을 때와 로그아웃한 뒤에 브라우저가 무엇을 받는지도 같은 종류의 질문이지만, 그것을 어느 계층이 최종 HTTP 응답으로 바꿀지는 이 기준에서 정하지 않았다. +Resource Server의 401·403을 BFF가 어떤 응답으로 변환할지는 정해야 한다. refresh 실패와 로그아웃 뒤 브라우저 응답도 같은 범주이며, 어느 계층이 최종 HTTP 응답을 만들지 아직 확정하지 않았다. ### 5. BFF에서도 XSS 방어는 별도로 필요하다 @@ -87,20 +87,20 @@ BFF 구조에서는 액세스 토큰과 리프레시 토큰을 서버가 보관 BFF에서는 OAuth 토큰 원문이 브라우저 JavaScript에 직접 드러나지 않지만, XSS(Cross-Site Scripting) 자체를 막는 CSP(Content Security Policy)와 출력 인코딩 같은 보호 조치, 그리고 외부 스크립트와 의존성을 안전하게 관리하는 방법은 따로 적용해야 한다. 악성 스크립트가 사용자의 세션으로 BFF를 호출하더라도 허용된 작업만 할 수 있도록, 애플리케이션의 인가 역시 요청마다 검증해야 한다. -## 적용 조건 +## server-side API composition이 필요한 경우 - 브라우저가 OAuth 토큰을 받아서는 안 될 때 - 백엔드가 화면에 맞춰 여러 API를 조합해야 할 때 - 로그인 상태를 애플리케이션이 소유해야 할 때 - 호출할 API가 늘어나도 브라우저는 BFF 하나만 알게 하고 싶을 때 -## 예외 +## BFF가 XSS와 애플리케이션 인가까지 대신 해결하지는 않는다 -- 서버에 상태를 두지 않는 직접 API 호출과 독립 클라이언트가 핵심이면 BFF 구조로 설계하지 않는다. 서버 상태와 단일 장애 지점만 늘어난다. +- 브라우저가 Resource Server를 직접 호출해야 하거나 서버 상태를 두지 않는 구성이 필요한 경우에는 BFF가 맞지 않을 수 있다. BFF를 추가하면 세션과 Authorized Client 상태를 운영해야 한다. - 브라우저가 API를 직접 호출해야 하는 구조라면 갱신용 자격 증명만 서버로 분리하는 구조가 맞다. - 서버에 상태를 둘 수 없는 환경이면 브라우저가 토큰을 직접 다루는 구조가 더 단순하다. -## 예시 +## AP3에서 브라우저와 BFF가 나누어 맡는 책임 - 브라우저 요청에는 Authorization 헤더가 없고 세션 쿠키만 있다 - BFF가 인가된 클라이언트에서 액세스 토큰을 읽어 Resource Server용 Bearer 요청을 새로 만든다 diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-forward-auth-header-trust.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-forward-auth-header-trust.md index 0c4aa8b..6481519 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-forward-auth-header-trust.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-forward-auth-header-trust.md @@ -22,16 +22,16 @@ source: 애플리케이션이 프록시가 붙인 사용자 정보 헤더만 보고 로그인한 사용자를 정하는 구조라면, 그 헤더가 정말 신뢰할 수 있는 프록시에서 온 것인지를 보장해야 한다. -## 관계 +## Forward-Auth에서는 identity header가 인증 결과가 된다 - **Forward-Auth에서 Client가 보낸 Identity Header를 신뢰하면 안 되는 이유** 앞에서 정리한 다섯 가지 조건이 실제 설정에 적용되어 있는지 확인한 결과. - **Forward-Auth 구조에서 Application Authorization을 어디까지 Edge에 둘 것인가** - 헤더를 어디까지 늘릴지가 이 기준의 미결 항목이다. + 현재는 `user`와 `email`만 전달하며 역할이나 권한 정보를 Edge에서 전달할지는 아직 정하지 않았다. - **OAuth Token과 Application Session을 구분하는 기준** 사용자 정보 헤더를 JWT나 세션과 같은 이름으로 부르지 않는다. -## 목적 +## 클라이언트가 만든 헤더와 프록시가 만든 헤더를 구분한다 Forward-auth는 요청을 애플리케이션에 넘기기 전에 별도의 인증 엔드포인트에 이 요청을 통과시켜도 되는지 먼저 묻는 방식이다. 인증에 성공하면 프록시가 사용자 정보 헤더를 붙여 주므로, 애플리케이션은 그 헤더를 기준으로 로그인한 사용자를 판단할 수 있다. @@ -39,7 +39,7 @@ Forward-auth는 요청을 애플리케이션에 넘기기 전에 별도의 인 그래서 사용자 정보 헤더를 인증 근거로 쓰려면 외부 요청이 인증 프록시를 거쳐야만 애플리케이션에 닿도록 경로부터 짜야 한다. 여기에 더해 애플리케이션이 받은 요청과 헤더가 신뢰할 수 있는 프록시를 지나온 것인지 확인할 방법도 같이 정한다. -## 규칙 +## 신뢰할 헤더는 프록시 경계에서 다시 만든다 ### 1. 외부에서 애플리케이션과 인증 프록시에 직접 접근하지 못하게 한다 @@ -91,20 +91,20 @@ Nginx에서는 해당 location에 internal을 설정해 외부에서 직접 부 이 네 가지를 확인한 것은 Nginx 설정 하나에서다. 같은 조건이 Traefik ForwardAuth 같은 다른 forward-auth 구현에서도 그대로 성립하는지는 확인하지 못했다. 대안 설정으로 같은 속성을 내려면 전달 헤더를 믿지 않도록 끄는 설정, 인증 응답 헤더를 허용 목록대로만 복사하는 처리, 별도의 로그인 리다이렉트 흐름, 업스트림 내부 자격 증명이나 더 강한 Workload Identity 주입이 함께 필요했다. 살펴본 대안 설정에는 마지막 항목이 없어서 같은 속성을 낸다고 입증하지 못했다. -## 적용 조건 +## upstream이 JWT 대신 identity header를 신뢰하는 경우 - 업스트림에 OAuth 클라이언트나 JWT 검증 코드를 넣기 어려울 때 - 레거시 서비스 여러 개 앞에 같은 로그인 정책을 걸 때 - 엣지에서 정책을 강제할 수 있을 때 - 이미 forward-auth로 돌아가는 구조를 점검할 때 -## 예외 +## 프록시 우회 경로가 열려 있으면 헤더 검증만으로 부족하다 - 백엔드로 바로 가는 경로나 헤더 덮어쓰기를 닫을 수 없는 환경이면 이 구조를 쓰지 않는다. - 애플리케이션이 사용자별 API 조합과 세밀한 인가를 직접 맡아야 하면 BFF(Backend For Frontend) 구조를 검토한다. - 임의 경로와 본문, 스트리밍을 그대로 넘기는 범용 리버스 프록시가 필요하면 URI 재작성과 타임아웃, 응답 헤더 처리를 따로 설계해야 한다. -## 예시 +## user와 email을 upstream으로 전달하는 현재 구성 - 외부에 여는 것은 엣지뿐이고 애플리케이션과 인증 프록시의 포트는 호스트에 열지 않는다 - 정상 세션에 위조 헤더를 얹은 요청은 200을 받지만 응답에 실린 사용자는 실제 사용자다 diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-idp-federation-boundary.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-idp-federation-boundary.md index 8700544..ea17b85 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-idp-federation-boundary.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-idp-federation-boundary.md @@ -18,24 +18,24 @@ source: # 외부 IdP 연동과 Application 인증 구조의 경계 -Google 로그인을 붙였다고 해서 SPA, Mediator, BFF, OAuth2-Proxy에 이어 다섯 번째 인증 구조가 새로 생기는 것은 아니다. 사용자가 Google에서 인증을 마치면 Keycloak이 그 결과를 받아 사용자를 확인하고, 애플리케이션에는 Keycloak 자신이 발급한 Authorization Code를 전달한다. +Google 로그인을 추가해도 애플리케이션이 상대하는 issuer는 Keycloak으로 유지된다. 사용자는 Google에서 인증하지만 Keycloak이 그 결과를 받아 사용자를 연결하고, 애플리케이션에는 Keycloak이 발급한 Authorization Code와 토큰을 전달한다. -## 관계 +## 외부 IdP 인증과 애플리케이션 OAuth 경계는 다르다 - **외부 IdP와의 연동이라도 별도의 인증 방식이 아니다.** - 이 기준을 프로젝트 결정으로 굳힌 기록이다. + 외부 IdP 연동은 애플리케이션 인증 패턴과 분리해서 설계하고 검증한다. - **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계** 브로커가 만든 authorization code를 애플리케이션이 받는 흐름이다. - **Authorization Code Flow의 Endpoint와 Credential 이동 기준** 외부 IdP를 붙여도 애플리케이션이 오가는 endpoint의 순서는 바뀌지 않는다. -## 목적 +## Google 연동 뒤에도 issuer가 누구인지 분리해서 본다 외부 IdP(Identity Provider)는 Keycloak 앞에서 사용자 인증을 수행한다. Google이 그중 하나다. 사용자가 Keycloak 로그인 화면에서 Google을 고르면 브라우저는 Google에서 인증을 마친다. Keycloak은 그 결과를 검증해 realm 사용자와 연결한 뒤 자신이 발급한 Authorization Code를 애플리케이션에 전달한다. Google 같은 외부 IdP가 추가돼도 애플리케이션이 상대하는 OAuth 경계는 Keycloak이다. 토큰을 브라우저가 받을지 서버가 관리할지와 Resource Server를 누가 호출할지는 기존 SPA, Mediator, BFF, OAuth2-Proxy 구조가 정한다. -## 규칙 +## 애플리케이션에는 Keycloak이 code와 token을 발급한다 ### 1. 외부 IdP 인증과 애플리케이션 인증 구조를 나눈다 @@ -65,19 +65,19 @@ Google에서 인증이 끝나면 그 결과는 먼저 Keycloak이 검증한다. 실제 계정 로그인, 공개 HTTPS callback, 사용자 동의(Consent), 외부 IdP의 도메인 정책은 확인하지 않았다. 따라서 mock provider 검증 결과를 실제 IdP 운영 연동의 완료 조건으로 쓰지 않는다. -## 적용 조건 +## Keycloak이 외부 IdP broker로 동작하는 경우 - 외부 IdP를 붙일 때 - 계정 연결 규칙을 정할 때 - 검증 범위를 문서로 적을 때 - 브로커를 거치는 흐름과 직접 OIDC 흐름을 비교할 때 -## 예외 +## 계정 연결 규칙은 애플리케이션 인증 패턴과 별도로 정한다 - 애플리케이션이 Keycloak 같은 브로커를 거치지 않고 Google 등 외부 IdP와 직접 OIDC 연동을 한다면 이야기가 달라진다. 이때는 애플리케이션이 외부 IdP가 직접 발급한 토큰을 쓰므로, 그 외부 IdP를 신뢰하고 토큰을 검증한다. - 조직에서 외부 IdP를 하나만 쓴다면 Keycloak 같은 브로커를 따로 두지 않고 애플리케이션이 그 IdP와 직접 연동하는 구조도 고를 수 있다. 이때는 여러 외부 IdP에서 들어온 계정을 하나의 내부 사용자와 어떻게 연결할지 정하는 계정 연결 정책이 대부분 필요 없다. -## 예시 +## Google에서 인증하고 Keycloak으로 돌아오는 흐름 - Google 로그인을 추가해도 애플리케이션이 고르는 것은 여전히 4가지 구조 중 하나다 - 브로커는 provider alias + upstream subject 조합을 기준으로 외부 계정을 식별한다 diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-pattern-selection.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-pattern-selection.md index 7f4e9ed..4a6b030 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-pattern-selection.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-pattern-selection.md @@ -22,7 +22,7 @@ source: SPA(Single Page Application), Mediator, BFF(Backend for Frontend), Forward-Auth는 토큰과 인증 상태를 다루는 방식이 서로 다르다. 브라우저가 액세스 토큰을 직접 쓰는지, Resource Server를 누가 호출하는지, 서버가 어떤 인증 상태를 보관하는지, Resource Server가 어떤 자격 증명을 검증하는지, CSRF(Cross-Site Request Forgery)를 어느 계층에서 처리하는지를 나란히 놓고 비교할 수 있다. 애플리케이션의 요구사항과 배포·운영 환경에 맞춰 고른다. -## 관계 +## 네 패턴은 토큰과 세션의 경계를 다르게 둔다 - **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계** 브라우저가 인가 코드를 토큰으로 바꾸고, 그 토큰을 들고 있다가, API까지 직접 호출한다. @@ -33,7 +33,7 @@ SPA(Single Page Application), Mediator, BFF(Backend for Frontend), Forward-Auth - **Forward-Auth에서 Client가 보낸 Identity Header를 신뢰하면 안 되는 이유** 인증을 엣지로 옮기면 보호 자원이 검증하는 대상이 JWT에서 헤더로 바뀐다. -## 목적 +## 브라우저 token 유무와 API caller를 기준으로 비교한다 브라우저에 OAuth 토큰이 노출되는 정도만 놓고 보면 구조마다 차이가 난다. 다만 토큰을 다른 계층으로 옮기면 브라우저에 노출되는 범위가 달라지는데, 그 토큰을 맡은 계층에서는 처리해야 할 항목이 늘어난다. @@ -43,7 +43,7 @@ Forward-Auth 구조에서는 애플리케이션이 OAuth 토큰을 직접 관리 선택 기준은 어느 구조가 더 안전한지에 대한 단일 순위가 아니라, 요구사항마다 달라지는 자격 증명 위치와 운영 책임이다. -## 규칙 +## 토큰 보관 위치와 서버 상태를 함께 본다 ### 1. 다섯 항목으로 구조를 비교한다 @@ -63,7 +63,7 @@ Forward-Auth에서는 인증 프록시가 세션을 관리하고, 인증이 끝 마찬가지로 애플리케이션으로 바로 들어오는 경로를 막을 수 없거나, 밖에서 들어온 사용자 정보 헤더를 엣지에서 확실히 지우거나 덮어쓸 수 없다면, 엣지가 전달한 사용자 정보를 인증 근거로 쓰는 구조는 고르지 않는다. -### 3. 선택 조건과 운영 책임을 같이 문서화한다 +### 3. 패턴을 선택할 때 운영 책임도 함께 확인한다 선택 기록에는 구조 이름과 함께 그 선택을 만든 보안 요구사항과 운영 조건이 들어간다. @@ -83,18 +83,18 @@ Forward-Auth에서는 인증 프록시가 세션을 관리하고, 인증이 끝 엣지가 전달할 정보가 역할·권한·도메인 정보까지 늘어나고 여러 API 응답의 조합과 인가 판단도 필요해지면, BFF가 인가와 API 호출을 소유하는 구성이 비교 대상이 된다. -## 적용 조건 +## 요구사항에 따라 AP1부터 AP4 가운데 하나를 고를 때 - 인증 구조를 처음 고를 때 - 한 구조에서 다른 구조로 옮기려 할 때 - 구조를 문서로 비교할 때 -## 예외 +## 외부 IdP 선택은 별도 패턴으로 세지 않는다 -- 이 문서에서 비교하는 AP1~AP4 네 패턴만 놓고 보면, 브라우저에 OAuth token을 둘 수 없고 server-side API composition이 필요할 때 AP3 BFF가 해당 조건을 만족한다. +- AP1~AP4 가운데 브라우저 JavaScript에 OAuth token을 두지 않으면서 server-side API composition이 필요한 경우에는 AP3 BFF가 해당 조건을 만족한다. - 학습이나 시연이 목적이면 운영 속성까지 비교하지 않아도 된다. -## 예시 +## 브라우저 token을 없애고 API composition이 필요한 경우 - SPA: 브라우저가 인가 코드 교환과 토큰 보관, API 호출을 모두 맡는다. - Mediator: 리프레시 토큰은 서버에 두고, 액세스 토큰은 응답 본문으로 브라우저에 돌려준다. diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-public-confidential-client.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-public-confidential-client.md index 13df6aa..8bdab9e 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-public-confidential-client.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-public-confidential-client.md @@ -23,7 +23,7 @@ source: OAuth 클라이언트 종류는 인증 서버에 대해 장기 자격 증명의 기밀성을 유지하고 신뢰할 수 있는 클라이언트 인증을 수행할 수 있는지로 구분한다. AP1의 SPA(Single Page Application)는 브라우저 실행 환경에서 이 조건을 충족하기 어려워 public client로 두었다. AP2~AP4는 서버 구성요소가 자격 증명을 보호할 수 있어 confidential client로 구성했고, 이 프로젝트에서는 `client_secret_basic`을 사용한다. -## 관계 +## OAuth client type은 secret 보관 능력으로 나뉜다 - **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계** SPA를 public client로 등록한 이유를 실제 구성에서 확인할 수 있다. @@ -32,7 +32,7 @@ AP1의 SPA(Single Page Application)는 브라우저 실행 환경에서 이 조 - **Authorization Code Flow의 Endpoint와 Credential 이동 기준** public client와 confidential client는 토큰 엔드포인트에서 사용하는 클라이언트 인증 방식이 다르다. -## 목적 +## 브라우저 token 노출 여부와 client type을 혼동하지 않는다 클라이언트 종류가 정하는 범위는 자격 증명 보호와 클라이언트 인증이다. PKCE(Proof Key for Code Exchange)는 authorization code를 교환하는 쪽이 원래 verifier를 가진 주체인지 확인하는 별도 보호 장치라서 클라이언트 인증과 함께 사용할 수 있다. @@ -40,7 +40,7 @@ AP1 SPA는 public client이고 브라우저가 code를 직접 교환한다. AP2~ 토큰 보관 위치와 API 호출 주체는 클라이언트 종류와 다른 축이다. 같은 confidential client라도 AP2는 액세스 토큰을 브라우저에 돌려주고, AP3 BFF(Backend for Frontend)와 AP4 프록시는 서버 쪽에서 다음 요청을 만든다. -## 규칙 +## secret을 안전하게 보관할 수 없으면 public client로 둔다 ### 1. 실행 환경에서 장기 자격 증명을 보호할 수 있는지 구분한다 @@ -78,19 +78,19 @@ confidential client가 authorization code를 교환해도 액세스 토큰을 AP3 BFF와 AP4 프록시는 다음 API 요청을 서버 쪽에서 만들기 때문에 브라우저에 액세스 토큰을 줄 필요가 없다. 세 구조가 모두 confidential client라는 사실만으로 이 차이는 설명되지 않는다. -## 적용 조건 +## SPA와 server-side component의 client 등록을 나눌 때 - 새 OAuth 클라이언트를 등록할 때 - SPA와 서버 중 어디가 code를 교환할지 정할 때 - PKCE와 클라이언트 인증을 어디에 걸지 정할 때 - 기존 클라이언트의 종류가 맞는지 다시 볼 때 -## 예외 +## public과 confidential 구분만으로 code exchange 위치가 결정되지는 않는다 - 같은 서비스가 브라우저용 public client와 서버용 confidential client를 따로 등록할 수 있다. - 백엔드가 사용자 없이 자기 자격으로 부르는 흐름은 Client Credentials를 쓰는 별도 클라이언트다. -## 예시 +## AP1 public client와 AP2부터 AP4 confidential client - SPA용 클라이언트 : public, standard flow만 켜고 implicit flow와 direct grant는 끈다 - mediator용 클라이언트 : confidential, client_secret_basic으로 token endpoint에서 인증한다 diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-runtime-verification-order.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-runtime-verification-order.md index 1a4de7b..41bc351 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-runtime-verification-order.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-runtime-verification-order.md @@ -17,18 +17,18 @@ source: 네 패턴의 경계가 실제로 성립하는지 보려면 스택을 띄우고 브라우저로 로그인까지 해 봐야 하는데, 패턴별 검증 절차는 스택을 다시 만들기 전에 볼륨을 초기화한다. 보존해야 할 realm이나 데이터베이스가 같은 Compose 프로젝트에 있으면 검증을 돌리는 사이에 그 데이터를 잃는다. -## 관계 +## 패턴별 경계는 실제 로그인 흐름으로 확인한다 - **Forward-Auth에서 Client가 보낸 Identity Header를 신뢰하면 안 되는 이유** 이 절차로 확인하는 경계 가운데 하나다. 위조 헤더를 보내 보는 것이 5번 규칙의 부정 입력이다. - **OAuth/OIDC 인증 패턴 선택 기준** 어느 구조를 고를지는 그 기준으로 정하고, 고른 구조가 실제로 그렇게 동작하는지는 이 절차로 확인한다. -## 목적 +## 한 번에 한 패턴만 띄워 관측값의 출처를 분명히 한다 이 절차는 두 가지를 막는다. 보존해야 할 realm과 데이터베이스를 검증 도중에 지우는 일과, 앞 단계가 어긋났는데도 나머지를 계속 돌려 마지막에 전체 통과를 남기는 일이다. -## 규칙 +## 데이터를 지우기 전에 보존 대상을 먼저 확인한다 ### 1. 대상이 일회용 환경인지 확정한 뒤에 시작한다 @@ -56,7 +56,7 @@ secret과 테스트 사용자 비밀번호는 환경변수로 주입하고 출 위조 헤더를 넣어도 로그인 세션 자체는 유효하기 때문에 요청은 200으로 돌아온다. 판정은 응답에 남은 사용자 이름으로 한다. 그 이름이 위조한 값이 아니라 원래 사용자면 프록시가 헤더를 덮어쓴 것이다. -여기서 관측할 값과 넣을 부정 입력은 커밋된 자동 테스트가 확인하도록 정의한 계약에서 온 것이고, 최신 실행 성적표가 아니다. 그래서 여기 넣는 부정 입력에 서명이 깨진 토큰과 만료된 토큰은 들어 있지 않다. 단위 테스트에서 합성 JWT를 주입해 컨트롤러가 200을 주는 것을 확인했더라도, 실제 서명 검증과 issuer 검증을 통과했다는 증거는 아니다. +여기서 관측할 값과 부정 입력은 커밋된 자동 테스트에 정의된 검증 항목을 기준으로 한다. 최신 실행 결과를 그대로 옮긴 목록은 아니다. 그래서 여기 넣는 부정 입력에 서명이 깨진 토큰과 만료된 토큰은 들어 있지 않다. 단위 테스트에서 합성 JWT를 주입해 컨트롤러가 200을 주는 것을 확인했더라도, 실제 서명 검증과 issuer 검증을 통과했다는 증거는 아니다. ### 6. 중단 조건에 걸리면 멈추고 그 지점을 보존한다 @@ -73,18 +73,18 @@ secret과 테스트 사용자 비밀번호는 환경변수로 주입하고 출 검증이 끝나면 테스트용 스택을 내린다. 백업이 필요했던 환경이라면 원래 프로젝트와 볼륨을 복구한 뒤 health와 로그인을 다시 확인한다. -## 적용 조건 +## Compose 스택을 다시 만들며 패턴을 검증하는 경우 - 검증 절차에 볼륨 초기화나 스키마 재생성처럼 되돌릴 수 없는 단계가 들어 있을 때 - 실제 브라우저와 컨테이너를 띄워야 확인되는 경계를 다룰 때 - 여러 구성을 같은 호스트에서 번갈아 검증할 때 -## 예외 +## 공유 볼륨에 보존할 데이터가 있으면 초기화 절차를 그대로 쓰지 않는다 - 일회용 환경이 아니면 이 절차를 그대로 실행하지 않는다. 별도 프로젝트로 복제한 뒤 그쪽에서 돌린다. - 정적 검사만으로 판정이 끝나는 항목은 스택을 띄우지 않는다. 4번 규칙의 앞 절반만 적용한다. -## 예시 +## 패턴 하나를 선택해 로그인부터 API 호출까지 확인하는 순서 - 볼륨 소유자를 확정하지 못한 경우: 시작하지 않고 별도 프로젝트로 복제한다 - 정적 realm 검증에서 redirect URI 불일치: 브라우저 E2E로 진행하지 않고 설정을 고친다 diff --git a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-token-vs-session.md b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-token-vs-session.md index a635bfd..0d40bd4 100644 --- a/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-token-vs-session.md +++ b/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-token-vs-session.md @@ -21,7 +21,7 @@ source: IdP의 SSO 세션, 액세스 토큰, 리프레시 토큰, 애플리케이션의 세션 쿠키, 인증 프록시의 세션 쿠키는 만드는 쪽과 쓰는 쪽이 각각 다르고 유효 시간도 서로 다르다. -## 관계 +## OAuth token과 application session은 서로 다른 상태다 - **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계** JavaScript 메모리의 OAuth 토큰과 Keycloak SSO 세션을 구분한 사례다. @@ -32,13 +32,13 @@ IdP의 SSO 세션, 액세스 토큰, 리프레시 토큰, 애플리케이션의 - **Forward-Auth에서 Client가 보낸 Identity Header를 신뢰하면 안 되는 이유** Forward-Auth에서는 업스트림이 JWT를 직접 검증하지 않고, 프록시 세션을 근거로 엣지가 만든 사용자 정보 헤더를 쓴다. -## 목적 +## 누가 만들고 누가 사용하는지 기준으로 상태를 구분한다 SPA(Single Page Application, 단일 페이지 애플리케이션), Mediator, BFF(Backend For Frontend) 구성에서는 Resource Server가 액세스 토큰을 검증한 뒤 JWT의 클레임에서 사용자 정보를 얻을 수 있다. Forward-Auth 구성에서는 애플리케이션이 인증 프록시가 전달한 사용자 정보 헤더를 쓴다. 두 경로가 같은 사용자 이름을 내놓더라도 한쪽은 액세스 토큰을 검증해서 얻은 값이고, 다른 한쪽은 신뢰하기로 정한 프록시가 전달한 값이다. 예를 들어 액세스 토큰의 `preferred_username`과 프록시가 만든 `X-Auth-Request-User`에는 모두 `regular-user`가 들어갈 수 있고, 이름만으로는 어느 쪽을 검증해서 얻은 값인지 구분되지 않는다. 로그아웃과 만료 처리에서도 같은 구분이 필요하다. IdP의 SSO 세션, 액세스 토큰과 리프레시 토큰, 애플리케이션 세션은 서로 다른 주체가 관리하고 수명도 다르다. 액세스 토큰이 만료되었다고 해서 애플리케이션 세션이나 IdP의 SSO 세션까지 같이 만료된 것은 아니다. 그래서 로그아웃할 때 무엇을 삭제하거나 무효화할지, 어떤 자격 증명이 만료되었을 때 어떤 상태를 계속 쓸 수 있는지를 각각 나눠서 설계한다. -## 규칙 +## SSO session과 token, application cookie를 같은 수명으로 보지 않는다 ### 1. 인증 상태를 종류별로 구분해서 기록한다 @@ -86,21 +86,21 @@ SPA에서 JavaScript 메모리에 두었던 OAuth 토큰을 지워도 Keycloak Mediator나 BFF처럼 서버가 애플리케이션 세션과 Authorized Client를 함께 관리하는 구조에서는 두 상태를 정리하는 방법도 각각 적는다. 애플리케이션 세션을 무효화하는 것과 Authorized Client에 저장된 액세스 토큰과 리프레시 토큰을 지우는 것은 서로 다른 처리이므로, 로그아웃할 때 어떤 상태를 삭제하고 어떤 상태를 유지할지 따로 확인한다. -## 적용 조건 +## 로그인 유지와 token 갱신 문제를 분석할 때 - 인증 상태를 표나 문서로 정리할 때 - 로그아웃과 만료 동작을 설계할 때 - 브라우저가 어떤 자격 증명을 저장하거나 전송하는지 설명할 때 - 여러 구조를 비교할 때 -## 예외 +## IdP session이 살아 있어도 application session은 끝날 수 있다 - 하나의 요청 흐름 안에서 어떤 세션이나 토큰을 가리키는지 이미 분명하면 짧은 이름을 쓸 수 있다. 다만 문서에 처음 나올 때는 전체 이름을 먼저 적어 어떤 상태를 가리키는지 분명하게 정의하고, 이후 같은 문맥에서는 뜻이 달라지지 않는 범위에서 세션, 액세스 토큰, 리프레시 토큰처럼 줄여서 쓸 수 있다. - IdP를 쓰지 않고 애플리케이션이 자체 로그인만 하는 구조에는 SSO 세션과 액세스 토큰, 리프레시 토큰이 없다. -## 예시 +## Keycloak SSO와 AP2·AP3·AP4 session cookie의 차이 - IdP SSO 세션 : IdP 도메인의 쿠키이고 애플리케이션 메모리와 별개다 - 액세스 토큰 : IdP가 만들고 Resource Server가 서명과 issuer, audience를 검증한다 diff --git a/docs/keycloak/tech-log-studio/tech-log-tree.json b/docs/keycloak/tech-log-studio/tech-log-tree.json index 799e050..e395329 100644 --- a/docs/keycloak/tech-log-studio/tech-log-tree.json +++ b/docs/keycloak/tech-log-studio/tech-log-tree.json @@ -102,7 +102,7 @@ "kinds": { "case": [ { - "title": "SPA에서 OAuth Token을 JavaScript Memory에 보관한 경우", + "title": "SPA에서 OAuth Token을 JavaScript 메모리에만 보관한 방식", "slug": "spa-browser-credential-boundary", "readiness": "READY", "source": [ @@ -144,7 +144,7 @@ "evidenceFiles": [] }, { - "title": "Refresh Token 관리만 서버로 이전, Access Token은 여전히 Browser에 노출", + "title": "Mediator에서는 Refresh Token만 서버에 남고 Access Token은 브라우저로 돌아온다", "slug": "split-custody-access-token", "readiness": "READY", "source": [ @@ -187,7 +187,7 @@ "evidenceFiles": [] }, { - "title": "BFF에서 Browser Token을 제거하고 Session과 CSRF를 처리한 방식", + "title": "BFF에서 OAuth Token을 브라우저 밖으로 옮기고 Session과 CSRF를 처리한 방식", "slug": "bff-session-csrf-responsibility", "readiness": "READY", "source": [ @@ -779,7 +779,7 @@ "evidenceFiles": [] }, { - "title": "외부 IdP와의 연동이라도 별도의 인증 방식이 아니다.", + "title": "외부 IdP 연동은 별도의 애플리케이션 인증 패턴이 아니다", "slug": "federation-is-not-an-application-pattern", "readiness": "READY", "decision-status": "ADOPTED",