Content

How to set up Kerberos authentication (SSO)

KerberosSSO

Introduction

From January 2019, Easy Redmine (version 2018.1.3, platform 05.02) supports user authentication via Kerberos. Easy Software provides Kerberos authentication as a premium service, which may be charged by a one-time fee.

The functionality is a part of the general SSO authentication setting (Administration >> Settings >> Authentication).

Image20190228110623_1.png

With the configuration described in detail below, you would enter: manager/admin@EASYPROJECT.COM where EASYPROJECT.COM is realm name.

This setting is the easy part. The bigger part, however, is done on the server side. Kerberos for Easy Redmine requires Apache web server. The configuration is carried out by our server experts according to your needs.

Below you can find a guideline to the configuration. It serves only as reference material about the setup that would be done. Please be aware this is not a guaranteed manual. By trying to configure Kerberos or any other SSO authentication on your server, you take full responsibility of the security and overall functioning of the application.

Don't hesitate to contact your account manager or support to plan the configuration with our experts.

Kerberos installation and set up

Contents

- how to install and prepare kerberos server
- how to use kerberos authentication on apache2 web-server
- how to use kerberos authentication on nginx web-server (only on CentOS based machines!)
- sources and useful links

 

Installation of Kerberos

For this discussion, we will create na MIT Kerberos domain with the following features (edit them to fit your needs):

Realm: EASYPROJECT.COM
Primary KDC: kdc01.easyproject.com (192.168.0.1)
Secondary KDC: kdc02.easyproject.com (192.168.0.2)
User principal: manager
Admin principal: easy/easy666

It is strongly recommended that your network-authenticated users have their uid in a different range (say, starting at 5000) than that of your local users.

Before installing the Kerberos server, a properly configured DNS server is needed for your domain. Since the Kerberos Realm by convention matches the domain name, this section uses the EASYPROJECT.COM domain configured in Primary Master of the DNS documentation.

The next part is very important!

!!!Also, Kerberos is a time sensitive protocol. So if the local system time between a client machine and the server differs by more than five minutes (by default), the workstation will not be able to authenticate. To correct the problem all hosts should have their time synchronized using the same Network Time Protocol (NTP) server. For details on setting up NTP see Time Synchronization.!!!

 

Installation of Kerberos server

1) First we need to install the krb5-kdc and krb5-admin-server packages.

sudo apt install krb5-kdc krb5-admin-server

You will be asked at the end of the install to supply the hostname for the Kerberos and Admin servers, which may or may not be the same server, for the realm.

By default the realm is created from the KDC's domain name.

2) Now we need to create the new realm with the kdb5_newrealm utility:

sudo krb5_newrealm

Configuration of Kerberos server

1) The questions asked during installation are used to configure the /etc/krb5.conf file. If you need to adjust the Key Distribution Center (KDC) settings simply edit the file and restart the krb5-kdc daemon. If you need to reconfigure Kerberos from scratch, perhaps to change the realm name, you can run the next command

sudo dpkg-reconfigure krb5-kdc

2) Once the KDC is properly running, an admin user -- the admin principal -- is needed. It is recommended to use a different username from your everyday username. Run

sudo kadmin.local

Authenticating as principal root/admin@EASYPROJECT.COM with password.
kadmin.local: addprinc manager/easy
WARNING: no policy specified for manager/admin@EASYPROJECT.COM; defaulting to no policy
Enter password for principal "manager/admin@EASYPROJECT.COM":
Re-enter password for principal "manager/admin@EASYPROJECT.COM":
Principal "manager/admin@EASYPROJECT.COM" created.
kadmin.local: quit

In the above example manager is the Principal, /admin is an Instance, and @EASYPROJECT.COM signifies the realm. The "every day" Principal, a.k.a. the user principal, would be manager@EASYPROJECT.COM, and should have only normal user rights.

Replace EASYPROJECT.COM and manager with your Realm and admin username.

3) Next, the new admin user needs to have the appropriate Access Control List (ACL) permissions. The permissions are configured in the /etc/krb5kdc/kadm5.acl file:

