donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: 문서 구조 변경 및 tech-visual 스킬 추가

Browse Source
This commit is contained in:
DongHyeonka
2026-09-04 18:20:00 +09:00
parent 43901f0abf
commit 2efb7ee1f2
683 changed files with 61180 additions and 10479 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/keycloak/final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.alt.md
+25
View File
@@ -0,0 +1,25 @@
# AP4 proxy session에서 trusted identity JSON까지
## Alternative text
브라우저, Nginx, oauth2-proxy, Spring upstream 사이에서 AP4_SESSION 검증, identity header 덮어쓰기, internal token 검증과 JSON 응답이 이어지는 순서도.
## Long description
브라우저가 AP4_SESSION cookie로 Nginx의 /api/edge를 호출한다. Nginx는 oauth2-proxy의 internal auth endpoint에 subrequest를 보내고 인증된 user와 email 결과를 받는다. 이어서 client가 보낸 동명 header를 사용하지 않고 oauth2-proxy 결과와 Nginx 환경의 internal token으로 /edge/me 요청을 새로 조립한다. Spring controller가 user header와 internal token을 함께 확인해 identity JSON을 만들고 Nginx가 브라우저에 전달한다.
## Elements and evidence
- **브라우저** (participant): AP4_SESSION cookie와 함께 edge endpoint를 호출하는 외부 client. Evidence: L992–L1007.
- **Nginx edge** (participant): Internal auth subrequest를 만들고 인증 결과를 allowlisted upstream header와 internal token으로 재조립한다. Evidence: L914–L939, L1009–L1028.
- **oauth2-proxy** (participant): AP4_SESSION을 검증하고 인증된 user, email과 필요 시 갱신 cookie를 auth response로 돌려준다. Evidence: L980–L990, L1009–L1015.
- **Spring upstream** (participant): Identity header와 internal token을 함께 검증해 allowlisted identity JSON을 반환한다. Evidence: L1017–L1026, L1030–L1063.
## Relationships
- **브라우저 → Nginx edge:** GET /api/edge + AP4_SESSION. Evidence: L992–L999.
- **Nginx edge → oauth2-proxy:** internal /oauth2/auth subrequest. Evidence: L922–L939, L1009–L1009.
- **oauth2-proxy → Nginx edge:** authenticated user + email. Evidence: L1009–L1015.
- **Nginx edge → Spring upstream:** GET /edge/me · trusted headers + internal token. Evidence: L1017–L1026.
- **Spring upstream → Nginx edge:** trusted identity JSON. Evidence: L1030–L1048.
- **Nginx edge → 브라우저:** pattern + user + email + identityHeader. Evidence: L1039–L1048, L1065–L1076.
docs/keycloak/final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.d2
+21
View File
@@ -0,0 +1,21 @@
# AP4 proxy session에서 trusted identity JSON까지
# Question: AP4에서 AP4_SESSION은 어떤 순서로 검증되고 allowlisted identity header와 internal token을 거쳐 JSON이 되는가?
direction: right
n0: "브라우저" {
shape: rectangle
}
n1: "Nginx edge" {
shape: rectangle
}
n2: "oauth2-proxy" {
shape: rectangle
}
n3: "Spring upstream" {
shape: rectangle
}
n0 -> n1: "GET /api/edge + AP4_SESSION"
n1 -> n2: "internal /oauth2/auth subrequest"
n2 -> n1: "authenticated user + email"
n1 -> n3: "GET /edge/me · trusted headers + internal token"
n3 -> n1: "trusted identity JSON"
n1 -> n0: "pattern + user + email + identityHeader"
docs/keycloak/final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.dot
+15
View File
@@ -0,0 +1,15 @@
digraph techviz {
graph [rankdir=LR, splines=ortho, nodesep=0.55, ranksep=0.85];
node [fontname=Helvetica, fontsize=11, margin="0.18,0.12", style="rounded,filled", fillcolor=white, color="#2d4357", penwidth=1.5];
edge [fontname=Helvetica, fontsize=10, color="#364b5f", penwidth=1.4, arrowsize=0.75];
n0 [label="브라우저", shape=box, style="rounded,filled"];
n1 [label="Nginx edge", shape=box, style="rounded,filled"];
n2 [label="oauth2-proxy", shape=box, style="rounded,filled"];
n3 [label="Spring upstream", shape=box, style="rounded,filled"];
n0 -> n1 [label="GET /api/edge + AP4_SESSION", style=solid];
n1 -> n2 [label="internal /oauth2/auth subrequest", style=solid];
n2 -> n1 [label="authenticated user + email", style=solid];
n1 -> n3 [label="GET /edge/me · trusted headers + internal token", style=solid];
n3 -> n1 [label="trusted identity JSON", style=solid];
n1 -> n0 [label="pattern + user + email + identityHeader", style=solid];
}
docs/keycloak/final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.drawio
+53
View File
@@ -0,0 +1,53 @@
<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="app.diagrams.net" modified="2026-07-23T00:00:00.000Z" agent="techviz-harness" version="24.7.17" type="device">
<diagram id="ap4-edge-forward-auth-flow" name="AP4 proxy session에서 trusted identity JSON까지">
<mxGraphModel dx="870" dy="542" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="870" pageHeight="1169" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="n_browser" value="브라우저" tooltip="AP4_SESSION cookie와 함께 edge endpoint를 호출하는 외부 client. | Evidence: L992-L1007" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
<mxGeometry x="45.0" y="35.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_nginx" value="Nginx edge" tooltip="Internal auth subrequest를 만들고 인증 결과를 allowlisted upstream header와 internal token으로 재조립한다. | Evidence: L914-L939, L1009-L1028" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="255.0" y="35.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_oauth2-proxy" value="oauth2-proxy" tooltip="AP4_SESSION을 검증하고 인증된 user, email과 필요 시 갱신 cookie를 auth response로 돌려준다. | Evidence: L980-L990, L1009-L1015" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
<mxGeometry x="465.0" y="35.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_spring-upstream" value="Spring upstream" tooltip="Identity header와 internal token을 함께 검증해 allowlisted identity JSON을 반환한다. | Evidence: L1017-L1026, L1030-L1063" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
<mxGeometry x="675.0" y="35.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="e_edge-request" value="GET /api/edge + AP4_SESSION" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_browser" target="n_nginx">
<mxGeometry relative="1" as="geometry">
<mxPoint x="225.0" y="128.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_auth-subrequest" value="internal /oauth2/auth subrequest" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_nginx" target="n_oauth2-proxy">
<mxGeometry relative="1" as="geometry">
<mxPoint x="435.0" y="190.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_auth-result" value="authenticated user + email" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_oauth2-proxy" target="n_nginx">
<mxGeometry relative="1" as="geometry">
<mxPoint x="435.0" y="252.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_upstream-request" value="GET /edge/me · trusted headers + internal token" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_nginx" target="n_spring-upstream">
<mxGeometry relative="1" as="geometry">
<mxPoint x="540.0" y="314.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_identity-map" value="trusted identity JSON" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_spring-upstream" target="n_nginx">
<mxGeometry relative="1" as="geometry">
<mxPoint x="540.0" y="376.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_browser-response" value="pattern + user + email + identityHeader" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_nginx" target="n_browser">
<mxGeometry relative="1" as="geometry">
<mxPoint x="225.0" y="438.0" as="offset"/>
</mxGeometry>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
docs/keycloak/final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.excalidraw
+835
View File
@@ -0,0 +1,835 @@
{
"type": "excalidraw",
"version": 2,
"source": "techviz-harness",
"elements": [
{
"id": "edge-edge-request",
"type": "arrow",
"x": 120.0,
"y": 140.0,
"width": 210.0,
"height": 0.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 484293938,
"version": 1,
"versionNonce": 138566560,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
210.0,
0.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-browser",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-nginx",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-edge-request",
"type": "text",
"x": 117.0,
"y": 116.0,
"width": 216,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 221805120,
"version": 1,
"versionNonce": 1825067634,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "GET /api/edge + AP4_SESSION",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "GET /api/edge + AP4_SESSION",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-auth-subrequest",
"type": "arrow",
"x": 330.0,
"y": 202.0,
"width": 210.0,
"height": 0.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 1667458436,
"version": 1,
"versionNonce": 1627457069,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
210.0,
0.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-nginx",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-oauth2-proxy",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-auth-subrequest",
"type": "text",
"x": 307.0,
"y": 178.0,
"width": 256,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 667482483,
"version": 1,
"versionNonce": 461894769,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "internal /oauth2/auth subrequest",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "internal /oauth2/auth subrequest",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-auth-result",
"type": "arrow",
"x": 330.0,
"y": 264.0,
"width": 210.0,
"height": 0.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 1075862510,
"version": 1,
"versionNonce": 1988805447,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
210.0,
0.0
],
[
0.0,
0.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-oauth2-proxy",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-nginx",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-auth-result",
"type": "text",
"x": 331.0,
"y": 240.0,
"width": 208,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 863949098,
"version": 1,
"versionNonce": 1824385289,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "authenticated user + email",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "authenticated user + email",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-upstream-request",
"type": "arrow",
"x": 330.0,
"y": 326.0,
"width": 420.0,
"height": 0.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 217844129,
"version": 1,
"versionNonce": 1633365074,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
420.0,
0.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-nginx",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-spring-upstream",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-upstream-request",
"type": "text",
"x": 352.0,
"y": 302.0,
"width": 376,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1518859962,
"version": 1,
"versionNonce": 257106806,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "GET /edge/me · trusted headers + internal token",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "GET /edge/me · trusted headers + internal token",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-identity-map",
"type": "arrow",
"x": 330.0,
"y": 388.0,
"width": 420.0,
"height": 0.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 7171349,
"version": 1,
"versionNonce": 969751315,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
420.0,
0.0
],
[
0.0,
0.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-spring-upstream",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-nginx",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-identity-map",
"type": "text",
"x": 456.0,
"y": 364.0,
"width": 168,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 509639853,
"version": 1,
"versionNonce": 489035676,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "trusted identity JSON",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "trusted identity JSON",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-browser-response",
"type": "arrow",
"x": 120.0,
"y": 450.0,
"width": 210.0,
"height": 0.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 1388383895,
"version": 1,
"versionNonce": 1053957646,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
210.0,
0.0
],
[
0.0,
0.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-nginx",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-browser",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-browser-response",
"type": "text",
"x": 69.0,
"y": 426.0,
"width": 312,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1885175380,
"version": 1,
"versionNonce": 735131413,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "pattern + user + email + identityHeader",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "pattern + user + email + identityHeader",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-browser",
"type": "rectangle",
"x": 45.0,
"y": 35.0,
"width": 150.0,
"height": 64.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1549664096,
"version": 1,
"versionNonce": 397227867,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-browser",
"type": "text",
"x": 55.0,
"y": 45.0,
"width": 130.0,
"height": 44.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 225442297,
"version": 1,
"versionNonce": 1441680053,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "브라우저",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "브라우저",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-nginx",
"type": "rectangle",
"x": 255.0,
"y": 35.0,
"width": 150.0,
"height": 64.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 721013300,
"version": 1,
"versionNonce": 1520646945,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-nginx",
"type": "text",
"x": 265.0,
"y": 45.0,
"width": 130.0,
"height": 44.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 117243520,
"version": 1,
"versionNonce": 936748041,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "Nginx edge",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "Nginx edge",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-oauth2-proxy",
"type": "rectangle",
"x": 465.0,
"y": 35.0,
"width": 150.0,
"height": 64.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1926678177,
"version": 1,
"versionNonce": 124865767,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-oauth2-proxy",
"type": "text",
"x": 475.0,
"y": 45.0,
"width": 130.0,
"height": 44.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 211503580,
"version": 1,
"versionNonce": 929312460,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "oauth2-proxy",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "oauth2-proxy",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-spring-upstream",
"type": "rectangle",
"x": 675.0,
"y": 35.0,
"width": 150.0,
"height": 64.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1886263514,
"version": 1,
"versionNonce": 1117537622,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-spring-upstream",
"type": "text",
"x": 685.0,
"y": 45.0,
"width": 130.0,
"height": 44.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1165629413,
"version": 1,
"versionNonce": 1538645325,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "Spring upstream",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "Spring upstream",
"autoResize": true,
"lineHeight": 1.25
}
],
"appState": {
"gridSize": 10,
"viewBackgroundColor": "#ffffff",
"currentItemFontFamily": 5
},
"files": {}
}
docs/keycloak/final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.manifest.json
+32
View File
@@ -0,0 +1,32 @@
{
"harness_version": "0.2.0",
"spec_id": "ap4-edge-forward-auth-flow",
"spec_version": "1.1",
"spec_sha256": "18ce47da22142be0655461f3677df193562cb037f936b1a8f3d846665187f300",
"source_context": {
"document": "document.md",
"document_sha256": "df4d1a604c74e756672b5b40510abfedb8c67b39af280a5f51985ea9972f5371",
"anchor": {
"kind": "marker",
"value": "ap4-edge-forward-auth-flow",
"line": 1108
}
},
"outputs": [
"ap4-edge-forward-auth-flow.svg",
"ap4-edge-forward-auth-flow.drawio",
"ap4-edge-forward-auth-flow.mmd",
"ap4-edge-forward-auth-flow.d2",
"ap4-edge-forward-auth-flow.dot",
"ap4-edge-forward-auth-flow.excalidraw",
"ap4-edge-forward-auth-flow.alt.md"
],
"lint_issue_count": 0,
"assumption_count": 0,
"assumptions_allowed": false,
"composition_profile": "sequence",
"reference_ids": [
"payment-approval-sequence"
],
"diagram_only": true
}
docs/keycloak/final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.mmd
+13
View File
@@ -0,0 +1,13 @@
%% AP4 proxy session에서 trusted identity JSON까지
%% question: AP4에서 AP4_SESSION은 어떤 순서로 검증되고 allowlisted identity header와 internal token을 거쳐 JSON이 되는가?
sequenceDiagram
participant n0 as 브라우저
participant n1 as Nginx edge
participant n2 as oauth2-proxy
participant n3 as Spring upstream
n0->>n1: GET /api/edge + AP4_SESSION
n1->>n2: internal /oauth2/auth subrequest
n2->>n1: authenticated user + email
n1->>n3: GET /edge/me · trusted headers + internal token
n3->>n1: trusted identity JSON
n1->>n0: pattern + user + email + identityHeader
docs/keycloak/final/assets/ap4-edge-forward-auth-flow/ap4-edge-forward-auth-flow.svg
+83
View File
@@ -0,0 +1,83 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="870" height="542" viewBox="0 0 870 542" role="img" aria-labelledby="diagram-title diagram-description">
<title id="diagram-title">AP4 proxy session에서 trusted identity JSON까지</title>
<desc id="diagram-description">브라우저가 AP4_SESSION cookie로 Nginx의 /api/edge를 호출한다. Nginx는 oauth2-proxy의 internal auth endpoint에 subrequest를 보내고 인증된 user와 email 결과를 받는다. 이어서 client가 보낸 동명 header를 사용하지 않고 oauth2-proxy 결과와 Nginx 환경의 internal token으로 /edge/me 요청을 새로 조립한다. Spring controller가 user header와 internal token을 함께 확인해 identity JSON을 만들고 Nginx가 브라우저에 전달한다.</desc>
<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;ap4-edge-forward-auth-flow&quot;,&quot;profile&quot;:&quot;sequence&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;document.md&quot;,&quot;document_sha256&quot;:&quot;df4d1a604c74e756672b5b40510abfedb8c67b39af280a5f51985ea9972f5371&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;marker&quot;,&quot;value&quot;:&quot;ap4-edge-forward-auth-flow&quot;,&quot;line&quot;:1108}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;,&quot;diagram_only&quot;:true}</metadata>
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
<path d="M 0 0 L 10 5 L 0 10 z" />
</marker>
<style>
:root { color-scheme: light; }
text { font-family: Inter, Pretendard, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #111827; }
.canvas { fill: #ffffff; }
.group-box { fill: #ffffff; stroke: #9ca3af; stroke-width: 1.4; stroke-dasharray: 7 5; }
.group-label-bg { fill: #ffffff; }
.group-label { font-size: 13px; font-weight: 650; fill: #374151; }
.edge { fill: none; stroke: #374151; stroke-width: 1.8; stroke-linejoin: round; stroke-linecap: round; marker-end: url(#arrow); }
.edge.style-dashed, .edge.semantic-dashed, .edge.assumption { stroke-dasharray: 7 5; }
.edge.style-dotted { stroke-dasharray: 2 5; }
.edge.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
.edge.emphasis-muted { stroke: #9ca3af; }
.edge.emphasis-warning, .edge.kind-failure, .edge.kind-error { stroke: #dc2626; stroke-width: 2.2; }
.edge-label-bg { fill: #ffffff; }
.edge-label { font-size: 12px; font-weight: 560; text-anchor: middle; }
.node-shape { fill: #ffffff; stroke: #4b5563; stroke-width: 1.7; }
.node-shape.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
.node-shape.emphasis-muted { stroke: #9ca3af; fill: #f9fafb; }
.node-shape.emphasis-warning { stroke: #d97706; stroke-width: 2; fill: #fffdf5; }
.node-shape.kind-database, .node-shape.kind-datastore, .node-shape.kind-storage { fill: #f8fafc; }
.node-shape.kind-queue, .node-shape.kind-event, .node-shape.kind-topic { fill: #fafafa; }
.node-shape.assumption { stroke-dasharray: 4 4; }
.storage-bottom, .controller-divider { fill: none; stroke: #4b5563; stroke-width: 1.4; }
.controller-led { fill: #4b5563; }
.actor-symbol { fill: none; stroke: #4b5563; stroke-width: 1.8; stroke-linecap: round; }
.actor-symbol.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
.node-label { font-size: 14px; font-weight: 650; text-anchor: middle; }
.node-role { font-size: 10px; letter-spacing: 0.04em; text-anchor: middle; fill: #6b7280; }
.node-detail-divider { stroke: #d1d5db; stroke-width: 1; }
.node-detail { font-size: 11px; fill: #374151; }
.assumption-badge { font-size: 9px; font-weight: 700; fill: #92400e; }
.failure-mark { stroke: #dc2626; stroke-width: 4; stroke-linecap: round; }
.lifeline { stroke: #9ca3af; stroke-width: 1.2; stroke-dasharray: 5 5; }
.timeline-axis { stroke: #374151; stroke-width: 1.8; marker-end: url(#arrow); }
.timeline-stem { stroke: #6b7280; stroke-width: 1.3; }
.timeline-marker { fill: #ffffff; stroke: #374151; stroke-width: 1.7; }
.timeline-marker.primary { fill: #2563eb; stroke: #2563eb; }
.timeline-marker.warning { fill: #dc2626; stroke: #dc2626; }
.timeline-label { font-size: 13px; font-weight: 650; text-anchor: middle; }
.timeline-detail { font-size: 11px; fill: #4b5563; text-anchor: middle; }
</style>
</defs>
<rect class="canvas" width="870" height="542" />
<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="992-1007" x="45.0" y="35.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="120.0" y="65.0">브라우저</text>
<line class="lifeline" x1="120.0" y1="99.0" x2="120.0" y2="512.0" />
<rect class="node-shape kind-participant emphasis-primary role-participant" data-evidence="914-939,1009-1028" x="255.0" y="35.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="330.0" y="65.0">Nginx edge</text>
<line class="lifeline" x1="330.0" y1="99.0" x2="330.0" y2="512.0" />
<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="980-990,1009-1015" x="465.0" y="35.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="540.0" y="65.0">oauth2-proxy</text>
<line class="lifeline" x1="540.0" y1="99.0" x2="540.0" y2="512.0" />
<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="1017-1026,1030-1063" x="675.0" y="35.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="750.0" y="65.0">Spring upstream</text>
<line class="lifeline" x1="750.0" y1="99.0" x2="750.0" y2="512.0" />
<polyline class="edge kind-request style-solid emphasis-normal" points="120.0,140.0 330.0,140.0" data-evidence="992-999" />
<rect class="edge-label-bg" x="115.5" y="114.0" width="219.0" height="22" rx="3" />
<text class="edge-label" x="225.0" y="129.0">1. GET /api/edge + AP4_SESSION</text>
<polyline class="edge kind-request style-solid emphasis-normal" points="330.0,202.0 540.0,202.0" data-evidence="922-939,1009-1009" />
<rect class="edge-label-bg" x="308.8" y="176.0" width="252.5" height="22" rx="3" />
<text class="edge-label" x="435.0" y="191.0">2. internal /oauth2/auth subrequest</text>
<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="540.0,264.0 330.0,264.0" data-evidence="1009-1015" />
<rect class="edge-label-bg" x="328.9" y="238.0" width="212.3" height="22" rx="3" />
<text class="edge-label" x="435.0" y="253.0">3. authenticated user + email</text>
<polyline class="edge kind-request style-solid emphasis-primary" points="330.0,326.0 750.0,326.0" data-evidence="1017-1026" />
<rect class="edge-label-bg" x="380.0" y="300.0" width="320.0" height="22" rx="3" />
<text class="edge-label" x="540.0" y="315.0">4. GET /edge/me · trusted headers + internal token</text>
<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="750.0,388.0 330.0,388.0" data-evidence="1030-1048" />
<rect class="edge-label-bg" x="450.6" y="362.0" width="178.8" height="22" rx="3" />
<text class="edge-label" x="540.0" y="377.0">5. trusted identity JSON</text>
<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="330.0,450.0 120.0,450.0" data-evidence="1039-1048,1065-1076" />
<rect class="edge-label-bg" x="75.3" y="424.0" width="299.4" height="22" rx="3" />
<text class="edge-label" x="225.0" y="439.0">6. pattern + user + email + identityHeader</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 7.5 KiB