설치형 RP 가이드

보안 모델

설치형 Interactive RP는 Public PKCE client다. 앱은 Hydra client secret이나 Hydra token을 보관하지 않는다. 복구 기능을 선택한 앱은 기기 키에 결합된 Baron 복구 자격증명을 OS 보안 저장소에 보관한다. 복구 및 다중 프로세스 연동을 따른다.

Installation ID: RP·환경·local enrollment별 256-bit random value
Device Key: 설치별 비대칭 key pair
Installation Binding: 서버가 Installation ID를 RP와 subject에 결속한 값
Device Session: Baron Token Vault를 가리키는 opaque session

MAC address, IMEI, serial, hostname, IP, User-Agent를 Installation ID로 사용하지 않는다. private key는 OS secure storage에 보관하고 다른 환경이나 RP와 공유하지 않는다.

최초 등록

앱이 새 Installation ID와 device key pair를 만든다.
일반 Public PKCE authorization과 consent를 완료한다.
앱이 authorization completion, Installation ID, public JWK, device proof를 Backend Broker에 제출한다.
Backend가 subject, RP, proof, quota, key tombstone을 검증한다.
Backend는 Hydra token을 Token Vault에 보관하고 opaque device session을 반환한다. RP별 발급 허용과 앱 opt-in이 켜져 있고 서버 전체 차단이 없으면 복구 자격증명도 반환한다.

Device public JWK를 DevFront Client JWKS에 등록하지 않는다.

Device Proof 시간 오류 처리

이 절은 저장소 코드의 응답을 설명합니다. 오류 정책은 Error Handling Policy에서 관리합니다. 구현과 검증 기록은 #2186을 참고하세요. 운영 반영 여부는 별도로 확인하세요.

Authorization completion의 시간 오류는 HTTP 400과 본문의 status=400을 반환합니다. 필수 code는 device_proof_expired처럼 서버가 확인한 실패를 식별합니다. 응답 구조와 코드 목록은 OpenAPI의 InstalledDeviceProofTimeFailureResponse를 따릅니다. message는 선택적인 영문 설명이며 번역하지 않습니다.

RP는 오류 상세에 HTTP 상태와 code를 표시합니다. message가 있으면 영문 그대로 표시하며, 문구를 해석해서 복구 동작을 선택하지 않습니다. next_action=restart_login이면 앱의 시각과 proof 생성 시점을 확인한 뒤 새 로그인을 시작합니다. 새 로그인에서는 authorization code와 proof를 새로 만듭니다. next_action=contact_support이면 request_id를 첨부해 관리자에게 문의합니다.

시간 진단의 retryable은 false입니다. 알 수 없는 코드나 다음 행동을 받아도 같은 proof 또는 authorization code를 자동 재전송하지 않습니다. 만료와 미래 발급 시각은 서버가 확인한 시간 조건입니다. 이 조건만으로 실제 기기 시계의 방향이나 네트워크 지연을 확정하지 않습니다.

공개 진단과 민감정보의 경계는 Error Handling Policy를 따릅니다.

Operation 호출

operation마다 현재 device key로 proof를 서명한다.
proof에는 method, path, body digest, nonce/issued time처럼 Backend가 요구하는 context를 결속한다.
idempotency key는 동일한 logical operation에 재사용하고 다른 payload에 재사용하지 않는다.
timeout 뒤 임의로 새 operation을 만들기 전에 기존 operation 상태를 조회한다.
Redis replay 방지는 보조 계층이며 durable 중복 실행 방지는 PostgreSQL execution ledger가 담당한다.

Device lifecycle

등록 상태와 활성 authorization/token family를 구분한다.
disable은 새 operation을 막고 local family/session을 fence한다.
revoke는 복구 가능한 disable보다 강한 종료다.
key rotation은 기존 key proof와 새 key possession을 모두 검증한다.
retired/revoked thumbprint는 tombstone으로 보존하고 재사용하지 않는다.
rotation 뒤에는 새 key로 fresh PKCE authorization이 필요할 수 있다.

Quota

사용자 device quota는 (client_id, subject_kind, subject_id) 경계에서 계산한다.
활성 수는 PostgreSQL token family 상태를 기준으로 한다.
Redis TTL이나 마지막 heartbeat만으로 active quota를 계산하지 않는다.
quota 퇴출은 local fence와 revoke outbox를 하나의 transaction에 기록한다.

운영 확인

DevFront inventory에서 device ID, subject UUID, Tenant, 등록 상태, 활성 authorization, key generation을 구분해 확인한다.
private JWK, Hydra token, raw vault material은 어떤 화면에도 표시하지 않는다.
disable/rotate/revoke 뒤 기존 proof와 session이 실패하는지 확인한다.

공통 Client 등록은 RP Integration Guide, 정확한 endpoint와 proof schema는 OpenAPI를 따른다.

5.0 KiB Raw Blame History