Saltar al contenido principal

Configuración del proveedor OIDC

información

OpenID Connect (OIDC) es un protocolo de autenticación que permite a los usuarios iniciar sesión usando sus cuentas existentes de proveedores como Google, Microsoft o su proveedor de identidad corporativo. Permite el inicio de sesión único (SSO) para una autenticación fluida y segura.

Esta guía le guía a través de la configuración de proveedores OIDC (OpenID Connect) para la autenticación SSO en la API de Unraid usando la WebGUI.

🚀 Inicio Rápido​

Navegando a la Configuración de OIDC
  1. Navegue hasta la WebGUI de su servidor Unraid.
  2. Ve a Configuración → Acceso de Gestión → API → OIDC
  3. Verás pestañas para diferentes proveedores - haz clic en el botón + para añadir un nuevo proveedor.

🚀 Inicio Rápido​

Página de inicio de sesión con opciones SSO Página de inicio de sesión que muestra el formulario de inicio de sesión tradicional con opciones SSO: botones "Iniciar sesión con Unraid.net" e "Iniciar sesión con Google"

Página de inicio de sesión con opciones SSO Página de inicio de sesión mostrando el formulario de inicio de sesión tradicional con opciones SSO - botones "Iniciar sesión con Unraid.net" e "Iniciar sesión con Google"

  • Pestañas de Proveedores: Cada proveedor configurado (Unraid.net, Google, etc.) aparece como una pestaña
  • Botón Añadir Proveedor: Haz clic en el botón + para añadir nuevos proveedores.
  • Desplegable de Modo de Autorización: Alternar entre modos "simple" y "avanzado"
  • Sección de Autorización Simple: Configura dominios de correo permitidos y direcciones específicas.
  • Botones Añadir Elemento: Haz clic para añadir múltiples reglas de autorización.

Entendiendo los Modos de Autorización​

La interfaz ofrece dos modos de autorización:

Entendiendo los Modos de Autorización​

La interfaz ofrece dos modos de autorización:

  • Permitir dominios de correo específicos (por ejemplo, @empresa.com).
  • Permitir direcciones de correo específicas.
  • Configurar quién puede acceder a tu servidor Unraid con una configuración mínima.

Cuándo usar el Modo Simple:

  • Deseas permitir a todos los usuarios de tu dominio corporativo.
  • Permitir direcciones de correo específicas.
  • Configurar quién puede acceder a tu servidor Unraid con una configuración mínima.
Modo Avanzado

El modo avanzado ofrece un control granular utilizando reglas basadas en claims. Usted puede:

  • Crear reglas de autorización complejas basadas en claims de JWT.

  • Usar operadores como equals, contains, endsWith, startsWith.

  • Combinar múltiples condiciones con lógica OR/AND.

  • Elegir si CUALQUIER regla debe pasar (modo OR) o TODAS las reglas deben pasar (modo AND).

    Cuándo usar el Modo Avanzado:

  • Necesitas verificar membresías de grupos.

  • Deseas verificar múltiples claims (por ejemplo, dominio de correo Y estado verificado).

  • Tienes requisitos de autorización complejos.

  • Necesitas un control detallado sobre cómo se evalúan las reglas.

Modo Avanzado​

El modo avanzado ofrece un control granular utilizando reglas basadas en claims. Usted puede:

Ejemplos de Modo Simple​

Permitir Dominio Corporativo​

En Autorización Simple:

  • Dominios de Correo Permitidos: Ingresar empresa.com.
  • Haz clic en Añadir Elemento para añadir múltiples direcciones.

Permitir Usuarios Específicos​

  • Direcciones de Correo Específicas: Añadir correos individuales.
  • Haz clic en Añadir Elemento para añadir múltiples direcciones.
Ejemplos de Modo Avanzado

Modo de Reglas de Autorización​

