Skip to content
This repository has been archived by the owner on Jan 28, 2020. It is now read-only.

GenericSetup

Jump to bottom
Thijs Kinkhorst edited this page Aug 19, 2015 · 3 revisions

Generic setup instructions

This document is a short howto for configuring mod_auth_mellon.

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 SAML 2.0 metadata

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

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 https://sp.example.org/myEntityID 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.

Adding SAML 2.0 metadata for the IdP

Next, you need to add the metadata for your IdP to your service provider. You should receive the metadata from the IdP as an XML file. Save that file in a place accessible to the Web server, e.g. as /etc/apache2/mellon/idp-metadata.xml.

Enabling the module

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

a2enmod auth_mellon authn_core authz_user

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 got from the IdP.
    MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.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 the IdP

Before your service provider can communicate with the IdP, the IdP must have metadata for your SP installed. You should therefore send the metadata you have generated for your SP to the administrators of the IdP.

Testing your SP

Once the IdP administrators have added your metadata to the IdP, you can proceed with testing your SP. Create a PHP script named "auth_mellon.php" with the following contents:

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

(You can of course also use different scripting languages.)

You can then go to:

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 that it receives from the IdP to the environment sent to scripts. The attributes will be prefixed with MELLON_.

In PHP, you can access the variables through $_SERVER. E.g.:

<?php
echo 'Hello ' . $_SERVER['MELLON_displayName'];

(Note that this example assumes that the IdP gives you the name of the user in an attribute named displayName. What attributes are available to your service provider depends on the IdP.

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.

Clone this wiki locally