跳到主要内容

OIDC提供商设置

信息

OpenID Connect (OIDC) 是一种身份验证协议，允许用户使用来自 Google、Microsoft 或您企业身份提供商等现有账户登录。它支持单点登录（SSO），实现无缝且安全的身份验证。

本指南将引导您在 Unraid API 中使用 WebGUI 配置用于 SSO 身份验证的 OIDC（OpenID Connect）提供商。

🚀 快速开始​

前往OIDC设置
  1. 前往您的 Unraid 服务器的 WebGUI。
  2. 进入设置 → 管理访问 → API → OIDC
  3. 您将看到不同提供商的选项卡 - 单击**+**按钮以添加新提供商.

OIDC提供商界面概览​

Login Page with SSO Options 显示传统登录表单以及 SSO 选项的登录页面 - “Login With Unraid.net”和“Sign in with Google”按钮

界面包括：

  • 提供商选项卡: 每个配置的提供商（Unraid.net，Google等）以选项卡形式出现。
  • 添加提供商按钮: 单击**+**按钮以添加新提供商.
  • 授权模式下拉菜单: 在“简单”和“高级”模式之间切换.
  • 简单授权部分: 配置允许的电子邮件域和具体地址.
  • 添加项目按钮: 单击以添加多条授权规则.

理解授权模式​

界面提供了两种授权模式：

简单模式（推荐）​

简单模式是配置授权的最简单方法。您可以：

  • 允许特定电子邮件域（例如，@company.com）
  • 允许特定的电子邮件地址.
  • Configure who can access your Unraid server with minimal setup.

何时使用简单模式：

  • 您想允许来自您公司域的所有用户.
  • 您有一个特定用户的小名单.
  • 你对OIDC配置比较陌生.
高级模式

高级模式通过基于声明的规则提供细粒度的控制。您可以：

  • 基于JWT声明创建复杂的授权规则.

  • 使用操作符如等于、包含、以…结束、以…开始.

  • 使用OR/AND逻辑结合多个条件.

  • 选择是否任何规则通过（OR模式）或所有规则通过（AND模式）

    何时使用高级模式：

  • 您需要检查组成员资格.

  • 您希望验证多个声明（例如，电子邮件域 AND 已验证状态）。

  • 您有复杂的授权需求.

  • 您需要对规则的评估方式进行精细化控制.

高级模式​

授权规则配置 高级授权规则显示以电子邮件为基础的访问控制的JWT声明配置及操作符以…结束

简单模式示例​

允许公司域​

在简单授权中：

  • 允许的电子邮件域: 输入company.com.
  • 这允许任何带有@company.com邮箱的人.

允许特定用户​

  • 特定电子邮件地址: 添加单个电子邮件.
  • 单击添加项目以添加多个地址.
高级模式示例

授权规则模式​

使用多个规则时，您可以选择它们的评估方式：

  • OR模式（默认）: 如果任何规则通过，用户将被授权

  • AND模式: 仅当所有规则通过时，用户才被授权

    电子邮件域与验证（AND模式）​

    要求同时进行电子邮件域与验证：

  1. 将授权规则模式设置为AND.
  2. 添加两条规则：
    • 规则 1：
      • 声明: email
      • 操作符: endsWith
      • 值: @company.com
    • 规则 2：
      • 声明: email_verified
      • 操作符: equals
      • 值: true

这确保用户必须同时拥有公司邮箱和已验证的电子邮件地址。

基于组的访问（OR模式）​

为了允许对多个组的访问：

  1. 授权规则模式: 选择OR（任何规则通过）或AND（所有规则必须通过）
  2. 为每个组添加规则：
    • 声明: groups
    • 操作符: contains
    • 值: admins 或添加另一个规则：
    • 声明: groups
    • 操作符: contains
    • 值: developers

在admins或developers组中的用户将被授权。

多个域​

  • 声明: email
  • 操作符: endsWith
  • 值: 添加多个域（例如，company.com, subsidiary.com）

复杂授权（AND模式）​

对于需要多种条件的严格安全要求：

  1. 将授权规则模式设置为AND.
  2. 添加所有必须通过的多条规则：
    • 电子邮件必须来自公司域
    • 电子邮件必须经过验证
    • 用户必须位于特定组中
    • 账户须启用双重身份验证（如果声明可用）
配置界面详情

