콘텐츠로 건너뛰기

sdk/linux

브라우저 실행에 xdg-open, 인증 콜백에 loopback TCP, PKCE S256, freedesktop.org Secret Service 토큰 저장소를 사용하는 Linux 데스크톱용 Rust SDK.

Markdown으로 보기

상태

Package 상태는 구현 및 로컬 검증 완료입니다. Rust 단위 테스트 suite가 통과했습니다. Secret Service D-Bus storage, xdg-open, 전체 loopback callback 및 실제 IdP round-trip을 검증하려면 여전히 desktop Linux integration environment가 필요합니다. 이 페이지는 구현된 동작을 설명하며 production-ready 상태임을 주장하지 않습니다.

Registry 상태: UNPUBLISHED. 이 SDK는 저장소 소스 checkout에서만 설치하고 외부 package registry를 사용하지 마세요.

요구 사항

  • Rust(stable, 2021 에디션)
  • tokio 비동기 런타임
  • 시스템 브라우저 실행을 위한 xdg-open(xdg-utils)과 Secret Service 저장소용 gnome-keyring 또는 kwallet이 있는 D-Bus 세션이 실행 중인 데스크톱 Linux
  • 헤드리스 / CI 환경: in-memory-storage 기능을 사용하거나 InMemoryStorage를 직접 주입하세요

설치

Cargo.toml에 xid-linux를 추가하세요:

[dependencies]
xid-linux = { path = "../xid/sdk/linux" }
tokio = { version = "1", features = ["full"] }

빠른 시작

use xid_linux::{XidClient, XidConfigBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Build config. offline_access is rejected until DPoP is implemented.
    let config = XidConfigBuilder::new()
        .issuer("https://xid.dev")
        .client_id("your_client_id")
        .redirect_uri("http://127.0.0.1:51234/callback")
        .redirect_port(51234)
        .build()?;

    // 2. Create client (default: Secret Service storage)
    let client = XidClient::configure(config)?;

    // 3. Sign in. xdg-open launches the browser and loopback TCP receives the callback.
    let session = client.sign_in(None).await?;
    println!("user: {}", session.user.sub);

    // 4. Get the current unexpired access token. Expiry returns SessionExpired.
    let token = client.get_access_token(None).await?;

    // 5. Clear local token and guest state. No revoke request is sent.
    client.sign_out().await?;
    Ok(())
}

헤드리스 / CI 사용

D-Bus Secret Service 데몬을 사용할 수 없는 경우 런타임 오류를 방지하려면 InMemoryStorage를 전달하세요:

use xid_linux::{XidClient, XidConfigBuilder};
use xid_linux::storage::InMemoryStorage;
use std::sync::Arc;

let config = XidConfigBuilder::new()
    .issuer("https://xid.dev")
    .client_id("your_client_id")
    .redirect_uri("http://127.0.0.1:51234/callback")
    .build()?;

let client = XidClient::configure_with_storage(config, Arc::new(InMemoryStorage::new()))?;

핵심 API

방법 설명
XidConfigBuilder::new() XidConfig 빌더. 필수 필드: issuer, client_id, redirect_uri. 선택 필드: scopes, redirect_port(기본값 51234), http_timeout_secs(기본값 30).
XidClient::configure(config) 기본 SecretServiceStorage로 클라이언트를 생성합니다.
XidClient::configure_with_storage(config, adapter) 사용자 정의 StorageAdapter(예: InMemoryStorage)로 클라이언트를 생성합니다.
sign_in(options) async xdg-open 브라우저를 열고 redirect_port에서 loopback TCP 리스너를 시작한 후 인증 코드 콜백을 기다려 교환하고, 토큰을 저장한 후 Session을 반환합니다.
get_session() async 현재 저장되어 있고 만료되지 않은 session을 반환합니다. 만료되면 로컬 token state를 지우고 SessionExpired를 반환합니다.
get_access_token(options) async 현재 만료되지 않은 access token을 반환합니다. 만료되었거나 force_refresh가 지정되면 로컬 token state를 지우고 SessionExpired를 반환합니다.
sign_out() async 로컬 token과 guest session storage를 지웁니다. revoke request는 전송하지 않습니다.
set_token_storage(adapter) 생성 후 저장소 어댑터를 교체합니다.

저장소 어댑터

어댑터 설명
SecretServiceStorage 기본값. D-Bus를 통해 freedesktop.org Secret Service(gnome-keyring 또는 kwallet)에 토큰을 저장합니다. 실행 중인 데스크톱 세션이 필요합니다.
InMemoryStorage 프로세스 메모리만 사용합니다. 프로세스 종료 시 토큰이 사라집니다. Secret Service가 없는 테스트 또는 CI 환경에 사용하세요.

보안

  • 공개 클라이언트 — client secret이 저장되거나 전송되지 않습니다.
  • PKCE S256만 사용합니다. 서버는 plain challenge 방식을 거부합니다.
  • CSRF를 방지하기 위해 loopback 콜백에서 OAuth state가 검증됩니다(RFC 8252 loopback 리디렉션).
  • Secret Service는 데스크톱 키링 데몬을 통해 저장된 토큰을 암호화합니다. 앱은 암호화 키를 직접 관리하지 않습니다.
  • DPoP가 구현될 때까지 SDK는 offline_access를 거부합니다. 예기치 않은 refresh_token response fields는 영속화하지 않습니다.

알려진 제한 사항

  • JWKS 기반 ID token 검증, nonce 검증, JWKS cache renewal이 구현되어 로컬에서 테스트되었습니다. L4 지원을 선언하려면 desktop Secret Service와 실제 IdP round-trip을 더 검증해야 합니다.
  • 리디렉션 포트는 고정되어 있으며 XID 콘솔에 등록된 redirect_uri와 일치해야 합니다. 동적 포트 무작위화(RFC 8252)는 동적 클라이언트 등록 지원이 필요합니다.
  • System browser redirect와 Secret Service storage에는 desktop environment 증거가 필요합니다.
탐색

입력하여 검색...

화살표 키로 이동Enter 키로 선택Escape 키로 닫기