はじめに | 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`	リライングパーティを設定する前に発行者メタデータを読み取ります。
認可	`/authorize`	ユーザーを統合 Hosted Auth フローへリダイレクトします。
トークン	`/token`	認可コードまたはリフレッシュトークンを交換します。
ユーザー情報	`/userinfo`	有効なアクセストークンのクレームを読み取ります。
管理 API	`/v1/*`	バックエンドから組織リソースを管理します。

最小構成の統合

OIDC アプリケーションを作成し、完全一致のリダイレクト URI 値を登録します。
ブラウザーとネイティブクライアントには PKCE S256 付きの認可コードフローを使用します。
発行者と JWKS URI に対して ID トークンとアクセストークンを検証します。
リフレッシュトークンはサーバー側、または安全なネイティブ認証情報ストアに保存します。

認可リクエスト

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')