ADFS

Starting from July 2021, we are a registered SAML SP (Service Provider) for the University of Waterloo's ADFS system.

Our metadata URL is https://csclub.uwaterloo.ca/saml/metadata.

Our SP certificate is currently set to expire in July 2031; make sure to renew it before then.

The ADFS IdP metadata XML (from the university) is set to expire in October 2025; make sure to download a new copy before then.

Paperwork

Unfortunately the form which we need to submit to IST to become a SP can only be accessed by faculty, so ask our club advisor to submit it for us (as of this writing, that is Dr. Prabhakar Ragde). IST may be slow to respond, so make sure to do this well before our certificate expires.

Here's some information which you'll need for the form:

• Environment requested: production environment
• URL for the application metadata file: https://csclub.uwaterloo.ca/saml/metadata
• Claims required to be passed to the application: group, emailaddress, surname, givenname, samaccountname, UPN
• Is 2FA required for this application: yes
• Valid Redirect URI: https://csclub.uwaterloo.ca/*

Apache setup

These steps are adapted from https://jdennis.fedorapeople.org/doc/mellon-user-guide/mellon_user_guide.html.
Also see https://cs.uwaterloo.ca/twiki/view/CF/ADFS.

Install the mod_auth_mellon module:

apt install libapache2-mod-auth-mellon

Create a keypair and SP metadata XML file:

mellon_create_metadata https://csclub.uwaterloo.ca https://csclub.uwaterloo.ca/saml

Because we use persistent format for Name IDs with ADFS IdP, add the following <NameIDFormat> line under the <SPSSODescriptor> scope like below in the generated XML metadata:

    <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
  </SPSSODescriptor>
</EntityDescriptor>

Place the files under /etc/apache2/saml on caffeine (make sure the private key is only readable by root), and store a copy under /home/sysadmin/certs/saml_csclub.uwaterloo.ca on xylitol.

Also download a copy of the ADFS IdP metadata XML file:

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

Enable the Mellon module:

a2enmod auth_mellon

Add the following snippet to /etc/apache2/sites-real/csc on caffeine:

    <Location / >
      MellonEnable info
      MellonEndpointPath /saml
      MellonSPMetadataFile /etc/apache2/saml/https_csclub.uwaterloo.ca.xml
      MellonSPPrivateKeyFile /etc/apache2/saml/https_csclub.uwaterloo.ca.key
      MellonSPCertFile /etc/apache2/saml/https_csclub.uwaterloo.ca.cert
      MellonIdPMetadataFile /etc/apache2/saml/FederationMetadata.xml
      MellonSecureCookie On
      MellonRedirectDomains *
      MellonMergeEnvVars On
      MellonSetEnvNoPrefix REMOTE_USER NAME_ID
      MellonSetEnvNoPrefix ADFS_GROUP http://schemas.xmlsoap.org/claims/Group
    </Location>

Now restart (or reload if the Mellon module is already loaded):

systemctl restart apache2

Testing

To make sure that everything is working, paste the following into /srv/saml-test/index.php on caffeine:

<?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");
    }
}
?>

Now add the following snippet to /etc/apache2/sites-real/csc:

    Alias /saml-test /srv/saml-test
    <Location /saml-test >
      AuthType Mellon
      MellonEnable auth
      Require valid-user
    </Location>

Now if you visit https://csclub.uwaterloo.ca/saml-test, you should get redirected to ADFS.

Known limitations

It is not currently possible to use any of the Mellon* directives in a .htaccess file. Here is the open GitHub issue for it (if it is now closed, please update this wiki page).

Tips

If you want to view the certificate information inside one of the metadata XML files, you can actually just copy the value inside the <X509Certificate> tag, then place it between PEM headers like this:

-----BEGIN CERTIFICATE-----
MIIC5DCCAcygAwIBAgIQR/h98Vka9rpD...
-----END CERTIFICATE-----

Now you can use openssl to analyze it:

openssl x509 -noout -text -in metadata.pem