manager/admin@EASYPROJECT.COM        *

This entry grants manager/admin the ability to perform any operation on all principals in the realm. You can configure principals with more restrictive privileges, which is convenient if you need an admin principal that junior staff can use in Kerberos clients. Please see the kadm5.acl man page for details.

4) Now restart the krb5-admin-server for the new ACL to take affect:

sudo systemctl restart krb5-admin-server.service

5) The new user principal can be tested using the kinit utility:

kinit manager/admin

manager/admin@EASYPROJECT.COM's Password:

After entering the password, use the klist utility to view information about the Ticket Granting Ticket (TGT):

klist
Credentials cache: FILE:/tmp/krb5cc_1000
        Principal: manager/admin@EASYPROJECT.COM

  Issued                 Expires               Principal
Jul 13 17:53:34  Jul 14 03:53:34  krbtgt/EASYPROJECT.COM@EASYPROJECT.COM

Where the cache filename krb5cc_1000 is composed of the prefix krb5cc_ and the user id (uid), which in this case is 1000. You may need to add an entry into the /etc/hosts for the KDC so the client can find the KDC. For example:

192.168.0.1   kdc01.example.com       kdc01

Replacing 192.168.0.1 with the IP address of your KDC. This usually happens when you have a Kerberos realm encompassing different networks separated by routers.

The best way to allow clients to automatically determine the KDC for the Realm is using DNS SRV records. Add the following to /etc/named/db.example.com:

_kerberos._udp.EASYPROJECT.COM.     IN SRV 1  0 88  kdc01.easyproject.com.
_kerberos._tcp.EASYPROJECT.COM.     IN SRV 1  0 88  kdc01.easyproject.com.
_kerberos._udp.EASYPROJECT.COM.     IN SRV 10 0 88  kdc02.easyproject.com.
_kerberos._tcp.EASYPROJECT.COM.     IN SRV 10 0 88  kdc02.easyproject.com.
_kerberos-adm._tcp.EASYPROJECT.COM. IN SRV 1  0 749 kdc01.easyproject.com.
_kpasswd._udp.EASYPROJECT.COM.      IN SRV 1  0 464 kdc01.easyproject.com.

Replace EASYPROJECT.COM, kdc01, and kdc02 with your domain name, primary KDC, and secondary KDC.

See Domain Name Service (DNS) for detailed instructions on setting up DNS.

Your new Kerberos Realm is now ready to authenticate clients.

Secondary KDC Configuration (Optional)

It is good practice to have a Secondary KDC in case the primary becomes unavailable. Also, if you have Kerberos clients that are in different networks (possibly separated by routers using NAT), it is wise to place a secondary KDC in each of those networks.

1)  install the packages, and when asked for the Kerberos and Admin server names enter the name of the Primary KDC:

sudo apt install krb5-kdc krb5-admin-server

2) Once you have the packages installed, create the Secondary KDC's host principal. From a terminal prompt, enter:

kadmin -q "addprinc -randkey host/kdc02.easyproject.com"

After, issuing any kadmin commands you will be prompted for your username/admin@EASYPROJECT.COM principal password.

3) Extract the keytab file:

kadmin -q "ktadd -norandkey -k keytab.kdc02 host/kdc02.easyproject.com"

4) There should now be a keytab.kdc02 in the current directory, move the file to /etc/krb5.keytab:

sudo mv keytab.kdc02 /etc/krb5.keytab

If the path to the keytab.kdc02 file is different adjust accordingly.

5) Also, you can list the principals in a Keytab file, which can be useful when troubleshooting, using the klist utility:

sudo klist -k /etc/krb5.keytab

The -k option indicates the file is a keytab file.

6) Next, there needs to be a kpropd.acl file on each KDC that lists all KDCs for the Realm. For example, on both primary and secondary KDC, create /etc/krb5kdc/kpropd.acl:

host/kdc01.easyproject.com@EASYPROJECT.COM
host/kdc02.easyproject.com@EASYPROJECT.COM

