HRSWEB ActiveDirectory How-To

HRSWEB ActiveDirectory How-To Page 1 of 1 Quintessential School Systems HRSWEB ActiveDirectory How-To Quintessential School Systems (QSS), 2011-2012 All Rights Reserved 867 American Street, Second Floor --- San Carlos, CA 94070 --- Voice 650/598-9500 --- Fax 650/372-3386 --- www.qss.com Published: September 2011 Revised: June 2012

HRSWEB ActiveDirectory How-To Page 2 of 2 Table of Contents Table of Contents... 2 Copyright Notice... 3 HRSWEB ActiveDirectory How-To... 4 Introduction... 4 HRSWEB GUI-based Configuration... 5 Logging in to HRSWEB with AD Credentials... 10 Manual Domain Logins... 10 Automatic Single Sign-On Logins... 11 SSO Configuration... 12 Domain Name Server (DNS) Requirements... 12 Domain Controller Configuration... 12 HRSWEB Application Server Configuration... 13 Web Browser Configuration... 14 Troubleshooting ActiveDirectory Functionality... 16 Domain Login (DL)... 16 Single Sign-On (SSO)... 17

HRSWEB ActiveDirectory How-To Page 3 of 3 Copyright Notice Copyright Quintessential School Systems, 2011-2012 This document contains proprietary information which is protected by copyright. All rights are reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system or translated into any language or computer language, in any form or by any means, electronic, mechanical, optical, chemical, manual or otherwise without the prior written approval of Quintessential School Systems (QSS). The information contained in this document is subject to change without notice. QUINTESSENTIAL SCHOOL SYSTEMS MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Quintessential School Systems shall not be liable for errors contained herein or resulting from the use of this material. QSS/OASIS, STUDENT/3000, and SCHOOL/3000 are registered trademarks of Quintessential School Systems. The samples of reports, windows, and dialog boxes in this document are provided to illustrate the operation of the software at a typical site. All names and addresses are fictitious. The actual windows, dialog boxes, and reports at your site may vary from the samples in this documentation.

HRSWEB ActiveDirectory How-To Page 4 of 4 HRSWEB ActiveDirectory How-To last updated 06/18/2012 for HRSWEB Core v0.991 and greater Introduction There are two aspects to HRSWEB ActiveDirectory (AD) support: Domain Login (DL) -- allows a user to manually enter their AD username/password credentials on an HRSWEB login screen and then be logged in to an associated HRSWEB user. Single Sign-On (SSO) -- provides an automatic login link on the HRSWEB home page which automatically passes the user s AD credentials (assuming the user has already logged in to Windows with these AD credentials) to the HRSWEB backend to log the user in to an associated HRSWEB user. DL and SSO may be enabled or disabled for all QCC and/or Staff users on an independent, perdistrict basis (the installation default is for DL and SSO to be disabled). Additionally, for a user to be able to use DL or SSO, the corresponding AuthDomain and AuthSingleSignon rights must also be enabled in one of the user s HRSWEB roles (the installation default for the HRSWEB QCC ADMIN user is have both of these rights enabled). While this documentation refers to Microsoft Windows ActiveDirectory or AD throughout, the domain login functionality is capable of supporting non-microsoft LDAP directory servers. However, the Single Sign-On functionality only supports Microsoft ActiveDirectory.

HRSWEB ActiveDirectory How-To Page 5 of 5 HRSWEB GUI-based Configuration AD support is configured via the Active Directory section of the admin -> Configuration -> Users screen: The AD-related fields on this screen are: Domain login controls whether QCC users or Staff users may use DL if they also have the AuthDomain right. Single sign-on controls whether QCC users or Staff users may use SSO if they also have the AuthSingleSignon right. Domain attribute defines the directory user object attribute name and search filter value used to retrieve the user object from the directory. The attribute name may be any

