외부 Client credentials 앱의 서비스 신원

외부에서 호스팅하는 OAuth 또는 OSDK 앱은 client ID와 secret으로 토큰을 발급받고 서비스 사용자 권한으로 Foundry API를 호출할 수 있습니다. 서버 간 통합, 자동 처리, 외부 플랫폼 연동이나 자체 사용자 체계를 가진 대규모 앱에 사용할 수 있습니다.

이 모델에서는 Foundry가 최종 사용자별로 로그인하거나 권한을 확인하지 않습니다. 외부 앱이 사용자 인증과 권한을 책임져야 하며, 서비스 사용자가 볼 수 있는 모든 데이터를 모든 최종 사용자에게 그대로 반환해서는 안 됩니다. 사용자별 검사는 신뢰할 수 있는 앱 백엔드에서 적용해야 합니다.

준비 조건

조직의 외부 애플리케이션 관리 권한과 외부 호스팅 환경이 필요합니다. 소비자의 Foundry 계정 및 조직을 만드는 기반 설정은 이 모델에 필수적이지 않습니다.

Developer Console 앱 생성

1. Developer Console에서 새 앱을 만듭니다.
2. Application type에서 Backend service를 선택합니다.
3. Permissions에서 Application permissions를 선택합니다. 이 선택이 Client credentials grant를 사용하게 하고 서비스 사용자를 생성합니다.
4. 생성된 client ID와 한 번만 표시되는 secret을 안전하게 보관합니다.
5. 미리 정한 프로젝트 및 작업보다 넓은 접근이 반드시 필요한 경우에만 생성 후 OAuth & restrictions에서 Unrestricted를 설정합니다. 이 옵션은 생성 마법사에서는 선택할 수 없습니다.

Unrestricted는 앱의 추가 제한을 제거하는 설정이지 서비스 사용자에게 모든 플랫폼 권한을 주는 설정이 아닙니다.

서비스 사용자 권한

서비스 사용자는 기본적으로 어떤 리소스에도 접근할 수 없습니다. 관리자는 앱이 실제로 사용하는 다음 대상을 허용해야 합니다.

• 필요한 리소스가 있는 프로젝트
• 필요한 객체 유형 등 온톨로지 유형
• 사용하는 데이터셋
• 액션 제출에 필요한 조건과 작업 권한
• API 기능을 제공할 역할

토큰은 이 서비스 사용자에 연결됩니다. 최종 사용자 한 명의 속성이나 그룹으로 제한 뷰를 자동 평가하는 모델로 해석하면 안 됩니다. Foundry 쪽 자격과 앱의 사용자별 접근 결정을 따로 설계합니다.

OSDK 연결

TypeScript 백엔드는 다음 순서로 구성할 수 있습니다.

1. Developer Console에서 앱용 OSDK 패키지를 생성합니다.
2. 앱이 읽거나 처리할 온톨로지 엔터티를 SDK 리소스에 추가합니다.
3. 생성한 OSDK 패키지를 외부 애플리케이션에 설치합니다.
4. OAuth client credentials를 서버 측 인증 클라이언트에 연결합니다.
5. OSDK 클라이언트로 서비스 사용자에게 허용된 데이터를 질의합니다.

OSDK는 리소스별 타입, 직렬화와 API 호출을 지원합니다. 앱의 사용자 인증 및 권한 로직을 대신 구현해 주는 것은 아닙니다. 토큰 엔드포인트와 요청 필드는 Client credentials grant를 사용합니다.

비밀과 운영 확인

Client secret을 공개 저장소나 브라우저에서 볼 수 있는 코드에 넣으면 안 됩니다. 노출되면 즉시 교체합니다. Secret을 교체한 뒤에는 이를 사용하는 외부 서버 설정도 갱신해야 합니다.

운영 전 담당자가 토큰 발급과 필요한 API 호출을 확인합니다. 오류별로 다음 범위를 살펴봅니다.

브라우저에 Foundry 토큰을 주지 않는 관리형 공개 사이트가 필요하면 Public Application을 검토합니다. 그 경로는 허용하는 API가 훨씬 좁으며 별도 보안 승인이 필요합니다.