API 인증과 OAuth 권한 범위
Foundry API는 OAuth 2.0으로 인증과 인가를 처리합니다. 각 호출의 Authorization 헤더에 Bearer 토큰을 전달합니다.
Authorization: Bearer <접근 토큰>
토큰을 가진 주체가 해당 토큰으로 리소스에 접근할 수 있으므로 토큰 자체를 비밀정보로 관리해야 합니다. 저장과 폐기, 노출 시 조치는 토큰과 API 키 보호를 따릅니다.
개발용 사용자 토큰
개발 중에는 자신의 계정에 연결된 임시 API 토큰을 만들 수 있습니다. 이 토큰에는 생성한 사용자의 권한이 적용됩니다.
- Foundry 사이드바 아래의 Account를 선택합니다.
- Settings → Tokens를 엽니다.
- Create token을 선택합니다.
필요하지 않은 토큰은 토큰 목록에서 Revoke로 폐기합니다. 만료된 토큰은 자동으로 폐기됩니다. 사용자 생성 토큰을 운영 애플리케이션이나 공유 및 공개 코드 저장소에 넣지 않습니다. 개발 환경에서는 환경 변수로 제공할 수 있습니다.
다음은 인증 헤더의 형식을 보여 주는 조회 예시입니다. FOUNDRY_HOST에는 https://를 제외한 실제 호스트 이름을, FOUNDRY_TOKEN에는 개발 토큰을 지정합니다.
curl -H "Authorization: Bearer $FOUNDRY_TOKEN" \
"https://$FOUNDRY_HOST/api/v2/ontologies"
운영 애플리케이션
운영 앱은 앱용 OAuth 2.0 클라이언트로 접근 토큰을 발급받습니다. 갱신 토큰을 발급하는 인증 흐름에서는 그 토큰으로 접근 토큰을 갱신할 수 있습니다. 아래 두 방식은 실행 주체와 토큰을 얻는 과정이 다릅니다.
| 방식 | 실행 주체와 토큰 획득 |
|---|---|
| 인가 코드 방식(Authorization code grant) | 사용자를 대신하여 실행합니다. 사용자를 Foundry 인증 화면으로 이동시켜 인증한 뒤 수명이 짧은 OAuth 접근 토큰을 얻습니다. |
| 클라이언트 인증 정보 방식(Client credentials grant) | 서비스 사용자로 실행합니다. 앱이 클라이언트 비밀값을 안전하게 보관하고 이를 사용하여 수명이 짧은 접근 토큰을 요청합니다. |
Developer Console의 앱 설정에서 흐름을 구성합니다. 기존 앱은 Control Panel의 Legacy OAuth 클라이언트 설정 경로를 사용할 수 있습니다. 클라이언트 비밀값은 공개 코드 저장소에 저장하지 않습니다.
OAuth 권한 범위
OAuth 클라이언트는 인가를 요청할 때 필요한 권한 범위(scope)를 지정합니다. 실제 권한은 앱이 요청한 범위와 실행 사용자 또는 서비스 사용자가 이미 가진 권한의 교집합입니다.
온톨로지 조회에는 api:ontologies-read, 쓰기에는 api:ontologies-write를 사용합니다. 두 작업이 모두 필요하면 두 범위를 요청합니다. 개별 엔드포인트가 요구하는 범위는 해당 요청 계약을 따릅니다.
Developer Console의 Platform SDK 패널에서는 앱이 요청할 수 있는 범위를 제한할 수 있습니다. 이 제한은 특정 사용자의 권한과 별개로 앱이 수행할 작업과 읽을 데이터의 범위를 통제합니다.
권한 범위는 허용할 권한의 집합으로 평가됩니다. 개별 엔드포인트 이름의 고정 목록과 같지는 않으며, 같은 권한으로 하위 서비스 엔드포인트를 호출할 수 있는 경우도 있습니다. 이러한 하위 서비스 접근 동작은 변경될 수 있으므로 명시된 API 계약을 기준으로 통합합니다.
구성한 클라이언트 사용
Developer Console의 Start developing 패널은 선택한 인증 방식에 맞는 예제 코드를 생성합니다. 생성한 SDK를 사용하지 않을 때에도 해당 OAuth 클라이언트의 엔드포인트와 매개변수로 접근 토큰을 발급받은 뒤, API 요청에는 같은 Bearer 헤더 형식으로 전달합니다.