1. business by integration Page 1 of 9 SINGLE SIGN-ON FOR APEX APPLICATIONS USING KERBEROS Author: Niels de Bruijn Version: 4.02 Date: 4-DEC-2014 2. business by integration Page 2 of 9 1 INTRODUCTION When using Oracle REST Data Services, you use the URL /apex/f?p=xxx to get to an APEX application where you normally have to authenticate yourself using username/password credentials. However, most end users of APEX applications have already authenticated themselves by logging on to the Windows domain, so why authenticate a second time to use the first APEX application? Wouldn’t it be nice if you could point your browser to an APEX app and you are instantly authenticated? A secure method to achieve this is to use the Kerberos protocol, which is the same protocol that Windows uses for authentication. In this document we will describe how to install and setup the Apache module mod_auth_kerb in a Linux environment that performs the authentication against a Windows domain controller. In this case, the APEX URL (/apex) will be protected, but you can protect any other web application with this approach that lies behind the Apache web server. Image 1: APEX architecture with Apache and Oracle REST Data Services. In this document we assume that you have setup a Windows domain controller with Active Directory (Windows Server 2003/2008) and you have Windows based client-PCs where you have to authenticate against the Windows domain. Also, make sure you have successfully installed and configured the Oracle Database with Oracle Application Express 4.2.x and Oracle REST Data Services 2.0.x. Remarks: 3. business by integration Page 3 of 9 - It doesn’t matter which operating system you use for Apache. Also, the server doesn’t have to be part of the Windows domain. If you are on Windows Server 2012, you might want to use Web Application Proxy instead of Apache, which has Kerberos authentication built in. - Use a firewall to restrict the communication with the server through port 443 (HTTPS). - For Linux/Unix environments, you can use Samba 4 as Domain Controller. - If you are interested to learn about other ways to get SSO in place, have a look at the following blog posting: http://wphilltech.com/options-for-windows-native-authentication-with- apex 2 CONFIGURATION OF THE WINDOWS DOMAIN CONTROLLER 2.1 ADD AN ENTRY IN DNS FOR APACHE First add the fully qualified domain name (FQDN) as additional hostname (not as alias) in your internal DNS server. In our example, we entered apex.mt-ag.com. You can verify this by executing nslookup apex.mt-ag.com. Remark: if the FQDN was registered as alias, the end user needs to authenticate himself through the Basic Authentication protocol and is requested to enter his username/password combination. 2.2 CREATE A SERVICE USER IN ACTIVE DIRECTORY Add a computer account, like APEX_SSO in Active Directory. Use this account to create a keytab file with which Apache may verify if users are authenticated: ktpass -princ HTTP/
[email protected] -mapuser "CN=APEX_SSO,CN=Computers,DC=mt-ag,DC=com" -crypto All -ptype KRB5_NT_SRV_HST -pass -out c:http_apex.mt-ag.com.keytab Remarks: 4. business by integration Page 4 of 9 - Although it is possible to use a user account, we recommend the usage of a computer account, since with this account type it is not possible to logon on a client pc that is registered in a windows domain. - Our domain in this example is called MT-AG.COM and the web address we use to access APEX through Apache is https://apex.mt-ag.com. - Run the command as administrator in a command prompt on the domain controller. - The password can be whatever you like it to be. - The address apex.mt-ag.com behind HTTP/ ist the web address entered in the browser by end users. - Although we access APEX by using HTTPS, you still need to specify HTTP behind –princ. - The filename of the keytab-file can be chosen freely. - Windows 2003 Server is not aware of the option –crypto all, so use -crypto RC4- HMAC-NT instead. Copy over the keytab file to the Linux server where you want to install Apache. In our example, this is the directory /opt/httpkeytab. 3 CONFIGURATION OF TOMCAT 7 After installation of Tomcat 7, make sure you add the following attributes in the file server.xml (printed in bold): Remark: failure to do so may lead to a „Page not found“ message in the browser upon accessing a protected URL or special characters could be displayed wrongly on the page if these are part of the URL. 5. business by integration Page 5 of 9 4 CONFIGURATION OF THE APACHE SERVER 4.1 INSTALL NTP The time on the Apache server should be kept in sync with the domain controller. You can achieve this by installing the NTP service: yum install ntp Make sure that it starts automatically upon server reboot: chkconfig ntpd on 4.2 INSTALL APACHE WITH MOD_AUTH_KERB By installing the module mod_auth_kerb, Apache will be installed as well: yum install mod_auth_kerb Make sure that Apache starts upon server reboot: chkconfig httpd on This document does not describe how to configure Apache so it can be accessed through Port 443 using a valid SSL server certificate. If you need this, you can find this on the internet. In our example, we assume that you have done this, but it is not required to get Single Sign-On to work. 4.3 CONFIGURE KERBEROS ON THE APACHE SERVER Edit the file /etc/krb5.conf: [logging] Default = FILE:/var/log/krb5libs.log Kdc = FILE:/var/log/krb5kdc.log admin_server = FILE:/var/log/kadmind.log [libdefaults] default_realm = MT-AG.COM dns_lookup_realm = false dns_lookup_kdc = false ticket_lifetime = 24h renew_lifetime = 7d forwardable = true default_tkt_enctypes = rc4-hmac default_tgs_enctypes = rc4-hmac 6. business by integration Page 6 of 9 [realms] MT-AG.COM = { kdc = mt-ag.com admin_server = MT-AG.COM default_domain = MT-AG.COM } [domain_realm] .mt-ag.com = MT-AG.COM mt-ag.com = MT-AG.COM Remarks: - After Kdc you can also state multiple hostnames, separated by a space. - No reboot of Apache is needed since this configuration is read each time the authentication process takes place. 4.4 PROTECT THE APEX URL IN APACHE Add the following lines to the file /etc/httpd/conf/httpd.conf: LoadModule auth_kerb_module /etc/httpd/modules/mod_auth_kerb.so LoadModule proxy_module /etc/httpd/modules/mod_proxy.so LoadModule proxy_http_module /etc/httpd/modules/mod_proxy_http.so LoadModule headers_module /etc/httpd/modules/mod_headers.so # Protect all APEX specific requests AuthType Kerberos AuthName "Kerberos Login" KrbAuthRealms MT-AG.COM KrbServiceName HTTP/
[email protected] Krb5KeyTab /opt/httpkeytab/http_apex.mt-ag.com.keytab require valid-user # When using mod_proxy, the variable REMOTE_USER isn’t passed to Tomcat, so explicitly set a new variable here. RewriteEngine On # RewriteCond %{LA-U:REMOTE_USER} (.+)$ # If you don’t want to remove the domain name, just disable the following line and enable the line before this comment. RewriteCond %{REMOTE_USER} (.+)@.* RewriteRule . - [E=RU:%1] RequestHeader set APEX_USER %{RU}e # Weiterleiten von Anfragen an Oracle REST Data Services # Die Weiterleitung kann entweder mit HTTP(S) oder mittels AJP 7. business by integration Page 7 of 9 stattfinden ProxyPass /apex http://localhost:8080/apex ProxyPassReverse /apex http://localhost:8080/apex # Static files of APEX Alias /i/ "/srv/www/htdocs/images/" Save the file and restart Apache. 5 AUTOMATED AUTHENTIFICATION IN AN APEX APPLICATION Within the APEX application, setup a new authentication scheme that reads out the HTTP header variable „APEX_USER“. Wenn APEX_USER is empty, the user will be redirected to a static HTML page (index.html) hosted by Apache. This page will inform the user that he or she is currently not logged on to the Windows domain. Note: if you are using an older version of APEX (< 4.2.3), the Schema Type “HTTP Header Variable” won’t be available. In this case, you will have to write a small PL/SQL function to achieve the same objective. Contact us if you need the code for this. 6 CONFIGURATION OF THE CLIENT PC The web address of Apache should be listed in the intranet zone in Internet Explorer, otherwise you will be prompted to enter your Windows credentials if you try to access your APEX application: 8. business by integration Page 8 of 9 When you are using Firefox, go to the URL about:config and set the attribute network.negotiate-auth.trusted-uris to mt-ag.com. You can now access your APEX application using either Internet Explorer or Firefox without the need to provide your credentials. Important: make sure that all browser requests aren’t routed through a proxy server. So if your browser was configured to use a proxy server, make sure that an exception for apex.mt-ag.com exists, otherwise you will get a “page not found” error, because the Kerberos ticket got lost along the way. 7 WHATS HAPPENING? 9. business by integration Page 9 of 9 If you would like to see what’s happening in the background, you can set the log level of Apache to debug and inspect the log files. Edit the file: /etc/httpd/conf/httpd.conf and change the row containing „LogLevel“ to „LogLevel debug“. Save the file and restart Apache. The log files you need to inspect are called access_log and error_log. With the Windows 7 or Windows 8 utility klist on a client pc, you can find out which Kerberos tickets the Windows Domain User currently has. If all was setup correctly, you should see a ticket for apex.mt-ag.com in the output. Still need help? You can find us here: https://apex.mt-ag.com. 8 OTHER USEFUL LINKS Weitere hilfreiche Infos: http://blog.hallowelt.biz/wp-content/uploads/SSO_mit_mod_auth_kerb_v3.pdf SSO configured in Tomcat instead of Apache: https://community.oracle.com/message/12748733 More SSO options: http://wphilltech.com/options-for-windows-native-authentication-with-apex Disclaimer: MT AG is not responsible for any damage, outages or loss of profit resulting from the usage of this document.