TopEase Single Sign On Windows AD

Transcription

1 TopEase Single Sign On Windows AD Version Control: Version Status Datum / Kurzzeichen Begründung 1.0 Final / gon New template and logo Copyright: This document is the property of Business-DNA Solutions GmbH, Switzerland. It is not allowed to copy, distribute or in any other way reproduce this document or parts thereof without written permission of Business-DNA Solutions GmbH. Page 1 / 11

2 Contents TOPEASE SINGLE SIGN ON PREAMBLE CHANGES FROM TOPEASE 6.2.X TO 6.3.X RELEASE BASIC SETUP FIRST CONNECTION TO ACTIVE DIRECTORY SERVER CONFIGURE IMPORT AND SYNCHRONIZATION SOURCES FOR USERS AND GROUPS CONFIGURE WEBEXPLORER SETTINGS REQUIREMENTS FOR BOTH MODULES Web User Internet Explorer (IE) REQUIREMENTS FOR THE NTLM MODULE Window REQUIREMENTS FOR THE KERBEROS MODULE Register the SPN s for your TopEase XChange Server Additional Information s for the Kerberos Module Use your own kr5.ini file SINGLE OR MULTIDOMAIN SINGLE DOMAIN MODE MULIT DOMAIN MODE ADDITIONAL INFORMATIONS ENHANCED LOGGING RESOLVE USERS USING PREWINDOWS2000USER PROPERTY RESOLVE MEMBERSHIPS FLAT CHANGE THE DEFAULT LDAP PORTS MOVING USERS AND GROUPS RENAMING USERS AND GROUPS Page 2 / 11

3 1 Preamble This document contains the procedure for set up Sing Sign On for TopEase XChange with a Microsoft Windows Active Directory. How to set up the access management in a model or to a share is not covered. 2 Changes from TopEase 6.2.x to 6.3.x Release WINS Support for Domain Controller Resolving has been removed Kerberos Module added for SSO with Web Portals 3 Basic Setup Login to the TopEase Administration Client select the tab Login. In the table Modules select ssoserverlogin. 3.1 First connection to Active Directory Server Enter a domain controller a user and a password and select the << Buttons to load the domain details. Page 3 / 11

4 Field Server Port User Password Domain Details Remarks Enter a server or a qualified Domain name, e.g. ch.mycompany.com. You can also enter a comma separated list of servers. If the connection to the first server fails, then a connection to the next server will be tried. If you plan to use Kerberos as web login, you must enter a full qualified name, otherwise Kerberos may not work! The port will be set automatically. If your domain is an Active Directory tree or forrest, then port 3268 will be set, this accesses the global catalog. If your domain is a single on, the port 389 will be set to access the domain. You have to enter a fully qualified user name. See image above. The users domain password. Shows all domains found the domain configuration of the server. 3.2 Configure import and synchronization sources for users and groups For each found domain you can set up from which element the TopEase XChange Administrator later can import and synchronize users and groups. Select a domain in the list Domain Details and click the button on the right side of the text boxes Groups and Users. Select one or more elements which define the base nodes to search for users and groups in Windows Active Direcotry. Do this for every domain where you want to import and synchronize users and groups. If you left a domain empty, the administrator cannot import anything from this domain. 4 Configure WebExplorer settings To enable Windows Active Directory based Single Sign On for the WebExplorer, you have to configure the setting for the WebExplorer pre authentication. The preauthentication is used to perform a NTML or Kerberos Login. Usually the same user entered in the Settings for LDAP Access can be used. Page 4 / 11

5 Field Domain Web-User Web-Password Module Remarks Full qualified Domain name e.g. my.domain.com The user without domain extension The password for the web user Select the Login Module to be used to authenticate the user. Currently they are 2 modules supported: NTLM (does not Support NTLMv2) Kerberos 4.1 Requirements for both Modules To use Web SSO there are some Requirements to your environment Web User You need a Domain user as pre authentication user. This can be simple user, with no additional rights. Your administrator can also deny the user to logon to any workstation. The user should have a long and comple xpassword that never expires Internet Explorer (IE) The IE is setup by default to perform SSO to any capable server in your Intranet! Open the Options Panel and selected the tab Security Select the zone Local Intranet and click on custom level. The entry User Authentication -> Logon should be setup as Automatic logon only in Intranet zone or Automatic logon with current user name and password. As mentioned before, this is a default setting. Page 5 / 11

