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 /etc/apache2/ssl/
    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.
Topic attachments
I Attachment Action Size Date Who Comment
PNGpng ADFS.png manage 26.8 K 2019-08-02 - 13:57 DevonMerner  
Topic revision: r3 - 2019-08-03 - 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