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.

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.

Glossary

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 https://adfs.uwaterloo.ca/FederationMetadata/2007-06/FederationMetadata.xml -P /etc/apache2/adfs
    IDEA!If you intend to use ADFS Test instead of ADFS Production, use the following FederationMetadata.xml file instead https://adfstest.uwaterloo.ca/FederationMetadata/2007-06/FederationMetadata.xml.
  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="http://www.w3.org/2000/09/xmldsig#">
        <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
            <KeyDescriptor use="signing">
                <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    <ds:X509Data>
                        <ds:X509Certificate>CERTGOESHERE</ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </KeyDescriptor>
            <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"/>
        </SPSSODescriptor>
    </EntityDescriptor>
    
    IDEA!Replace HOST_URL with the public URL for your host (e.g https://cs.uwaterloo.ca). 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 http://schemas.xmlsoap.org/claims/Group
    
            MellonCond ADFS_GROUP grouper-dept-cscf [MAP]
            MellonCond ADFS_GROUP MFA-Enrolled [MAP]
    </Location>
    
    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:
    Group
    emailaddress
    surname
    givenname
    samaccountname
    
    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!

<?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.

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

Topic attachments
I Attachment Action Size Date Who Comment
PNGpng ADFS.png manage 26.8 K 2019-08-02 - 13:57 DevonMerner  
Topic revision: r7 - 2019-12-04 - DevonMerner
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback