Active Directory Federation Service

IDEA! 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.

IDEA! The original developer of the Apache mellon module has discontinued development and encourages everyone to use latchset's fork of Mellon located here:

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

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


Term Definition
SSO Single Sign On is used to share authentication between multiple services and systems without the user needing to re-authenticate or manage separate login credentials.
MFA Multi Factor Authentication is used to provide extra security in the case that a password is compromised by requiring a physical device on the user's person to provide a one-time token or code to approve the login.

Ubuntu Apache2 Setup

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
    wget -P /etc/apache2/adfs
    IDEA!If you intend to use ADFS Test instead of ADFS Production, use the following FederationMetadata.xml file instead
  6. Generate the MellonSPMetadataFile.xml file for your service and place it in the same /etc/apache2/adfs directory
    <EntityDescriptor entityID="HOST_URL" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="">
        <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
            <KeyDescriptor use="signing">
                <ds:KeyInfo xmlns:ds="">
            <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="HOST_URL/mellon/logout"/>
            <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="HOST_URL/mellon/postResponse" index="0"/>
    IDEA!Replace HOST_URL with the public URL for your host (e.g Replace CERTGOESHERE with the public X509 SSL certificate with the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- removed.
  7. If you wish to have your entire site secured via ADFS, add the following Location configuration to your Apache site configuration.
    <Location />
            AuthType Mellon
            MellonEnable auth
            MellonSPPrivateKeyFile /path/to/private/key
            MellonSPCertFile /path/to/public/x509/certificate
            MellonSPMetadataFile /etc/apache2/adfs/MellonSPMetadataFile.xml
            MellonIdPMetadataFile /etc/apache2/adfs/FederationMetadata.xml
            MellonSecureCookie On
            MellonRedirectDomains *
            MellonEndpointPath /mellon
            MellonSetEnvNoPrefix ADFS_GROUP
            MellonCond ADFS_GROUP grouper-dept-cscf [MAP]
            MellonCond ADFS_GROUP MFA-Enrolled [MAP]
    IDEA!MellonEndpointPath must match what you have specified in the MellonSPMetadataFile.xml for AssertionConsumerService and SingleLogoutService.
  8. Submit a request to IST via their ADFS support/service request page while including the MellonSPMetadataFile.xml generated earlier. The normal claims that should be requested are:
    IDEA!Be sure to specify whether you want multifactor authentication enabled for your service.

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.

IDEA! 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!

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.

IDEA! 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
  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
    ./configure --enable-diagnostics
  4. Build and install the module
    make install

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


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.


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 /melloon/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.

Topic attachments
I Attachment History Action Size Date Who Comment
PNGpng ADFS.png r1 manage 26.8 K 2019-08-02 - 13:57 DevonMerner  
Edit | Attach | Watch | Print version | History: r11 < r10 < r9 < r8 < r7 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r11 - 2020-05-21 - DevonMerner
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback