Authentification unique (single sign-on) dans JMap Pro / SSO (single sign-on) in JMap Pro

Produit concerné / Related product	JMap Admin	Versions	4.0, 5.0, 6.0, 7.0

Jump to English version

Un nouveau gestionnaire d'utilisateurs a été intégré dans le correctif D JMap 4.0.2 : Active Directory.

Quoiqu'il était déjà possible de se connecter à Active Directory avec le gestionnaire d'utilisateurs LDAP, ce nouveau gestionnaire d'utilisateurs permet en plus d'activer l'authentification unique dans les applications JMap Pro déployées sur le réseau intranet. Par conséquent, l'ouverture d'une application JMap Pro bien configurée ne requiert plus d'authentification, puisque l'authentification se fait par le système en utilisant le compte Windows courant via le mécanisme Kerberos *.

La configuration de l'authentification unique (SSO) dans JMap demande une série d'étapes essentielles pour son bon fonctionnement :

Configuration d'un Service Principal Name (SPN) et de son authentification Kerberos dans Active Directory.
Configuration du gestionnaire d'utilisateurs dans JMap Admin.
Définition des permissions des utilisateurs dans les projets.
Déploiement d'une application pour laquelle SSO est activé.
Modification de la base de registres des clients potentiels.
Ouverture de l'application avec SSO.

Guide étape par étape

1. Configuration d'un Service Principal Name (SPN) et de son authentification Kerberos dans Active Directory.

Important : correspondance SPN / Gestionnaire AD

Dans JMap Pro, la cible Kerberos (SPN) est construite à partir de Domain + Adresse du serveur du Gestionnaire d’utilisateurs Active Directory configuré dans JMap Admin.
En conséquence, l’SPN à créer dans Active Directory doit être exactement :

jmap_spn/<valeur du champ “Adresse du serveur” dans JMap Admin>

Recommandé : utiliser un FQDN (ex. dc-01.example.local), éviter les IP et les noms courts.
Le service class attendu par JMap est jmap_spn

1.1. Dans Active Directory, créez un nouvel utilisateur et faites en sorte que son mot de passe n'expire jamais. (ex. svc_jmap).

1.2. Activer AES128 et AES256 sur le compte.

1.3. Dans une fenêtre d'invite de commandes, exécutez :

setspn -S jmap_spn/[FQDN à saisi dans "Adresse du serveur"] [Compte de service à utiliser par JMap]

# Exemple
# Compte de service à utiliser par JMap (ex. svc_jmap)
# FQDN à saisi dans "Adresse du serveur" (ex. dc-01.example.local)
setspn -S jmap_spn/dc-01.example.local svc_jmap

# Vérifier
setspn -L svc_jmap

# Détecter des doublons éventuels
setspn -X

Si vous avez saisi un nom court dans “Adresse du serveur” (ex. dc-01), l’SPN devra être jmap_spn/dc-01 , cela peut fonctionner, mais le FQDN est préférentiel.

1.4. Nettoyage des SPN obsolètes (recommandé). Supprimez les SPN non conformes (IP, noms courts non utilisés, anciens, hôtes de serveurs JMap au lieu du DC/LDAP).

# Exemple
setspn -D jmap_spn/10.0.0.36 svc_jmap
setspn -D JMap/dc-01.example.local svc_jmap

Un SPN doit être unique et pointer vers le même host que “Adresse du serveur” dans JMap Admin.

Note pour les sections 1.5. et 1.6.
Les étapes avec ktpass (et les chiffrements DES/RC4) étaient destinées à de très anciens environnements ou à des services non-Windows qui exigent un keytab.
Pour JMap Pro (SSO Kerberos), n’utilisez pas ktpass : contentez-vous d’enregistrer l’SPN via setspn et d’activer AES128/AES256 sur le compte de service.

1.5. Dans une fenêtre d'invite de commandes, exécutez :

ktpass -princ service/server.domain.com@DOMAIN.COM -ptype KRB5_NT_PRINCIPAL -crypto All -mapuser "server"

