Extension:SimpleSAMLphp

From mediawiki.org
This page is a translated version of the page Extension:SimpleSAMLphp and the translation is 97% complete.
Cette extension est maintenue par un membre de Groupe des acteurs de MediaWiki .
Cette extension nécessite que l'extension PluggableAuth soit d'abord installée.
Manuel des extensions MediaWiki
SimpleSAMLphp
État de la version : stable
Implémentation Identité de l'utilisateur
Description Étend l'extension PluggableAuth pour fournir une authentification à l'aide de SimpleSAMLphp.
Auteur(s) Robert Vogel, Cindy Cicalese
Dernière version 7.0.1 (2023-06-12)
Politique de compatibilité Le master conserve la compatibilité arrière.
MediaWiki 1.35+
Composer mediawiki/simple-s-a-m-lphp
Licence Licence MIT
Téléchargement
  • $wgSimpleSAMLphp_MandatoryUserInfoProviders
  • $wgSimpleSAMLphp_InstallDir
Téléchargements trimestriels 113 (Ranked 58th)
Traduire l’extension SimpleSAMLphp sur translatewiki.net si elle y est disponible
Problèmes Tâches ouvertes · Signaler un bogue

L’extension SimpleSAMLphp (Security Assertion Markup Language) utilise l’extension PluggableAuth pour fournir une authentification en utilisant SimpleSAMLphp. Elle est principalement conçue pour prendre en charge les flux d'authentification initiés par fournisseur de service SP (Service Provider) en renseignant à la demande, les comptes utilisateur.

Installation

Cette extension nécessite que l'extension PluggableAuth et que SimpleSAMLphp soient déjà installés.


  • Téléchargez et placez le(s) fichier(s) dans un répertoire appelé SimpleSAMLphp dans votre dossier extensions/.
    Les développeurs et les contributeurs au code doivent à la place installer l'extension à partir de Git en utilisant:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/SimpleSAMLphp
  • Ajoutez le code suivant à la fin de votre fichier LocalSettings.php  :
    wfLoadExtension( 'SimpleSAMLphp' );
    
  • Installation et configuration SimpleSAMLphp
    • Notez que vous devrez probablement changer le type d'enregistrement de la session dans SimpleSAMLphp en quelque chose de différent de phpsession (voir la section des problèmes connus)
  • Configurez selon les besoins.
  • Yes Fait – Accédez à Special:Version sur votre wiki pour vérifier que l'extension a bien été installée.

Configuration

Les valeurs des paramètres de configuration doivent être obligatoirement renseignées :

Paramètre Valeur par défaut Description
$wgSimpleSAMLphp_InstallDir aucune Chemin sur le serveur local où SimpleSAMLphp est installé.

Des variables de configuration optionnelles sont fournies en supplément.

Ajouter le greffon à $wgPluggableAuth_Config :

$wgPluggableAuth_Config['Log in using my SAML'] = [
	'plugin' => 'SimpleSAMLphp',
	'data' => [
		'authSourceId' => 'default-sp',
		'usernameAttribute' => 'username',
		'realNameAttribute' => 'name',
		'emailAttribute' => 'email'
	]
];

Champs de data

Toutes versions

Nom du champ Valeur par défaut Description
authSourceId aucune AuthSourceId utilisé pour l'authentification.
usernameAttribute aucune nom de l'attribut à utiliser pour le nom d'utilisateur de l'utilisateur (par défaut il est mis en minuscules, si non souhaité voir ci-dessous ).
realNameAttribute aucune Nom du ou des attributs à utiliser pour le vrai nom de l'utilisateur. Il peut s'agir d'un seul nom d'attribut ou d'un tableau de noms d'attributs. Dans ce dernier cas, les valeurs d'attribut seront concaténées avec des espaces entre elles pour former la valeur du nom réel de l'utilisateur.
emailAttribute aucune Nom de l'attribut à utiliser pour l'adresse courriel de l'utilisateur.
userinfoProviders [  'username' => 'username',  'realname' => 'realname',  'email' => 'email']
attributeProcessors [

"...\\MapGroups::factory"

]

