OIDC 单点登录

除了内置的用户名/密码登录之外，Xinference 还可以对接外部 OpenID Connect（OIDC）身份提供方（例如 Keycloak）进行用户认证。SSO 用户在首次登录时自动创建，之后与其他用户一样进行管理。

OIDC 要求启用基于数据库的身份验证系统（默认已启用）——参见 身份验证系统（基于数据库）。

配置

在运行 RESTful API 的进程上设置以下环境变量以启用 OIDC：

环境变量	含义
XINFERENCE_OIDC_ENABLED	设置为 1 / true / yes 以启用 OIDC。默认：禁用。
XINFERENCE_OIDC_ISSUER	身份提供方的 Issuer URL，例如 https://keycloak.example.com/realms/myrealm。Xinference 会从 <issuer>/.well-known/openid-configuration 自动发现提供方的各个端点。
XINFERENCE_OIDC_CLIENT_ID	在身份提供方注册的 OAuth 客户端 ID。
XINFERENCE_OIDC_CLIENT_SECRET	OAuth 客户端密钥（必须使用 confidential 类型的客户端）。
XINFERENCE_OIDC_REDIRECT_URI	指向 Xinference 的回调 URL，即 http(s)://<xinference-endpoint>/api/oidc/callback。同一 URL 必须在身份提供方注册为有效的重定向 URI。

设置 XINFERENCE_OIDC_ENABLED 后，其余四个变量均为必填——否则 Xinference 会拒绝启动并报告缺失的变量。

示例（Keycloak）：

export XINFERENCE_OIDC_ENABLED=1
export XINFERENCE_OIDC_ISSUER=https://keycloak.example.com/realms/myrealm
export XINFERENCE_OIDC_CLIENT_ID=xinference
export XINFERENCE_OIDC_CLIENT_SECRET=<client-secret>
export XINFERENCE_OIDC_REDIRECT_URI=http://xinference.example.com:9997/api/oidc/callback
xinference-local -H 0.0.0.0

登录流程

• 将用户引导至 Xinference 端点上的 GET /api/oidc/authorize。Xinference 会将浏览器重定向到身份提供方的授权页面（请求 openid profile email 权限范围）。

• 在身份提供方登录成功后，浏览器返回 /api/oidc/callback。Xinference 用授权码换取令牌，根据提供方发布的 JWKS 校验 ID 令牌的签名，签发自己的访问令牌和刷新令牌，然后重定向到 Web UI。

用户创建与权限

• 用户通过 OIDC 的 sub 声明进行匹配。首次登录时会自动创建账号，用户名取自提供方的 preferred_username （若无则回退到 email）， source 设置为 oidc。

• 新创建的 SSO 用户初始只拥有 models:list 权限。管理员可以通过 用户管理 页面或 /v1/admin/users API 授予更多权限——变更在用户的下一次请求时生效，无需重新登录。

• 在用户管理中禁用某个 SSO 用户后，即使其身份提供方账号仍然有效，该用户也无法登录。

• OIDC 用户没有本地密码，因此本地密码登录和修改密码不适用于他们。