HRSWEB ActiveDirectory How-To Page 6 of 6 attribute defined for a user object. The attribute value is a string template containing variables that are expanded prior to searching the directory for a user object where the attribute matches the expanded value string. The following variables may be specified in the attribute value string: o For all user name syntaxes: <qss_credential> - the full syntax user name used to bind to the directory o For Windows user name syntaxes, i.e. jdoe@qss.com or QSS\jdoe : <qss_windomain> - the Windows domain (i.e. qss.com or QSS ) <qss_winuser> - the Windows user (i.e. jdoe ) o For LDAP Distinguished Name (DN) syntax, i.e. attr1=val1,attr2=val2, : <attrname> - DN attribute attrname value, i.e. <cn>, <uid>, etc. If multiple attributes of the same name are present in the DN, only the last (rightmost) value will be represented by <attrname>. <qss_dn1> - last (rightmost) DN component attribute value <qss_dn2> - next to last DN component attribute value <qss_dnx> - first (leftmost) DN component attribute value Note that DN syntax tends to repeat attributes in hierarchical order, i.e.: CN=Joe Smith,DC=qss,DC=com For the above example, the variable <CN> would contain the value Joe Smith but the variable <DC> would only contain the last DC attribute value of com. The alternative variables of <qss_dn1>, <qss_dn2>, etc, are provided to reference ordered DN attributes. So you could specify <qss_dn1> and it would contain com, and <qss_dn2> would contain qss. Note that the numbering is from right to left and mirrors the right to left hierarchical order of DN syntax. Some example domain attribute settings depending on user name syntax: User Name Syntax Domain Attribute Name Domain Attribute Value user@domain userprincipalname <qss_credential> domain\user samaccountname <qss_winuser> attr1=val1, distinguishedname <qss_credential> Domain template specifies the template to be used to convert short domain user names (i.e. user ) to fully-qualified names used to authenticate to the configured directory server. This template is ignored for full domain user names of the following syntaxes:

HRSWEB ActiveDirectory How-To Page 7 of 7 o Windows new-style user@domain o Windows old-style domain\user o LDAP DN style CN=user,DC=domain,DC=org (simplistic example) The domain template consists of a fully-qualified domain user string. When used by HRSWEB to expand a short name, all occurrences of the substring <qss_login> will be replaced by the short name. Some example domain templates might look like this: o Windows new-style - <qss_login>@qss.com o Windows old-style QSS\<qss_login> o LDAP DN style CN=<qss_login>,CN=Users,DC=qss,DC=com Domain search base URL specifying a domain controller LDAP directory or Global Catalog container to be used as the subtree search base for validating AD credentials. The following variations are supported: o ldap://hostname/dn (port 389 unencrypted single-domain directory) o ldaps://hostname/dn (port 636 SSL-encrypted single-domain directory) o ldap://hostname:3268/dn (port 3268 unencrypted multi-domain global catalog) o ldaps://hostname:3269/dn (port 3269 SSL-encrypted multi-domain global catalog) Where hostname is the domain controller or directory server hostname and dn is the search base container in Distinguished Name (DN) format, i.e. DC=qss,DC=com etc. Note that SSO setup requires additional manual configuration steps on the domain controller, HRSWEB application server, and end-user browsers. This will be described later in this document. Throughout HRSWEB wherever a domain user can be specified, full credential syntax ( user@domain or domain\user or attr1=val1, ) or short credential syntax ( user ) can be entered. If a short domain user name is entered, the domain template value from the configuration screen above will be used to expand the short name into a full name. Thus based on the example screen above, if jdoe is entered as a domain user, then jdoe@qss.com will be the corresponding expanded full name. The domain search base configuration field determines where in the AD tree that HRSWEB starts a subtree search when authenticating credentials. You can specify LDAP or Global Catalog URLs with or without SSL encryption, plus the distinguished name (DN) of the AD container where the search will start. Typically this will be the DN of the AD domain (i.e. DC=qss,DC=com ). All of these configuration fields are district-specific, so if different districts are using separate AD infrastructure, each district can specify appropriate values here and it will just work assuming the HRSWEB application server has TCP connectivity to the relevant domain controllers.

