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://dc.example.com:389_
# 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 build.example.com{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_domain_user.png!
# 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/build.example.com@EXAMPLE.COM -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\]_:
{code}
EXAMPLE.COM = {
kdc = dc.example.com
default_domain = example.com
}
{code}
#* add below under section _\[domain_realm\]_
{code}
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM
{code}
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:
{code}
$ sudo a2enmod proxy_http rewrite headers
{code}
#* 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:
{code}
$ sudo chown www-data apache.keytab
$ sudo chgrp www-data apache.keytab
$ sudo chmod 600 apache.keytab
{code}
# Create file _/etc/apache/sites-available/build.example.com.conf_ with below content to define virtual host for QuickBuild:
{code}
<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>
{code}
# Run below commands to enable virtual host created above and restart Apache:
{code}
$ a2ensite build.example.com.conf
$ sudo service apache2 restart
{code}
# 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:
!trust-user.png!
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 example.com:
#* on Internet Explorer, open _Internet Options/Security /Local intranet_ to add _.example.com_:
!ie_intranet.png!
#* 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:
!firefox-intranet.png!
# 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.
!sso-signin.png!
{note}You can still login to QuickBuild with normal user/password without clicking the SSO button{note}
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://dc.example.com:389_
# 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 build.example.com{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_domain_user.png!
# 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/build.example.com@EXAMPLE.COM -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\]_:
{code}
EXAMPLE.COM = {
kdc = dc.example.com
default_domain = example.com
}
{code}
#* add below under section _\[domain_realm\]_
{code}
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM
{code}
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:
{code}
$ sudo a2enmod proxy_http rewrite headers
{code}
#* 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:
{code}
$ sudo chown www-data apache.keytab
$ sudo chgrp www-data apache.keytab
$ sudo chmod 600 apache.keytab
{code}
# Create file _/etc/apache/sites-available/build.example.com.conf_ with below content to define virtual host for QuickBuild:
{code}
<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>
{code}
# Run below commands to enable virtual host created above and restart Apache:
{code}
$ a2ensite build.example.com.conf
$ sudo service apache2 restart
{code}
# 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:
!trust-user.png!
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 example.com:
#* on Internet Explorer, open _Internet Options/Security /Local intranet_ to add _.example.com_:
!ie_intranet.png!
#* 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:
!firefox-intranet.png!
# 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.
!sso-signin.png!
{note}You can still login to QuickBuild with normal user/password without clicking the SSO button{note}