Active Directory Federation Service

As of May 2019, CAS authentication on University of Waterloo systems is now deprecated. ADFS is the new standard for campus-wide single sign-on moving forward.

The original developer of the Apache mellon module has discontinued development and encourages everyone to use latchset's fork of Mellon located here: https://github.com/latchset/mod_auth_mellon

Active Directory Federation Service (ADFS) provides users with a single sign-on authentication system using claims-based authorization.

For an overview on the service, view IST's ADFS Service Page.

IST configuration notes: https://wiki.uwaterloo.ca/display/ISTKB/XML+template+or+Apache+set+up+for+ADFS

Glossary

Ubuntu Apache2 Setup

Within CSCF-controlled systems, normally Web services should be implemented as part of our Haproxy installation, which automatically provides ADFS authentication.

Individual applications should not be directly configured to use ADFS (or any other authentication system). Instead, they should rely on the $REMOTE_USER CGI variable provided by Apache, and Apache should be configured to use ADFS.

While ADFS is supported on many different operating systems and webserver engines, this guide will only cover installation for Apache2 on Ubuntu 18.04 LTS using the recommended Mellon authentication module.

This guide also assumes that you have a basic understanding of Apache2 and that it is already setup and running on your server.

1. Setup and install Apache2 with SSL on your webserver
2. Install the Mellon authentication module for Apache2

   apt-get install libapache2-mod-auth-mellon

3. Confirm that Mellon is enabled for Apache

   a2enmod auth_mellon

4. Create a directory under /etc/apache2 to store ADFS configuration files

   mkdir /etc/apache2/adfs

5. Download and place the appropriate FederationMetadata.xml file for IST's ADFS service in a safe directory such as /etc/apache2/adfs:
   • For the production ADFS service (usual):

     wget https://adfs.uwaterloo.ca/FederationMetadata/2007-06/FederationMetadata.xml -P /etc/apache2/adfs

   • For the development ADFS service (only possibly if you are setting up a test service):

     wget https://adfstest.uwaterloo.ca/FederationMetadata/2007-06/FederationMetadata.xml -P /etc/apache2/adfs

6. Generate a self-signed certificate for ADFS with openssl req -x509 -nodes -days 3650 -newkey rsa:2049 -keyout /etc/apache2/adfs/adfs-signing.key -out /etc/apache2/adfs/adfs-signing.cert
   • This certificate will be used to sign and encrypt information between the Idp (IST) and SP (your host)
   • This certificate must match between what is currently specified on your server in the below configuration, and on IST's side. Changing it will require IST to update the certificate on their side.
7. Add the following configuration to your Apache site configuration.

   <Location />
           MellonEnable info
   
           MellonSPPrivateKeyFile /etc/apache2/adfs/adfs-signing.key
           MellonSPCertFile /etc/apache2/adfs/adfs-signing.cert
           MellonIdPMetadataFile /etc/apache2/adfs/FederationMetadata.xml
           MellonSecureCookie On
           MellonRedirectDomains *
           MellonMergeEnvVars On
   
           MellonSetEnvNoPrefix REMOTE_USER NAME_ID
           MellonSetEnvNoPrefix ADFS_GROUP http://schemas.xmlsoap.org/claims/Group
   </Location>
   <Directory />
           AuthType Mellon
   </Directory>
   

   Most of these are actually optional and may be adjusted depending on what you want to do.
   • MellonMergeEnvVars makes all the groups appear in one CGI variable, separated by colons, rather than one per group
   • MellonSetEnvNoPrefix REMOTE_USER cleans up the environment by suppressing the redundant $MELLON_NAME_ID CGI variable
   • MellonSetEnvNoPrefix ADFS_GROUP puts the groups in $ADFS_GROUP rather than $MELLON_http://schemas.xmlsoap.org/claims/Group
   • AuthType can be put in the <Location> rather than in a separate <Directory> if you do not need to override it in an .htaccess file
