Passer au contenu principal

Configuration du fournisseur OIDC

info

OpenID Connect (OIDC) est un protocole d'authentification qui permet aux utilisateurs de se connecter à l'aide de leurs comptes existants auprès de fournisseurs tels que Google, Microsoft ou votre fournisseur d'identité d'entreprise. Il permet l'authentification unique (SSO) pour une authentification fluide et sécurisée.

Ce guide vous explique comment configurer des fournisseurs OIDC (OpenID Connect) pour l'authentification SSO dans l'API Unraid à l'aide du WebGUI.

🚀 Démarrage rapide​

Accéder aux paramètres OIDC
  1. Accédez au WebGUI de votre serveur Unraid.
  2. Allez à Paramètres → Accès à la gestion → API → OIDC
  3. Vous verrez des onglets pour différents fournisseurs - cliquez sur le bouton + pour ajouter un nouveau fournisseur.

Aperçu de l'interface des fournisseurs OIDC​

Page de connexion avec options SSO Page de connexion affichant un formulaire de connexion traditionnel avec des options SSO - boutons "Connexion avec Unraid.net" et "Connexion avec Google"

Page de connexion avec options SSO Page de connexion affichant un formulaire de connexion traditionnel avec des options SSO - boutons "Connexion avec Unraid.net" et "Connexion avec Google"

  • Onglets de fournisseur : Chaque fournisseur configuré (Unraid.net, Google, etc.) apparaît comme un onglet.
  • Bouton Ajouter un fournisseur : Cliquez sur le bouton + pour ajouter de nouveaux fournisseurs.
  • Mode de l'autorisation : Basculer entre les modes "simple" et "avancé"
  • Section d'autorisation simple : Configurer les domaines d'email autorisés et les adresses spécifiques.
  • Boutons Ajouter élément : Cliquez pour ajouter plusieurs règles d'autorisation.

Comprendre les modes d'autorisation​

L'interface propose deux modes d'autorisation :

Mode simple (recommandé)​

Quand utiliser le mode simple :

  • Autoriser des domaines d'email spécifiques (e.g., @company.com).
  • Autoriser des adresses email spécifiques.
  • Configurer qui peut accéder à votre serveur Unraid avec une configuration minimale.

Quand utiliser le mode simple :

  • Vous souhaitez autoriser tous les utilisateurs de votre domaine d'entreprise.
  • Vous avez une petite liste de utilisateurs spécifiques.
  • Vous êtes débutant dans la configuration OIDC.
Mode avancé

