OAuth 스코프(scope)는 사용자가 외부 애플리케이션에 데이터나 기능 접근을 허용하거나 거부하도록 하는 권한 묶음이다. 금융 API를 활용하는 분석 도구나 모델 컨텍스트 프로토콜(MCP)로 API와 상호작용하는 인공지능 도구처럼, 사용자 대신 데이터를 다루는 제3자 앱을 플랫폼에 연결할 때 활용할 수 있다.

스코프가 필요한 경우

스코프는 API나 서비스가 최종 사용자에 관한 데이터를 보유하거나 사용자를 대신해 이메일을 보내는 등 관련 기능을 제공하고, 요청 앱이 그 API나 서비스를 운영하는 조직과 다른 곳에 속할 때 유용하다. 데이터가 사용자와 관련이 없다면 사용자 동의가 핵심인 스코프 대신 다른 권한 부여 방식을 쓰는 편이 낫다. API와 앱이 같은 조직 소유라면 스코프로 권한을 줄일 수는 있지만, 사용자 동의 없이 권한을 제한하는 다른 방법도 있다.

스코프는 권한을 나타내는 공백 구분 문자열이다. 각 스코프의 의미는 데이터를 제공하는 플랫폼이 정하며, OAuth 표준은 문자열의 내부 구조를 규정하지 않는다. OAuth 2 표준은 클라이언트가 요청한 스코프를 권한 서버가 정책이나 사용자의 지시에 따라 전부 또는 일부 무시할 수 있다고 정한다. 요청한 범위와 실제 발급 범위가 다르면 서버는 발급된 범위를 응답에 알려야 한다. 요청에 스코프가 없을 때는 미리 정한 기본값으로 처리하거나 잘못된 스코프 오류를 반환해야 한다.

OAuth 흐름에서는 권한 요청 URL에 scope 매개변수가 들어가고, 사용자에게 동의 화면이 표시된다. 발급된 액세스 토큰의 스코프는 요청값과 다를 수 있으며, API는 토큰의 스코프를 검사해 접근을 제한해야 한다. 스코프는 토큰에 적용되지만 역할 기반 접근 제어(RBAC)의 역할은 사용자나 그룹에 적용된다. 스코프는 제3자 앱이 요청하고 사용자가 명시적으로 동의하며, 토큰 수명 동안 유효하다. 역할은 관리자나 업무 규칙에 따라 정해지고 로그인으로 승인되는 경우가 일반적이다.

설계와 운영

플랫폼을 설계할 때는 외부 개발자와 협의해 필요한 API와 기능을 파악하고, 공개할 API를 목록화해 기능을 묶어야 한다. 보안팀과도 논의하고, 외부 개발자에게 묶음이 실제 사용 방식에 맞는지 확인한다. 처음부터 스코프를 많이 만들기보다 작은 집합으로 시작해 필요하면 추가하는 편이 낫다. 스코프는 제3자 앱에 반영된 뒤 오래 유지되는 경향이 있기 때문이다.

이름과 설명은 사용자와 개발자 모두 이해할 수 있어야 한다. 권한을 지나치게 세분화하면 사용자와 개발자 모두 선택에 피로를 느낄 수 있고, 지나치게 넓은 범위는 무엇을 허용하는지 불분명하게 만든다. 예를 들어 accounts.read는 계좌 정보와 잔액 조회, transfers.write는 계좌 간 송금 시작을 나타낼 수 있다. 자원에 묶이지 않은 기능에는 creditScore.calculate처럼 별도 스코프를 둘 수도 있다. read와 write를 기준으로 가능한 조합을 검토하되, 실제로 제공하지 않을 권한까지 모두 만들 필요는 없다.

계층 구조를 쓸 수 있지만 너무 깊게 중첩하면 사용자가 권한 차이를 이해하기 어렵고, 개발자가 필요 이상으로 넓은 권한을 요청하거나 API 구현이 복잡해질 수 있다. 스코프 이름에 버전을 넣는 방식도 있지만, 구글·슬랙·Zendesk처럼 버전 정보를 스코프 문자열에 넣지 않는 대형 제공업체도 있다. admin 같은 포괄적 관리자 스코프는 제3자 앱이 사용자에게 요청하지 않도록 설계 단계부터 피하라고 글은 권고한다.

외부 개발자가 활용할 수 있도록 공개 스코프 전체 목록과 각 권한이 다루는 데이터·기능, 응답 예시, 인증·호출 제한·요금 같은 비기능 조건을 문서화해야 한다. OAuth 기본 사용법과 SDK 또는 예제 앱도 도움이 된다. API 접근에 별도 승인이나 요금, 서비스 약관 동의가 필요하다면 비기술적 절차도 안내해야 한다. 실제로 접근을 허용할 계획이 없다면 스코프를 구현할 이유가 없다고 글은 지적한다.

어떤 앱이 어떤 스코프를 얼마나 자주 쓰는지 추적하면 사용 현황과 보안 적절성, 성능 문제를 파악하는 데 도움이 된다. 스코프가 오래 쓰이는 만큼 폐기 정책과 이전 지원, 외부 개발자에게 변경을 알릴 방법도 미리 고려해야 한다. API는 요청마다 토큰의 스코프를 확인하고, 예상하지 못한 스코프도 처리해야 한다. URL에 포함된 값은 사용자나 클라이언트가 바꿀 수 있으므로 입력을 검증하고, 스코프별 접근 테스트도 작성해야 한다.

스코프가 복잡해지면 검증 비용과 구현 복잡도가 커질 수 있다. API 구현에 따라 단순 조회나 접두사 트리 같은 자료구조를 고려할 수 있으며, OpenAPI 설정에 리소스별 스코프를 지정하는 방법도 있다. OAuth 2.1 초안과 스코프 설명은 OAuth 2 RFC 및 OAuth 2.1 초안에서 확인할 수 있다.

더 세밀한 권한 표현

스코프는 기본적으로 문자열이라 내부 구조가 없다. 2023년 공개된 Rich Authorization Requests(RAR) 표준은 JSON 구조를 담는 authorization_details 매개변수로 이 한계를 보완한다. locations, actions, datatypes 같은 선택 항목을 사용할 수 있고 자체 필드를 추가할 수도 있다. 다만 이 방식은 일부 표준에서 쓰이지만 scope 매개변수만큼 널리 지원되지는 않는다.

스코프 설계와 운영에 관한 원문은 FusionAuth의 가이드에서 볼 수 있다. 함께 참고할 자료로는 OIDC 스코프 정의, OAuth 2와 OAuth 2.1의 차이, 권한 부여 모델, OpenAPI의 스코프 설정, RAR 표준이 있다.

부록: 원문 예시

text
${fusionAuthURL}/oauth2/authorize?client_id=${clientId}   &response_type=code   &redirect_uri={redirectURI}   &state=${stateValue}   &code_challenge=${codeChallenge}   &code_challenge_method=S256   &scope=profile%20email%20openid%20offline_access%20accounts.read%20creditScore.read%20investments.read%20profile.read%20transactions.read