7) Create an empty database on the Secondary KDC:

sudo kdb5_util -s create

8) Now start the kpropd daemon, which listens for connections from the kprop utility. kprop is used to transfer dump files:

sudo kpropd -S

9) On the Primary KDC, create a dump file of the principal database:

sudo kdb5_util dump /var/lib/krb5kdc/dump

10) Extract the Primary KDC's keytab file and copy it to /etc/krb5.keytab:

kadmin -q "ktadd -k keytab.kdc01 host/kdc01.easyproject.com"

sudo mv keytab.kdc01 /etc/krb5.keytab

Make sure there is a host for kdc01.easyproject.com before extracting the Keytab.

11) Using the kprop utility push the database to the Secondary KDC:

sudo kprop -r EASYPROJECT.COM -f /var/lib/krb5kdc/dump kdc02.easyproject.com

There should be a SUCCEEDED message if the propagation worked. If there is an error message check /var/log/syslog on the secondary KDC for more information.

12) You may also want to create a cron job to periodically update the database on the Secondary KDC. For example, the following will push the database every hour (note the long line has been split to fit the format of this document):

# m h  dom mon dow   command
0 * * * * /usr/sbin/kdb5_util dump /var/lib/krb5kdc/dump &&
/usr/sbin/kprop -r EASYPROJECT.COM -f /var/lib/krb5kdc/dump kdc02.easyproject.com

13) Back on the Secondary KDC, create a stash file to hold the Kerberos master key:

sudo kdb5_util stash

14) Finally, start the krb5-kdc daemon on the Secondary KDC:

sudo systemctl start krb5-kdc.service

The Secondary KDC should now be able to issue tickets for the Realm. You can test this by stopping the krb5-kdc daemon on the Primary KDC, then by using kinit to request a ticket. If all goes well you should receive a ticket from the Secondary KDC. Otherwise, check /var/log/syslog and /var/log/auth.log in the Secondary KDC.

Kerberos Linux Client

You will now need to configure a Linux system as a Kerberos client. This will allow access to any kerberized services once a user has successfully logged into the system.

1) In order to authenticate to a Kerberos Realm, the krb5-user and libpam-krb5 packages are needed, along with a few others that are not strictly necessary but make life easier. To install the packages enter the following in a terminal prompt:

sudo apt install krb5-user libpam-krb5 libpam-ccreds auth-client-config

The auth-client-config package allows simple configuration of PAM for authentication from multiple sources, and the libpam-ccreds will cache authentication credentials allowing you to login in case the Key Distribution Center (KDC) is unavailable. This package is also useful for laptops that may authenticate using Kerberos while on the corporate network, but will need to be accessed off the network as well.

2) To configure the client in a terminal enter:

sudo dpkg-reconfigure krb5-config

You will then be prompted to enter the name of the Kerberos Realm. Also, if you don't have DNS configured with Kerberos SRV records, the menu will prompt you for the hostname of the Key Distribution Center (KDC) and Realm Administration server.

The dpkg-reconfigure adds entries to the /etc/krb5.conf file for your Realm. You should have entries similar to the following:

[libdefaults]
        default_realm = EASYPROJECT.COM
...
[realms]
        EXAMPLE.COM = {
                kdc = 192.168.0.1
                admin_server = 192.168.0.1
        }

If you set the uid of each of your network-authenticated users to start at 5000, as suggested in Installation, you can then tell pam to only try to authenticate using Kerberos users with uid > 5000:

# Kerberos should only be applied to ldap/kerberos users, not local ones.
for i in common-auth common-session common-account common-password; do
sudo sed -i -r \
-e 's/pam_krb5.so minimum_uid=1000/pam_krb5.so minimum_uid=5000/' \
/etc/pam.d/$i
done

This will avoid being asked for the (non-existent) Kerberos password of a locally authenticated user when changing its password using passwd.

 

3) You can test the configuration by requesting a ticket using the kinit utility. For example:

kinit manager@EASYPROJECT.COM
Password for manager@EASYPROJECT.COM:

When a ticket has been granted, the details can be viewed using klist:

klist
Ticket cache: FILE:/tmp/krb5cc_1000
Default principal: manager@EASYPORJECT.COM

Valid starting     Expires            Service principal
07/24/08 05:18:56  07/24/08 15:18:56  krbtgt/EASYPROJECT.COM@EASYPROJECT.COM
        renew until 07/25/08 05:18:57
Kerberos 4 ticket cache: /tmp/tkt1000
klist: You have no tickets cached

4) Next, use the auth-client-config to configure the libpam-krb5 module to request a ticket during login:

sudo auth-client-config -a -p kerberos_example

You will should now receive a ticket upon successful login authentication.

 

Apache 2 configuration

1) Install the mod_auth_kerb authentication module

Apache does not itself provide support for SPNEGO but it can be added using the module mod_auth_kerb. This is included in most major GNU/Linux distributions, but because it is a third-party module it is usually packaged separately from Apache. On Debian-based systems it is provided by the package libapache2-mod-auth-kerb:

apt-get install libapache2-mod-auth-kerb

and on Red Hat-based systems by the package mod_auth_kerb:

yum install mod_auth_kerb

2) Apache modules must be loaded before they can be used, but both of the above packages arrange for this to happen automatically. If for any reason you need to do this manually then the appropriate configuration directive is:

LoadModule auth_kerb_module /usr/lib/apache2/modules/mod_auth_kerb.so

(where the pathname of the module should be replaced with whatever is appropriate for your system).

3) Create a service principal for the web server

SPNEGO requires that a Kerberos service principal be created for the web server. The service name is defined to be HTTP, so for the server www.easyproject.com the required service principal name is HTTP/www.easyproject.com@easyproject.COM.

If you are using MIT Kerberos then the service principal can be created using the kadmin command:

kadmin -p manager/admin -q "addprinc -randkey HTTP/www.easyproject.com"

4) Create a keytab for the service principal

A keytab is a file for storing the encryption keys corresponding to one or more Kerberos principals. mod_auth_kerb needs one in order to make use of the service principal created above. If you are using MIT Kerberos then the keytab (like the service principal) can be created using the kadmin command. Its ownership must be such that it is readable by the Apache process.

On Debian-based systems a suitable location for the keytab would be /etc/apache2/http.keytab and the appropriate owner is www-data:

kadmin -p manager/admin -q "ktadd -k /etc/apache2/http.keytab HTTP/www.easyproject.com"
chown www-data /etc/apache2/http.keytab

On Red Hat-based systems a suitable location would be /etc/httpd/http.keytab and the appropriate owner is apache:

kadmin -p manager/admin -q "ktadd -k /etc/httpd/http.keytab HTTP/www.easyproject.com"
chown apache /etc/httpd/http.keytab

The -k option specifies the pathname to the keytab, which will be created if it does not already exist.

5) If you wish to check that the key has been correctly added to the keytab then you can attempt to use it to authenticate as the service principal, then view the resulting ticket-granting ticket using klist:

kinit -k -t /etc/apache2/http.keytab HTTP/www.easyproject.com
klist

6) Specify the authentication method to be used

Apache must be told which parts of which web sites are to use authentication provided by mod_auth_kerb. This is done using the AuthType directive with a value of Kerberos. Some further directives are then needed to configure how mod_auth_kerb should behave.

If the intent is to apply these directive to the whole of a given web site then they can be placed in a <Location> container with a path corresponding to the root of the site:

<Location />
 AuthType Kerberos
 AuthName "Acme Corporation"
 KrbMethodNegotiate on
 KrbMethodK5Passwd off
 Krb5Keytab /etc/apache2/http.keytab
</Location>

The AuthName directive specifies the HTTP authorisation realm. Its purpose is to indicate to the user which of the various passwords he might know is needed to gain access to a particular web site. With true Kerberos authentication there should be no password prompt, and mod_auth_kerb appears to work perfectly well without an AuthName having been specified; however the Apache documentation states that it is required, so it would seem prudent to supply one anyway. A suitable value might be the domain name, the name of the Kerberos realm, or the name of the organisation to which the web site belongs.

In addition to the SPNEGO protocol, mod_auth_kerb has the ability to ask the user for a password using basic authentication then validate that password by attempting to authenticate to the KDC. This can be useful if there is a need for the web site to be accessible to its authorised users from machines that are not part of the Kerberos realm, however it is significantly less secure than true Kerberos authentication. Both SPNEGO and password authentication are enabled by default. In this example there is no requirement for the site to be accessible to non-SPNEGO-enabled web browsers, therefore password authentication has been disabled using the KrbMethodK5Passwd directive. For completeness, SPNEGO has been explicitly enabled using the KrbMethodNegotiate directive.

The Krb5Keytab directive specifies the pathname of the keytab to which the HTTP service principal has been added. It should match whatever was passed to the ktadd command of kadmin earlier in this procedure.

Although a <Location> container has been used in this example, it would be equally acceptable for the above directives to be placed within a <Directory>, <Files> or <Proxy> container or within an .htaccess file.

7) Specify a list of authorised users

Setting the authentication method does not by itself restrict access to the server. This is because Apache defaults to allowing access by anonymous users, and unless that behaviour is overridden then the authentication method (whatever it might be) will not be invoked.

In this example there are only four users who need access, and the simplest way to arrange that is by means of a Require directive:

<Location />
 # ...
 Require user dougal@EASYPROJECT.COM brian@EASYPROJECT.COM ermintrude@EASYPROJECT.COM dylan@EASYPROJECT.COM
</Location>

8) Reload the Apache configuration

See Cause a system service to reload its configuration. On recent Debian-based systems the required command is:

service apache2 force-reload

 

Nginx configuration

This section only applies to CentOS/RedHat based OS.

1) Make sure Nginx is installed in your system.
All the next commands should be run from root user or using sudo.

2) Run the next command to check what modules are available in your nginx installation.

Nginx -V

(look for “ with-stream=dynamic” in the output of the command to make sure your steam module is avaialble)

3) Go to your root and search for the ngx_stream_module.so file

 cd /
 find / -name ngx_stream_module.so

Note the exact path of the steam module file
For example, it can be placed in “ /usr/lib64/nginx/modules/ngx_stream_module.so ” you will need this path to set it in nginx.conf

If you don't have ngx_stream_module, you need to uninstall your default nginx and reinstall it back from sources or specific rpm package. On this page you may find the exact versions of nginx packages which include ngx_stream_module - https://rpmfind.net/linux/rpm2html/search.php?query=ngx_stream_module.so()(64bit)

4) Now all set to write your Nginx configration.

vim /etc/nginx/nginx.conf
############################################
user nginx;
worker_processes 1;
load_module /usr/lib64/nginx/modules/ngx_stream_module.so;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;
events {
worker_connections 1024;
}
stream {
#…
 error_log /var/log/nginx/stream_error.log debug;
 server {
 listen 88;
 proxy_pass kdc01.easyproject.com:88;
 }
 server {
 listen 749;
 proxy_pass kdc01.easyproject.com:749;
 }
}
############################################

5) Restart nginx service.

systemctl enable nginx
systemctl start nginx

6) Check if the assigned ports are open now.

netstat -tupnl |grep nginx

Now our Nginx is ready to redirect the requests to kerb server.

 

Sources and useful links

https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/managing_smart_cards/configuring_a_kerberos_5_server

https://help.ubuntu.com/lts/serverguide/kerberos.html.en

http://www.microhowto.info/howto/configure_apache_to_use_kerberos_authentication.html

https://active-directory-wp.com/docs/Networking/Single_Sign_On/Kerberos_SSO_with_Apache_on_Linux.html

https://medium.com/@Santii/how-to-setup-kerberos-behind-a-reverse-proxy-nginx-d692f609191c

Easy Redmine 2019 Free Trial

Full-featured, 30 Days, SSL protected, Daily Backups, In your Geo Location

or