Utilisé pour configurer le mécanisme de synchronisation de groupe et pour ajouter le traitement des données de réponse SAML arbitraires. Exemple voir ci-dessous. Le repli d'usine a la signature suivante :
callback(
    \User $user,
    array $attributes,
    \Config $config,
    SimpleSAML\Auth\Simple $saml )
: MediaWiki\Extension\SimpleSAMLphp\IAttributeProcessor

Avant la version 7.0.0

En version 7.0.0, la prise en charge du mapping des groupes a été déplacée vers PluggableAuth avec de légères modifications de syntaxe. Pour plus d'informations sur la configuration de la synchronisation de groupe dans les versions 7.0.0+ voir la documentation PluggableAuth.

Nom de champ Valeur par défaut Description
mapGroups_Map [] Mappage des attributs SAML aux groupes MediaWiki de la forme :

'mapGroups_Map' => [ 'mediawiki group' => ['saml attribute' => ['group 1', 'group 2', '...']]]

Aucun mappage de groupe n'est effectué si $mapGroups_Map est nul.

syncAllGroups_GroupAttributeName "groups" S'il est configuré pour utiliser "SyncAllGroups", cet attribut SAML sera lu
syncAllGroups_GroupNameModificationCallback null S'il est configuré pour utiliser "SyncAllGroups", ceci peut être utilisé pour modifier/normaliser les groupes provenant de l'IdP (Identity Provider). Voir l'exemple ci-dessous.
syncAllGroups_LocallyManaged [ "sysop" ] S'ils sont configurés pour utiliser "SyncAllGroups", ces groupes d'utilisateurs locaux ne seront pas influencés par ce qui est défini dans la réponse SAML
groupAttributeDelimiter null Si l'IdP renvoie la liste des groupes dans une seule chaîne (par exemple "saml attribute" => [ "group 1,group 2,group 3" ] au lieu de "saml attribute" => [ "group 1", "group 2", "group 3" ]), cette valeur peut être définie pour fractionner la chaîne. Sachez que dans ce cas, seul le premier élément de la valeur d'attribut SAML est évalué. Ce paramètre s'applique aux deux mécanismes de synchronisation de groupe "MapGroups" et "SyncAllGroups"

Ne pas convertir les noms d'utilisateur en minuscules

Par défaut, les noms d'utilisateur sont passés en minuscules. La casse initiale peut être conservée en déclarant :

$wgPluggableAuth_Config['Log in using my SAML'] = [
	'plugin' => 'SimpleSAMLphp',
	'data' => [
		// ...
		'userinfoProviders' => [
			'username' => 'rawusername'
		]
	]
];

Définir le fournisseur d’informations utilisateur personnalisé

Si vous souhaitez modifier l'un des champs username, realname ou email avant la connexion, par exemple, si votre source SAML ne fournit pas d'attribut explicite pour le nom d'utilisateur et que vous souhaitez utiliser l'adresse courriel sans le domaine pour le nom d'utilisateur, vous pouvez configurer un repli personnalisé pour $wgSimpleSAMLphp_MandatoryUserInfoProviderFactories. Pour créer l'objet, une spécification valide de ObjectFactory doit être paramètrée.

Pour les cas simples d'utilisation, on peut utiliser MediaWiki\Extension\SimpleSAMLphp\UserInfoProvider\GenericCallback, en supposant que votre attribut courriel s'appelle mail (s'il s'appelle autrement, changez les deux instances de $attributes['mail'] en $attributes['YourEmailAttributeName']) :

$wgSimpleSAMLphp_MandatoryUserInfoProviders['myusername'] = [
	'factory' => function() {
		return new \MediaWiki\Extension\SimpleSAMLphp\UserInfoProvider\GenericCallback( function( $attributes ) {
			$mailAttribute = 'mail';
			if ( !isset( $attributes[$mailAttribute] ) ) {
				throw new Exception( 'missing email address' );
			}
			$parts = explode( '@', $attributes[$mailAttribute][0] );
			return strtolower( $parts[0] );
		} );
	}
];