Al usar múltiples reglas, puedes elegir cómo son evaluadas:

  • Modo OR (predeterminado): El usuario está autorizado si CUALQUIER regla pasa.

  • Modo AND: El usuario está autorizado solo si TODAS las reglas pasan.

    Correo de Dominio con Verificación (Modo AND)​

    Para requerir tanto el dominio del correo como la verificación:

  1. Configura Modo de Reglas de Autorización a AND.
  2. Añadir dos reglas:
    • Regla 1:
      • Claim: email
      • Operador: endsWith
      • Valor: @empresa.com
    • Regla 2:
      • Claim: email_verified
      • Operador: equals
      • Valor: true

Esto asegura que los usuarios deben tener tanto un correo de la empresa COMO una dirección de correo verificada.

Acceso Basado en Grupos (Modo OR)​

Para permitir el acceso a múltiples grupos:

  1. Configura Modo de Reglas de Autorización a OR (predeterminado).
  2. Agrega reglas para cada grupo:
    • Claim: groups
    • Operador: contains
    • Valor: admins O añada otra regla:
    • Claim: groups
    • Operador: contains
    • Valor: developers

Los usuarios en el grupo admins O developers serán autorizados.

Múltiples Dominios​

  • Claim: email
  • Operador: endsWith
  • Valores: Añadir múltiples dominios (por ejemplo, empresa.com, filial.com)

Autorización Compleja (Modo AND)​

Para seguridad estricta que requiere múltiples condiciones:

  1. Configura Modo de Reglas de Autorización a AND.
  2. Añadir múltiples reglas que TODAS deben pasar:
    • El correo debe ser del dominio de la empresa
    • El correo debe estar verificado
    • El usuario debe estar en un grupo específico
    • La cuenta debe tener 2FA habilitado (si el claim está disponible)
Detalles de la Interfaz de Configuración

Pestañas de Proveedores​

  • Cada proveedor configurado aparece como una pestaña en la parte superior.

  • Haz clic en una pestaña para cambiar entre configuraciones de proveedores.

  • El botón + a la derecha añade un nuevo proveedor.

    Desplegable de Modo de Autorización​

  • Simple: Mejor para la autorización basada en correo (recomendado para la mayoría de los usuarios).

  • Avanzado: Para reglas complejas basadas en claims utilizando claims de JWT.

    Campos de Autorización Simple​

    Cuando el modo "simple" está seleccionado, verás:

    • Dominios de Correo Permitidos: Ingresa dominios sin @ (por ejemplo, empresa.com).
      • Texto de ayuda: "Usuarios con correos que terminan en estos dominios pueden iniciar sesión"
    • Direcciones de Correo Específicas: Añadir direcciones de correo individuales.
      • Texto de ayuda: "Solo estas direcciones de correo exactas pueden iniciar sesión"
    • Botones Añadir elemento para añadir varias entradas.

    Campos de Autorización Avanzada​

    Cuando el modo "avanzado" está seleccionado, verás:

    • Modo de Reglas de Autorización: Elige OR (cualquier regla pasa) o AND (todas las reglas deben pasar).
    • Reglas de Autorización: Añadir múltiples reglas basadas en claims.
    • Para cada regla:
      • Claim: El claim de JWT a verificar.
      • Operador: Cómo comparar (equals, contains, endsWith, startsWith).
      • Valor: Qué coincidir.

    Elementos Adicionales de la Interfaz​

  • Habilitar sandbox para desarrolladores: alterna para habilitar el sandbox de GraphQL en /graphql.

  • La interfaz utiliza un tema oscuro para mejor visibilidad.

  • Los indicadores de validación de campos ayudan a garantizar una configuración correcta.

URI de Redirección Requerida​

precaución

Todos los proveedores deben configurarse con este formato exacto de URI de redirección.

http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
consejo

Reemplaza TU_IP_UNRAID con la dirección IP actual de tu servidor (por ejemplo, 192.168.1.100 o tower.local).

✅ Probando Tu Configuración​

Página de inicio de sesión con Botones SSO Página de inicio de sesión de Unraid mostrando tanto la autenticación de usuario/contraseña tradicional como opciones SSO con botones personalizados de proveedores

  • Guarda la configuración de tu proveedor
  • Cerrar sesión (si estás conectado)

Página de inicio de sesión con Botones SSO Página de inicio de sesión de Unraid mostrando tanto la autenticación de usuario/contraseña tradicional como opciones SSO con botones personalizados de proveedores

