This documentation relates to QuickBuild 9.0.x
Select here if you are using a different version

Single Sign-On with Windows Domain Account

Purpose

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

Assumptions

  1. Windows domain is example.com
  2. Windows domain controller server is Windows 2012 R2, and can be accessed via LDAP protocol: ldap://dc.example.com:389
  3. QuickBuild server is installed at Ubuntu 3.13.0-40-generic, with DNS name build.example.com, and running on port 8810

Steps

  1. Login to ubuntu server, and make sure below commands work as expected:
    • $ nslookup build.example.com

      This command should return ip address of the ubuntu server

    • $ nslookup <ip address of ubuntu server>

      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.
  2. Create a domain user quickbuild in your domain controller, with following options:
  3. Create another domain user apache with same options as above
  4. On domain controller, open powershell as Administrator, and run below command to generate keytab for apache user:
    ktpass -princ HTTP/build.example.com@EXAMPLE.COM -mapuser apache -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL -pass <password of apache user> -out apache.keytab

    The generated apache.keytab will be used later.

  5. Login to ubuntu server to install and configure kerberos client package:
    sudo apt-get install krb5-user

    Input EXAMPLE.COM when installation procedure asks for default Kerberos realm. After installing Kerberos, modify /etc/krb5.conf:

    • add below under section [realms]:
              EXAMPLE.COM = {
                      kdc = dc.example.com
                      default_domain = example.com
              }
      
    • add below under section [domain_realm]
              .example.com = EXAMPLE.COM
              example.com = EXAMPLE.COM
      

      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.

  6. Continue to configure apache httpd server on the ubuntu server:
    • Install apache httpd server if it is not already installed:
      sudo apt-get install apache2
    • Install apache kerberos module if it is not already installed:
      sudo apt-get install libapache2-mod-auth-kerb
    • 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
      
  7. Create file /etc/apache/sites-available/build.example.com.conf 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: https://build.example.com:443
            ServerName build.example.com
    
            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
            </Proxy>
    
            ProxyPass / http://localhost:8810/
            ProxyPassReverse / http://localhost:8810/
    
            <Location />
                    AuthType Kerberos
                    AuthName "Build Server"
                    KrbAuthRealms EXAMPLE.COM
                    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$" ""
            </Location>
    
            # 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
            </LocationMatch>
    
            ErrorLog ${APACHE_LOG_DIR}/quickbuild-error.log
            CustomLog ${APACHE_LOG_DIR}/quickbuild-access.log combined
            LogLevel warn
    </VirtualHost>
    
  8. Run below commands to enable virtual host created above and restart Apache:
    $ a2ensite build.example.com.conf
    $ sudo service apache2 restart
    
  9. Login to QuickBuild as administrator and switch to page Administration/Security Settings to perform below tasks:
    • Add an authenticator of type Active Directory with below properties:
    • Trust user name in http header 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
  10. 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 example.com:
    • 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 you should be able to visit _http://build.example.com_ without using any password. QuickBuild will display your current domain user as logged-in user.
In case you want to sign in as a different user in this single sign-in environment, just sign out from QuickBuild, and input desired user/password to login to QuickBuild again.

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.