외부 인증 애플리케이션과 OAuth 2.0
외부 인증 애플리케이션(Outbound application)은 Foundry가 외부 OAuth 2.0 서버의 클라이언트로 동작하도록 묶어 관리하는 인증 설정입니다. Foundry에서 만든 워크플로가 호출 사용자를 대신하여 외부 시스템에 접근할 때 사용하며, Control Panel에서 조직 수준으로 관리합니다.
지원하는 방식은 OAuth 2.0의 인가 코드 방식(Authorization code grant)입니다. 클라이언트 인증 정보 방식(Client credentials grant)을 설정하는 리소스는 아닙니다. 그 방식이 필요하면 웹훅에서 해당 인증 요청을 구성하는 별도의 경로를 사용합니다.
소스에 이 애플리케이션을 연결하면 각 사용자가 외부 제공자의 로그인과 인가 절차를 거쳐 자신의 토큰을 얻습니다. 애플리케이션을 선택할 수 있는 권한과 사용자가 외부 시스템에 인가한 상태는 구분해야 합니다.
관리 화면과 권한
Control Panel의 Organization settings → Outbound applications로 이동합니다. 여러 조직에 접근할 수 있다면 애플리케이션을 만들 조직을 먼저 선택합니다.
이 화면에는 Manage outbound applications 작업 권한이 필요하며, 기본적으로 Organization administrator 역할에 부여됩니다.
조직 안에서 Data Connection 소스를 설정할 권한이 있는 사용자는 그 조직의 외부 인증 애플리케이션을 소스의 인가 방식으로 선택할 수 있습니다.
새 애플리케이션 구성
New application을 선택하고 외부 OAuth 제공자에서 준비한 설정을 입력합니다.
| 설정 | 필수 여부 | 의미와 조건 |
|---|---|---|
| Authorization page URL | 필수 | 사용자가 로그인하고 인가하는 외부 서버의 인가 엔드포인트. 예시는 https://oauth.example.com/authorize |
| Token endpoint URL | 필수 | 인가 코드나 갱신 토큰을 접근 토큰으로 교환하는 엔드포인트. 예시는 https://oauth.example.com/token |
| Egress policy | 필수 | Foundry가 토큰 엔드포인트에 접근하도록 허용하는 외부 통신 정책 |
| Application name | 필수 | Data Connection의 인증 방식 선택 화면에 표시할 이름 |
| Description | 선택 | 애플리케이션 설명 |
| Approval prompt | 필수 | 외부 제공자의 로그인 팝업을 열기 전에 사용자에게 표시할 안내 문구 |
| Client ID | 필수 | 외부 OAuth 제공자에서 발급받은 클라이언트 ID. 제공자에 따라 다른 이름을 사용할 수 있음 |
| Client secret | 필수 | 외부 OAuth 제공자의 클라이언트 비밀값. 제공자에 따라 다른 이름을 사용할 수 있음 |
| Scopes | 필수 | 외부 서버의 해당 클라이언트에 구성한 권한 범위 목록. 빈 값은 빈 범위 목록을 전달하는 설정 |
| Access token expiration | 선택 | 서버가 만료 시간을 반환하지 않을 때 사용할 접근 토큰 만료 시간. 서버가 값을 반환하면 이 설정은 무시 |
| Enable PKCE | 선택 | 인가 코드 교환에 추가 검증을 사용하는 PKCE 활성화 |
권한 범위(Scope)는 외부 서비스의 관리 화면에 설정한 목록과 일치해야 합니다.
PKCE(Proof Key for Code Exchange)는 인가 코드 방식에 추가 검증을 적용하여 CSRF와 인가 코드 주입 공격에 대응하는 확장입니다. 공개 클라이언트에 특히 권장되며 일부 OAuth 서버는 이를 강제합니다.
네트워크 경로
외부 통신 정책은 플랫폼 인스턴스 단위로 관리합니다. OAuth 서버가 Foundry에서 직접 도달할 수 있는 위치라면 직접 연결 정책이 권장됩니다. 별도 사설 네트워크에 있다면 Data Connection 에이전트를 통한 에이전트 프록시 정책을 사용할 수 있습니다.
이 정책은 Foundry에서 OAuth 서버로 가는 연결을 통제합니다. 인가 페이지는 사용자의 브라우저에서 열리므로, 인가를 시작하는 컴퓨터도 외부 OAuth 서버에 접근할 수 있어야 합니다.
저장 후 인가 확인
애플리케이션을 저장하고 활성화하면 Your authorization에 Authorized 또는 Not authorized가 표시됩니다.
인가되지 않았다면 Set up authorization을 선택하여 외부 제공자의 인가 절차를 진행합니다. 이 방법은 소스에 애플리케이션을 연결하기 전에도 사용할 수 있습니다. 절차를 마치면 해당 애플리케이션을 사용하는 워크플로에 필요한 사용자의 인가 상태를 저장합니다.
활성화, 초기화와 삭제
| 작업 | 저장한 토큰과 구성에 미치는 영향 |
|---|---|
| 활성화 | 사용자가 대화형 인가 절차를 수행할 수 있음 |
| 비활성화 | 기존 접근 토큰과 갱신 토큰을 사용할 수 없게 하고 새 사용자의 인가도 막음. 토큰 자체는 삭제하지 않음 |
| 다시 활성화 | 보관된 토큰을 다시 사용할 수 있는 상태로 전환 |
| 초기화 | 이 애플리케이션을 인가한 모든 사용자의 접근 토큰과 갱신 토큰을 영구 제거. 구성은 유지 |
| 삭제 | 모든 사용자의 접근 토큰과 갱신 토큰, 클라이언트 비밀값을 포함한 애플리케이션 구성을 영구 제거 |
새 애플리케이션은 기본으로 활성화됩니다. 비활성화는 생성한 뒤에 할 수 있습니다.
초기화하면 사용자의 기존 인가 정보가 제거되므로 다음에 토큰이 필요한 작업을 수행할 때 각 사용자가 다시 인가해야 합니다. 삭제는 되돌릴 수 없으며, 사용을 잠시 막으려는 경우에는 비활성화를 선택합니다.
REST API 소스에서 사용
외부 인증 애플리케이션은 여러 조직의 사용자가 함께 사용하는 방식은 지원하지 않습니다. 여러 조직이 같은 OAuth 서버에 인가해야 한다면 조직마다 별도 애플리케이션과 별도 REST API 소스를 만들어야 합니다.
애플리케이션을 만들고 활성화한 뒤 REST API 소스의 도메인 설정에서 인증 방식으로 OAuth 2.0을 선택하고 사용할 애플리케이션을 고릅니다.
이 도메인을 사용하는 웹훅을 처음 실행할 때는 각 사용자에게 인가 화면이 열립니다. 예를 들어 Workshop의 액션에서 웹훅을 실행하면 외부 OAuth 서버의 인증 페이지가 팝업으로 나타나고, 사용자는 Foundry가 자신을 대신하여 작업하도록 인가합니다.
갱신 토큰 흐름을 구성하면 외부 서비스에서 인가를 철회하거나 애플리케이션을 초기화하지 않는 한 반복 로그인을 줄일 수 있습니다. 갱신 흐름이 없다면 접근 토큰이 만료될 때마다 다시 인가해야 합니다. 접근 토큰은 몇 분 또는 몇 시간 만에 만료될 수 있으므로 갱신 흐름을 구성하는 것이 권장됩니다.
지원되는 실행 경로
| 기능 | OAuth 사용 방식과 조건 |
|---|---|
| Python 함수, TypeScript v2 함수 | 소스의 OAuth 토큰으로 코드에서 외부 시스템에 직접 인증 가능 |
| TypeScript v1 함수 | 웹훅을 사용하는 방식 필요 |
| 함수 기반 액션 | 기반 함수가 OAuth 소스를 호출하면 토큰을 자동으로 전달 |
| 웹훅 부수 효과 | OAuth를 설정한 REST API 소스의 웹훅 요청에 토큰 포함 |
| Workshop 액션 | 유효한 토큰이 없으면 인가 팝업을 시작하고, 이미 인가한 경우 토큰을 사용 |
| Workshop의 직접 함수 호출 | 함수 기반 변수나 위젯 내용 조회에서는 인가 팝업을 시작할 수 없음. 인가가 필요한 경우 함수 기반 액션으로 감싸서 사용 |
| AIP 챗봇 | OAuth 기반 액션 도구를 호출하는 에이전트에 같은 토큰 수명주기 적용 |
| Automate, 예약 함수 | 사용자의 유효한 토큰이 있는 경우 자동 실행에 사용 가능 |
자동 실행 전에 사용자가 Workshop, AIP Studio 또는 Control Panel 같은 대화형 화면에서 인가를 완료해야 합니다. 이때 갱신 토큰이 만료되었다면 대화형 화면에서 다시 인가해야 합니다.
웹훅을 액션 규칙으로 직접 호출하는 구성에서는 웹훅을 첫 규칙으로 실행하고 이후 함수가 응답을 처리하도록 설정할 수 있습니다. 웹훅의 입력을 함수에서 얻는 구성도 가능합니다.
기존 웹훅 기반 OAuth 설정
사용자 지정 웹훅으로 OAuth 요청을 직접 구성하는 방식은 기존 기능 유지 단계(Legacy)입니다. 추가 개발은 예정되어 있지 않지만 지원은 유지됩니다. 플랫폼 인스턴스에 따라 이 구성을 사용할 수 없을 수도 있습니다.
외부 서버가 표준 인가 코드 흐름을 지원하면 앞의 표준 설정과 직접 연결 또는 에이전트 프록시 정책을 사용합니다. 비표준 토큰 교환이 필요한 경우에는 사용자 지정 웹훅으로 인가 흐름을 구성할 수 있습니다. 이 기존 방식은 에이전트 워커를 사용하는 REST API 소스로 OAuth 서버에 연결합니다.
기존 방식의 입력
| 항목 | 필수 여부 | 의미 |
|---|---|---|
| Source connection | 필수 | 에이전트 워커로 내부 OAuth 서버에 연결하는 REST API 소스 |
| Webhook to get token | 필수 | 토큰 엔드포인트에서 접근 토큰을 얻는 웹훅 |
| Webhook to get refresh token | 선택 | 토큰 엔드포인트에서 토큰을 갱신하는 웹훅 |
| Authorization page URL | 필수 | 외부 제공자의 인가 엔드포인트 |
인증 서버 연결과 웹훅 준비
- OAuth 서버에 접근할 수 있는 REST API 소스를 만듭니다. 서버 도메인과 필요한 클라이언트 비밀값을 구성합니다.
- 이 소스에서
/token을 호출하는 웹훅을 만듭니다. - 자동 갱신이 필요하면 갱신용 웹훅도 만듭니다.
이 기존 OAuth 설정에는 함수로 게시한 웹훅을 사용할 수 없습니다. 토큰 획득 및 갱신 웹훅에서 함수 게시를 비활성화해야 합니다.
토큰 획득 웹훅의 입력
토큰 획득 웹훅은 클라이언트 ID, 리다이렉트 URI와 인가 코드로 유효한 토큰을 요청합니다.
| 입력 매개변수 | 필수 여부 | 타입 |
|---|---|---|
client_id | 필수 | String |
redirect_uri | 필수 | String |
authorization_code | 필수 | String |
code_verifier | PKCE를 활성화한 경우 필수 | String |
웹훅의 폼 본문에는 grant_type=authorization_code도 설정해야 합니다. 외부 OAuth 서버가 추가 입력을 요구한다면 그 조건에 맞추어 요청을 구성합니다.
토큰 획득 웹훅의 출력
| 출력 매개변수 | 필수 여부 | 타입과 동작 |
|---|---|---|
access_token | 필수 | String |
scope | 필수 | String |
refresh_token | 선택 | String. 갱신 토큰이 없으면 접근 토큰 만료 후 사용자가 다시 인가해야 함 |
expires_in | 선택 | String. 없거나 값이 반환되지 않으면 애플리케이션의 접근 토큰 만료 설정을 사용 |
갱신 웹훅
갱신 웹훅은 /token에 갱신 토큰과 클라이언트 ID를 전달하여 새 토큰을 얻습니다. 이 웹훅도 함수로 게시한 형태를 사용할 수 없습니다.
| 입력 매개변수 | 필수 여부 | 타입 |
|---|---|---|
client_id | 필수 | String |
refresh_token | 필수 | String |
폼 본문에는 grant_type=refresh_token을 설정합니다.
출력은 토큰 획득 웹훅과 같은 계약을 사용합니다. access_token, scope는 필수이고 refresh_token, expires_in은 선택적 문자열입니다. 갱신 토큰이 제공되지 않으면 다시 대화형 인가가 필요할 수 있으며, 만료 정보가 없으면 애플리케이션에 지정한 만료 설정을 사용합니다.