Para permitir el acceso a múltiples grupos:

  • Configura Modo de Reglas de Autorización a OR (predeterminado)
  • Agrega reglas para cada grupo:
  • Keycloak: https://keycloak.example.com/realms/YOUR_REALM
  • Authelia: https://auth.yourdomain.com

✅ Probando Tu Configuración​

Página de inicio de sesión con botones SSO Página de inicio de sesión de Unraid que muestra tanto la autenticación tradicional con nombre de usuario/contraseña como opciones SSO con botones personalizados de proveedores

  1. Guarda la configuración de tu proveedor.
  2. Cerrar sesión (si estás conectado).
  3. Habilita el registro de depuración para ver los claims reales y la evaluación de reglas.
  4. El botón de tu proveedor configurado debería aparecer.
  5. Haz clic para probar el flujo de inicio de sesión.

Solución de problemas​

Problemas comunes​

Error "Proveedor no encontrado": asegúrese de que la URL del emisor sea correcta y de que el proveedor admita el descubrimiento OIDC (/.well-known/openid-configuration).

"Error de autorización": en el modo simple, compruebe que los dominios de correo electrónico se hayan introducido correctamente (sin @). En el modo avanzado, verifique que los nombres de las notificaciones coincidan exactamente con lo que envía su proveedor, compruebe si el modo de regla de autorización está configurado correctamente (OR frente a AND) y asegúrese de que todas las notificaciones obligatorias estén presentes en el token. Habilite el registro de depuración para ver las notificaciones reales y la evaluación de reglas.

"URI de redirección no válido": asegúrese de que la URI de redirección en su proveedor coincida exactamente, incluya el puerto correcto si usa una configuración no estándar y verifique que el protocolo de la URI de redirección coincida con la configuración de su servidor (HTTP o HTTPS).

No puede ver el botón de inicio de sesión: compruebe que haya al menos una regla de autorización configurada y verifique que el proveedor esté habilitado y guardado.

Desplegable de Modo de Autorización​

Para solucionar problemas:

  1. Habilitar registro de depuración:
LOG_LEVEL=debug unraid-api start --debug
  1. Dominios de Correo Permitidos: Ingresa dominios sin @ (por ejemplo, empresa.com)
  • Claims recibidos del proveedor.
  • Evaluación de reglas de autorización.
  • Errores de validación de tokens.

Cuando el modo "avanzado" está seleccionado, verás:

Si encuentra problemas, consulte la documentación OIDC de su proveedor, revise los registros de la API de Unraid para ver mensajes de error detallados, asegúrese de que su proveedor admita el descubrimiento OIDC estándar y verifique la conectividad de red entre Unraid y el proveedor. Para obtener ayuda adicional, visite los foros de Unraid.

Elementos Adicionales de la Interfaz​

Proveedor Unraid.net​

El proveedor Unraid.net está integrado y preconfigurado. Solo necesita configurar las reglas de autorización en la interfaz.

Configuración:

  • URL del Emisor: https://accounts.google.com
  • ID/Secreto del Cliente: Desde tus credenciales de cliente OAuth 2.0
  • URI de redirección: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
consejo

Ajuste el protocolo a la configuración de su servidor. Use http:// si accede a su servidor Unraid sin SSL/TLS (lo habitual para el acceso desde la red local). Use https:// si ha configurado SSL/TLS en su servidor. Algunos proveedores OIDC (como Google) requieren HTTPS y no aceptarán URIs de redirección HTTP.

Reemplaza TU_IP_UNRAID con la dirección IP actual de tu servidor (por ejemplo, 192.168.1.100 o tower.local).

Authelia​

Pasos de configuración

Configura las credenciales OAuth 2.0 en Google Cloud Console:

  1. Ve a APIs y servicios → Credenciales.
  2. Haz clic en Crear credenciales → ID de cliente OAuth.
  3. Elige Aplicación web como el tipo de aplicación.
  4. Agrega tu URI de redirección a URIs de redirección autorizados.
  5. Configura la pantalla de consentimiento OAuth si se solicita.

