跳到主要内容

OIDC提供商设置

:::info[What 什么是OIDC？

OpenID Connect (OIDC) 是一种认证协议，允许用户使用现有账户（如Google、Microsoft或公司身份提供商）登录。它为无缝和安全登录提供了单点登录(SSO)支持。

:::

This guide walks you through configuring OIDC (OpenID Connect) providers for SSO authentication in the Unraid API using the web interface.

🚀 快速开始​

前往OIDC设置
  1. Navigate to your Unraid server's web interface
  2. 进入设置 → 管理访问 → API → OIDC
  3. 您将看到不同提供商的选项卡 - 单击**+**按钮以添加新提供商

OIDC提供商界面概览​

Login Page with SSO Options Login page showing traditional login form with SSO options - "Login With Unraid.net" and "Sign in with Google" buttons

界面包括：

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

理解授权模式​

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

简单模式（推荐）​

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

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

何时使用简单模式：

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

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

  • 基于JWT声明创建复杂的授权规则
  • 使用操作符如等于、包含、以…结束、以…开始
  • 使用OR/AND逻辑结合多个条件
  • 选择是否任何规则通过（OR模式）或所有规则通过（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（默认）
  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是必须的​

:::caution[Important 配置

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

:::

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

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

发布者URL格式​

发布者URL字段接受这两种格式，但强烈推荐基础URL以保障安全：

  • 基础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

✅ 测试您的配置​

登录页面显示 SSO 按钮 Unraid 登录页面显示传统的用户名/密码认证和带有定制提供商按钮的 SSO 选项

  1. 保存您的提供商配置
  2. 登出（如果已登录）
  3. 导航到登录页面
  4. 您的配置提供商按钮应出现
  5. 单击以测试登录流程

🔧 故障排除​

常见问题​

“找不到提供商”错误​

  • 确保发布者URL正确
  • 检查提供商是否支持OIDC发现（/.well-known/openid-configuration）

“认证失败”​

  • 在简单模式中：检查电子邮件域是否正确输入（不带@）
  • 在高级模式中：
    • 验证声明名称是否与提供商发送的完全匹配
    • 检查授权规则模式是否设置正确（OR vs AND）
    • 确保令牌中存在所有必需的声明
  • 启用调试日志以查看实际声明和规则评估

“无效重定向URI”​

  • 确保您的提供商中的重定向URI完全匹配
  • 如果使用非标准配置，请包括正确的端口
  • 验证重定向URI协议是否与服务器配置匹配（HTTP或HTTPS）

无法看到登录按钮​

  • 检查至少配置了一条授权规则
  • 验证提供者已启用/保存

调试模式​

要排除故障：

  1. 启用调试日志：
LOG_LEVEL=debug unraid-api start --debug
  1. 检查日志：
  • 从提供商接收到的声明
  • 授权规则评估
  • 令牌验证错误

🔐 安全最佳实践​

  1. 使用简单模式进行授权 - 防止过于宽松的配置并减少错误配置风险
  2. 授权时要具体 - 不要使用过于宽泛的规则
  3. 定期旋转密钥 - 定期更新客户端密钥
  4. 全面测试 - 验证仅预定用户可以访问

💡 需要帮助吗？​

  • 检查提供商的OIDC文档
  • 查看 Unraid API 日志以获取详细的错误信息
  • 确保您的提供商支持标准的 OIDC 发现
  • 验证 Unraid 和提供商之间的网络连接

🏢 提供者特定设置​

Unraid.net 提供者​

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

配置：

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

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

使用简单模式（允许的电子邮件域/地址）或高级模式来配置授权规则，以满足复杂的需求。

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 域名要求

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

  • 选项 1: 反向代理 - 设置一个反向代理（如 NGINX 代理管理器或 Traefik），使用有效域名指向您的 Unraid API
  • 选项 2: Tailscale - 使用 Tailscale 获取 Google 可接受的有效 *.ts.net 域
  • 选项 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

使用带 groups 声明的高级模式进行基于组的授权。

Microsoft/Azure AD​

在 Azure Portal 中，Azure Active Directory → 应用注册项下注册一个新应用。记录应用 ID，创建客户端密钥，并记录您的租户 ID。

配置：

  • 发行者 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​

在 Keycloak 管理控制台中创建一个新的保密客户端，使用 openid-connect 协议，并从凭据选项卡复制客户端密钥。

配置：

  • 发行者 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​

在 Authentik 中创建一个新的 OAuth2/OpenID 提供者，然后创建一个应用程序并将其链接到提供者。

配置：

  • 发行者 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

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