Assurez-vous d'avoir aussi initialisé myusername dans userinfoProviders du champ data :

$wgPluggableAuth_Config['Log in using my SAML'] = [
	'plugin' => 'SimpleSAMLphp',
	'data' => [
		// ...
		'userinfoProviders' => [
			'username' => 'myusername'
		]
	]
];

Correspondance des groupes (avant la version 7.0.0)

En version 7.0.0, la prise en charge du mappage des groupes a été déplacée vers PluggableAuth avec de légères modifications de syntaxe. Pour plus d'informations sur la configuration de la synchronisation de groupe en version 7.0.0+ voir la documentation PluggableAuth.

Cas d'utilisation : votre IdP SAML lit les groupes à partir de LDAP ou de la base de données et stocke ces informations dans un attribut de la réponse SAML. Vous pouvez l'utiliser pour mapper les groupes MediaWiki aux utilisateurs appartenant à certains groupes connus donnés par votre IdP.

Exemple :

  • Votre IdP envoie un attribut nommé "groups" avec une liste de noms tels que "administrator", "student", "teacher", ... dans la réponse SAML après authentification.
  • Tous les utilisateurs qui ont la valeur "administrator" dans l'attribut "groups" doivent être mappés au groupe "sysop" de MediaWiki pour leur donner les droits administrateur dans votre instance de MediaWiki.
  • Créez une carte de groupe dans votre LocalSettings.php comme suit : $wgSimpleSAMLphp_GroupMap = ['sysop' => ['groups' => ['administrator']]];

Vous pouvez proposer des mappages assez complexes correspondant à vos besoins. Si vous avez plusieurs attributs de SAML, ajoutez-les simplement au tableau avec le tableau des valeurs que vous souhaitez mapper.

Si un groupe MediaWiki n'existe pas, il sera créé à la volée lors du premier mappage réussi d'un utilisateur.

Si un utilisateur appartient à un groupe MediaWiki qui n'est plus mappé sur cet utilisateur (par exemple, en perdant l'appartenance au groupe dans la source de données utilisateur SAML), l'utilisateur sera supprimé de ce groupe MediaWiki lors de la prochaine connexion. De cette manière vous pouvez également supprimer en masse des groupes de SAML et de leurs appartenances - il suffit de changer les valeurs de mappage pour qu'elles ne correspondent plus à la réponse SAML, mais ne modifiez pas le nom du groupe MediaWiki.

Mappage des groupes 2

Depuis la version 4.3, on peut également configurer un mécanisme de synchronisation de groupe alternatif. Outre les "MapGroups" par défaut, on peut utiliser "SyncAllGroups", qui prend tous les groupes de la réponse SAML et leur assigne l'utilisateur.

Pour ce faire, ajoutez ce qui suit au LocalSettings.php :

$wgSimpleSAMLphp_AttributeProcessorFactories = [
	"MediaWiki\\Extension\\SimpleSAMLphp\\AttributeProcessor\\SyncAllGroups::factory"
];

Si l'IdP renvoie des noms de groupe qui ne conviennent pas au wiki, on peut mettre en place une procédure de repli qui modifie les noms des groupes. Par exemple certaines configurations IdP peuvent renvoyer des LDAP-DN comme "CN = Admin, OU = Groups, DC = SomeDomain". On pourrait alors préciser en LocalSettings.php :

$wgSimpleSAMLphp_SyncAllGroups_GroupNameModificationCallback = function ( $origGroupName ) {
    return preg_replace( '#^CN=(.*?),OU=.*$#', '$1', $origGroupName );
};

Traitement des données arbitraires de la réponse SAML

Les "processeurs d'attributs" peuvent également être utilisés pour traiter des données arbitraires de la réponse SAML. Dans ce cas, il faut d'abord créer une nouvelle classe PHP qui implémente l'interface MediaWiki\Extension\SimpleSAMLphp\IAttributeProcessor. Pour plus de commodité, la classe de base MediaWiki\Extension\SimpleSAMLphp\AttributeProcessor\Base peut être utilisée; elle possède son repli de factory et un constructeur propre. Exemple :