Configuración:

  • Guarda la configuración de tu proveedor
  • Cerrar sesión (si estás conectado)
  • Ámbitos requeridos: openid, profile, email
  • URI de redirección: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
advertencia

Haga coincidir el protocolo con la configuración de su servidor: Use http:// si accede a su servidor Unraid sin SSL/TLS (típico para acceso a red local). Use https:// si ha configurado SSL/TLS en su servidor. Algunos proveedores OIDC (como Google) requieren HTTPS y no aceptarán URIs de redirección HTTP.

  • Opción 1: Proxy inverso - Configura un proxy inverso (como NGINX Proxy Manager o Traefik) con un nombre de dominio válido que apunte a tu API de Unraid.
  • Opción 2: Tailscale: use Tailscale para obtener un dominio válido *.ts.net que Google aceptará. Para obtener más información sobre Tailscale, consulte Acceso remoto.
  • Opción 3: DNS dinámico - Usa un servicio de DNS dinámico para obtener un nombre de dominio público para tu servidor.

Recuerda actualizar tu URI de redirección tanto en Google Cloud Console como en la configuración OIDC de tu Unraid para usar el dominio válido.

Para dominios de Google Workspace, use el modo avanzado con la notificación hd para restringir el acceso al dominio de su organización.

"URI de redirección inválido"​

Recuerda actualizar tu URI de redirección tanto en Google Cloud Console como en la configuración OIDC de tu Unraid para usar el dominio válido.

Configuración:

  • Verifica que al menos una regla de autorización esté configurada
  • ID de Cliente: unraid-api (o según configurado en Keycloak)
  • Secreto del Cliente: De la pestaña Credenciales de Keycloak
  • Ámbitos requeridos: openid, profile, email
  • URI de redirección: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Google requiere nombres de dominio válidos para los URIs de redirección OAuth. No se aceptan direcciones IP locales y dominios .local. Para usar Google OAuth con su servidor Unraid, necesitará:

Authentik​

Crea un nuevo Proveedor OAuth2/OpenID en Authentik, luego crea una aplicación y vincúlala al proveedor.

Configuración:

  • URL del Emisor: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
  • ID de Cliente: De la configuración del proveedor Authentik
  • Secreto del Cliente: De la configuración del proveedor Authentik
  • Ámbitos requeridos: openid, profile, email
  • URI de redirección: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Configura el cliente OIDC en tu configuration.yml de Authelia con el ID de cliente unraid-api y genera un secreto con hash usando el comando hash-password de Authelia.

Modo de Depuración​

Para solucionar problemas:

Configuración:

  • URL del Emisor: https://YOUR_DOMAIN.okta.com
  • ID de Cliente: unraid-api (o según configurado en Keycloak)
  • Secreto del Cliente: De la configuración de la aplicación Okta
  • Ámbitos requeridos: openid, profile, email
  • URI de redirección: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Crea un nuevo Proveedor OAuth2/OpenID en Authentik, luego crea una aplicación y vincúlala al proveedor.

Authentik​

Crea un nuevo Proveedor OAuth2/OpenID en Authentik, luego crea una aplicación y vincúlala al proveedor.

Configuración:

  • URL del Emisor: https://authentik.example.com/application/o/<application_slug>/
  • ID de Cliente: De la configuración del proveedor Authentik
  • Secreto del Cliente: De la configuración del proveedor Authentik
  • Ámbitos requeridos: openid, profile, email
  • URI de redirección: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Crea una nueva aplicación web OIDC en el Console de Administración de Okta y asigna los usuarios o grupos apropiados.

💡 ¿Necesitas ayuda?​

Crea una nueva aplicación web OIDC en el Console de Administración de Okta y asigna los usuarios o grupos apropiados.

Configuración:

  • URL del Emisor: https://YOUR_DOMAIN.okta.com
  • ID de Cliente: De la configuración de la aplicación Okta
  • Secreto del Cliente: De la configuración de la aplicación Okta
  • Ámbitos requeridos: openid, profile, email
  • URI de redirección: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Configura el cliente OIDC en tu configuration.yml de Authelia con el ID de cliente unraid-api y genera un secreto con hash usando el comando hash-password de Authelia.