FeideSetup

Feide setup instructions

Introduction

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

Installing mod_auth_mellon

First you need to install mod_auth_mellon. For Debian Wheezy it is available in the wheezy-backports repository. It may also be available in the repositories of other Linux distributions. Refer to the README file for information about building it from source.

Creating metadata

mod_auth_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_auth_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_auth_mellon

This configuration assumes that you want to provide attributes from mod_auth_mellon to all scripts on your server, while only triggering authentication if the user accesses https://sp.example.org/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 mod_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_auth_mellon, you should send the metadata file you created (i.e. the .xml-file) to Feide at [email protected]. You should also include a list of the attributes that your service requires. See the list of available attributes.

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_auth_mellon

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

Manual login

To start a login operation manually, you can use the mod_auth_mellon login endpoint.

https://sp.example.org/mellon/login?ReturnTo=/index.html

The ReturnTo parameter is the URL the user should be sent to after logging in. See the README file for more details.

Logout

To start a logout operation, you need to send the user the mod_auth_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 mod_auth_mellon session for each request. This can be done by checking whether the MELLON_NAME_ID variable is set.