use MediaWiki\Extension\SimpleSAMLphp\AttributeProcessor\Base;

class SyncLanguage extends Base {
    public function run() {
        //initialiser le genre dans $this->user à partir d'une valeur de $this->attributes
    }
}

Il doit ensuite être instancié en utilisant $wgSimpleSAMLphp_AttributeProcessors.

Avant 5.0, c'était $wgSimpleSAMLphp_AttributeProcessorFactories.

Compatibilité

Configurations testées
Noyau MediaWiki Extension:PluggableAuth Extension:SimpleSAMLphp SimpleSAMLphp (Fournisseur de service / bibliothèque) Notes
1.39.5 7.0 7.0 2.1.1 (minimum PHP version required is PHP 8.0) OK
1.39.3 7.0 7.0 2.0.2 OK
1.39.3 7.0-dev 7.0-dev 1.19.6 OK
1.39.3 6.2 5.0.1 1.18.4 Erreur
1.39 6.1 5.0 2.0.0-rc1 OK
1.39 6.1 5.0 1.19.6 OK
1.39 6.1 5.0 1.18.8 OK
1.35 5 4.0 1.18.8 OK


Notes des versions

Version 7.0.0
  • Rendu compatible avec PluggableAuth 7.0.0
  • Utilisez le nouveau cadre de population de groupe PluggableAuth; prend en charge la récupération des attributs comprenant des groupes
  • Améliorations du code
  • Correction de bogues :
    • T305031: Erreur lors de la déconnexion via l'API
Version 5.0.1
  • Corriger la synchronisation de groupe
Version 5.0.0
  • Version stable
Version 5.0.0-beta
Version 4.5.2
  • bogue corrigé: les groupes ne sont pas supprimés dans MW si l'attribut n'existe pas (T246351)
Version 4.5.1
  • correction de l'avertissement: $wgSimpleSAMLphp_GroupMap n'est pas un tableau
  • amélioration du chargement des informations utilisateur et des groupes
  • tests améliorés
Version 4.5
  • Ajout de la prise en charge des fournisseurs d'informations utilisateur personnalisés
  • mis à jour vers la version 2 du manifeste
Version 4.4
Version 4.3
  • Ajout de la prise en charge des processeurs d'attributs
  • Correction d'un bogue dans le traitement des attributs SAML
  • Ajout d'un espace de noms compatible PSR-4
  • Arrêt du support pour les versions MW < 1.31
Version 4.2
  • Les fonctions de nom d'utilisateur, de vrai nom et de courriel ont été supprimées afin qu'elles puissent être remplacées dans une sous-classe pour permettre des règles personnalisées
  • Style de codage et répertoires
  • Débogage amélioré
Version 4.1
  • Implémente l'accroche PluggableAuthPopulateGroups pour remplir les groupes MediaWiki à partir des attributs SAML. Merci à Poikilotherm d'avoir contribué à cette fonctionnalité.
Version 4.0
  • Ajout d'un message d'erreur facultatif à authenticate()
  • Numéro de version incrémenté à synchroniser avec les extensions PluggableAuth et OpenID Connect

Débogage

L'authentification unique SSO peut être difficile à configurer correctement, en particulier pour les nouveaux administrateurs système chargés de connecter leur nouvelle instance de MediaWiki au fournisseur d'identité de la société. Les extensions PluggableAuth et SimpleSAMLphp elles-mêmes sont très stables, et les problèmes principaux sont habituellement liés au paramètrage.

Pour commencer à déboguer, affectez $wgDebugLogFile à un chemin de fichier sur votre système local. Vous n'avez pas besoin de mettre $wgShowExceptionDetails à true ; en fait, vous ne devriez probablement pas le faire, pour des raisons de sécurité.

Visitez votre wiki et essayez de vous connecter avec PluggableAuth. Une fois que vous avez rencontré votre erreur, consultez le fichier de débogage et cherchez des lignes qui commencent par [PluggableAuth] et [SimpleSAMLphp].

En cas de problème d'authentification, le journal de débogage indique quelque part [PluggableAuth] Authentication failed.

