code를 받은 다음 OAuth access token으로 교환합니다.
OAuth access token은 계정 리소스 인터페이스에 접근하는 데 사용됩니다. 모델 API를 호출하려면 해당 API Key를 사용합니다. OAuth 인증은 API Key를 자동으로 생성하거나, 서비스를 활성화하거나, 잔액을 추가하지 않습니다.
연동 방식 선택
표준 리디렉션에는
embed=studio, embed_origin 또는 postMessage가 필요하지 않습니다. Studio 컴포넌트 모드에서는 호스트가 인증 페이지를 생성하고 메시지 브리지를 유지합니다. 제3자는 본문 끝의 컴포넌트 프로토콜에 따라 연동하고, 이 두 매개변수를 직접 조합하지 마십시오.
엔드포인트 및 발견 문서
애플리케이션 관리 인터페이스에는 계정 로그인 인증이 필요하며, 익명 동적 등록(DCR) 인터페이스가 아닙니다. MCP 서비스 자체의 발견/등록 주소는 이 표의 계정 OAuth 엔드포인트와 다른 진입점입니다. 특정 MCP에 연결할 때는 해당 서비스의 문서와 발견 결과에 따라 작업하십시오.
발견 문서는 엔드포인트와 프로토콜 기능을 가져오는 데 사용됩니다. 현재 흐름은 OAuth token을 반환하며
id_token은 반환하지 않습니다. openid scope가 존재한다는 이유만으로 완전한 OpenID Connect 로그인 흐름으로 처리하지 마십시오.
권한 범위: 현재 scope 이름 사용
scope는 공백으로 구분되고 대소문자를 구별하는 권한 이름입니다. 새 애플리케이션은 profile:read, email:read, phone:read 등의 구체적인 권한을 사용합니다.
신청 가능한 권한을 가져오는 위치
로그인 후 OAuth 애플리케이션 목록 인터페이스GET /api/v1/oauth2/applications/는 available_scopes를 반환합니다. 애플리케이션 관리 페이지의 권한 선택기도 동일한 카탈로그를 사용합니다. 이것이 일반 셀프서비스 애플리케이션이 사용해야 하는 선택 가능한 범위입니다.
Discovery의 scopes_supported에는 플랫폼이 인식하는 모든 권한 이름이 포함되며, 귀하의 애플리케이션이 그중 모든 항목을 신청할 수 있음을 의미하지는 않습니다. 실제 인증에서는 다음을 동시에 확인합니다.
- 해당 권한이 이 애플리케이션 유형에 위임될 수 있는지;
- 해당 권한이 이 OAuth 애플리케이션의 허용 범위에 등록되어 있는지;
- 현재 사용자가 요청된 권한을 보유하고 있는지.
invalid_scope를 반환합니다. 인증 코드 교환 및 갱신 시에도 다시 확인하며, 권한을 자동으로 보충하거나 상향하지 않습니다.
일반 셀프서비스 애플리케이션에서 선택 가능한 권한
다음은 현재 카탈로그(2026-10-09)이며, 연동 시에는available_scopes를 기준으로 합니다.
예를 들어, 프로필만 읽으려면
profile:read를 사용하고, 이메일이 필요하면 email:read를 추가하며, 기존 API Key를 읽으려면 profile:read credentials:read를 사용합니다. 실제로 Key를 생성하거나 수정해야 할 때만 credentials:write를 신청하고, 갱신이 필요할 때 offline_access를 추가합니다.
일부 권한은 플랫폼이 승인한 신뢰할 수 있는 애플리케이션에만 제공됩니다. 예: sites:read, sites:write, platform-tokens:read; 다른 일부 권한은 일반 제3자 OAuth 애플리케이션에 공개되지 않습니다. 클라이언트 유형 public/confidential은 secret을 보관할 수 있는지 여부를 설명하며, 애플리케이션이 신뢰할 수 있는지와는 관련이 없습니다. 셀프서비스로 생성한 애플리케이션은 신뢰 권한을 직접 활성화할 수 없습니다.
account는 지정된 공식 계정 관리 MCP에서 사용하는 계정 권한 선택기이며, 제3자 애플리케이션의 “모든 권한” scope가 아니므로 다른 scope와 혼용할 수 없습니다. 제3자는 필요한 구체적인 권한을 명확히 나열해야 합니다.
이전 문서에서 마이그레이션
이전 이름은 호환 별칭으로 허용되지 않습니다. OAuth 애플리케이션에 등록된 scopes, 인증 URL 및 자체 권한 판단을 함께 업데이트하십시오. 애플리케이션 구성을 수정해도 이미 발급된 token에 권한이 추가되지 않으며, 사용자가 다시 인증해야 합니다.
1단계: OAuth 애플리케이션 등록
OAuth 애플리케이션 관리를 열고 애플리케이션을 생성한 후 다음을 입력합니다:- 이름, 설명, 애플리케이션 Logo: 권한 부여 페이지의 애플리케이션 측에 표시됩니다.
- 클라이언트 유형: 순수 프런트엔드, 모바일 또는 데스크톱 클라이언트는 Public을 선택합니다. 백엔드에서 secret을 보관할 수 있는 서비스는 Confidential을 선택합니다.
- 콜백 주소: 프로덕션 환경에서는 HTTPS를 사용하고, 애플리케이션이 실제로 콜백을 처리하는 전체 URL을 등록합니다.
- 권한: 페이지에서 제공하는 목록에서 실제로 필요한 scopes를 선택합니다.
client_id를 저장합니다. Confidential 클라이언트는 client_secret을 서버 측에 저장해야 하며, HTML, 프런트엔드 빌드 변수 또는 URL에 넣을 수 없습니다. Public 클라이언트는 token을 교환할 때 secret을 사용하지 않으며, 등록 응답에 해당 필드가 포함되어 있더라도 이를 클라이언트가 비밀로 유지할 수 있는 자격 증명으로 취급할 수 없습니다.
redirect_uri는 등록, 권한 부여 및 token 교환 시 경로, 후행 슬래시 및 쿼리 매개변수를 포함하여 정확히 일치해야 합니다. 각 계정은 최대 20개의 애플리케이션을 만들 수 있습니다. Secret은 생성/교체 시에만 표시됩니다. 교체 후 이전 secret은 클라이언트 인증이 필요한 교환을 계속 수행할 수 없습니다.
2단계: 버튼으로 권한 부여 시작
연결을 클릭할 때마다 새로운 무작위state와 code_verifier를 생성하고, 다음을 계산합니다:
state, verifier 및 콜백 주소를 애플리케이션 자체 세션에 저장한 뒤, URL 인코딩된 매개변수로 권한 부여 페이지를 엽니다:
plain이 나열되어 있더라도 Public 클라이언트는 이를 사용할 수 없습니다. Confidential 클라이언트도 S256 사용을 권장합니다. 권한 부여를 시작할 때 PKCE를 사용했다면 교환 시 해당 verifier를 반드시 제출해야 합니다.
사용자가 동의한 후 redirect_uri로 돌아오며, 쿼리 매개변수에는 code와 원본 그대로 반환된 state가 포함됩니다. 거부 시 error=access_denied, 오류 설명 및 state가 반환됩니다. 콜백을 처리하기 전에 state가 이번 세션과 일치하는지 먼저 확인합니다. 권한 부여 코드는 10분 동안 유효하며 한 번만 교환할 수 있습니다. 실패한 후에는 연결을 다시 시작해야 하며, 오래된 콜백 URL을 반복해서 새로고침하지 마십시오.
3단계: OAuth token 교환
Public 클라이언트는 브라우저 또는 클라이언트에서 직접 교환합니다. Confidential 클라이언트는 자체 백엔드에서 교환합니다. 요청 본문은 폼 인코딩을 지원하며, 다음 변수는 애플리케이션이 이번 권한 부여에서 얻은 데이터를 나타냅니다:client_secret 폼 필드도 추가해야 합니다. 현재 client_secret_post가 지원되며, HTTP Basic 클라이언트 인증을 이미 지원되는 방식으로 간주하지 마십시오.
성공 응답에서 access_token, token_type, expires_in 및 실제로 부여된 scope를 읽습니다. 요청하고 승인받은 경우에만 offline_access에 refresh_token이 있습니다. OAuth access token을 모델 API의 API Key로 취급하지 말고, token, verifier 또는 권한 부여 코드를 로그, 분석 이벤트 또는 공유 링크에 기록하지 마십시오.
4단계: 사용자 정보와 API Key 읽기
먼저 OAuth access token을 사용하여 UserInfo를 요청합니다:id는 사용자 식별자입니다. profile:read 또는 openid로 기본 프로필(예: username, nickname, avatar, is_verified, date_joined, registration_method)을 읽을 수 있습니다. 이메일에는 email:read가 필요하며, 휴대전화 번호 및 지역에는 phone:read가 필요합니다. 권한이 부여되지 않은 필드가 항상 존재한다고 의존하지 마십시오.
기존 API Key가 필요하고 credentials:read가 승인된 경우, UserInfo의 id를 필터 조건으로 사용합니다:
count와 items를 사용하며, Key 필드는 **items[*].token**이고 data[0].value가 아닙니다. user_id=me는 이 인터페이스에서 유효한 사용자 ID가 아닙니다. 여러 페이지의 데이터는 offset/limit로 계속 읽어야 하며, 첫 번째 페이지를 전체 자격 증명으로 간주하지 마십시오.
애플리케이션, 서비스 및 유효 상태에 따라 적용 가능한 자격 증명을 선택하고, 무작정 첫 번째 항목을 가져오지 마십시오. 목록이 비어 있다고 해서 권한 부여 실패를 의미하지는 않습니다. 사용자가 아직 적용 가능한 Key를 생성하지 않았을 수 있습니다. OAuth access token의 권한 제어와 API Key 자체의 서비스 범위, 할당량 및 만료 조건은 서로 다른 제약입니다.
API Key 읽기를 허용한다는 것은 제3자가 이를 저장하고 사용할 수 있음을 의미합니다. OAuth 요청을 철회하거나 애플리케이션 로그인 상태를 삭제해도 이미 복사된 API Key는 무효화되지 않습니다. 사용자는 자격 증명 관리에서 해당 Key를 별도로 철회하거나 교체해야 합니다.
실행 가능한 Public / PKCE 브라우저 예제
다음 페이지를 등록한REDIRECT_URI에 배포하고, CLIENT_ID와 콜백 주소를 교체합니다. 버튼은 표준 권한 부여를 시작하며, 동일한 페이지로 돌아온 후 개인 프로필과 기존 Key 수를 읽습니다. 예제는 Key를 표시하거나 영속화하지 않습니다. 프로덕션 애플리케이션은 실제 용도에 따라 결과를 사용합니다. 먼저 독립 브라우저 페이지에서 검증한 다음, 이후의 iframe 요구 사항에 따라 검수합니다.
sessionStorage를 읽을 수 있도록 반드시 동일한 출처, 동일한 브라우저 탭/iframe에 있어야 합니다. 프로덕션 애플리케이션은 자체 세션 방식으로 토큰을 관리하고 만료를 처리하며, 응답을 받은 후 권한 부여 URL 매개변수를 제거해야 합니다. 페이지의 주 인터페이스는 먼저 렌더링되어야 하며, 네트워크 실패는 연결 상태에만 영향을 주어야 합니다.
화이트 라벨 웹사이트의 iframe
고객 웹사이트가 직접 권한 부여 페이지로 이동
표준 OAuth 매개변수와 자체 콜백 처리만 사용하면 됩니다.window.location.assign()은 현재 iframe을 탐색하며, 부모 페이지는 화이트 라벨 도메인에 유지됩니다. 아이콘을 위해 embed=studio를 추가하거나 Studio 메시지 프로토콜을 구현할 필요가 없습니다.
다음 조건을 충족해야 합니다:
- 애플리케이션 페이지와 콜백 페이지는 HTTPS를 사용하고 실제로 접근 가능하며, 화이트 라벨 부모 도메인이 iframe을 통해 임베드할 수 있도록 허용해야 합니다. 양쪽의
Content-Security-Policy: frame-ancestors및X-Frame-Options를 확인합니다. - sandbox는 페이지에 필요한 스크립트, 양식 및 출처/저장소 기능을 허용해야 합니다. 팝업 로그인을 지원할 때는 해당 팝업 기능도 필요합니다. Studio에서 제공하는 Website 컴포넌트 구성을 우선 사용합니다.
- 브라우저는 현재 임베드 시나리오에서 권한 부여 상태에 필요한 저장소 사용을 허용해야 합니다. 화이트 라벨 사이트의 로그인 상태와 AuthFrontend의 로그인 상태는 다를 수 있으므로, 화이트 라벨 사이트에 로그인했다고 해서 권한 부여 페이지에도 이미 로그인되어 있다고 가정해서는 안 됩니다.
- 콜백의 token 교환 서비스는 사용 가능해야 하며, 교차 출처 요청은 애플리케이션 출처를 허용해야 합니다. DNS, CORS, HTTP 오류는 모두 재시도 가능한 상태로 표시되어야 하며, 전체 페이지의 렌더링이 중단되어서는 안 됩니다.
Studio의 현재 계정을 사용한 권한 부여
Studio의 「설정 → 홈 → 웹사이트 컴포넌트」에서 OAuth를 활성화하고,client_id와 등록된 콜백 주소를 입력합니다. 웹사이트와 콜백은 동일한 HTTPS 출처를 사용해야 하며, Studio 출처와는 달라야 합니다. 타사 페이지는 다음이 필요합니다:
- 정확한 부모 사이트 origin으로
acedatacloud:oauth:ready를 전송하고,acedatacloud:oauth:init를 수신하고 검증합니다. - 버튼이 state와 PKCE verifier를 생성하고,
acedatacloud:oauth:authorize(state, S256 challenge)를 전송합니다. verifier는 자체 페이지 내부에 보관합니다. - 부모 창, origin 및 state를 검증하고,
acedatacloud:oauth:result의 code 또는 error를 처리한 후 표준 token 엔드포인트에서 교환합니다. Studio는 컴포넌트 영역에 권한 부여 페이지를 표시하며, 사용자가 동의한 후 메시지로 권한 부여 코드를 반환하고, 애플리케이션은 리디렉션할 필요가 없습니다. 로그인되어 있지 않을 때는login_required를 반환하고, 거부 시에는access_denied를 반환하며, 대기 시간 초과 시에는authorization_timeout을 반환합니다. 계정 변경은 애플리케이션 iframe을 다시 생성하고 완료되지 않은 권한 부여를 취소합니다.
profile:read credentials:read를 요청하며, offline_access를 포함하지 않습니다. refresh token을 반드시 받을 수 있다고 가정하지 마십시오. embed=studio, embed_origin은 Studio 호스트와 권한 부여 페이지에서 관리하며, 고객 페이지는 메시지 프로토콜만 준수하면 됩니다.
전체 버튼 예시는 Studio 웹 컴포넌트 OAuth 연동 가이드를 참조하십시오.
수명 주기, 갱신 및 철회
Access token의 기본 유효 기간은 15일이며, 매 응답의expires_in을 기준으로 갱신 또는 재권한 부여를 계획해야 합니다. refresh token의 기본 유효 기간은 30일이며, 기간은 서비스 설정의 영향을 받습니다. 이 두 값을 영구적인 약속으로 하드코딩하지 마십시오.
offline_access 권한을 받은 후 다음을 호출할 수 있습니다:
일반적인 오류 및 검수
배포 전에 최소한 다음을 검증하십시오: 올바른 콜백, 거부, 잘못된 state, 만료/이미 사용된 code, Key 없음, 네트워크 실패, token 만료, 필요한 scope 누락, 그리고 iframe 환경에서의 최초 로그인과 계정 전환. 테스트 증거에 전체 code, token 또는 API Key를 저장하지 마십시오.
2단계 인증 및 재권한 부여
사용자가 2단계 인증을 활성화한 후, Ace Data Cloud는 권한 부여 페이지에서 인증기 인증 코드 또는 일회용 복구 코드 검증을 완료한 다음 권한 부여 코드를 전달합니다. 귀하의 애플리케이션은 계속 표준 OAuth 흐름을 사용해야 하며, 사용자에게 인증기 키 및 복구 코드를 요청하거나 저장하거나 전달해서는 안 됩니다. 사용자가 2단계 인증을 활성화, 변경, 비활성화하거나 계정을 복구한 후에는 이전 계정 세션, 갱신 토큰 및 관련 플랫폼 권한 부여 토큰이 무효화될 수 있습니다. 유효하지 않은 세션 또는invalid_grant를 받으면 사용자에게 표시되는 권한 부여 흐름을 다시 시작하십시오. 이전 권한 부여 코드를 반복해서 사용하지 말고, 검증을 우회하려고 시도하지 마십시오. 일반 모델 API Key의 인증 방식은 그대로 유지됩니다. 계정 탈취가 의심되는 경우에는 영향을 받은 API Key를 별도로 확인하고 철회해야 합니다.