提供商选项卡​

  • 每个配置的提供商显示为顶部的选项卡.

  • 单击选项卡在提供商配置之间切换.

  • 右侧的**+**按钮添加新的提供商.

    授权模式切换区​

  • 简单：最适合基于电子邮件的授权（推荐给大多数用户）。

  • 高级: 用于复杂的基于JWT声明的规则.

    简单授权字段​

    选择“简单”模式时，您将看到：

    • 允许的电子邮件域：输入不带 @ 的域名（例如，company.com）。
      • 帮助文本：“这些域名结尾的电子邮件可以登录”
    • 特定电子邮件地址: 添加单个电子邮件地址.
      • 帮助文本：“只有这些精确的电子邮件地址可以登录”
    • 添加项目按钮添加多个条目.

    高级授权字段​

    选择“高级”模式时，您将看到：

    • 授权规则模式：选择 OR（任意规则通过）或 AND（所有规则都必须通过）。
    • 授权规则: 添加基于声明的多条规则.
    • 对于每条规则:
      • 声明: 要检查的JWT声明.
      • 运算符：如何比较（等于、包含、以…结尾、以…开头）。
      • 值: 匹配对象.

    附加界面元素​

  • 启用开发者沙盒：切换以启用位于 /graphql 的 GraphQL 沙盒。

  • 界面使用深色主题以提高可见性.

  • 字段验证指示器帮助确保正确配置.

重定向URI是必须的​

注意

所有提供商必须使用此精确重定向URI格式进行配置：

http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
提示

将YOUR_UNRAID_IP替换为您实际的服务器IP地址（例如，192.168.1.100或tower.local）。

发布者URL格式​

⚠️ 安全注意：始终尽量使用基本URL格式。系统会自动附加/.well-known/openid-configuration以便进行OIDC发现。直接使用完整发现URL会禁用重要的发行者验证检查，OpenID Connect规范不推荐这样做。

  • 基础URL（推荐）: https://accounts.google.com
  • 完整发现URL: https://accounts.google.com/.well-known/openid-configuration

⚠️ 安全注意：始终尽量使用基本URL格式。系统会自动附加/.well-known/openid-configuration以便进行OIDC发现。直接使用完整发现URL会禁用重要的发行者验证检查，OpenID Connect规范不推荐这样做。

正确基础URL的示例：

  • Google: https://accounts.google.com
  • Microsoft/Azure: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
  • Keycloak: https://keycloak.example.com/realms/YOUR_REALM
  • Authelia: https://auth.yourdomain.com

✅ 测试您的配置​

Login Page with SSO Buttons Unraid 登录页面同时显示传统的用户名/密码身份验证以及带有自定义提供商按钮的 SSO 选项

  1. 保存您的提供商配置.
  2. 操作符: endsWith
  3. 导航到登录页面.
  4. 您的配置提供商按钮应出现.
  5. 单击以测试登录流程.

故障排除​

常见问题​

“未找到提供商”错误： 请确保 issuer URL 正确，并且该提供商支持 OIDC 发现（/.well-known/openid-configuration）。

“授权失败”： 在简单模式下，检查电子邮件域是否输入正确（不带 @）。在高级模式下，验证声明名称是否与您的提供商发送的内容完全一致，检查授权规则模式是否设置正确（OR 或 AND），并确保令牌中包含所有必需的声明。启用调试日志以查看实际声明和规则评估结果。

“无效的重定向 URI”： 请确保提供商中的重定向 URI 与此处完全一致；如果使用非标准配置，请包含正确的端口，并验证重定向 URI 协议与您的服务器配置一致（HTTP 或 HTTPS）。

看不到登录按钮： 检查是否至少配置了一条授权规则，并验证该提供商已启用/已保存。

授权模式切换区​

要排除故障：

  1. 检查日志：
LOG_LEVEL=debug unraid-api start --debug
  1. 检查日志：
  • 检查日志：
  • 授权规则评估.
  • 令牌验证错误.

选择“高级”模式时，您将看到：

如果遇到问题，请查阅您的提供商的 OIDC 文档，查看 Unraid API 日志以获取详细错误信息，确保您的提供商支持标准 OIDC 发现，并验证 Unraid 与提供商之间的网络连接。如需更多帮助，请访问 Unraid 论坛。

附加界面元素​

Unraid.net 提供商​

