Skip to content

docs: document OIDC IdP email verification requirement #209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
boris-w merged 1 commit into from
Aug 10, 2026
Merged

docs: document OIDC IdP email verification requirement #209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions en/deploy/oidc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,28 @@ This allows users to log in via GitHub, Google, or your OIDC provider.

---

## Identity Provider Security Requirements

Teable trusts the email address returned by your IdP and uses it to automatically link OIDC logins to existing accounts with the same email. The identity provider you connect **must guarantee that user email addresses are verified**.

<Warning>
Do not connect identity providers that let users set arbitrary, unverified email addresses (for example, multi-tenant IdPs with open registration). On such providers, an attacker can register an account using the email address of an existing user on your instance and take over that account by signing in via OIDC. This risk is especially acute when local password login is also enabled on the same instance.
</Warning>

Recommendations:

- Only connect enterprise-grade IdPs under your control (such as Okta, Azure Entra ID, Google Workspace, or Keycloak) with email verification enabled.
- If your instance uses SSO exclusively, set [`PASSWORD_LOGIN_DISABLED=true`](/en/deploy/env) to disable local password login and further reduce the attack surface.

---

## Important Notes

1. **HTTPS Required**: All URLs must use HTTPS in production
2. **Callback URL Must Match**: The callback URL in Teable must exactly match what's configured in your IdP
3. **Restart Required**: After changing environment variables, restart Teable for changes to take effect
4. **Secure Storage**: Never commit secrets to version control; use environment variables or secret managers
5. **IdP Must Verify Emails**: See [Identity Provider Security Requirements](#identity-provider-security-requirements) above

---

Expand Down
16 changes: 16 additions & 0 deletions zh/deploy/oidc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,28 @@ SOCIAL_AUTH_PROVIDERS=github,google,oidc

---

## 身份提供商安全要求

Teable 会信任 IdP 返回的邮箱地址，并用它将 OIDC 登录与相同邮箱的已有账号自动关联。因此，所连接的身份提供商**必须保证用户邮箱归属已经过验证**。

<Warning>
不要接入允许用户自行填写、且不验证邮箱归属的身份提供商（例如开放注册的多租户 IdP）。在这类 IdP 上，攻击者可以注册账号并将邮箱设置为你实例中已有用户的地址，再通过 OIDC 登录接管该账号。当实例同时开放本地密码登录时，此风险尤其突出。
</Warning>

建议：

- 仅接入由你控制、企业级的 IdP（如 Okta、Azure Entra ID、Google Workspace、Keycloak 等），并确保其开启了邮箱验证。
- 如果实例完全通过 SSO 登录，可设置 [`PASSWORD_LOGIN_DISABLED=true`](/zh/deploy/env) 禁用本地密码登录，进一步收窄攻击面。

---

## 重要注意事项

1. **必须使用 HTTPS**：生产环境中所有 URL 必须使用 HTTPS
2. **回调 URL 必须匹配**：Teable 中的回调 URL 必须与 IdP 中配置的完全一致
3. **需要重启**：修改环境变量后需要重启 Teable 才能生效
4. **安全存储**：切勿将密钥提交到版本控制系统；使用环境变量或密钥管理工具
5. **IdP 必须验证邮箱**：详见上方「身份提供商安全要求」

---

Expand Down