SAML Authentication with Active Directory Federated Services (ADFS) and mod_auth_mellon

The following details how to use ADFS infrastructure via SAML authentication to authenticate to an OpenOnDemand deployment.

Prepare the Host

Before beginning, retrieve the following information from the ADFS administrator:

  1. The SAML 2.0 service URL (e.g., https://adfs.organization.com/ADFS/ls)
  2. The IdP metadata URL (e.g., https://adfs.organization.com/ADFS/metadata.xml)
  3. Ensure SSL is properly configured and any organizational certificate authorities are properly integrated into the host’s trust store, see Add SSL Support

Install mod_auth_mellon

  1. Ensure Software Collections is enabled on the system

  2. Install the mod_auth_mellon module:

    yum install httpd24-mod_auth_mellon httpd24-mod_ssl
    

Configure mod_auth_mellon

Note that this configuration assumes that SAML has been configured such that the returned NameID directly maps to a Unix user on the OOD host. For more information, see https://jdennis.fedorapeople.org/doc/mellon-user-guide/mellon_user_guide.html

  1. Download the IDP metadata file

    cd /etc/httpd/mellon/
    wget https://adfs.organization.com/ADFS/metadata.xml -O idpmetadata.xml
    
  2. Generate the mellon metadata

    export mellon_endpoint="https://$(hostname)/mellon"
    /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh "${mellon_endpoint}" "${mellon_endpoint}/metadata"
    mv *.cert ./mellon.cert
    mv *.key ./mellon.key
    mv *.xml ./mellon_metadata.xml
    
  3. Create a mellon configuration file

    vi /etc/httpd/conf.d/00-mellon.conf
    
  4. Add the following to the 00-mellon.conf file

    <Location />
      MellonSPPrivateKeyFile /etc/httpd/mellon/mellon.key
      MellonSPCertFile /etc/httpd/mellon/mellon.cert
      MellonSPMetadataFile /etc/httpd/mellon/mellon_metadata.xml
      MellonIdPMetadataFile /etc/httpd/mellon/idpmetadata.xml
    
      MellonEndpointPath /mellon
      MellonEnable "auth"
    </Location>
    
  5. Convert the key and cert files into pfx format

    openssl pkcs12 -export -inkey /etc/httpd/mellon/mellon.key -in /etc/httpd/mellon/mellon.cert -out /etc/httpd/mellon/mellon.pfx
    
  6. Provide the mellon.pfx and mellon_metadata.xml files to your ADFS administrator. The files can then be imported into the ADFS system.

Configure OOD

  1. Edit the ood_portal.yml file to include the following:

    # /etc/ood/config/ood_portal.yml
    ---
    # ...
    # Your other custom configuration options...
    # ...
    
    auth:
      - 'AuthType Mellon'
      - 'Require valid-user'
    
  2. Restart the HTTPD

    systemctl restart httpd