시작하기 | XID

XID Cloud에서 시작

XID Cloud는 https://xid.dev에서 실행되며 무료입니다. 조직 하나, 애플리케이션 하나, 몇 줄의 코드가 필요합니다.

이 페이지 상단의 무료로 시작을 선택합니다. 가입하고 조직 이름을 정하면 XID가 조직을 만들고 콘솔을 엽니다.
콘솔에서 애플리케이션을 열고 애플리케이션을 만듭니다. 앱의 정확한 리디렉션 URI를 등록하고 클라이언트 ID를 복사합니다.
앱을 XidProvider로 감싸고 issuer https://xid.dev와 클라이언트 ID를 지정한 뒤, 백엔드에서 authenticateRequest로 액세스 토큰을 검증합니다.

import { XidProvider } from '@xid-kit/react'

export function App() {
  return (
    <XidProvider
      mode="oidc"
      issuer="https://xid.dev"
      clientId="client_abc123"
      redirectUri="https://app.example.com/auth/callback"
    >
      <Layout />
    </XidProvider>
  )
}

import { authenticateRequest } from '@xid-kit/backend'

const state = await authenticateRequest(request, {
  jwtKey: env.XID_JWKS_PUBLIC_KEY,
  issuer: 'https://xid.dev',
})
if (!state.isSignedIn) return new Response('Unauthorized', { status: 401 })

SDK는 XID 저장소에서 소스로 배포됩니다. 표준 OIDC 라이브러리도 아래 엔드포인트와 함께 사용할 수 있습니다.

셀프 호스팅 인스턴스에서는 https://xid.dev 대신 자체 인스턴스 도메인을 사용합니다. 배포 방법은 셀프 호스팅에 있습니다.

기본 URL

XID는 ID 공급자입니다. 인스턴스 도메인은 OIDC 발급자, API 기본 URL, Hosted Auth 기본 URL, 콘솔 기본 URL입니다. 조직은 정책, 브랜딩, 멤버십, 리소스 격리를 제공합니다.

먼저 인스턴스 도메인의 /.well-known/openid-configuration을 읽습니다. 디스커버리 문서는 해당 발급자의 인가, 토큰, 사용자 정보, 로그아웃, JWKS 엔드포인트를 애플리케이션에 제공합니다.

접점	경로	사용
OIDC 디스커버리	`/.well-known/openid-configuration`	RP를 설정하기 전에 발급자 메타데이터를 읽습니다.
인가	`/authorize`	사용자를 통합 Hosted Auth 흐름으로 리디렉션합니다.
토큰	`/token`	인가 코드 또는 갱신 토큰을 교환합니다.
사용자 정보	`/userinfo`	유효한 액세스 토큰의 클레임을 읽습니다.
관리 API	`/v1/*`	백엔드에서 조직 리소스를 관리합니다.

최소 연동

OIDC 애플리케이션을 만들고 정확한 리디렉션 URI 값을 등록합니다.
브라우저 및 네이티브 클라이언트에는 PKCE S256을 사용하는 인가 코드 흐름을 사용하세요.
ID 토큰과 액세스 토큰을 발급자 및 JWKS URI에 대해 검증합니다.
갱신 토큰은 서버 측 또는 안전한 네이티브 자격 증명 저장소에 저장하세요.

인가 요청

sequenceDiagram
  participant Browser
  participant RP
  participant XID
  RP->>Browser: /authorize + PKCE S256
  Browser->>XID: /authorize + PKCE S256
  XID->>Browser: /sign-in
  Browser->>XID: WebAuthn / SSO
  XID->>Browser: code
  Browser->>RP: code
  RP->>XID: /token + PKCE S256
  XID->>RP: ID token + access token

const authorizeUrl = new URL('https://xid.dev/authorize')
authorizeUrl.searchParams.set('client_id', clientId)
authorizeUrl.searchParams.set('redirect_uri', redirectUri)
authorizeUrl.searchParams.set('response_type', 'code')
authorizeUrl.searchParams.set('scope', 'openid profile email')
authorizeUrl.searchParams.set('code_challenge', codeChallenge)
authorizeUrl.searchParams.set('code_challenge_method', 'S256')