Developer Console 앱의 접근 제한

Developer Console 앱에는 Foundry 인증을 처리하는 OAuth 클라이언트가 연결됩니다. 토큰으로 할 수 있는 일은 실행 주체의 권한, 앱에 설정한 최대 제한 및 인증 요청에서 요구한 작업 scope의 교집합으로 정합니다.

• Authorization code grant는 로그인한 사용자의 권한을 사용합니다.
• Client credentials grant는 앱의 서비스 사용자 권한을 사용합니다.
• 앱 제한은 허용할 리소스와 작업의 최대 범위입니다.
• 인증 시 요청하는 scope는 작업 범위를 더 좁힙니다. 리소스 범위는 앱 제한과 사용자의 권한에서 정합니다.

Restricted와 Unrestricted

모든 새 앱은 Restricted로 생성합니다. 생성 마법사에는 이 선택이 없으며 앱을 만든 뒤 OAuth & restrictions > Application restrictions에서 바꿉니다.

Restricted는 Developer Console에서 지정한 리소스와 작업만 허용합니다. Unrestricted는 앱의 최대 리소스/작업 제한을 두지 않으며 실행 주체의 권한과 인증 시 scope 조건을 따릅니다.

Unrestricted로 바꾸면 기존 프로젝트 접근 및 작업 제한 구성이 제거됩니다. 다시 Restricted로 바꾸면 프로젝트와 API 작업을 재구성해야 하며 빠진 리소스를 사용하는 앱이 실패할 수 있습니다.

제한 앱의 리소스와 작업

사용자가 어떤 데이터셋을 읽을 권한이 있어도 제한 앱에서 읽으려면 해당 데이터셋이 있는 프로젝트와 api:use-datasets-read 작업을 앱에 허용해야 합니다. 사용자의 권한만으로 앱 제한을 넘어갈 수 없습니다.

Ontology SDK

Ontology SDK 탭에서 객체 유형, 인터페이스, 액션과 함수를 추가합니다. 추가한 엔터티는 앱의 허용 리소스에 들어가며 이후 생성하는 SDK에도 포함됩니다.

Platform SDK

플랫폼 API를 사용하는 경우 Platform SDK 탭에서 Foundry 프로젝트를 허용 리소스로 추가합니다. 제한 앱은 선택 프로젝트 안의 리소스를 읽거나 쓸 수 있습니다. 프로젝트에 속하지 않는 관리 리소스가 필요하면 Unrestricted 사용 여부를 검토합니다.

작업 제한은 Platform SDK 탭에서만 설정합니다. API 이름 공간별로 사용할 메서드를 선택합니다. 예를 들어 admin 이름 공간은 /api/{version}/admin/ 경로에 대응합니다.

제한 앱의 API 수준 보안은 호출할 엔드포인트를 허용 작업 목록에 명시하도록 요구합니다. 제한 설정은 특정 장치나 시스템에 Foundry가 전송할 수 있는 데이터의 상한으로도 사용합니다.

Unrestricted가 필요한 경우

배포 시 대상 리소스를 미리 정할 수 없거나 아직 생기지 않은 프로젝트를 다루는 작업, 공간과 조직 및 플랫폼 인스턴스처럼 프로젝트 밖 관리 리소스, 공개 플랫폼 API에 아직 없는 서비스 엔드포인트를 사용하는 워크플로에 필요할 수 있습니다.

실행 주체가 접근할 수 있는 폭넓은 리소스를 사용할 수 있으므로 신뢰하는 코드에만 사용합니다. 클라이언트 비밀값을 저장할 수 없는 브라우저 앱에 서비스 사용자 인증을 넣어 범위를 넓히면 안 됩니다.

앱을 만든 뒤 제한 해제