HRSWEB ActiveDirectory How-To Page 8 of 8 As alluded to above, AD credentials must be associated with corresponding HRSWEB QCC/Staff credentials for this initial release of AD support. If DL/SSO has been enabled for Staff users, there will be optional domain user and domain password fields on the registration screen for new Staff users. If the Staff user wishes to use AD credentials to log on to HRSWEB, the user must fill in the domain user/pass fields. The domain password will be verified at registration time to prove the Staff user controls the AD user but otherwise won t be stored in the HRSWEB database. An example Staff registration screen is shown below: If HRSWEB QCC and Staff users have been granted the right to edit their own user information, and if they have been granted DL/SSO rights, then domain user/pass fields will appear on the user edit screen. The user can then establish an association by specifying the AD credentials. HRSWEB admin users with sufficient rights can edit other QCC/Staff users domain user field without having to specify the domain password. This ensures good security because there will never be any valid reason for an HRSWEB user to have to reveal their AD password to the HRSWEB helpdesk/admin. An example user edit screen is shown below:

HRSWEB ActiveDirectory How-To Page 9 of 9 Currently a single AD credential may only be associated with a single HRSWEB QCC/Staff user in each district. This is by design and avoids the need to have a second login screen to ask which of multiple QCC/Staff users should apply to the current HRSWEB session if you had AD credentials associated with many HRSWEB users. This initial release of AD support requires manual specification of the AD credential to establish an association with an HRSWEB QCC/Staff user because there are no standard AD attributes where QSS customers store the district number and employee number that would be required to establish an automatic association with HRSWEB QCC/Staff users. And where certain QSS customers may be storing the district number and employee number in their AD via custom attributes, it is not being done consistently for all AD users. So there still needs to be a fallback manual method. Future releases of AD support may provide for automatic di_no/emp_no association, but there is currently no scheduled release timeframe for this.

HRSWEB ActiveDirectory How-To Page 10 of 10 Logging in to HRSWEB with AD Credentials Manual Domain Logins When manual domain logins are enabled for a district, the HRSWEB login screen will have an extra User type choice of Domain in addition to the standard QCC, Staff, Guest choices. Specify Domain and then enter your AD credentials with the same user name syntax used when establishing the association with the corresponding HRSWEB user: After clicking the Login button you will be logged in the same as if you had directly used the associated QCC/Staff user credentials instead of AD credentials.

HRSWEB ActiveDirectory How-To Page 11 of 11 Automatic Single Sign-On Logins When automatic single sign-on logins are enabled for a district, the HRSWEB home page login link changes slightly with the addition of two sub-menu items: Clicking login or Automatic will attempt an automatic SSO login using the user s AD credentials that they used to log on to Windows. Clicking Manual will display the traditional HRSWEB manual login screen. If SSO login succeeds by finding an HRSWEB user associated with the AD credentials, the user is logged on to that HRSWEB user. If the SSO login fails for any reason, HRSWEB will attempt to display the manual login screen. Because different web browsers vary in their SSO capabilities, there may be certain circumstances where a browser error message will be displayed instead of the HRSWEB manual login screen. If that happens, the user should manually return to the HRSWEB application home page by either re-entering the URL or clicking on a bookmark.

