refs #744: standardize overview and cookbook documentation

docs/design/744-windows-ad-dds-end-user-mapping/troubleshooting.md

@@ -0,0 +1,43 @@
+# 트러블슈팅: OCI AD Bridge · OAuth · DDS MCP
+
+[개요로 돌아가기](README.md) · [적용 Cookbook](cookbook.md) · [아키텍처](architecture.md)
+
+## Windows AD Bridge
+
+| 증상 | 원인 확인 | 해결 |
+|---|---|---|
+| WinRM TCP/5986 `Connection refused` | listener, Windows Firewall, NSG 확인 | RDP로 installer를 실행하거나 WinRM HTTPS를 별도로 구성한다. Bridge 자체 오류가 아니다. |
+| OCI Run Command plugin은 `RUNNING`인데 command가 `ACCEPTED`/`VISIBLE` | 단순 `echo`도 실행되지 않으면 script 문제가 아님 | Windows Oracle Cloud Agent/Run Command service, outbound OCI 연결, plugin log를 RDP에서 점검한다. |
+| LDAPS certificate 오류 | Bridge host가 AD DS server/CA certificate를 신뢰하는지 확인 | CA chain을 Windows trust store에 배포하고 LDAPS를 유지한다. |
+| Bridge `Connected`가 되지 않음 | OCI 443, AD 636, Bridge service account credential/권한 확인 | NSG/proxy/firewall 및 최소 AD 권한을 순서대로 점검한다. |
+
+## 동기화와 delegated authentication
+
+| 증상 | 원인 확인 | 해결 |
+|---|---|---|
+| Alice/Bob이 OCI Domain에 보이지 않음 | 선택한 사용자 OU/하위 OU와 initial sync 상태 | OU 범위와 filter를 수정하고 sync를 재실행한다. |
+| OCI 로그인 비밀번호가 실패 | delegated authentication test에서 동일 AD 계정으로 재현 | AD 비밀번호, Bridge AD 연결, service account delegated-auth 권한을 확인한다. |
+| AD 비밀번호를 OCI local password로 입력하려 함 | delegated authentication 활성화 여부 | 성공 시험 후 활성화한다. 활성화 뒤 실제 비밀번호 원천은 AD다. |
+
+## OCI OAuth와 AIPF
+
+| 증상/오류 | 원인 | 해결 |
+|---|---|---|
+| `/admin/v1/admin/v1/Apps` 및 401 | `oci identity-domains --endpoint`에 `/admin/v1`까지 넣음 | CLI에는 Domain base URL만 사용한다. raw request target에만 `/admin/v1`을 넣는다. |
+| `No such option: --header` | `oci raw-request` 옵션명 오류 | `--request-headers '{"Content-Type":"application/json"}'`를 사용한다. |
+| `Missing required attribute(s): basedOnTemplate` | confidential client app template 누락 | `basedOnTemplate.value=CustomWebAppTemplateId`를 지정한다. |
+| authorize URL이 302 대신 200 | OCI Domain이 sign-in HTML과 session cookie를 반환 | 정상이다. browser에서 OCI login UI가 표시되는지 확인한다. |
+| AIPF callback 오류 | redirect URI가 두 AIPF 경로 중 실제 요청 경로와 다름 | `/agentFactory/.../callback`과 `/v1/.../callback` 둘 다 등록한다. |
+| 이전 사용자로 자동 로그인 | OCI Domain browser SSO session 유지 | OCI logout 후 새 MCP source를 연결한다. |
+
+## MCP와 DDS
+
+| 증상 | 원인 | 해결 |
+|---|---|---|
+| MCP `401` / tools discovery 실패 | OCI issuer/audience가 runtime에 반영되지 않았거나 token 만료 | discovery/JWT claim을 기준으로 issuer·audience를 설정한다. |
+| token 검증은 되지만 `AUTHORIZATION_DENIED` | OCI `iss + sub` binding 미등록/비활성 | `CB_EXTERNAL_IDENTITY_BINDING`과 DDS END USER mapping을 함께 확인한다. |
+| `DDS_CONTEXT_UNAVAILABLE` | DB service client/scope/domain URL 설정 문제 | `DDS_MCP_SERVICE_TEST`, `DDS_ORACLE_DB_TEST`, `DB_ACCESS_SCOPE`, DB application identity를 확인한다. |
+| `ORA-52602` | database-access token issuer/resource/scope 불일치 | DB의 OCI Domain URL 정규형(`:443` 포함), resource app ID/scope를 맞춘다. |
+| Alice 성공, Bob “DDS 보호 객체” | Bob DATA GRANT 없음 | 의도된 default deny다. 정책상 필요할 때만 최소 grant를 추가한다. |
+
+외부 오류 메시지에는 SQL, table명, secret을 노출하지 않는다. 내부 감사에는 correlation ID, 내부 user ID, 선택 DDS END USER, allow/deny 결과를 남긴다.