Bienvenue
Jalios Community
Tout ce que vous souhaitez savoir sur l'écosystème Jalios
Présentation, installation et configuration du Module d'authentification SAML , utilisant la norme SAML 2.0, destiné à s'interfacer avec toutes les solutions majeures de gestion d'identité du marché supportant le protocole SAMLv2 : ADFS, OIF, OpenAM, Shibboleth, ...
Déployez le module SAML et redémarrez JPlatform
Saisissez l'Entity ID que vous souhaitez affecter à JPlatform dans l'interface d'édition des propriétés du module et enregistrez.
Configuration de l'IdP
WEB-INF/data/saml2/sp-metadata.xml
généré automatiquement par JPlatformhttps://jplatform.example.com/plugins/SAMLPlugin/saml2/metadata.jsp
AuthnRequest
demandant un NameID
au format transient
,NameID
depuis la configuration du module SAMLConfiguration de JPlatform
WEB-INF/data/saml2/idp-metadata.xml
[SAMLManager] - SAML Plugin is enabled
doit être visible dans les logs du serveurLe module est désormais prêt à fonctionner.
Tests
Accédez au formulaire de connexion, un bouton Connexion avec SAML vous permet de tester l'authentification. En cas d'échec de connexion, les logs du serveurs vous indiqueront la raison de l'échec.
Dès que vous avez validé que l'authentification est fonctionnelle, vous pouvez modifier les réglages du module pour activer l'authentification SAML automatique afin que les utilisateurs n'aient pas à utiliser le bouton de connexion.
Suivez la documentation complète pour découvrir toutes les possibilités offertes par le module.
Le module SAML supporte 2 profiles de SSO définis dans la spécification SAML 2.0
AuthnRequest
) signée, en HTTP-Redirect binding
, avec un NameID
au format transient
,HTTP-POST binding
,HTTP-POST binding
Toutes les étapes ci-dessous sont requises pour une mise en œuvre du module en environnement de production.
Il est impératif de définir un nom globalement unique et stable qui identifie JPlatform en tant que Service Provider, c'est l'entity ID.
En général, l'entity ID est une URL absolue, mais il s'agit bien d'un nom, pas d'un emplacement. L'entity ID n'a pas besoin de pointer une ressource web existante.
Le module SAML utilise par défaut l'URL du site comme Entity ID.
Vous pouvez modifier ce réglage :
custom.prop
jcmsplugin.saml.SPSSO.entityID: https://jcms.example.com/
Des certificats sont nécessaires pour la signature et pour le chiffrement des messages échangés entre le SP et l'IdP.
Au premier démarrage de JPlatform avec le module, un keystore contenant une clé privé et un certificat auto-signé est généré pour la signature ET l'encryption :
Ce certificat est enregistré dans WEB-INF/data/saml2/default-keystore.jks
$ keytool -list -keystore default-keystore.jks -storepass changeit -keypass changeit
Cependant, la génération de certificats dédiés à la production (distinct pour la signature et le chiffrement) est préférable et doit se faire comme indiqué ci après :
$ keytool.exe -genkey -keyalg RSA -alias "SAML Signing" -keystore signing.jks -validity 3650 -keysize 1024 Entrez le mot de passe du fichier de clés : changeit Ressaisissez le nouveau mot de passe : changeit Quels sont vos nom et prénom ? [Unknown]: SAML Signing - jcms.example.com Quel est le nom de votre unité organisationnelle ? [Unknown]: Quel est le nom de votre entreprise ? [Unknown]: Quel est le nom de votre ville de résidence ? [Unknown]: Quel est le nom de votre état ou province ? [Unknown]: Quel est le code pays à deux lettres pour cette unité ? [Unknown]: Est-ce CN=SAML Signing - jcms.example.com, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown ? [non]: oui Entrez le mot de passe de la clé pour <SAML Signing> (appuyez sur Entrée s'il s'agit du mot de passe du fichier de clés) : changeit Ressaisissez le nouveau mot de passe : changeit
custom.prop
(auquel cas un redémarrage est nécessaire) jcmsplugin.saml.SPSSO.signing-certificate.path: WEB-INF/data/saml2/sp-signing-certificate.jks jcmsplugin.saml.SPSSO.signing-certificate.password: changeit
jcmsplugin.saml.SPSSO.encryption-certificate.path: WEB-INF/data/saml2/sp-encryption-certificate.jks jcmsplugin.saml.SPSSO.encryption-certificate.password: changeit
Notes :
keystore JKS
(extension .jks
)PKCS12
(avec l'extension .pfx
ou .p12
) L'enregistrement de l'IdP auprès de JPlatform s'effectue en indiquant les métadonnées de l'IdP à JPlatform.
Voici quelques exemples d'URL communes permettant de récupérer les métadonnées de l'IdP :
https://adfs.example.local/FederationMetadata/2007-06/FederationMetadata.xml
http://oif.example.local/fed/idp/metadata
https://shib.example.local/idp/profile/Metadata/SAML
https://openam.example.local/openam/saml2/jsp/exportmetadata.jsp?realm=MYREALM&entityid=https://idp.example.local/openam
Pour référencer ces métadonnées dans JPlatform, 2 possibilités :
custom.prop
(auquel cas un redémarrage est nécessaire)jcmsplugin.saml.IDPSSO.metadata.path: https://idp.example.local/path/to/metadata
custom.prop
(auquel cas un redémarrage est nécessaire) jcmsplugin.saml.IDPSSO.metadata.path: WEB-INF/data/saml2/myidp-metadata.xml
Pour enregistrer JPlatform en tant que Service Provider sur votre IdP, vous devez récupérer le fichier de metadata de JPlatform.
Avant de procéder à cette étape, assurez-vous que la configuration de l'Entity ID et des certificats a été effectuée et prise en compte par JPlatform et le module SAML (soit par un redémarrage, soit par modification depuis l'interface d'édition des propriétés).
Le module SAML génère le fichier de metadonnées dans le chemin suivant de la webapp : WEB-INF/data/saml2/sp-metadata.xml
.
Le fichier est régénéré à chaque démarrage ou chaque modification de configuration.
Le fichier est également accessible via une URL (publique par défaut, mais modifiable depuis le module)https://jplatform.example.com/plugins/SAMLPlugin/saml2/metadata.jsp
Récupérez ce fichier et procédez à son ajout dans l'IdP, en suivant la documentation spécifique à votre IdP.
Pour Microsoft AD FS, vous pouvez suivre l'un des guides suivant :
Pour Microsoft Azure AD, vous pouvez suivre le guide suivant :
Dans la configuration par défaut du module, la réponse d'authentification SAML envoyée par l'IdP doit contenir un attribut permettant à JPlatform d'identifier l'utilisateur dans la base des membres.
Il est important de configurer un attribut en correspondance avec la configuration des logins dans JPlatform.
Quelques exemples de mises en œuvre :
ldap.mapping.login: userPrincipalName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
ldap.mapping.login: uid
urn:oid:0.9.2342.19200300.100.1.1
email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
Il s'agit ici d'exemples, pas de recommandations. Les configurations possibles sont multiples ; il faut s'assurer de respecter les règles de votre IdP et leur cohérence avec les choix effectués dans JPlatform.
Pour procéder à la configuration :
custom.prop
(auquel cas un redémarrage est nécessaire) jcmsplugin.saml.authn-response.attribute-statement-mbr-mapping.login: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
Par défaut le comportement du module SAML est de ne PAS procéder à une authentification automatique des utilisateurs auprès de l'IdP.
Lorsque l'utilisateur arrive sur le formulaire d'authentification, un bouton Connexion avec SAML lui est proposé.
Il est possible de modifier la configuration du module pour permettre une redirection systématique des utilisateurs anonymes vers l'IdP, pour authentification.
Modifiez l'option Activer l'authentification SAML
custom.prop
(auquel cas un redémarrage est nécessaire) jcmsplugin.saml.automatic-saml-auth: true
Notes :
Quelle que soit la configuration, le bouton de connexion peut être personnalisé :
icon.jcmsplugin-saml: plugins/SAMLPlugin/docs/images/icon.gif
plugin.prop
de votre module de sitejcmsplugin.saml.authenticate-with-saml
fr.prop
, en.prop
, ...) de votre module de siteComme tous les modules de SSO proposés par Jalios, le module SAML permet de définir une ou plusieurs règles d'accès qui permettent d'identifier deux populations :
Pour connaitre en détail le fonctionnement et la mise en place de règles d'accès, consultez l'article : Règles d'accès des modules de SSO (aka AccessRules)
Dans le module SAML, la configuration des règles d'accès s'effectue par propriété, avec le préfixe jcmsplugin.saml.
.
Voici un exemple (totalement fictif) pour proposer l'authentification SAML uniquement aux utilisateurs de Firefox sur le réseau local :
jcmsplugin.saml.access-rule.class: MetaAccessRule jcmsplugin.saml.meta-access-rule.expression: (firefox && localnetwork) jcmsplugin.saml.meta-access-rule.firefox.class: UserAgentAccessRule jcmsplugin.saml.meta-access-rule.firefox.regex: .*Firefox.* jcmsplugin.saml.meta-access-rule.localnetwork.class: IpAccessRule jcmsplugin.saml.meta-access-rule.localnetwork.regex: ^192\\.168\\.0\\..*
Il est également possible de changer l'objectif de la règle d'accès du module SAML en modifiant la propriété jcmsplugin.saml.access-rule.behavior
:
userAuthorize
(comportement par défaut) : la règle d'accès sert à déterminer si on peut proposer l'authentification SAML aux utilisateurs (que l'authentification soit automatique ou manuelle)userWithAutomaticConnexion
: la règle d'accès déclenche l'authentification automatique pour les utilisateurs qui valide la règle, pour les autres utilisateur l'authentification reste possible depuis le formulaire de login (Cette dernière possibilité de configuration est disponible depuis l'évolution SAML-27 intégrée dans les version 2.2 du module SAML)
Le comportement par défaut du module SAML est
AuthnRequest
) dont le format de NameID
souhaité est de type transient
.Il est cependant possible de modifier la configuration du module pour demander un format de NameID
spécifique afin de lire l'identifiant utilisateur dans le NameID
reçu en réponse. Pour cela
NameID
souhaité dans la propriété jcmsplugin.saml.websso-profile.nameid-format
jcmsplugin.saml.authn-response.attribute-statement-mbr-mapping.login
à une valeur vide pour utiliser le NameID
reçu en réponse.Cette configuration est possible depuis l'évolution SAML-19 intégrée dans les version 1.2 et 2.1 du module SAML
Le comportement par défaut du module SAML est d'accepter les réponses d'authentification SAML si et seulement si l'authentification de l'utilisateur effectué par l'IdP date de moins de 2 heures (7200 secondes), avec une marge d'erreur de 60 secondes (en cas de différence d'horodatage entre l'IdP et le SP).
Ces options peuvent être modifiées via les propriétés suivantes (en secondes) :
jcmsplugin.saml.websso-profile.max-auth-age: 7200
jcmsplugin.saml.websso-profile.time-margin: 60
Il est recommandée de paramétrer une durée d'expiration identique dans l'IdP et le SP (JPlatform).
Cette configuration est possible depuis l'évolution SAML-12 intégrée dans les version 1.2 et 2.0 du module SAML
Le comportement par défaut du module SAML est de conserver l'authentification SAML valide tant que le navigateur du client reste ouvert (en respectant les durée de validité de cookie configuré dans JPlatform).
Ainsi, dès que l'utilisateur ferme son navigateur, une authentification SAML auprès de l'IdP devra à nouveau être effectuée lors sa prochaine session de navigation.
En positionnant la propriété suivante, il est possible de persister l'authentification :jcmsplugin.saml.auth.use-persistent-cookie: true
Dans tous les cas c'est la configuration des cookies d'authentification de JPlatform qui s'applique.
Voir à ce sujet : Quelle est la durée maximum des cookies de connexion ?
Cette configuration est possible depuis l'évolution SAML-28 intégrée dans les version 2.2 du module SAML
Le comportement par défaut du module SAML est d'utiliser l'unique URL de base du site dans les endpoint communiqués à l'IdP dans les métadonnées SAML.
La conséquence est que l'IdP redirige systématiquement l'utilisateur vers cette URL configurée dans les propriétés du site (propriété channel.url
)
Si votre site est accessible via plusieurs URLs (comme par exemple https://intranet.example.com/ et https://extranet.example.com/), il est possible de déclarer les autres URLs dans la propriété jcmsplugin.saml.SPSSO.additional-base-urls
Exemple :
channel.url: https://intranet.example.com/
jcmsplugin.saml.SPSSO.additional-base-urls: https://extranet.example.com/ https://other.example.com/
La modification de cette configuration nécessite le rechargement des propriétés du module ou le redémarrage du site, afin de provoquer la régénération des métadonnées SAML. Les nouvelles métadonnées doivent être relus par l'IdP pour prise en compte (rappel : les métadonnées sont accessibles via le fichier WEB-INF/data/saml2/sp-metadata.xml
ou via l'URL/plugins/SAMLPlugin/saml2/metadata.jsp
).
Cette configuration est possible depuis l'évolution SAML-23 intégrée dans les version 2.2 du module SAML
Vous pouvez activez la synchronisation des utilisateurs à partir des informations issus de l'IdP.
Le principe est de configurer l'IdP pour envoyer les informations utilisateurs dans la réponse SAML, afin de permettre à JPlatform de créer et/ou mettre à jour les membres existants avec ces informations.
Pour cela
jcmsplugin.saml.sync-with-saml: true
jcmsplugin.saml.mapping.name
Description | Propriété |
---|---|
Nom | jcmsplugin.saml.mapping.name |
Prénom | jcmsplugin.saml.mapping.f-name |
Civilité | jcmsplugin.saml.mapping.salut |
Organisation | jcmsplugin.saml.mapping.organization |
Service | jcmsplugin.saml.mapping.department |
Fonction | jcmsplugin.saml.mapping.job |
jcmsplugin.saml.mapping.mail |
|
Téléphone | jcmsplugin.saml.mapping.phone |
Mobile | jcmsplugin.saml.mapping.mobile |
Voie et numéro | jcmsplugin.saml.mapping.street |
Code postal | jcmsplugin.saml.mapping.postalCode |
Boîte postale | jcmsplugin.saml.mapping.postOfficeBox |
Ville | jcmsplugin.saml.mapping.locality |
Département / Région | jcmsplugin.saml.mapping.region |
Pays | jcmsplugin.saml.mapping.country |
Langue Option disponible depuis SAML-52, version 2.4.1 du module |
jcmsplugin.saml.mapping.language |
Coordonnées | jcmsplugin.saml.mapping.address |
Informations | jcmsplugin.saml.mapping.info |
Responsable Option disponible depuis SAML-49, version 2.4 du module |
jcmsplugin.saml.mapping.manager |
Assistant Option disponible depuis SAML-49, version 2.4 du module |
jcmsplugin.saml.mapping.assistant |
Groupes Consultez la section suivante pour plus de détails sur la configuration de la synchronisation des groupes. |
jcmsplugin.saml.mapping.groups |
Options avancées :
Propriétés | Valeur par défaut | Description |
---|---|---|
jcmsplugin.saml.sync.create-new-account |
true |
Active ou désactive la création automatique d'un nouveau Membre après l'authentification SAML, si aucun Membre n'a pu être trouvé pour les informations de connexion reçues. |
jcmsplugin.saml.sync.update-existing-account |
true |
Active ou désactive la mise à jour automatique des comptes existants à partir des informations SAML. |
jcmsplugin.saml.sync.create-db-member |
false |
Active la création de Membres DB (au lieu de Membre JStore par défaut) |
Cette configuration est possible depuis l'évolution SAML-1 intégrée dans les version 2.2 du module SAML
Si vous activez la synchronisation des utilisateurs à partir des informations issus de l'IdP, il est également possible de configurer la synchronisation pour inclure les groupes de l'utilisateur.
La synchronisation des groupes est désactivée par défaut.
2 approches peuvent être utilisées pour la synchronisation des groupes :
Quelque soit l'approche retenue, les limites suivantes s'appliquent :
Configuration (coté JPlatform) :
L'attribut SAML dans lequel le module va lire l'information des groupes se renseigne dans la propriété jcmsplugin.saml.mapping.groups
.
Par exemple :
jcmsplugin.saml.mapping.groups: http://schemas.xmlsoap.org/claims/Group
Les groupes existant sont trouvés dans JPlatform, en cherchant une des informations suivantes (en utilisant la valeur récupérée dans l'attribut SAML)
jcmsplugin.saml.sync.search-group-by-name
, la valeur de cette propriété doit être le code de langue ISO-639 du nom du Groupe à rechercherjcmsplugin.saml.sync.search-group-by-name: fr
jcmsplugin.saml.sync.search-group-by-extradata
, sa valeur doit être le nom de l'extradata de Group à rechercher
# Declare Group ExtraData
extra.Group.saml-group-mapping:
# Provide I18N properties for field modification in Group edit form
en.extra.Group.saml-group-mapping: IdP Group ID
en.extra.Group.saml-group-mapping.help: Unique value returned by the Identity Provider, used during SAML member synchronization to retrieve the corresponding group in JPlatform
fr.extra.Group.saml-group-mapping: ID de groupe dans l'IdP
fr.extra.Group.saml-group-mapping.help: Valeur unique retournée par l'Identity Provider, utilisée lors de la synchronisation SAML d'un membre pour trouver le groupe correspondant dans JPlatform.
# Configure SAML plugin to search for this ExtraData during member sync
jcmsplugin.saml.sync.search-group-by-extradata: extra.Group.saml-group-mapping
Cette configuration est possible depuis l'évolution SAML-1 intégrée dans les version 2.2 du module SAML
Lorsque la configuration LDAP est active sur le site, les utlisateurs sont synchronisés avec le LDAP à chaque authentification SAML.
Il peut être utile de désactiver la synchronisation LDAP à l'authentication pour améliorer les performances, si l'utilisation du LDAP est activé et déjà synchronisé périodiquement.
Cette configuration peut s'effectuer depuis l'interface d'édition des propriétés du module.
La propriété correspondante est la suivante :
jcmsplugin.saml.sync-with-ldap: false
Cette configuration est possible depuis l'évolution SAML-8 intégrée dans les version 1.1 du module SAML
Il est possible de modifier l'algorithme à utiliser avec la propriété suivante qui accepte les valeurs SHA-1
, SHA-256
, SHA-384
, et SHA-512
:
jcmsplugin.saml.sig-algo: SHA-512
Cette configuration est possible depuis l'évolution SAML-24 intégrée dans les version 2.2 du module SAML
Depuis la version 2.2 du module, l'algorithme de signature par défaut a été modifié pour passer de SHA-1
à SHA-256
.
Les points suivants ne sont PAS supportés par le module
Ce binding n'est pas supporté.
Pour plus d'informations à ce sujet, rejoignez
Lorsque la synchronisation des utilisateurs à partir de l'IdP est activée, les limites suivantes s'appliquent :
<logger name="jcmsplugin.SAMLPlugin"> <level value="TRACE" /> </logger>
<logger name="com.jalios.jcmsplugin.saml"> <level value="TRACE" /> </logger>
<logger name="com.jalios.jcms.authentication.rules"> <level value="TRACE" /> </logger>
<logger name="org.opensaml"> <level value="TRACE" /> </logger>
<logger name="com.jalios.jcms.authentication"> <level value="TRACE" /> </logger>