6 Your web server must be recognized as Intranet server. To check this, open a web page on your web server and check the status bar. If the Zone Local Intranet is not displayed, then you have to add it to your sites list. 4.2 Requirements for the NTLM Module The NTLM Module does not work if client and/or domain controllers are configured to work only with NTLMv2. In this case you will get a Dialog to enter username and password instead to log in without to enter your credentials. The LmCompatibiltyLevel must be set to 0 2, otherwise NTLM login will not work. See: If your company uses NTLMv2 you can use the Kerberos login module Window 7 The standard value for a Windows 7 Client, after installation, is set higher as 2 by default. If SSO with NTLM works for Windows-2000 and Vista clients but not on Windows 7, then you have to change this registry entry and restart the workstation. 4.3 Requirements for the Kerberos Module The Kerberos Module does not depend on the configured NTLM version; it works also if NTLM is disabled. If you want to work with Kerberos you have to do some extra configurations. The Kerberos does not perform a login when you open the browser on the server. You can login, but it s not a Kerberos login. The user which is used to run the XChange Server will be took as logged in user Register the SPN s for your TopEase XChange Server Following the Kerberos specification, every pre authentication user for a specific service (in our case HTTP), has to registered. This is done with setspn.exe command. See for detailed information s and how to get the setspn.exe if it is not installed on your server. You have to register your service with any DNS name of your server (including aliases) with your web-user (see Chapter 4 Configure WebExplorer settings ). Example: Your server name is server1 and is member of the domain pul.test. The configured user is called userm. For your server there is a DNS alias named topease. In this case you have to register 3 SPN s (SPN = Service Principal Name). Page 6 / 11

7 The last command lists all SPN s for a specific user, you can use to check if the SPN s are registered. After registering your SPN s you must restart the windows server! Important: The service name HTTP must be written upper case, do not type http! You cannot register multiple users for the same service, but a user can be the service principal for multiple services Additional Information s for the Kerberos Module Do not change any configurations described here if you re not familiarly with Kerberos and the Java Kerberos Implementation! Kerberos will be configured with the configured server as KDC, the domain as default realm (they will be added as system properties). Enter a full qualified server name, like yourserver.domain.net in the server text field of the configuration, otherwise Kerberos may not work! The kerb5.conf file is located in the server installation directory, which contains all other configurations Use your own kr5.ini file If you want to use a specific KDC or do other changes to the configuration you can add the entries to the section # Java Additional Parameters in TopEase XChange.conf (located in the installation directory) Entry wrapper.java.additional.kk=-djava.security.krb5.conf =<YourKrb5Conf> wrapper.java.additional.kk=-dtopease.web.sso.use.krb5.conf=true Remarks Default is krb5.conf Default is false Page 7 / 11