HRSWEB ActiveDirectory How-To Page 12 of 12 SSO Configuration There is much complexity to how SSO works under the hood, and it is beyond the scope of this document to dive deeply into those details. For a good tutorial on SSO please see http://www.grolmsnet.de/kerbtut/. Domain Name Server (DNS) Requirements SSO requires strict adherence to good DNS practice. SSO WILL NOT WORK unless all of the following conditions are met: The HRSWEB server has a DNS A record matching its Fully-Qualified Domain Name (FQDN) to its IP address. Note that an FQDN consists of a hostname portion and a domain name portion. An example FQDN would be linux-demo.qss.com where linux-demo is the hostname portion and qss.com is the domain name portion. The HRSWEB server has a DNS PTR record matching its IP address to its FQDN. This IP address and FQDN must exactly match the IP and FQDN from the DNS A record. The HRSWEB server linux hostname must exactly match the DNS hostname. Continuing the current example, the linux hostname should be linux-demo. Domain Controller Configuration Perform the following steps for each AD domain that HRSWEB will need to accept credentials for: 1. Create a special SSO user account (not computer account) within the domain. You can name this user account anything you like, but for the purposes of this example we ll use hrsweb_sso. Uncheck the user must change password option and check the password never expires option when creating the user account. Choose any initial password you want; it will be changed in the next step. 2. From the domain controller command-line prompt (i.e. cmd.exe), run the CASE- SENSITIVE ktpass utility to associate a Service Principal Name (SPN) with the user account created above: ktpass ^ -princ HTTP/<HRSWEB server FQDN>@<domain> ^ -mapuser hrsweb_sso@<domain> ^ -pass <a new user password for hrsweb_sso> ^ -ptype KRB5_NT_PRINCIPAL ^ -crypto rc4-hmac-nt ^

HRSWEB ActiveDirectory How-To Page 13 of 13 -out C:\Windows\Temp\<domain>.krb5keytab Where <HRSWEB server FQDN> is the DNS FQDN of the HRSWEB application server and where <domain> is the Windows domain in uppercase, i.e. QSS.COM. 3. Upload the resulting krb5keytab file to the HRSWEB application server machine in the /etc/opt/qss[/<instance>]/hrsweb directory. These are binary files so use a binary-safe file transfer method. HRSWEB Application Server Configuration 1. Log on to the HRSWEB application server as root. 2. cd /etc/opt/qss[/<instance>]/hrsweb 3. If there is only one krb5keytab file for one AD domain, rename it to sso.krb5keytab. Otherwise, combine multiple krb5keytab files into a single sso.krb5keytab file as follows: a. /opt/qss[/<instance>]/hrsweb/rails/bin/ktutil b. For each krb5keytab file do rkt <filename>. c. wkt sso.krb5keytab d. exit 4. chmod 640 sso.krb5keytab 5. chown qssmgr:qss sso.krb5keytab 6. Use krb5.conf.sample as a template to create krb5.conf: [libdefaults] default_realm = QSS.COM default_tkt_enctypes = arcfour-hmac-md5 dns_lookup_kdc = false dns_lookup_realm = false dns_fallback = false permitted_enctypes = arcfour-hmac-md5 [domain_realm] linux01.qss.com = QSS.COM [realms] QSS.COM = {

HRSWEB ActiveDirectory How-To Page 14 of 14 } admin_server = 192.168.192.100 kdc = 192.168.192.100 master_kdc = 192.168.192.100 For each domain modify the [domain_realm] section to map the FQDN of the HRSWEB application server to the Kerberos realm (typically the AD domain in uppercase). For each domain modify the [realms] section to define a realm with the admin_server, kdc, and master_kdc fields all containing the IP address of the appropriate domain controller. Choose any realm to specify as the default_realm in the [libdefaults] section. The default has no effect on HRSWEB but is used if command-line Kerberos utilities must be used for troubleshooting. 7. chmod 640 krb5.conf 8. chown qssmgr:qss krb5.conf 9. Edit proxy_sso.conf to specify the whitespace-delimited list of realms for the KrbAuthRealms directive: KrbAuthRealms QSS.COM 10. Edit common.sysconfig to specify the krb5.conf file: export KRB5_CONFIG=/etc/opt/qss[/<instance>]/hrsweb/krb5.conf 11. Stop then start the HRSWEB applications: /etc/init.d/qss_hrsweb_ctl stop /etc/init.d/qss_hrsweb_ctl start Web Browser Configuration Certain web browsers require configuration before SSO can be used. Note that all web browsers require you to use FQDNs in your URLs when accessing HRSWEB in order for SSO to work. Chrome No additional configuration is required.

