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

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ko/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/linux

## 상태

패키지 상태: **구현됨 · 로컬 검증 완료**. cargo test가 24개 케이스를 통과합니다. Secret Service D-Bus 저장소와 전체 브라우저 리디렉션 흐름은 데스크톱 Linux에서 gnome-keyring 또는 kwallet이 실행 중이어야 합니다. 실제 IdP 왕복 테스트는 수동 검증 대기 중입니다. 이 페이지는 구현된 동작을 문서화하며, 프로덕션 준비 완료를 의미하지 않습니다.

## 요구 사항

- 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를 추가하세요:

```toml
[dependencies]
xid-linux = { path = "../sdk/linux" }   # local development
# published release:
# xid-linux = "0.1"
tokio = { version = "1", features = ["full"] }
```

## 빠른 시작

```rust
use xid_linux::{XidClient, XidConfigBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
// 1. Build config
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 -- opens xdg-open browser, loopback TCP receives callback
let session = client.sign_in(None).await?;
println!("user: {}", session.user.sub);

// 4. Get access token (auto-refresh)
let token = client.get_access_token(None).await?;

// 5. Sign out (revokes refresh token + clears storage)
client.sign_out().await?;
Ok(())
}
```

## 헤드리스 / CI 사용

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

```rust
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` | 저장된 세션을 반환하며 만료가 임박한 경우 자동으로 refresh 토큰을 교체합니다. |
| `get_access_token(options) async` | 유효한 액세스 토큰 문자열을 반환하며 필요 시 자동으로 갱신합니다. |
| `sign_out() async` | /revocation 엔드포인트에서 refresh 토큰을 폐기하고 로컬 저장소를 지웁니다. |
| `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는 데스크톱 키링 데몬을 통해 저장된 토큰을 암호화합니다. 앱은 암호화 키를 직접 관리하지 않습니다.
- Refresh 토큰은 XID 서버에 의해 매번 사용 시 교체됩니다. SDK는 각 갱신 호출 후 새 토큰을 저장합니다.

## 알려진 제한 사항

- JWKS 기반 ID token 검증과 cache refresh는 구현되어 로컬 테스트를 통과했습니다. L4 지원 전에는 desktop Secret Service와 IdP 검증이 필요합니다.
- 리디렉션 포트는 고정되어 있으며 XID 콘솔에 등록된 redirect\_uri와 일치해야 합니다. 동적 포트 무작위화(RFC 8252)는 동적 클라이언트 등록 지원이 필요합니다.
- System browser redirect와 Secret Service storage에는 desktop environment 증거가 필요합니다.

Source: https://xid.dev/ko/sdks/linux/index.mdx