1. 앱 생성에서 Client-facing application 또는 Backend service를 선택합니다. 기밀 인증 정보를 안전하게 보관할 수 있는 서버만 Backend service를 사용합니다.
2. 로그인한 사람의 권한이면 User permissions, 서비스 사용자 권한이면 Application permissions를 선택합니다. Client-facing은 User permissions만 사용합니다.
3. 플랫폼 API만 사용하면 Resources에서 No, I will not use an Ontology SDK를 선택할 수 있습니다. 곧 Unrestricted로 바꿀 경우 프로젝트와 작업 제한은 그때 제거되므로 생성 시 추가를 생략할 수 있습니다.
4. Backend service의 client secret은 생성 때 한 번만 표시하므로 안전한 저장소에 보관합니다. 잃으면 회전해야 합니다. 공개 Client-facing 전용 앱에는 client secret이 없습니다.
5. 생성한 앱의 OAuth & restrictions에서 Unrestricted로 변경합니다.
6. 코드의 인증 요청에 필요한 작업 scope를 지정합니다.

독립 OAuth 클라이언트 이전은 기존 연결을 새 앱으로 옮기는 경로입니다.

인증 요청 scope

아래 helper는 공개 OAuth로 온톨로지와 데이터셋 읽기 작업을 요청합니다. 입력 값은 실제 앱 설정이며 토큰이나 비밀값을 코드에 고정하지 않습니다.

import { createClient } from "@osdk/client";
import { createPublicOauthClient } from "@osdk/oauth";

export function createReadClient(clientId: string, foundryUrl: string, redirectUrl: string, ontologyRid: string) {
    const scopes = ["api:use-ontologies-read", "api:use-datasets-read"];
    const auth = createPublicOauthClient(clientId, foundryUrl, redirectUrl, { scopes });
    return createClient(foundryUrl, ontologyRid, auth);
}

리소스 ID를 이 scope 배열로 요청하지 않습니다. 인증 시에는 작업만 요청하고 실제 리소스는 앱 제한과 실행 주체의 권한으로 정합니다.

클라이언트 수준과 요청 수준 모두에서 제한이 없는 일반 토큰 요청은 권한 없는 토큰이 될 수 있습니다. Client credentials의 위 예외를 다른 grant에 확대해서 적용하지 않습니다.

API 수준 보안

2025년 6월 1일 이후 생성한 제한 앱 및 이전한 앱은 각 API 작업을 명시적으로 허용하는 보안을 적용합니다.

내부 서비스 엔드포인트

새 제한 앱의 scope는 api:use- 접두사를 사용합니다. 예를 들어 api:use-ontologies-read는 공개 Foundry API만 허용하며 일반 내부 서비스 API 접근을 허용하지 않습니다.

사용자 식별, 인가와 접근 진단을 위한 다음 관리 경로는 예외로 제한 앱에서도 호출할 수 있습니다.

• /multipass/api/oauth2/...
• /multipass/api/me/...
• /multipass/api/authz/...
• /multipass/api/token/...
• /multipass/api/organizations/...

이 예외 경로는 광범위한 공개 API 사용을 위한 목록이 아니며 일반 내부 서비스 호출 권한을 뜻하지 않습니다.

이름 공간 사이의 암묵적 허용 제거

이전 모델은 한 API 이름 공간의 scope가 의존하는 다른 이름 공간 일부까지 허용할 수 있었습니다. 새 use- scope는 직접 허용한 이름 공간만 제공합니다.

온톨로지 읽기/쓰기만 허용한 앱이 /api/v2/admin/users/getCurrent를 호출하면 ApiUsageDenied가 발생할 수 있습니다. admin 작업이 필요하면 별도로 허용하고 요청해야 합니다.

새로 만들거나 이전한 앱은 기본으로 api:use-ontologies-read와 api:use-ontologies-write를 설정합니다. 이 기본 설정이 모든 플랫폼 API를 허용하는 것은 아닙니다.

기존 앱 이전

Platform SDK resources에서 Migrate를 선택합니다.

대화 상자에서 안내한 새 scope를 코드에 추가합니다. 전환 중 일시적인 실패를 피하려면 이 단계에서 원래 scope를 아직 제거하지 않습니다.

앱 이전이 성공한 뒤 오래된 scope를 제거합니다.

Unrestricted도 내부 서비스가 필요하지 않다면 api:use-*를 사용합니다. 이 구분은 admin, ontologies, datasets, streams 등 모든 API 이름 공간에 적용합니다.