L'extension SimpleSAMLphp fonctionne ainsi :

  1. L'utilisateur clique sur le bouton de connexion SSO au wiki.
  2. L'utilisateur est dirigé vers Special:PluggableAuthLogin. Il détecte que le wiki utilise l'extension SimpleSAMLphp. SimpleSAMLphp (le logiciel, pas l'extension) détecte qu'aucune session de connexion n'a encore été définie.
  3. Special:PluggableAuthLogin appelle la fonction authenticate() de l'extension SimpleSAMLphp, qui appelle l'API de SimpleSAMLphp pour commencer le processus d'authentification.
  4. SimpleSAMLphp redirige l'utilisateur vers la page de connexion du fournisseur d'identité.
  5. Une fois que l'utilisateur s'est authentifié avec IdP, il génère une assertion et redirige vers l'URL ACS (service client d'assertion) de votre instance SimpleSAMLphp locale, qui redirige ensuite vers le Special:PluggableAuthLogin du wiki.
  6. Special:PluggableAuthLogin reconnaît maintenant le cookie de session et gère la connexion de l'utilisateur.

Si vous rencontrez une boucle de redirection de connexion, le processus d'authentification ne pourra jamais consigner un message d'erreur ou de réussite. Cela indique que l'appel à la méthode requireAuth() de SimpleSAMLphp ne se termine jamais, ce qui signifie que SimpleSAMLphp essaie de recommencer le processus d'authentification. Ceci est généralement dû au fait qu'il ne détecte pas la session de connexion malgré qu'elle soit établie. Assurez-vous de ne pas faire les erreurs courantes, telles que laisser store.type dans votre configuration SimpleSAMLphp en tant que phpsession au lieu de le modifier en une autre méthode, ou mettre votre instance SimpleSAMLphp dans un domaine différent de celui de votre wiki sans proxy adapté. (Par exemple, si votre instance de SimpleSAMLphp se trouve dans le domaine canonique saml.mywiki-sso.com mais que votre wiki est situé à my.wiki, la session ne sera jamais stockée sur my.wiki et Special:PluggableAuthLogin redirigera vers le fournisseur d'identité au lieu de connecter l'utilisateur, créant ainsi une boucle de connexion.)

Si vous rencontrez un message d'erreur sur Special:PluggableAuthLogin après une redirection réussie du fournisseur d'identité IdP, il y a probablement une erreur de configuration PluggableAuth/SimpleSAMLphp dans votre LocalSettings.php. Vérifiez si vous avez correctement configuré vos attributs. Les attributs doivent parfois être des URL (comme si vous utilisiez Azure Active Directory).

Bogues connus

Collision dans le gestionnaire de session entre MediaWiki et le fournisseur de service de SimpleSAML

Si vous utilisez MediaWiki 1.27 ou version ultérieure avec PluggableAuth 2.0 ou version ultérieure, des problèmes ont été observés lorsque SimpleSAMLphp est configuré pour utiliser phpsession pour store.type. Cela peut être dû à phab:T147161. Pour résoudre ce problème, utilisez un type différent de dépôt dans la configuration du logiciel SimpleSAMLphp en ajustant simplesamlphp/config/config.php (voir https://simplesamlphp.org/docs/stable/simplesamlphp-maintenance#section_2_3). Par exemple, pour SQLite, utilisez:

'store.type' => 'sql',
'store.sql.dsn' => 'sqlite:/path/where/the/apache/user/can/write/sqlitedatabase.sq3',

Pour MySQL, utilisez :

'store.type' => 'sql',
'store.sql.dsn' => 'mysql:host=xxx;port=xxx;dbname=xxx',
'store.sql.username' => 'xxx',
'store.sql.password' => 'xxx',

Message d'erreur à la déconnexion

Depuis MediaWiki 1.35 par défaut (habillage Vector) la déconnexion n'est plus réalisée en appelant Special:UserLogout, mais par une requête POST XHR. Ceci n'est pas compatible avec la manière dont SAML fonctionne et résultait en un message d'erreur dans les versions antérieures à la 7.0.0 de cette extension (voir la capture d'écran).