HRSWEB ActiveDirectory How-To Page 15 of 15 Firefox 1. Type about:config (without the quotes) in the URL field and press Enter. 2. Click the I ll be careful, I promise! button. 3. Type negotiate (without the quotes) in the Filter field. 4. Double-click network.negotiate-auth.trusted-uris. 5. Enter the URL for the specific HRSWEB application (including the port number) or the entire HRSWEB server (omitting the port number) and click the OK button. Internet Explorer 1. Click Tools, Internet options, Advanced, then scroll to the Security section and check Enable Integrated Windows Authentication. If this was not already checked, exit and restart the browser. 2. Click Tools, Internet options, Security, Local intranet, Sites. Make sure Automatically detect intranet network is checked. Click the Advanced button then add the URL for the HRSWEB application server to the list of local intranet web sites. Click Close, OK, OK.

HRSWEB ActiveDirectory How-To Page 16 of 16 Troubleshooting ActiveDirectory Functionality Domain Login (DL) Check /var/opt/qss[/<instance>]/<app>/production.log to see if any LDAP errors are being logged when the application attempts to lookup the AD credentials. Try switching the AD domain template user syntax between the supported formats of user@domain, domain\user, and attr1=val1,attr2=val2,. Is the domain search base configuration field correct, particularly the AD container DN? Use the linux command-line ldapsearch tool to perform some test AD queries. For example, to look up an AD user and display all of the user s attributes, do the following: /usr/bin/ldapsearch \ -x \ -D "<authuser>" \ -w "<authpass>" \ -H ldap://<adhost> \ -b '<containerdn>' \ -s sub \ '(samaccountname=<searchuser>)' \ '*' where: o <authuser> is the AD user to authenticate as prior to doing the search. Note that this syntax can be user@domain or domain\user for Microsoft AD servers or full distinguishedname (DN) syntax of attr1=val1,attr2=val2, for all directory servers. o <authpass> is the AD user s password required for authentication. o <adhost> is the domain controller hostname o <containerdn> is the DN of the container where the search will start from, i.e. DC=qss,DC=com etc. o <searchuser> is the AD user to search for and the format depends on which search filter attribute you have chosen to search against. LDAP search filter syntax is complicated for details see RFC 4515 (http://www.rfceditor.org/rfc/rfc4515.txt). userprincipalname user@domain

HRSWEB ActiveDirectory How-To Page 17 of 17 Single Sign-On (SSO) samaccountname user (note the domain is not specified) distinguishedname attr1=val1,attr2=val2, The same troubleshooting techniques for domain login also apply. Examine /var/opt/qss[/<instance>]/hrsweb/<app>/access_log to see if AD credentials are displayed in the third field of automatic login attempts. Examine /var/opt/qss[/<instance>]/hrsweb/<app>/error_log for mod_auth_kerb messages. Unfortunately these messages tend to be somewhat cryptic. For greater detail from mod_auth_kerb, edit /opt/qss[/<instance>]/rails/conf/httpd.conf and specify LogLevel debug instead of LogLevel warn, then stop/start Apache. Re-test and then re-examine the error_log. Change the log level back when you are done debugging. Double-check proper DNS configuration and described above. Check browser-side DNS resolution to make sure that 1) the correct hostname is being used and 2) there is no local hosts file overriding DNS resolution with an incorrect non- FQDN hostname. For Internet Explorer and Firefox, verify that the hostname has been added to the list of trusted sites. Packet-trace between browser and domain controller to capture the Kerberos handshake that occurs when SSO login is attempted. Was the Service Principal Name (SPN), i.e. HTTP/<FQDN>@<domain retrieved without error? Edit /opt/qss[/<instance>]/hrsweb/rails/conf/httpd.conf to switch from encrypted https to plain old http, then stop/start Apache. Packet trace or use in-browser debugging tools to capture the http authentication handshake that occurs when SSO login is attempts. Note that problems at this level are already likely reflected in error_log mod_auth_kerb messages. The Kerberos debugging techniques described in http://www.grolmsnet.de/kerbtut/ may be helpful. The referenced Kerberos command-line utilities can be found in /opt/qss[/<instance>]/hrsweb/rails/bin.