조직도 M2M조회 추가, 자동로그인 보완

2026-05-13 13:44:30 +09:00
parent 72288f1d39
commit 8c2b2f71ef
29 changed files with 2985 additions and 81 deletions
--- a/docs/integrations-org-context-json-api.md
+++ b/docs/integrations-org-context-json-api.md
@@ -0,0 +1,138 @@
+# 조직 Context JSON API 계약
+
+## 목적
+
+외부 연동앱이 계정 세션 없이 M2M 방식으로 Baron SSO의 조직구성을 조회할 수 있게 한다. 조직구성은 Baron SSO backend의 tenant/user projection을 SSOT로 사용하며, iframe 또는 `postMessage` 계약은 사용하지 않는다.
+
+## 인증
+
+API Key 기반 headless 통신만 허용한다.
+
+```http
+X-Baron-Key-ID: <client id>
+X-Baron-Key-Secret: <client secret>
+```
+
+필요 scope는 다음과 같다.
+
+```text
+org-context:read
+```
+
+API Key 발급/회수는 사람의 관리 행위이므로 super admin 권한으로만 수행한다. 반면 아래 조직 Context 조회 API는 사용자 세션 없이 API Key만으로 동작한다.
+
+## Endpoint
+
+```http
+GET /api/v1/integrations/org-context
+```
+
+### Query
+
+| 이름 | 기본값 | 설명 |
+| --- | --- | --- |
+| `tenantSlug` | `hanmac-family` | 조회할 subtree root tenant slug. 지정하지 않으면 `hanmac-family` 전체 subtree를 반환한다. |
+| `includeUsers` | `true` | `false`이면 `users`와 `directUserIds`를 비운다. |
+
+상위 조직 지정은 slug만 사용한다. UUID 기반 지정은 계약에 포함하지 않는다.
+
+## 예시 요청
+
+```bash
+curl 'https://sso.example.com/api/v1/integrations/org-context?tenantSlug=hanmac&includeUsers=true' \
+  -H 'X-Baron-Key-ID: 01970f08-91da-7286-bd19-882fb98d1f2c' \
+  -H 'X-Baron-Key-Secret: <secret>'
+```
+
+## 예시 응답
+
+```json
+{
+  "schemaVersion": "baron.org-context.v1",
+  "issuedAt": "2026-05-13T12:00:00Z",
+  "scope": {
+    "tenantId": "01970f08-91da-7286-bd19-882fb98d1f2c",
+    "tenantSlug": "hanmac"
+  },
+  "tree": {
+    "id": "01970f08-91da-7286-bd19-882fb98d1f2c",
+    "type": "COMPANY",
+    "name": "한맥기술",
+    "slug": "hanmac",
+    "parentId": "01970f07-4f01-7d9a-a71e-b53ad508f345",
+    "status": "active",
+    "description": "",
+    "domains": [],
+    "memberCount": 0,
+    "visibility": "public",
+    "createdAt": "2026-05-13T00:00:00Z",
+    "updatedAt": "2026-05-13T00:00:00Z",
+    "directUserIds": [],
+    "children": [
+      {
+        "id": "01970f09-2b7b-7f83-b9d6-4f6c8b33f01a",
+        "type": "USER_GROUP",
+        "name": "플랫폼실",
+        "slug": "platform",
+        "parentId": "01970f08-91da-7286-bd19-882fb98d1f2c",
+        "status": "active",
+        "description": "",
+        "domains": [],
+        "memberCount": 0,
+        "visibility": "internal",
+        "orgUnitType": "실",
+        "createdAt": "2026-05-13T00:00:00Z",
+        "updatedAt": "2026-05-13T00:00:00Z",
+        "directUserIds": [
+          "01970f0a-5c28-74d8-a73a-f6e9e9a7b210"
+        ],
+        "children": []
+      }
+    ]
+  },
+  "tenants": [
+    {
+      "id": "01970f08-91da-7286-bd19-882fb98d1f2c",
+      "type": "COMPANY",
+      "name": "한맥기술",
+      "slug": "hanmac",
+      "parentId": "01970f07-4f01-7d9a-a71e-b53ad508f345",
+      "status": "active",
+      "description": "",
+      "domains": [],
+      "memberCount": 0,
+      "visibility": "public",
+      "createdAt": "2026-05-13T00:00:00Z",
+      "updatedAt": "2026-05-13T00:00:00Z"
+    }
+  ],
+  "users": [
+    {
+      "id": "01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
+      "email": "user@example.com",
+      "name": "홍길동",
+      "role": "user",
+      "status": "active",
+      "tenantIds": [
+        "01970f09-2b7b-7f83-b9d6-4f6c8b33f01a"
+      ],
+      "tenantSlugs": [
+        "platform"
+      ],
+      "grade": "책임",
+      "position": "실장",
+      "jobTitle": "Backend Engineer",
+      "createdAt": "2026-05-13T00:00:00Z",
+      "updatedAt": "2026-05-13T00:00:00Z"
+    }
+  ]
+}
+```
+
+## 정책
+
+- `tenantSlug`가 없으면 `hanmac-family` 전체 subtree를 반환한다.
+- `tenantSlug`는 slug만 허용한다. UUID를 query 계약으로 쓰지 않는다.
+- `visibility=private` tenant와 그 하위 tenant는 제외한다.
+- `visibility=internal` tenant는 M2M 연동용 JSON API에는 포함한다.
+- 외부 앱은 `schemaVersion`을 확인하고, 알 수 없는 version이면 별도 fallback을 적용한다.