Voir aussi tâche T305031

Comme solution de contournement avant la version 7.0.0, vous pouvez modifier le lien de déconnexion et le faire pointer vers Special:Logout à nouveau, en ajoutant :

\Hooks::register(
	'SkinTemplateNavigation::Universal',
	function( \SkinTemplate $sktemplate, array &$links ) {
		if ( !isset( $links['user-menu']['logout'] ) ) {
			return;
		}
		$links['user-menu']['custom-logout'] = $links['user-menu']['logout'];
		unset ( $links['user-menu']['logout'] );
	}
);

au fichier LocalSettings.php.

Full Examples of Authentication and Authorization

Example for MW 1.35

  • System RockyLinux8/RHEL8
  • MediaWiki 1.35.11
  • PluggableAuth 6.3
  • SimpleSAMLphp 5.0.1
// chargement et configuration de PluggableAuth pour  SAML IDP/SSO
wfLoadExtension( "PluggableAuth" );

$wgPluggableAuth_EnableAutoLogin = true;
$wgPluggableAuth_EnableLocalLogin = false;
$wgPluggableAuth_EnableLocalProperties = false;
$wgGroupPermissions['*']['autocreateaccount'] = true;

// chargement et configuration de SimpleSAMLphp pour  SAML IDP/SSO
wfLoadExtension( "SimpleSAMLphp" );
$wgSimpleSAMLphp_InstallDir = '/opt/simplesamlphp';

// SAML AuthENTICATION (Tell Mediawiki "WHO" the user "IS")
$wgPluggableAuth_Config['Log in using SAML']['data'] += [ 'mapGroups_Map'  => [

     'sysop'           => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansSysop'          ]],
     'bureaucrat'      => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansBureaucrat'     ]],
     'interface-admin' => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansInterfaceAdmin' ]],
     'Viewer'          => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansViewer'         ]],
     'Contributor'     => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansContributor'    ]]

]];

Example for MW 1.39

  • System RockyLinux8/RHEL8
  • SimpleSAMLphp (ServiceProvider / library) v2.2.1
  • MediaWiki v1.39.7
  • Extension:PluggableAuth v7.0.0
  • Extension:SimpleSAMLphp v7.0.0
// Load and Configure PluggableAuth for SAML IDP/SSO
wfLoadExtension( "PluggableAuth" );
$wgPluggableAuth_EnableAutoLogin = true;
$wgPluggableAuth_EnableLocalLogin = false;
$wgPluggableAuth_EnableLocalProperties = false;
$wgGroupPermissions['*']['autocreateaccount'] = true;

// Load and Configure SimpleSAMLphp for SAML IDP/SSO
wfLoadExtension( "SimpleSAMLphp" );
$wgSimpleSAMLphp_InstallDir = '/opt/simplesamlphp';

// SAML AuthENTICATION (Tell Mediawiki "WHO" the user "IS")
$wgPluggableAuth_Config['Log in using SAML'] = [
    'plugin' =>   'SimpleSAMLphp',
    'data'   => [ 
'yourIDPauthSourceId'      => 'default-sp',
'NameOfYourIDPusernameAttribute' => 'ValueOfYourIDPusernameAttribute',
'NameOfYourIDPrealNameAttribute' => 'ValueOfYourIDPrealNameAttribute',
'NameOfYourIDPemailAttribute'    => 'ValueOfYourIDPemailAttribute'
                ]
];

// SAML AuthORIZATION (Tell Mediawiki "WHAT" roles the user "HAS")
$wgPluggableAuth_Config['Log in using SAML'] += [
    'groupsyncs'  => [ [ 'type' => 'mapped',
                         'map'   => [ 
'sysop'           => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansSysop'          ],
'bureaucrat'      => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansBureaucrat'     ],
'interface-admin' => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansInterfaceAdmin' ],
'Contributor'     => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansContributor'    ],
'Viewer'          => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansViewer'         ],
                                    ]
                     ] ]
];