View Source

h1. Purpose

This tutorial explains how to set up an environment so that Windows domain user can access QuickBuild without using password.

h1. Assumptions

# Windows domain is _example.com_
# Windows domain controller server is Windows 2012 R2, and can be accessed via LDAP protocol: _ldap://
# QuickBuild server is installed at Ubuntu 3.13.0-40-generic, with DNS name _build.example.com_, and running on port 8810

h1. Steps
# Login to ubuntu server, and make sure below commands work as expected:
#* {code}$ nslookup{code}
This command should return ip address of the ubuntu server
#* {code}$ nslookup <ip address of ubuntu server>{code}
This command should return _build.example.com_
#* Make sure _build.example.com_ is the only host record in your DNS pointing to the ubuntu server, and vice versa for the reverse lookup dns records (PTR). Otherwise, single sign-on may not work for some unknown reason.
# Create a domain user _quickbuild_ in your domain controller, with following options:
# Create another domain user _apache_ with same options as above
# On domain controller, open powershell as Administrator, and run below command to generate keytab for apache user:
{code}ktpass -princ HTTP/ -mapuser apache -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL -pass <password of apache user> -out apache.keytab{code}
The generated _apache.keytab_ will be used later.
# Login to ubuntu server to install and configure kerberos client package:
{code}sudo apt-get install krb5-user{code}
Input _EXAMPLE.COM_ when installation procedure asks for default Kerberos realm. After installing Kerberos, modify _/etc/krb5.conf_:
#* add below under section _\[realms\]_:
kdc =
default_domain =
#* add below under section _\[domain_realm\]_
Now test if Kerberos client works by runnig command _kinit _<your Windows domain logon name>_. If configured correctly, it should prompt you to input your domain password to get the ticket. Then you should be able to list the ticket by running _klist_.
# Continue to configure apache httpd server on the ubuntu server:
#* Install apache httpd server if it is not already installed:
{code}sudo apt-get install apache2{code}
#* Install apache kerberos module if it is not already installed:
{code}sudo apt-get install libapache2-mod-auth-kerb{code}
#* Enable below apache modules:
$ sudo a2enmod proxy_http rewrite headers
#* Copy file _apache.keytab_ generated above from your domain controller to ubuntu server and place it under directory _/etc/apache2_, and then run below commands against the file:
$ sudo chown www-data apache.keytab
$ sudo chgrp www-data apache.keytab
$ sudo chmod 600 apache.keytab
# Create file _/etc/apache/sites-available/ with below content to define virtual host for QuickBuild:
<VirtualHost *:80>
# if you are configuring reverse proxy with https enabled, make sure to prepend the ServerName
# directive with "https://" schema, for example:

ProxyRequests Off

# turn off this option. We will rely on ProxyPassReverse to translate
# urls in Http response headers.
ProxyPreserveHost Off

<Proxy *>
Order allow,deny
Allow from all

ProxyPass / http://localhost:8810/
ProxyPassReverse / http://localhost:8810/

<Location />
AuthType Kerberos
AuthName "Build Server"
KrbServiceName HTTP
Krb5Keytab /etc/apache2/apache.keytab
KrbMethodNegotiate on

# Turn on this option in case the browser does not support Kerberos authentication,
# in that case, it will fall back to http basic authentication to prompt user for
# password.
KrbMethodK5Passwd on

Require valid-user

# Below directives puts logon name of authenticated user into http header _X-Forwarded-User_
# so that QuickBuild can use it
RequestHeader unset X-Forwarded-User
RewriteEngine On
RewriteCond %{LA-U:REMOTE_USER} (.+)
RewriteRule .* - [E=RU:%1,NS]
RequestHeader set X-Forwarded-User %{RU}e

# Remove domain suffix to get the simple logon name
RequestHeader edit X-Forwarded-User "@EXAMPLE.COM$" ""

# Below directives turn off Kerberos authentication for various QuickBuild services as their clients
# are not able to handle Kerberos authentication. QuickBuild will use the traditional http basic
# authentication in this case.
<LocationMatch "/(rest|service|agent_update|file_transfer|download|batch_download)">
AuthType None
Order allow,deny
Allow from all

RequestHeader unset X-Forwarded-User

ErrorLog ${APACHE_LOG_DIR}/quickbuild-error.log
CustomLog ${APACHE_LOG_DIR}/quickbuild-access.log combined
LogLevel warn
# Run below commands to enable virtual host created above and restart Apache:
$ a2ensite
$ sudo service apache2 restart
# Login to QuickBuild as administrator, switch to page _Administration/Security Settings_, and specify SSO provider as _SSO via Trusted Http Header_ with http header set to _X-Forwarded-User_ passed from Apache reverse proxy like below:
Here we only trust this header if it originates from ip _127.0.0.1_ as Apache is installed on the same server
# Now everything has been configured at server side, logon to a Windows workstation with your domain account and open your browser. Before visiting _build.example.com_, we still need to configure the browser to trust url
#* on Internet Explorer, open _Internet Options/Security /Local intranet_ to add _.example.com_:
#* Chrome internet option is pretty much the same as Internet Explorer
#* on Firefox, input _about:config_ on the address bar, and search for _negotiate_ in the config. Then add _example.com_ to config _network.negotiate-auth.delegation-uris_ and _network.negotiate-auth.trusted-uris_ like below:
# Now visit QuickBuild sign-in page, there should exist a SSO login button to let users login without username/password. Permission of users logged in this way will be determined by default group configured at SSO provider page.
{note}You can still login to QuickBuild with normal user/password without clicking the SSO button{note}