8 Replace kk so that the list of entries wrapper.java.additional.kk is a non interrupted list. The first entry defines the location to your krb5 configuration file. With the second entry the default realm and the KDC will not be set as system property. 5 Single or Multidomain Depending on the configuration settings of your Active Directory TopEase Administrator Client runs in Single or Multi Domain mode. The two modes differ in resolving memberships to groups. 5.1 Single Domain Mode In Single Domain Mode the memberships of the user are fully accessible without limitation on group types. This is because TopEase XChange reads directs from the domain controller. 5.2 Mulit Domain Mode In Multi Domain Mode there are limitations on loading, synchronization and resolving user memberships. In Multi Domain Mode TopEase XChange accesses the Global Catalog (GC) of Microsoft Windows Active Directory. The Global Catalog contains a reduced set of user and group information s, but these information s are replicated to all Domain Controllers which runs the Global Catalog Service. For TopEase XChange this will end in current limitations: User and group description are not synchronized Only distribution groups are accessible. Local domain and security groups will not be shared in the Global Catalog. So you have to set up the group memberships with distribution groups. The configured servers must run the global catalog service. You have to enter only Global Catalog servers in the Server Textfield in Settings for LDAP Access Section 6 Additional Informations 6.1 Enhanced logging If you need deeper informations about the login process, you can set up to properties to extend the logged informations. This configuration has to be done in the file <TopEase XChange InstallDir>/ TopEase XChange.conf. Add the entries to the section # Java Additional Parameters in TopEase XChange.conf Entry wrapper.java.additional.kk=-daccess.manager.trace=true wrapper.java.additional.kk =-Dnt.server.module.trace.time=true Remarks Produces detail information s of the user login. Like memberships and more details This logs the time used for perform a login with Windows AD. Replace kk so that the list of entries wrapper.java.additional.kk is a non interrupted list. Page 8 / 11

9 These two entries produce a lot of information in your Log File. Please do not run your TopEase XChange by default with these entries set. Your Log File will be grow really fast. Use these entries only for troubleshooting purpose. 6.2 Resolve users using prewindows2000user property If your login with Windows AD does not work proper, e.g. you can login using the designer but not using TopEase WebExplorer or Server Jobs ends with a error message. Then check user entry of the user who s login fails on your windows server. If in your domain the User logon name and User logon name (pre-windows 2000) are different, then you have to set the prewindows2000user property. If you set this property and your domain forest contains multiples users with the same user logon name, then the login for these users runs slower. This is caused while TopEase XChange cannot resolve the user using user@domain.com which is unique inside a forest. The user logon name is only unique inside each single domain of a forest. So it s also not a good practice to work with the built in Windows AD user administrator! To turn on this property open the files pam.xml and psm.xml inside your TopEase XChange installation directory, and search for these entry on each file, <Property name="useprewindows2000user">false</property> change the these entries to <Property name="useprewindows2000user">true</property> save the changed files and restart the TopEase XChange Service. 6.3 Resolve memberships flat By default the TopEase AccessManager resolves all memberships of a User. If the User is Member of Group A and Group A is member of Group B, the user will be Member of Group A and B. If you don t use the resolved Memberships you can prevent it setting an entry into the psm.xml file (this file is located in the installation directory of TopEase XChange). This may speed up your login time. Page 9 / 11

10 Enter the property with name resolvegroupsflat and set the value to true. If this property is not set or the value is false, then the TopEase AccessManager resolves also memberships of Groups. If this property is set to true, then only direct memberships of User will be used. Based on the exampla above: If the property resolvegroupsflat is set to true and the User is Member of Group A and Group A is member of Group B, the User will be only Member of Group A. 6.4 Change the default LDAP Ports If your administrator has changed the TCP/IP Ports to access Windows Active Directory and Global Catalog you can set up your server to access the servers by your specific port. This configuration has to be done in the file <TopEase XChange InstallDir>/ TopEase XChange.conf. Add the entries to the section # Java Additional Parameters in TopEase XChange.conf Entry Remarks wrapper.java.additional.kk=-dwindows.ldap.port=nnn Default is 389. wrapper.java.additional.kk =-Dwindows.ldap.gc.port=nn Default is 3268 Replace kk so that the list of entries wrapper.java.additional.kk is a non interrupted list and replace nn with your configured ports. Restart the TopEase XChange and login to TopEase Administration Client, go to the ssoserverlogin configuration and click on the << Button on the right side of the Domain Details table. 6.5 Moving users and groups You can move users and groups within the Active Directory as you want. After moving you can synchronize the users and groups and the data will be updated. Page 10 / 11

11 6.6 Renaming users and groups You can also rename your users and groups as you like and then synchronize it with the TopEase Administrator Client. But if you rename a group or a user and the new names is already occupied by another user or group the synchronization is not possible. In TopEase XChange a user or group name must be unique. Page 11 / 11