8. Submit a request to IST via their ADFS support/service request page. Fill out the fields as follows:
   1. Request type: New ADFS service
   2. Environment requested: Production environment (except possibly if you are setting up a test service)
   3. Application metadata file: URL; give https://your.site.uwaterloo.ca/mellon/metadata to have mod_auth_mellon generate it automatically
   4. The claims required to be passed to the application: None are required, however several might be useful.
      • The userid of the logged in user will always be available in the $REMOTE_USER CGI variable, even if no claims at all are requested.
      • Group: This will provide the AD groups of the user; useful for group-based authorization.
      • surname, givenname: Names of the user; could be useful for some applications.
      • emailaddress: Email address of the user; not as useful as it sounds, because you can just form userid@uwaterloo.ca anyway.
      • EmployeeID: HR ID of the user; could be useful for some employee-targeted applications.
      • StudentID: UW ID of the user; could be useful for some student- or instructor-targeted applications. (This claim requires special security approval).
   5. Does this application require two-factor authentication: Specify as required.
   6. Additional information: Normally none need be specified.
9. To require authentication in a particular area of the site, use one of the following in an appropriate <Directory> or <Location> section or an .htaccess file:
   1. Authentication only, no access control other than requiring a valid login:

      Require valid-user

   2. Authentication and authorization, access restricted to a given list of userids:

      Require user userid1 userid2 userid3

   3. Authentication and authorization, access restricted to a specified group:

      MellonEnable auth
      MellonCond ADFS_GROUP required-group-name [MAP]
      

Troubleshooting MellonCond

The MellonCond setting is used to filter what users are allowed/not allowed to access locations on the Apache webserver by targeting their exposed claims.

You can view what claims are exposed for a user by placing the following PHP script on your webserver and navigating to it as the user you want to troubleshoot. If the user is not authenticated or no claims are exposed then this script will not output anything.

The location that this script is placed in MUST be protected by AuthType mellon and MellonEnable auth. MellonEnable info will populate the script only if the user has already authenticated to a different part of the webserver protected with MellonEnable auth first!

<?php
header('Content-Type: text/plain');

foreach($_SERVER as $key=>$value) {
  if(substr($key, 0, 7) == 'MELLON_' || substr($key, 0, 5) == 'ADFS_') {
    echo($key . '=' . $value . "\r\n");
  }
}
?>

Compiling Mellon From Source / Using Diagnostics

In order to use the Diagnostics capabilities of Mellon, you will need to compile it from source with the --enable-diagnostics flag.

These steps assume that you are using an Ubuntu 18.04 LTS server that doesn't already have Mellon installed from apt.

1. Clone the Mellon git repository

   git clone https://github.com/Uninett/mod_auth_mellon.git

2. Install the dependencies required to compile mod_auth_mellon

   apt-get update
   apt-get install autoconf pkg-config lasso openssl liblasso3 liblasso3-dev libcurl14-openssl-dev apache2-dev libcurl libcurl4-openssl-dev

3. Enter the directory and configure it for building

   cd mod_auth_mellon
   ./autogen.sh
   ./configure --enable-diagnostics

4. Build and install the module

   make
   make install

This will allow you to use the MellonDiagnosticsEnable and MellonDiagnosticsFile parameters in your Apache configuration.

Troubleshooting

When performing extended troubleshooting, MellonDiagnostics and a browser SAML Decoder extension may be useful to provide relevant information.

My browser is automatically directed to /mellon/postResponse with a Forbidden error

To debug this issue, you will want to enable MellonDiagnostics and view the Mellon logs on the webserver in order to locate the correct error.

InvalidNameIDPolicy

This error occurs when the Mellon client is trying to use a NameIDPolicy that is currently unsupported or not enabled on the Service Provider (SP).

Fix: Confirm that IST has enabled the default "transient" NameIDPolicy for your service.

My browser enters a infinite redirect loop before or after authenticating with ADFS

This can occur when ADFS redirects you to the wrong mellon endpoint on your webserver.

For example; Your webserver may see that someone is trying to access /mellon/postResponse which isn't correct and is seen as a normal web directory. Your webserver will then direct you to the ADFS page which will send you right back to the wrong URL. This will repeat until the header becomes too big and the browser throws an error.

Fix: Ensure that the MellonEndpointPath option in your Apache config matches the ones mentioned in your MellonSPMetadata.xml file on both your client and service provider and that there are no typos.