OpenAthens LA support ended on 31 March 2020

Search

Skip to end of metadata
Go to start of metadata

Kerberos authentication can be used by delegating to an Apache module. 

The steps are:

Enable the connection in Active Directory

This example uses idp.yourdomain.com as the FQDN of the runtime (i.e. you would authenticate at https://idp.yourdomain.com/oala/sso), and yourdomain.com as the name of your domain controller.

On the Windows box hosting your Kerberos installation, you should use the ktpass command, as follows:
(Modified from: http://support.microsoft.com/kb/324144)
To create a UNIX keytab file to permit the UNIX host to authenticate with a Windows 2000-based server, you must create a user in Active Directory. This user is used by the Kerberos service on the client. To generate the keytab file and copy it to the UNIX host.

  1. Start the Active Directory Management tool.
  2. Right-click the Users folder, point to New, and then click User.
    1. Set the User login name as the FQDN of the runtime, e.g. idp.yourdomain.com.
    2. Note the Display name as the ‘account’
  3. Type the name of the UNIX host for which you want to add Kerberos support.
  4. Save the user.
  5. start a command prompt, and then type the following command:

     

    ktpass -princ HTTP/hostname@NT-DNS-REALM-NAME mapuser account -pass password -out hostname.keytab

     

    where:
    • hostname is the runtime’s FQDN.
    • NT-DNS-REALM-NAME is the Active Directory realm with which you want to authenticate. In capitals.
    • account is the account that you created in Active Directory.
    • password is the password for the account.

    • case is sensitive

      Example:

      ktpass -princ HTTP/idp.yourdomain.com@YOURDOMAIN.COM mapuser oala -pass swordfish -out idp.yourdomain.com.keytab

Install Apache module on the runtime

sudo yum install mod_auth_kerb

Configure the module on the runtime 

  • Copy the keytab file you created earlier to the /tmp folder of your OpenAthens LA Runtime Server using your favourite file transfer program (you can't copy it directly to the correct folder).
  • Move the file to the /etc/httpd/conf/ folder:

     

    sudo mv /tmp/idp.yourdomain.com.keytab /etc/httpd/conf/idp.yourdomain.com.keytab
  • Update the ownership, permissions and security context:

     

    sudo chown root:root /etc/httpd/conf/idp.yourdomain.com.keytab
    sudo chmod 644 /etc/httpd/conf/idp.yourdomain.com.keytab
    sudo chcon -u system_u -r object_r -t httpd_config_t /etc/httpd/conf/idp.yourdomain.com.keytab

     

    This is what you want to see if you list the contents of the folder with the -Z argument:

     

    [root@runtime conf]# ls -Z /etc/httpd/conf/
    # -rw-r--r--. root root system_u:object_r:httpd_config_t:s0 httpd.conf
    # -rw-r--r--. root root system_u:object_r:httpd_config_t:s0 magic
    # -rw-r--r--. root root system_u:object_r:httpd_config_t:s0 idp.yourdomain.com.keytab

     

    Next update the Kerberos config file at /etc/krb5.conf to know the details of your Active Directory domain.

     

    sudo nano /etc/krb5.conf
    [libdefaults]
      default_realm = YOURDOMAIN.COM
      dns_lookup_realm = true
      dns_lookup_kdc = true
    [realms]
      yourdomain.com = {
        kdc = dc-01.yourdomain.com:88
        kdc = dc-02.yourdomain.com:88
      }
    [domain_realm]
      .idp.yourdomain.com = YOURDOMAIN.COM
      idp.yourdomain.com = YOURDOMAIN.COM
  • Most of the defaults should be acceptable however you will need to modify the following:

    • default_realm - This refers to the default administrative domain that will be used (in case you have multiple).
    • [realms] - This lists the kerberos domain controllers (kdc) server URI's (e.g. dc-01.yourdomain.com:88) which will be used for authentication within the domain. This is most likely your active directory service, and multiple domain controllers can be listed within a realm.
    • [domain_realm] - This matches a hostname to a domain realm, this is so that when a client accesses a location it will know which realm to consult, so in the example you are protecting "idp.yourdomain.com" which then matches that to YOURDOMAIN.COM which will be used for the authentication.
  • More information on kerberos configuration can be found on http://www.kerberos.org/.
  • Once the module is installed and configured you will need to modify the /oala/auth 'location' by creating a config file. Still as root:

     

    sudo nano /etc/httpd/conf.d/openathensla-runtime.kerb.local
    <Location /oala/auth>
      AuthType Kerberos
      AuthName "Organisation Name"
      KrbMethodNegotiate On
      KrbMethodK5Passwd On
      KrbAuthRealms YOURDOMAIN.COM
      Krb5KeyTab /etc/httpd/conf/idp.yourdomain.com.keytab
      require valid-user
    </Location>

     

    Where:
    • AuthName - Change to something that matches your organisation.
    • KrbAuthRealm - This is the same as the default realm used in kerberos configuration.
    • Krb5KeyTab - This matches the location and name of the keytab file you generated and copied over earlier.

Enable Kerberos as the authentication store in the LA administration interface

  • On the authentication store tab, add a new store using the green plus button. Select the delegate authentication type.

  • In the right-hand panel, give it a name and select Apache as the delegation type



  • Update the authentication provider setting for any attached runtimes

    • On the overview tab, select the runtime connections bar in the right-hand panel

    • For each of your runtimes click on edit and step through the wizard until page 3 of 4



    • Select your new authentication provider and complete the wizard

  • Publish
Anything to watch out for?

If you have users who are in a very large number of distribution or security groups it is possible that the headers passed to OpenAthens LA could be larger than the 8KB default limit which would fail. This limit can be adjusted by adding a line to the openathensla-runtime.kerb.local file defined above:

LimitRequestFieldSize 16384

This example doubles the allowable header size to 16K. It is best not to do this unless you have to though.

This article represents steps known to work and all Kerberos information is taken from Microsoft support documents. Our service desk can only support the interaction at the OpenAthens LA end - questions about the operation of Kerberos should be addressed to the vendor.

  • No labels