开始使用 | 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 是身份提供方。实例域名是 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')