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
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 :
Merci pour cette documentation ! Du bon jalios
Merci Olivier. Je mets en place ce module chez un client en mode POC et te fait un retour.
Bonjour, nous avons une question : est ce que le module supporte du multi IDP ?
Bonjour. Non, le module n'a pas été spécifié ni testé pour supporter plusieurs IdP.
REX pour les IdP (tels de ADFS) qui utilisent un niveau de chiffrement élevé : Longueur de clé de cryptage trop importante lors de l'authentification SAML
Voici une réponse du support :
Il faut que l'expiration de l'authentification configurée dans l'IdP soit la même dans le SP (JPlatform).
Donc :
soit vous modifiez le SP (JPlatform) pour utiliser une valeur de jcmsplugin.saml.websso-profile.max-auth-age
...max-auth-age
similaire à celle de l'IdPsoit vous modifiez l'IdP pour utiliser expirer l'authentification de la même façon que ce que vous avez indiqué dans le SP (JPlatform)
Pourquoi aucune note sur ce paramétrage possible dans la doc ?
Bonjour Cyrille Arzoumanian,
merci Olivier Jaquemet . Effectivement on pense pas à tout toujours :) .
J'ai juste tournée en rond pendant un certain temps ? on teste et on revient vers vous.
Belle journée
Bonjour pour info le lien fourni en exemple pour récupérer les métadata d'ADFS, chapitre 5.3, (https://adfs.example.local/FederationMetadata/2007-06/FederationMetadata.xml) n'est plus valide.
Bonjour, il s'agit d'un exemple de lien pour la forme de l'URL, le domaine "example.local" n'existant pas, je viens de retirer la possibilité de cliquer dessus.
Bonjour,
Nous avons un message d'erreur sur notre serveur ADFS 3 lorsque nous tentons de charger le fichier de sp-Metadata.xml : "Some of the content in the federation metadata was skipped because it is not supported by AD FS. Review the properties of the trust carefully before you save the trust to the ADFS configuration database."
Le fichier généré par JCMS est il normalement compatible avec ADFS 3 ?
Bonjour,
Actuellement en version 2.1 du module nous sommes interessés par l'évolution en 2.2 pour la récupération du fichier de méta-données via une URL plutôt que de copier celui-ci à la main à chaque mise à jour des certificats de notre IdP.
Par contre, la documentation ne précise pas si, lorsque le chemin est une URL, le SP Jalios mets à jour régulièrement (quotidiennement?) les informations (notamment certificats de signature) ou s'il faut éditer les propriétés du module pour "forcer" leur mise à jour.
Merci d'avance pour votre retour
Bonjour Olivier RAGOT ,
Je vous confirme que lorsque vous configurez le module SAML 2.2 pour référencer les méta-données via une URL, un rechargement automatique aura lieu.
La fréquence de rechargement est calculée automatiquement à partir des informations
validUntil
oucacheDuration
si elles sont présentes dans les méta-données (1). Autrement un réglage par défaut s'applique (2).Vous pouvez modifier le niveau de log (dans le fichier de configuration
log4j.xml
) pour provoquer l'affichage des dates de rechargement dans les logs de l'application :Vous aurez alors des message de ce type :
(1) cf section 2.3.1 de spécifications des méta-données SAML
(2) cf javadoc de la classe AbstractReloadingMetadataProvider de la librairie OpenSAML2 pour une description complète de l'algo utilisé pour déterminer la fréquence de rechargement
Merci pour ce retour Olivier Jaquemet .
Bonne journée
Bonjour, est ce que le plugin permet l'accès aux metadatas distantes (jcmsplugin.saml.IDPSSO.metadata.path) en passant par un proxy?
Bonjour Patrice Maziero ,
Oui. Si votre proxy de sortie est renseigné dans les propriétés du site, ce proxy sera utilisé pour la récupération des métadonnées SAML distantes.
Le paramétrage du proxy de sortie positionne les propriétés suivante :
(Notez que ces propriétés JPlatform sont automatiquement propagée en tant que propriétés système Java pour être utilisé par toutes les APIs de requête d'accès distant)
Ça fonctionne, merci!
Autre point, j'essaye de synchroniser les groupes avec ceux de l'idp.
Je reçoit de l'idp le groupe "900" dans l'attribut "roles" :
j'ai tenté la conf suivante (custom.prop) sans succès :
Le groupe "900" existe déjà dans JPlatform mais à la connexion le nouveau Member créé n'a pas de groupe associé, pourtant l'idp transmet bien "roles"="900"
Patrice Maziero l'exemple dans la documentation contenait une erreur, que vous avez très logiquement repris...
Vous avez positionné la propriété
jcmsplugin.saml.saml.sync.search-group-by-name: fr
il s'agit en fait de
jcmsplugin.saml.sync.search-group-by-name: fr
(je viens de corriger la documentation...)
Bonjour Patrice Maziero ,
Est-il possible de configurer la synchronisation des groupes avec plusieurs attributs du compte ?
JPlatform trouve et assigne au compte le groupe correspondant à la valeur de chaque attribut configuré.