> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/zh-cn/pei-zhi/overleaf-toolkit/authentication/oidc-authentication.md).

# OIDC 身份验证

此功能由 [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep)。这里我们为您的配置提供一些文档。

### 配置

在内部，Overleaf OIDC 模块使用 [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect) 库。如果你在配置 OpenID Connect 时遇到问题，建议阅读以下内容的 README： `passport-openidconnect` 的 README，以了解它所期望的配置。

环境变量 `EXTERNAL_AUTH` 是启用 OIDC 身份验证模块所必需的。此环境变量指定启用哪些外部身份验证方式。该变量的值是一个列表。如果该列表包含 `oidc` 则会启用 OIDC 身份验证。

例如： `EXTERNAL_AUTH=ldap oidc`

使用 OIDC 身份验证方法时，用户会被重定向到身份提供方（IdP）的认证站点。如果 IdP 成功完成用户认证，系统会在 Overleaf 用户数据库中查找包含以下内容的记录： `thirdPartyIdentifiers` 字段，其结构如下：

```
thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]
```

该 `externalUserId` 必须与 IdP 服务器返回的配置文件中的用户 ID 匹配（参见 `OVERLEAF_OIDC_USER_ID_FIELD` 环境变量），并且 `providerId` 必须与 OIDC 提供方的 ID 匹配（参见 `OVERLEAF_OIDC_PROVIDER_ID`).

如果没有找到匹配记录，系统会在数据库中搜索主电子邮件地址与 IdP 用户配置文件中的电子邮件匹配的用户：

* 如果找到了这样的用户， `thirdPartyIdentifiers` 字段将被更新。
* 如果没有找到匹配用户，并且未禁用即时（JIT）账户创建，则会使用该电子邮件地址和从 IdP 配置文件中获取的 `thirdPartyIdentifiers` 创建一个新用户。

在这两种情况下，用户都被认为已与外部 OIDC 用户“关联”。用户可以在 `/user/settings` 页面。

#### 环境变量

以下五个必需变量的值可以通过使用 `.well-known/openid-configuration` 端点从你的 OpenID 提供方（OP）获取。

* `OVERLEAF_OIDC_ISSUER` **（必需）**
* `OVERLEAF_OIDC_AUTHORIZATION_URL` **（必需）**
* `OVERLEAF_OIDC_TOKEN_URL` **（必需）**
* `OVERLEAF_OIDC_USER_INFO_URL` **（必需）**
* `OVERLEAF_OIDC_LOGOUT_URL` **（必需）**

以下两个必需变量的值将由你的 OP 管理员提供

* `OVERLEAF_OIDC_CLIENT_ID` **（必需）**
* `OVERLEAF_OIDC_CLIENT_SECRET` **（必需）**
* `OVERLEAF_OIDC_SCOPE`
  * 默认： `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * OP 的任意 ID，默认为 `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * OP 的名称，用于 `关联账户` 部分中的 `/user/settings` 页面，默认为 `OIDC Provider`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * 身份服务的显示名称，用于登录页面（默认： `使用 $OVERLEAF_OIDC_PROVIDER_NAME 登录`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * OP 的描述，用于 `关联账户` 部分（默认： `使用 $OVERLEAF_OIDC_PROVIDER_NAME 登录`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * `了解更多` OP 描述中的 URL，默认：无 `了解更多` 描述中的链接。
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * 不要在 `/user/settings` 页面上显示 OP，如果用户的账户未与 OP 关联，则默认 `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * 此属性的值将被 Overleaf 用作外部用户 ID，默认为 `id`。其他可能合理的值有 `email` 和 `用户名` （对应于 `preferred_username` OIDC 声明）。
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * 限制通过 OIDC 进行身份验证的用户的即时（JIT）账户创建。如果设置为以逗号分隔的域名列表，则只有当用户电子邮件地址的域名与列表中的某个域匹配时，才会创建新账户。如果域名不匹配，管理员必须使用 OIDC 用户的电子邮件地址手动创建用户账户，并使用强随机密码，或者更好地，完全不使用该 `hashedPassword` 字段。域名可以包含前导 `*.` 通配符以匹配子域。
    * 示例：要允许为电子邮件地址类似于以下形式的用户创建 JIT 账户 `name@example.com` 和 `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * 示例：要完全禁用 JIT 账户创建：\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * 如果设置为 `true`，在登录时更新用户 `first_name` 和 `last_name` 字段，并禁用 `/user/settings` 页面。
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` 和 `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * 当这两个环境变量都设置时，登录过程会更新 `user.isAdmin = true` 如果 OP 返回的配置文件包含由 `OVERLEAF_OIDC_IS_ADMIN_FIELD` 指定的属性，且其值与 `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`的数组，否则 `user.isAdmin` 会被设置为 `false`匹配，则 `OVERLEAF_OIDC_IS_ADMIN_FIELD` 为 `email` 则使用属性的值 `emails[0].value` 进行匹配检查。

你的 OpenID 提供方的重定向 URL 是 `https://my-overleaf-instance.com/oidc/login/callback`.

<details>

<summary>示例 variables.env 文件</summary>

{% code title="variables.env" overflow="wrap" %}

```dotenv
OVERLEAF_APP_NAME="Our Overleaf Instance"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# 使用 ImageMagick 启用缩略图生成
ENABLE_CONVERSIONS=true

# 禁用邮箱确认要求
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## 通过 nginx-proxy 设置 TLS
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Our Overleaf Instance
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=support@example.com

OVERLEAF_LEFT_FOOTER=[{"text": "联系您的支持团队", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"你好，我在右侧", "url":"https://github.com/yu-i-i/overleaf-cep"}]

OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
OVERLEAF_EMAIL_SMTP_PORT=587
OVERLEAF_EMAIL_SMTP_SECURE=false
# OVERLEAF_EMAIL_SMTP_USER=
# OVERLEAF_EMAIL_SMTP_PASS=
# OVERLEAF_EMAIL_SMTP_NAME=
OVERLEAF_EMAIL_SMTP_LOGGER=false
OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
OVERLEAF_CUSTOM_EMAIL_FOOTER=该系统由 x 部门运行

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

#################
## CE 的 OIDC ##
#################

EXTERNAL_AUTH=oidc

OVERLEAF_OIDC_PROVIDER_ID=oidc
OVERLEAF_OIDC_ISSUER=https://keycloak.provider.com/realms/example
OVERLEAF_OIDC_AUTHORIZATION_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/auth
OVERLEAF_OIDC_TOKEN_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/token
OVERLEAF_OIDC_USER_INFO_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/userinfo
OVERLEAF_OIDC_LOGOUT_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/logout
OVERLEAF_OIDC_CLIENT_ID=Overleaf-OIDC
OVERLEAF_OIDC_CLIENT_SECRET=DoNotUseThisATGgaAcTgCcATgGATTACAagGtTCaGcGTAG
OVERLEAF_OIDC_IDENTITY_SERVICE_NAME='使用 Keycloak OIDC 提供方登录'
OVERLEAF_OIDC_PROVIDER_NAME=OIDC Keycloak 提供方
OVERLEAF_OIDC_PROVIDER_INFO_LINK=https://openid.net
OVERLEAF_OIDC_IS_ADMIN_FIELD=email
OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=overleaf.admin@example.com
OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false
```

{% endcode %}

</details>


---

# 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://ayakaleaf-pro.ayaka.space/on-premises/zh-cn/pei-zhi/overleaf-toolkit/authentication/oidc-authentication.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.