Introduction

This document is a short howto for configuring mod_mellon for use with Feide.

Installing mod_mellon

First you need to install mod_mellon. If you are running Debian Lenny, you can download precompiled packages. Otherwise you will need to download and compile the source. Refer to the README file for more information.

Creating metadata

mod_mellon requires metadata for your service provider. To create this metadata, you can use a script:

• mellon_create_metadata.sh

This script takes in two options:

• The entity ID, which identifies your service.
• The base URL to the endpoints for mod_mellon.

Example:

 mellon_create_metadata.sh urn:mace:feide.no:services:org.example.sp https://sp.example.org/mellon 

This will create three files:

• A .key-file, which contains the private key in PEM format. This file should be set in the MellonSPPrivateKeyFile option.
• A .cert-file, which contains the certificate in PEM format. This file should be set in the MellonSPCertFile option.
• A .xml-file, which contains the metadata file for the SP. This file should be set in the MellonSPMetadataFile option.

You should save the files in some directory, e.g. /etc/apache2/mellon. The files should also be readable by the web-server. You may therefore have to change the owner to the user Apache is running as.

Retrieving metadata for the IdP

Feide runs two IdPs. An IdP for testing, and an IdP for production. Here we will assume that you are connecting to the Feide test-IdP. The metadata for the Feide test-IdP can be downloaded from:

https://idp-test.feide.no/simplesaml/saml2/idp/metadata.php

You should save this file in a place accessible to the Web server, e.g. as /etc/apache2/mellon/idp-test.feide.no.xml.

Enabling the module

If you are installing from a Debian package, you can enable the module by running

a2enmod auth_mellon

Otherwise, you will need to add the configuration to the Apache configuration file yourself. Refer to the global configuration example in the README file.

Configuring mod_mellon

This configuration assumes that you want to provide attributes from mod_mellon to all scripts on your server, while only triggering authentication if the user accesses /auth_mellon.php.

# This is a server-wide configuration that will add information from the Mellon session to all requests.
<Location />
    # Add information from the auth_mellon session to the request.
    MellonEnable "info"

    # Configure the SP metadata
    # This should be the files which were created when creating SP metadata.
    MellonSPPrivateKeyFile /etc/apache2/mellon/urn_mace_feide.no_services_org.example.sp.key

    MellonSPCertFile /etc/apache2/mellon/urn_mace_feide.no_services_org.example.sp.cert
    MellonSPMetadataFile /etc/apache2/mellon/urn_mace_feide.no_services_org.example.sp.xml

    # IdP metadata. This should be the metadata file you downloaded from the IdP.
    MellonIdPMetadataFile /etc/apache2/mellon/idp-test.feide.no.xml

    # The location all endpoints should be located under.
    # It is the URL to this location that is used as the second parameter to the metadata generation script.
    # This path is relative to the root of the web server.
    MellonEndpointPath /mellon
</Location>

# This is a location that will trigger authentication when requested.
<Location /auth_mellon.php>
    # This location will trigger an authentication request to the IdP.
    MellonEnable "auth"
</Location>

Sending metadata to Feide

After you have configured mod_mellon, you should send the metadata file you created (i.e. the .xml-file) to Feide at support@feide.no. When Feide has added your metadata, you should be able to test authentication by accessing:

https://sp.example.org/auth_mellon.php

You should be redirected to the login page on the IdP. After authentication, you should be redirected back to the original URL.

Retrieving attributes from mod_mellon

mod_mellon will add the attributes of the user to the environment sent to scripts. In PHP you can access the variables like this:

<?php
header('Content-Type: text/plain');
foreach($_SERVER as $key=>$value) {
  if(substr($key, 0, 7) == 'MELLON_') {
    echo($key . '=' . $value . "\r\n");
  }
}
?>

Logout

To start a logout operation, you need to send the user the mod_mellon logout endpoint.

https://sp.example.org/mellon/logout?ReturnTo=/logged_out.html

The ReturnTo parameter is the URL the user should be sent to after logging out.

You should also remember that the user can be logged out by the IdP. To handle this, you should check that the user has a valid mellon session for each request. This can be done by checking whether the MELLON_NAME_ID variable is set.