où "service/server.domain.com@DOMAIN.COM" est le nom du SPN créé et où "server" est le nom de l'utilisateur créé dans Active Directory.

1.6. Dans un environnement Windows Server 2003, il est toutefois nécessaire de spécifier un type d'encryption, puisque la valeur "All" n'est pas supportée. Dans cet environnement, des tests concluants ont été effectués avec le type "DES-CBC-CRC".

Exemple :

ktpass -princ jmap_spn/osiriswinsrvr2@OSIRISLAB.NET -ptype KRB5_NT_PRINCIPAL -crypto All -mapuser jmap

Targeting domain controller: OSIRISWINSRVR2.osirislab.net

Using legacy password setting method

Successfully mapped jmap_spn/osiriswinsrvr2 to jmap.

2. Configuration du gestionnaire d'utilisateurs dans JMap Admin.

2.1. Dans JMap Admin -> Utilisateurs/Groupes -> Gestionnaire, sélectionner "Gestionnaire d'utilisateurs Active Directory", configurez :

Adresse du serveur : saisir le FQDN du DC/LDAP (ex. ldap://dc-01.example.local ou ldaps://dc-01.example.local). Cette valeur est réutilisée pour le SSO : elle devient la partie “host” du SPN demandé par le client JMap Pro.

DN : le Distinguished Name de la configuration à utiliser dans LDAP (ex. dc=osirislab,dc=net).

Domaine : indiquer le REALM en MAJUSCULES (ex. EXAMPLE.LOCAL). C’est la partie @REALM de la cible Kerberos.

utilisateur / SPN : le nom de l'utilisateur créé dans Active Directory pour lequel un SPN a été créé (ex. svc_jmap).

Mot de passe : le mot de passe de cet utilisateur.

et s'assurez-vous que la case à cocher Activer l'authentification unique est bien cochée.

2.2. Avant de sauvegarder cette configuration, assurez-vous que les deux ports utilisés pour communiquer avec le contrôleur de domaine et le service Kerberos sont ouverts. Par défaut, ces ports sont 389 (TCP) et 88 (TCP/UDP).

3. Définition des permissions des utilisateurs dans JMapAdmin et dans les projets.

3.1. Assurez vous qu'au moins un utilisateur pour lequel le mot de passe est connu est configuré comme administrateur de JMap Server.

3.2. Donnez la permission d'ouverture de projet à des utilisateurs créés dans Active Directory.

4. Déploiement d'une application pour laquelle SSO est activé.

4.1. Assurez vous que l'application sera utilisée sur le réseau intranet seulement. Une communication avec le contrôleur de domaine doit être possible. L'authentification unique ne fonctionne que pour les applications de type "applet" et "Java Web Start".

4.2. Lors du déploiement, cochez les cases Accès contrôlé et Activer l'authentification unique.

Pour la validation SSO du client, le nom du service basé sur l'hôte est généré en fonction de la configuration du gestionnaire d’utilisateur et requiert le format service/host.domain.com@REALM. Par contre, la configuration SSL pourrait forcer un format non compatible. Le cas survenant, l’argument jmapspn peut être ajouté au fichier launcher.properties de l’application client et permet d’utiliser directement sa valeur. (Se référer à la section 1, la valeur utilisée est aussi affichée dans les logs du client.)

Ex: arguments=[…] -enablesso true -jmapspn jmap_spn/myserver@mydomain.com

5. Modification de la base de registres des clients potentiels.

Cette étape n’est plus requise depuis la version JMap Lima HF4. L’utilisation de GSS-API ne requiert plus de modifications à la base de registre.

Par défaut, Windows ne permet pas aux applications d'obtenir le ticket Kerberos (TGT) enregistré dans le système. Dans le client JMap, il est nécessaire d'obtenir celui-ci pour valider l'authenticité de la session Windows en cours avec le serveur Kerberos (Active Directory), et pour éviter de refaire l'authentification dans le client JMap. Pour contourner cette limitation, il est nécessaire d'ajouter une valeur de type DWORD nommée allowtgtsessionkey dans la base de registres de chacun des postes, et de lui assigner la valeur 1.

Cette valeur doit être ajoutée à l'endroit suivant :

^{Windows XP}
^{HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\}

^{Autres Windows}
^{HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters}

6. Ouverture de l'application avec SSO.

Une fois la configuration terminée, l'ouverture de l'application déployée ne devrait pas afficher d'authentification. Si une boite d'authentification est affichée :

6.1. Validez que l'ordinateur du client est enregistré sur le domaine configuré dans JMap Admin et qu'une session Windows sur ce domaine a été initiée.

6.2. Validez que l'utilisateur a les permissions d'ouverture du projet en question.

6.3. Validez la configuration du gestionnaire d'utilisateurs Active Directory dans JMapAdmin.

6.4. Validez qu'il n'y a pas un grand écart entre l'heure affichée sur les postes clients et celle des serveurs.

6.5. Validez la configuration de l'utilisateur et du SPN dans Active Directory.

6.6. Consultez le support technique de JMap.

Légende :
* Le transfert du ticket Kerberos (TGT) entre le client JMap et JMap Server se fait de façon sécurisée.

English version

A new User Manager has been integrated into the patch D JMap 4.0.2 : Active Directory.

Although it was possible to connect to Active Directory with LDAP User Manager, this new User Manager allows to active the unique authentication in applications JMap Pro deployed on the intranet. Therefore, the opening of a well configured JMap Pro application do not requires authentication, since authentication is done by the system using the current Windows account via Kerberos* mechanism.

Configuring single authentication (SSO) in JMap request a series of essential steps for proper operation:

Configuring a Service Principal Name (SPN) and its Kerberos authentication in Active Directory
Configuring the User Manager in JMap Admin.
Definition of user permissions on the projects.
Deploying an application for which SSO is enabled.
Changing the registry database of potential customers.
Opening the application with SSO.

Step-by-step guide

1. Configuring a Service Principal Name (SPN) and its Kerberos authentication in Active Directory.

Important: SPN / AD User Manager alignment

In JMap Pro, the Kerberos target (SPN) is built from the Domain and Server address fields of the Active Directory User Manager configured in JMap Admin.
Therefore, the SPN you create in Active Directory must be exactly:

jmap_spn/<value of the “Server address” field in JMap Admin>

Recommended: use a FQDN (e.g., dc-01.example.local), avoid IPs and short hostnames.
The expected service class for JMap is jmap_spn.

1.1. In Active Directory, create a new user and ensure that the password never expires. (e.g., svc_jmap).

1.2. Unable AES128 and AES256 for the service account.

1.3. In a Command Prompt window, execute:

setspn -S jmap_spn/[FQDN à saisi dans "Adresse du serveur"] [Compte de service à utiliser par JMap]

# Example
# Service account to be use by JMap (ex. svc_jmap)
# FQDN to use in "Server adress" (ex. dc-01.example.local)
setspn -S jmap_spn/dc-01.example.local svc_jmap

# Verify
setspn -L svc_jmap

# Detect potential duplicates
setspn -X

If you entered a short hostname in “Server address” (e.g., dc-01), the SPN must be jmap_spn/dc-01, this can work, but FQDN is preferred.

1.4. Cleanup of obsolete SPNs (recommended). Remove non-compliant SPNs (IPs, unused short names, legacy entries, etc.

# Example
setspn -D jmap_spn/10.0.0.36 svc_jmap
setspn -D JMap/dc-01.example.local svc_jmap

An SPN must be unique and must point to the same host as “Server address” in JMap Admin.

Note for 1.5. and 1.6. sections
The ktpass steps (and legacy DES/RC4 ciphers) were for very old environments or non-Windows services that demand a keytab.
For JMap Pro (Kerberos SSO), do not use ktpass, just register the SPN with setspn and enable AES128/AES256 on the service account.

1.5. In a Command Prompt window, execute:

ktpass -princ service/server.domain.com@DOMAIN.COM -ptype KRB5_NT_PRINCIPAL -crypto All -mapuser "server"

which "service/server.domain.com@DOMAIN.COM" is the SPN name created and "server" is the user name created in Active Directory.

1.6. In a Windows Server 2003 environment, however, it is necessary to specify an encryption type, since the value "All" is not supported. In this environment, conclusive tests were performed with the "DES-CBC-CRC" type.

Ex:

ktpass -princ jmap_spn/osiriswinsrvr2@OSIRISLAB.NET -ptype KRB5_NT_PRINCIPAL -crypto All -mapuser jmap

Targeting domain controller: OSIRISWINSRVR2.osirislab.net

Using legacy password setting method

Successfully mapped jmap_spn/osiriswinsrvr2 to jmap.

Reference on Microsoft Service Principal Names: http://social.technet.microsoft.com/wik ... s/717.aspx

2. Configuring the User Manager in JMap Admin

2.1. In JMap Admin -> Utilisateurs / Groupes -> Gestionnaire, sélectionner "Gestionnaire d'utilisateurs Active Directory", configure:

Server address : enter the FQDN of the DC/LDAP (e.g., ldap://dc-01.example.local or ldaps://dc-01.example.local). This value is reused by SSO: it becomes the host part of the SPN requested by the JMap Pro client.

DN : the Distinguished Name of the configuration to use in LDAP (Ex. : dc=osirislab,dc=net).

Domain : enter the REALM in UPPERCASE (e.g., EXAMPLE.LOCAL). This is the @REALM part of the Kerberos target.

user / SPN : user's name created in Active Directory for which a SPN was created (e.g., svc_jmap).

Password : user's password.

and ensure that the checkbox Enable SSO is checked.

2.2. Before you save this configuration, make sure that the two ports used to communicate with the domain controller and the Kerberos service are open. By default, these ports are 389 (TCP) and 88 (TCP / UDP).

3. Definition of user permissions in JMap Admin and projects.

3.1. Ensure that at least one user for which the password is known is configured as JMap Server administrator.

3.2. Give the opening project permission to users created in Active Directory.

4. Deploying an application for which SSO is enabled.

4.1. Ensure that the application will be used on the intranet only. Communication with the domain controller should be possible. SSO only works for applications "applet" type and "Java Web Start".

4.2. During deployment, check the boxes Controlled Access and Enable SSO.

For the SSO client authentication, the host-based service name is generated from the JMap UserManager’s domain and server address values. The SSL configuration might make these values incompatible for the format service/host.domain.com@REALM, in which case an argument jmapspn can be added to the launcher.properties file of the deployment and will allow to specify a specific value. Refer to section 1 of this document. In all cases the current value is visible in the client logs.

Ex: arguments=[…] -enablesso true -jmapspn jmap_spn/myserver@mydomain.com

5. Changing the registry database of potential customers.

This step is not required for JMap Lima HF4 and up. Newer JMap versions use GSS-API which does not require any registry modification.

By default, Windows does not allow applications to obtain the Kerberos ticket (TGT) registered in the system. In JMap client, it is necessary to get it to validate the authenticity of the Windows session with the Kerberos (Active Directory) server, and to avoid repeating the authentication in the JMap client. To overcome this limitation, it is necessary to add a DWORD value named allowtgtsessionkey in the registry database of each item, and assign the value 1.

This value must be added to the following location:

^{Windows XP}
^{HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\}

^{Autres Windows}
^{HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters}

6. Opening the application with SSO.

Once the setup is complete, the opening of the deployed application should not display the authentication. If an authentication box is displayed:

6.1. Validate that the client computer is logged to the configured domain in JMap Admin and a Windows session on this area has been initiated.

6.2. Validate that the user has permission to open the project.

6.3. Validate the configuration of Active Directory User Manager in JMap Admin.

6.4. Confirm that there is no significant difference between the time displayed on the clients and the servers.

6.5. Validate the user and the SPN configuration in Active Directory.

6.6. Consult the technical support of JMap.

Legend:
* The Kerberos ticket (TGT) transfer between the JMap client and JMap JMap Server is made safely.