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
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
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.
- Setup and install Apache2 with SSL on your webserver
- Install the Mellon authentication module for Apache2
apt-get install libapache2-mod-auth-mellon
- Confirm that Mellon is enabled for Apache
a2enmod auth_mellon
- Create a directory under /etc/apache2 to store ADFS configuration files
mkdir /etc/apache2/adfs
- 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
- 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.
- 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
- Submit a request to IST via their ADFS support/service request page. Fill out the fields as follows:
- Request type: New ADFS service
- Environment requested: Production environment (except possibly if you are setting up a test service)
- Application metadata file: URL; give
https://your.site.uwaterloo.ca/mellon/metadata
to have mod_auth_mellon generate it automatically
- The "entityID" for the service will automatically specify http or https depending on whether SSL has been configured in Apache.
- This metadata file must match between IST and your server. If SSL becomes disabled or expired, then the metadata file might change the entityID to http which would break ADFS due to a mismatch between Mellon and IST.
- 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).
- Does this application require two-factor authentication: Specify as required.
- Additional information: Normally none need be specified.
- 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:
- Authentication only, no access control other than requiring a valid login:
Require valid-user
- Authentication and authorization, access restricted to a given list of userids:
Require user userid1 userid2 userid3
- Authentication and authorization, access restricted to a specified group:
MellonEnable auth
MellonCond ADFS_GROUP required-group-name [MAP]
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.
- Clone the Mellon git repository
git clone https://github.com/Uninett/mod_auth_mellon.git
- 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
- Enter the directory and configure it for building
cd mod_auth_mellon
./autogen.sh
./configure --enable-diagnostics
- 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.
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.