Le mode avancé offre un contrôle granulaire utilisant des règles basées sur les assertions. Vous pouvez :

  • Créer des règles d'autorisation complexes basées sur les revendications JWT.

  • Utiliser des opérateurs comme équivaut, contient, termine par, commence par.

  • Combiner plusieurs conditions avec la logique OU/ET.

  • Choisir si TOUTE règle doit passer (mode OU) ou si TOUTES les règles doivent passer (mode ET).

    Quand utiliser le mode avancé :

  • Vous devez vérifier les appartenances à des groupes.

  • Vous souhaitez vérifier plusieurs revendications (e.g., domaine de l'email ET statut vérifié).

  • Vous avez des exigences d'autorisation complexes.

  • Vous avez besoin d'un contrôle minutieux sur la façon dont les règles sont évaluées.

Mode avancé​

Le mode avancé offre un contrôle granulaire utilisant des règles basées sur les assertions. Vous pouvez :

Exemples de mode simple​

Autoriser le domaine de l'entreprise​

Dans l'autorisation simple :

  • Domaines d'email autorisés : Saisir company.com.
  • Cliquez sur Ajouter un élément pour ajouter plusieurs adresses.

Autoriser des utilisateurs spécifiques​

  • Adresses email spécifiques : Ajouter des emails individuels.
  • Cliquez sur Ajouter un élément pour ajouter plusieurs adresses.
Exemples de mode avancé

Mode des règles d'autorisation​

Lorsque vous utilisez plusieurs règles, vous pouvez choisir comment elles sont évaluées :

  • Mode OU (par défaut) : L'utilisateur est autorisé si TOUTE règle passe.

  • Mode ET : L'utilisateur est autorisé uniquement si TOUTES les règles passent.

    Domaine d'email avec vérification (mode ET)​

    Pour exiger à la fois le domaine de l'email ET la vérification :

  1. Réglez Mode Règle d'Autorisation sur ET.
  2. Ajouter deux règles :
    • Règle 1 :
      • Revendication : email
      • Opérateur : termine par
      • Valeur : @company.com
    • Règle 2 :
      • Revendication : email_verified
      • Opérateur : équivaut
      • Valeur : true

Cela assure que les utilisateurs doivent avoir à la fois un email d'entreprise ET une adresse email vérifiée.

Accès basé sur les groupes (mode OU)​

Pour autoriser l'accès à plusieurs groupes :

  1. Réglez Mode Règle d'Autorisation sur OU (par défaut).
  2. Ajouter des règles pour chaque groupe :
    • Revendication : groups
    • Opérateur : contient
    • Valeur : admins Ou ajoutez une autre règle :
    • Revendication : groups
    • Opérateur : contient
    • Valeur : développeurs

Les utilisateurs dans le groupe admins OU développeurs seront autorisés.

Domaines multiples​

  • Revendication : email
  • Opérateur : termine par
  • Valeurs : Ajouter plusieurs domaines (par ex., company.com, subsidiary.com)

Autorisation complexe (mode ET)​

Pour une sécurité stricte nécessitant plusieurs conditions :

  1. Réglez Mode Règle d'Autorisation sur ET.
  2. Ajouter plusieurs règles qui DOIVENT TOUTES passer :
    • L'email doit provenir du domaine de l'entreprise
    • L'email doit être vérifié
    • L'utilisateur doit être dans un groupe spécifique
    • Le compte doit avoir une authentification à deux facteurs activée (si la réclamation est disponible)
Détails de l'interface de configuration

Onglets des fournisseurs​

  • Chaque fournisseur configuré apparaît comme un onglet en haut.

  • Cliquez sur un onglet pour basculer entre les configurations des fournisseurs.

  • Le bouton + à droite ajoute un nouveau fournisseur.

  • Simple: Idéal pour l'autorisation basée sur email (recommandé pour la plupart des utilisateurs).

  • Avancé: Pour des règles complexes basées sur les assertions à l'aide de revendications JWT.

    Champs d'Autorisation Simple​

    Quand le mode "simple" est sélectionné, vous verrez :

    • Domaines d'email autorisés : Entrez des domaines sans @ (e.g., company.com).
      • Texte d'aide : "Les utilisateurs avec des emails se terminant par ces domaines peuvent se connecter"
    • Adresses email spécifiques : Ajouter des adresses email individuelles.
      • Texte d'aide : "Seules ces adresses email exactes peuvent se connecter"
    • Boutons Ajouter un élément pour ajouter plusieurs entrées.

    Champs d'Autorisation Avancée​

    Quand le mode "avancé" est sélectionné, vous verrez :

    • Mode Règle d'Autorisation : Choisissez OU (toute règle passe) ou ET (toutes les règles doivent passer).
    • Règles d'Autorisation : Ajouter plusieurs règles basées sur les revendications.
    • Pour chaque règle :
      • Revendication : La revendication JWT à vérifier.
      • Opérateur : Comment comparer (équivaut, contient, termine par, commence par).
      • Valeur : À quoi appariement.

    Éléments supplémentaires de l'interface​

  • Activer le bac à sable développeur : basculez pour activer le bac à sable GraphQL sur /graphql.

  • L'interface utilise un thème sombre pour une meilleure visibilité.

  • Les indicateurs de validation des champs aident à garantir une configuration correcte.

URI de redirection requis​

précaution

Tous les fournisseurs doivent être configurés avec ce format exact d'URI de redirection :

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

Remplacez YOUR_UNRAID_IP par l'adresse IP réelle de votre serveur (par exemple, 192.168.1.100 ou tower.local).

✅ Tester votre configuration​

Page de connexion avec boutons SSO Page de connexion Unraid affichant à la fois l'authentification par nom d'utilisateur/mot de passe traditionnel et les options SSO avec des boutons de fournisseur personnalisés

  • Enregistrez votre configuration de fournisseur
  • Déconnectez-vous (si connecté)

Note de sécurité : Utilisez toujours le format URL de base lorsque possible. Le système ajoute automatiquement /.well-known/openid-configuration pour la découverte OIDC. Utiliser directement l'URL complète de découverte désactive les vérifications importantes de validation de l'émetteur et n'est pas recommandé par la spécification OpenID Connect.

Pour autoriser l'accès à plusieurs groupes :

  • Réglez Mode Règle d'Autorisation sur OU (par défaut)
  • Ajouter des règles pour chaque groupe :
  • Keycloak : https://keycloak.example.com/realms/YOUR_REALM
  • Authelia : https://auth.yourdomain.com

✅ Tester votre configuration​

Page de connexion avec boutons SSO Page de connexion Unraid affichant à la fois l'authentification traditionnelle par nom d'utilisateur/mot de passe et les options SSO avec des boutons de fournisseur personnalisés

  1. Enregistrez votre configuration de fournisseur.
  2. Déconnectez-vous (si connecté).
  3. Activez la journalisation du débogage pour voir les revendications réelles et l'évaluation des règles.
  4. Votre bouton de fournisseur configuré devrait apparaître.
  5. Cliquez pour tester le processus de connexion.

Dépannage​

Problèmes courants​

Erreur "Provider not found" : Vérifiez que l'URL de l'émetteur est correcte et que le fournisseur prend en charge la découverte OIDC (/.well-known/openid-configuration).

"Authorization failed" : En mode simple, vérifiez que les domaines de messagerie sont saisis correctement (sans @). En mode avancé, vérifiez que les noms des revendications correspondent exactement à ce que votre fournisseur envoie, vérifiez si le mode de règle d'autorisation est défini correctement (OR ou AND), et assurez-vous que toutes les revendications requises sont présentes dans le jeton. Activez les journaux de débogage pour voir les revendications réelles et l'évaluation des règles.

"Invalid redirect URI" : Vérifiez que l'URI de redirection dans votre fournisseur correspond exactement, incluez le port correct si vous utilisez une configuration non standard, et vérifiez que le protocole de l'URI de redirection correspond à la configuration de votre serveur (HTTP ou HTTPS).

Impossible de voir le bouton de connexion : Vérifiez qu'au moins une règle d'autorisation est configurée et assurez-vous que le fournisseur est activé/enregistré.

Pour résoudre les problèmes :

  1. Activer la journalisation du débogage :
LOG_LEVEL=debug unraid-api start --debug
  1. Domaines d'email autorisés : Entrez des domaines sans @ (e.g., company.com)
  • Réclamations reçues du fournisseur.
  • Évaluation des règles d'autorisation.
  • Erreurs de validation de jeton.

Quand le mode "avancé" est sélectionné, vous verrez :

Si vous rencontrez des problèmes, consultez la documentation OIDC de votre fournisseur, examinez les journaux de l'API Unraid pour obtenir des messages d'erreur détaillés, assurez-vous que votre fournisseur prend en charge la découverte OIDC standard et vérifiez la connectivité réseau entre Unraid et le fournisseur. Pour obtenir de l'aide supplémentaire, visitez les forums Unraid.

Éléments supplémentaires de l'interface​

Fournisseur Unraid.net​

Le fournisseur Unraid.net est intégré et préconfiguré. Vous devez uniquement configurer les règles d'autorisation dans l'interface.

Configuration :

  • URL de l'émetteur : https://accounts.google.com
  • ID/Secret Client : De vos identifiants de client OAuth 2.0
  • URI de redirection : http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
astuce

Faites correspondre le protocole à la configuration de votre serveur. Utilisez http:// si vous accédez à votre serveur Unraid sans SSL/TLS (cas typique d'un accès depuis le réseau local). Utilisez https:// si vous avez configuré SSL/TLS sur votre serveur. Certains fournisseurs OIDC (comme Google) requièrent HTTPS et n'accepteront pas les URI de redirection HTTP.

Remplacez YOUR_UNRAID_IP par l'adresse IP réelle de votre serveur (par exemple, 192.168.1.100 ou tower.local).

Authelia​

Étapes de configuration

Configurez des identifiants OAuth 2.0 dans le Google Cloud Console :

  1. Allez dans APIs & Services → Informations d'identification.
  2. Cliquez sur Créer des identifiants → ID client OAuth.
  3. Choisissez Application Web comme type d'application.
  4. Ajoutez votre URI de redirection à URIs de redirection autorisés.
  5. Configurez l'écran de consentement OAuth si vous y êtes invité.

Configuration :

  • Enregistrez votre configuration de fournisseur
  • Déconnectez-vous (si connecté)
  • Portées requises : openid, profile, email
  • URI de redirection : http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
avertissement

Google exige des noms de domaine valides pour les URI de redirection OAuth. Les adresses IP locales et les domaines .local ne sont pas acceptés. Pour utiliser Google OAuth avec votre serveur Unraid, vous aurez besoin de :

  • Option 1 : Proxy inverse - Configurez un proxy inverse (comme NGINX Proxy Manager ou Traefik) avec un nom de domaine valide pointant vers votre API Unraid.
  • Option 2 : Tailscale - Utilisez Tailscale pour obtenir un domaine *.ts.net valide que Google acceptera. Pour plus d'informations sur Tailscale, consultez Accès à distance.
  • Option 3 : DNS dynamique - Utilisez un service DDNS pour obtenir un nom de domaine public pour votre serveur.

N'oubliez pas de mettre à jour votre URI de redirection à la fois dans le Google Cloud Console et dans votre configuration OIDC Unraid pour utiliser le domaine valide.

Pour les domaines Google Workspace, utilisez le mode avancé avec la revendication hd pour restreindre l'accès au domaine de votre organisation.

"URI de redirection invalide"​

Configurez le client OIDC dans votre configuration.yml d'Authelia avec l'ID client unraid-api et générez un secret haché en utilisant la commande hash-password d'Authelia.

Configuration :

  • Vérifiez qu'au moins une règle d'autorisation est configurée
  • ID client : unraid-api (ou tel que configuré dans Keycloak)
  • Secret du client : Depuis l'onglet Credentials de Keycloak
  • Portées requises : openid, profile, email
  • URI de redirection : http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Les règles d'autorisation peuvent être configurées dans l'interface en utilisant des domaines email ou des revendications avancées.

Authentik​

Créez un nouveau fournisseur OAuth2/OpenID dans Authentik, puis créez une application et liez-la au fournisseur.

Configuration :

  • URL de l'émetteur : https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
  • ID client : Depuis la configuration du fournisseur Authentik
  • Secret du client : Depuis la configuration du fournisseur Authentik
  • Portées requises : openid, profile, email
  • URI de redirection : http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Les règles d'autorisation peuvent être configurées dans l'interface.

Mode Débogage​

Pour résoudre les problèmes :

Configuration :

  • URL de l'émetteur : https://YOUR_DOMAIN.okta.com
  • ID client : unraid-api (ou tel que configuré dans Keycloak)
  • Secret du client : Depuis la configuration de l'application Okta
  • Portées requises : openid, profile, email
  • URI de redirection : http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Les règles d'autorisation peuvent être configurées dans l'interface en utilisant des domaines email ou des revendications avancées.

Authentik​

Créez un nouveau fournisseur OAuth2/OpenID dans Authentik, puis créez une application et liez-la au fournisseur.

Configuration :

  • URL de l'émetteur : https://authentik.exemple.com/application/o/<application_slug>/
  • ID client : Depuis la configuration du fournisseur Authentik
  • Secret du client : Depuis la configuration du fournisseur Authentik
  • Portées requises : openid, profile, email
  • URI de redirection : http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Les règles d'autorisation peuvent être configurées dans l'interface.

🏢 Configuration spécifique au fournisseur​

Créez une nouvelle application Web OIDC dans la console d'administration Okta et assignez des utilisateurs ou des groupes appropriés.

Configuration :

  • URL de l'émetteur : https://YOUR_DOMAIN.okta.com
  • ID client : Depuis la configuration de l'application Okta
  • Secret du client : Depuis la configuration de l'application Okta
  • Portées requises : openid, profile, email
  • URI de redirection : http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Les règles d'autorisation peuvent être configurées dans l'interface.