상태
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 증거가 필요합니다.