Unraid.net 提供商是内置且预配置的。您只需在界面中配置授权规则。

配置：

  • 发行者 URL: 预配置（内置提供程序）
  • 客户端 ID/Secret: 预配置（内置提供程序）
  • 重定向 URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
提示

将协议与您的服务器设置相匹配。如果在未使用 SSL/TLS 的情况下访问您的 Unraid 服务器，请使用 http://（本地网络访问通常如此）。如果您已在服务器上配置 SSL/TLS，请使用 https://。某些 OIDC 提供商（如 Google）要求使用 HTTPS，不接受 HTTP 重定向 URI。

将YOUR_UNRAID_IP替换为您实际的服务器IP地址（例如，192.168.1.100或tower.local）。

Google​

设置步骤

在 Google Cloud Console 中设置 OAuth 2.0 凭据：

  1. 转到 API 和服务 → 凭据.
  2. 点击 创建凭据 → OAuth 客户端 ID.
  3. 选择 Web 应用程序 作为应用程序类型.
  4. 将您的重定向 URI 添加到 授权重定向 URI.
  5. 如果出现提示，请配置 OAuth 同意屏幕.

配置：

  • 发行者 URL：https://accounts.google.com
  • 客户端 ID/Secret: 来自您的 OAuth 2.0 客户端凭据
  • 所需范围: openid, profile, email
  • 重定向 URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
警告

Google 要求 OAuth 重定向 URI 使用有效的域名。不接受本地 IP 地址和 .local 域。要在您的 Unraid 服务器上使用 Google OAuth，您需要：

  • 选项 1: 反向代理 - 设置一个反向代理（如 NGINX 代理管理器或 Traefik），使用有效域名指向您的 Unraid API.
  • 选项 2：Tailscale - 使用 Tailscale 获取一个 Google 会接受的有效 *.ts.net 域。有关 Tailscale 的更多信息，请参阅 远程访问。
  • 选项 3: 动态 DNS - 使用 DDNS 服务为您的服务器获取公共域名.

请记得在 Google Cloud 控制台和 Unraid OIDC 配置中更新您的重定向 URI 以使用有效的域名。

对于 Google Workspace 域，请使用高级模式和 hd 声明来限制对您组织域的访问。

Authelia​

在 Authelia configuration.yml 中配置 OIDC 客户端，使用客户端 ID unraid-api 并使用 Authelia hash-password 命令生成一个哈希密钥。

配置：

  • 发行者 URL：https://auth.yourdomain.com
  • 客户端 ID：unraid-api（或在 Authelia 中配置）
  • 客户端 Secret：您的未哈希密钥
  • 所需范围: openid, profile, email, groups
  • 重定向 URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

对于 Google Workspace 域，使用高级模式和 hd 声明来限制对您组织域的访问。

Microsoft/Azure AD​

配置：

配置：

  • 发行者 URL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
  • 客户端 ID: 您的应用程序（客户端）ID
  • 客户端 Secret: 生成的客户端秘密
  • 所需范围: openid, profile, email
  • 重定向 URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

可以在界面中配置授权规则，使用电子邮件域或者高级声明。

Keycloak​

配置：

配置：

  • 发行者 URL：https://keycloak.example.com/realms/YOUR_REALM
  • 客户端 ID: unraid-api（或在 Keycloak 中配置）
  • 客户端 Secret: 来自 Keycloak 凭据选项卡
  • 所需范围: openid, profile, email
  • 重定向 URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

对于基于角色的授权，使用 realm_access.roles 或 resource_access 声明的高级模式。

Authentik​

配置：

配置：

  • 发行者 URL: https://authentik.example.com/application/o/<application_slug>/
  • 客户端 ID: 来自 Authentik 提供者配置
  • 客户端 Secret: 来自 Authentik 提供者配置
  • 所需范围: openid, profile, email
  • 重定向 URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

可以在界面中配置授权规则。

Okta​

在 Okta 管理控制台中创建一个新的 OIDC Web 应用程序，并分配适当的用户或组。

配置：

  • 发行者 URL: https://YOUR_DOMAIN.okta.com
  • 客户端 ID: 来自 Okta 应用程序配置
  • 客户端 Secret: 来自 Okta 应用程序配置
  • 所需范围: openid, profile, email
  • 重定向 URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

可以在界面中配置授权规则，使用电子邮件域或者高级声明。