Scope 레퍼런스

Source: oauth/scopes.md · Live: https://docs.1pass.dev/oauth/scopes LLM-sanitized: internal links absolutized, VitePress containers → admonitions, line numbers in the Jump-to Index reference this rendered file (1-indexed).

📍 Jump-to Index

• L24-L36: ## 표준 Scope
• L37-L47: ## 커스텀 Scope
• L48-L72: ## 앱 등록 시 allowed_scopes
  • L59-L72: ### Scope 설정
• L73-L122: ## Scope drift 처리
  • L86-L122: ### 감지 방법
• L123-L130: ## required 마킹
• L131-L140: ## 재인가 UX
• L141-L148: ## 요청 방법

---

Scope 레퍼런스

Scope는 공백 구분 문자열입니다 (profile:basic email phone, 콤마 ❌).

표준 Scope

scope	userinfo 반환 필드	비고
profile:basic	sub, preferred_name, full_name	기본 신원. 등록·요청 모두 정확히 profile:basic 사용. scope drift 검사(기본 block)는 정확 문자열 비교라 단독 profile 은 미등록으로 거부됨 (userinfo claim 매핑만 profile≈profile:basic 동등)
email	sub, email, email_verified
phone	sub, phone_number	별도 동의
address	sub, address, postal_code	별도 동의
identity:level	sub, identity_verified_level (0/1/2/3)	실명인증 레벨. 신규 앱은 명시 요청 필요 (legacy 앱은 profile에 자동 포함)
openid	id_token 발급 + sub	OIDC 1.0 활성화

identity_verified_level 값: 0 unverified · 1 email_verified · 2 phone_verified · 3 sp_verified. logi는 실명/주민번호 미보유, 정수 플래그만 제공.

커스텀 Scope

네임스페이스 필수 형식 <namespace>:<key> (콜론 1개):

krx_listing:reviewer_role
blog:post.write

User#custom_claims jsonb {namespace: {key: value}} 로 저장, scope 요청 시 id_token/userinfo 에 병합.

앱 등록 시 allowed_scopes

{
  "oauth_application": {
    "redirect_uris": ["https://app.example.com/cb"],
    "allowed_scopes": ["profile:basic", "email"]
  }
}

Scope 설정

logi apps edit <id> --add-scope phone

app = OauthApplication.kept.find_by(name: "your_app")
app.set_scopes!(["openid", "profile:basic", "email", "phone"])

⚠️ Warning: 앱의 allowed_scopes 가 비어 있으면 OAuth 가 거절됩니다 allowed_scopes 가 빈 앱은 authorize 시 invalid_scope: no allowed scopes 로 거절됩니다. 콘솔 → 앱 상세 → Scopes 에서 사용할 scope(openid, profile:basic, email 등)를 활성화해야 OAuth 가 동작합니다. 등록 경로별로 초기 scope 가 다릅니다 — 웹 콘솔 등록 폼은 scope 미지정 시 openid profile:basic email baseline 을 자동 시드하고, API/CLI 등록은 요청에 담은 allowed_scopes 만 등록되며(미지정 시 비어 있음), MCP/DCR connector 는 openid agent:read agent:write 상한만 받습니다(profile:basic/email 등 신원 scope 미포함). scope 가 비어 있거나 부족하면 이 화면에서 직접 활성화하세요.

Scope drift 처리

기본 정책은 block 입니다 — 요청 scope 중 allowed_scopes 에 없는 것이 하나라도 있으면 요청 전체가 invalid_scope 로 거절됩니다 (callback-safe redirect). 운영자가 앱 단위로 log_only(미등록 scope silent drop 후 등록된 subset 으로 진행) 또는 alert(log_only + 관리자 알림) 로 완화할 수 있습니다.

케이스	기본 (block)	log_only / alert
모든 요청 scope 등록됨	✅ 진행	✅ 진행
일부 미등록	❌ invalid_scope	⚠️ 미등록 drop, 등록된 것으로 진행
모두 미등록	❌ invalid_scope	❌ invalid_scope
required: true scope 가 effective 에서 누락	❌ invalid_scope	❌ invalid_scope

정책과 무관하게 drift 는 항상 기록됩니다 (로그 + drift record + webhook_url 설정 시 최초 1회 webhook) — block 으로 거절된 경우에도 운영자가 원인을 추적할 수 있습니다.

감지 방법

1. 서버 로그 (client_id 로 grep):

[oauth] scope_drift app_id=4 client_id=logi_xxx policy=block dropped=phone,address kept=profile:basic,email

2. Webhook scope.drift_detected (HMAC-SHA256 서명, (app_id, scope_name) 페어당 1회):

{
  "event_type": "scope.drift_detected",
  "application_id": 4,
  "payload": {
    "scope_name": "phone",
    "client_id": "logi_xxx",
    "first_seen_at": "2026-04-29T01:30:00Z",
    "allowed_scopes": ["openid", "profile:basic", "email"]
  }
}

3. 토큰 응답 헤더 X-Logi-Scope-Drift — 최근 7일 내 기록된 drift 이력을 정상 token 응답에 echo. 기본 block 정책에서는 drift 가 포함된 요청 자체가 invalid_scope 로 거절되므로, 이 헤더는 이후의 정상 token 응답(드리프트 없는 요청)에 이력으로 나타납니다:

HTTP/1.1 200 OK
X-Logi-Scope-Drift: address,phone

if drift = res["X-Logi-Scope-Drift"]
  Rails.logger.warn("[logi] scope drift: #{drift}")
end

4. Escalation webhook scope.drift_unresolved — 초기 알림 7일 후에도 drift 진행 중이면 1회 발사.

5. 개발자 대시보드 — Apps 카드에 "Scope drift" 핀, 상세에 drift 테이블.

required 마킹

app.oauth_application_scopes.create!(oauth_scope: email_scope, required: true)

필수 scope 거부 시 → access_denied.

재인가 UX

사용자가 profile:basic email 동의 이후:

요청 scope	동작
동일하거나 축소 (profile:basic)	UI 스킵, 즉시 code 발급
확장 (profile:basic email phone)	"NEW" 배지 + 추가 동의
Consent revoke 후	Consent 화면 재노출

요청 방법

GET /oauth/authorize?...&scope=profile:basic+email+openid&...

공백 구분, URL encoding 시 %20 또는 +. 응답 scope 필드는 실제 부여된 scope 를 echo (사용자가 일부만 동의 가능).