> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/zh/system-administration/configuring-vergeos-as-oidc-client.md).

# 将 VergeOS 配置为 OIDC 客户端

## 概述

{% hint style="info" %}
**要点**

* 配置 VergeOS 使用 OIDC 身份验证
* 连接到 VergeOS OIDC 身份提供商
* 启用自动用户创建和同步
* 自定义登录外观和行为
  {% endhint %}

本指南说明如何配置 VergeOS 系统或租户，以使用另一个 VergeOS 系统作为 OIDC 身份提供商进行身份验证。

## 前提条件

* 可访问 VergeOS OIDC 提供商系统
* 提供商的 Well Known 配置 URL
* 提供商的 Client ID 和 Client Secret
* 对客户端 VergeOS 系统的管理访问权限
* 客户端 VergeOS 系统的完整 URL

## 步骤

### 1. 访问授权设置

* 点击 **系统** 在顶部菜单中
* 选择 **认证来源**
* 点击 **新建**

### 2. 配置基本设置

* **名称**：输入此认证来源的标识符（显示在登录按钮上）
* **驱动程序**：选择 **OpenID（Well Known 配置）**
* **基础 URL**：输入 Well Known 配置 URL
* **重定向 URI**：输入此 VergeOS 系统的完整 URL
* **Client ID**：从提供商处粘贴客户端 ID
* **Client Secret**：从提供商处粘贴客户端密钥

### 3. 配置身份验证参数

这些设置通常使用默认值效果最佳：

* **令牌提示参数**：保持为 `post_logout_redirect_uri`
* **重定向参数**：保持为 `post_logout_redirect_uri`
* **范围**：保持为 `openid profile email groups`
* **组范围**：保持为 `groups`

### 4. 启用推荐选项

勾选这些选项以获得最佳功能：

* **解码 ID 令牌**
* **更新远程用户**
* **更新用户电子邮件地址**
* **更新用户显示名称**
* **更新组成员资格**

### 5. 配置用户创建

选择您偏好的用户创建方式：

* **自动创建用户**：输入 `.*` 以自动创建所有用户
* **按组自动创建用户**：指定用于限制自动创建的组

### 6. 自定义登录外观

可选择配置：

* 按钮背景颜色
* 按钮文字颜色
* 自定义 Font Awesome 图标
* 图标颜色（使用 HEX 代码）

### 7. 保存配置

* 点击 **提交** 以创建授权来源

## 最佳实践

* 在大规模部署前，使用测试用户测试身份验证
* 除非需要排查问题，否则保持调试模式关闭
* 记录您的配置选择以便日后参考
* 定期验证用户同步是否按预期工作

## 故障排除

{% hint style="warning" %}
**常见问题**

* **身份验证失败**
  * 验证 Client ID 和 Secret 是否正确
  * 检查 Well Known 配置 URL
  * 确保重定向 URI 完全匹配
* **用户同步问题**
  * 验证已启用组范围
  * 检查组成员资格设置
  * 临时启用调试模式
* **登录按钮缺失**
  * 验证授权来源已启用
  * 检查登录样式设置
  * 清除浏览器缓存
    {% endhint %}

## 其他资源

* [Font Awesome 图标参考](https://fontawesome.com/v4.7.0/cheatsheet/)
* [将 VergeOS 作为 OIDC 提供商进行设置](/knowledge-base/zh/system-administration/setting-up-vergeos-as-identity-provider-oidc.md)

## 反馈

{% hint style="info" %}
**需要帮助吗？**

如果您在配置 OIDC 客户端设置时遇到任何问题，或对该过程有任何疑问，请随时联系我们的支持团队。
{% endhint %}

***

{% hint style="info" %}
**文档信息**

* 最后更新：2024-01-22
* VergeOS 版本：4.12 及更高版本
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/knowledge-base/zh/system-administration/configuring-vergeos-as-oidc-client.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.