Installation Guide for Configuring mod_auth_mellon with Red Hat Single Sign-On

There are two hosts involved:

  1. The host on which the Red Hat Single Sign-On is running on, this will be referred to as $idp_host because Red Hat Single Sign-On is a SAML Identity Provider. In SAML identity providers are referred to by the acronym IdP.
  2. The host on which the web application is running on, this will be referred to as $sp_host. In SAML an application using an IdP is called a Service Provider and are usually referred to by the acronym SP.

The following steps need to performed on $sp_host with root privileges.

Configure the Mellon SP

Install the necessary packages

You will need:

  1. The Apache Web Server (httpd)
  2. The Mellon SAML SP add-on module for Apache
  3. Tools to create X509 certificates

Do this:

yum install httpd mod_auth_mellon mod_ssl openssl

Create a configuration directory for Apache SAML

It is advisable to keep configuration files related to Apache's use of SAML in one location. We will create a new directory saml2 located under the Apache configuration root /etc/httpd.

Do this:

mkdir /etc/httpd/saml2

Configure the Mellon SP

Configuration for Apache add-on modules are located in the directory /etc/httpd/conf.d and have a file name extension of .conf. We will add the file /etc/httpd/conf.d/mellon.conf and place Mellon's configuration directives in it.

Mellon's configuration directives can roughly be broken down into two classes of information:

1. What URL's to protect with SAML authentication
2. What SAML parameters will be used when a protected URL is referenced.

Apache configuration directives typically follow a hierarchical tree structure in URL space, these are known as locations. You will need to specify one or more URL locations that Mellon will protect. You have flexibility in how you add the configuration parameters that will apply to each location. You can either add all the necessary parameters to the location block or you can add Mellon parameters to a common location high up in the URL location hierarchy that specific protected locations will inherit (or some combination of the two). Since it is common for a SP to operate the same way no matter which location triggers SAML actions our example configuration will place common Mellon configuration directives in the root of the hierarchy and then specific locations to be protected by Mellon can be defined with minimal directives which avoids duplicating the same parameters for each protected location.

Our example will have just one protected location https://$sp_host/protected.

Do this:

Create the file /etc/httpd/conf.d/mellon.conf with this content:

<Location / >
    MellonEnable info
    MellonEndpointPath /mellon/
    MellonSPMetadataFile /etc/httpd/saml2/mellon_metadata.xml
    MellonSPPrivateKeyFile /etc/httpd/saml2/mellon.key
    MellonSPCertFile /etc/httpd/saml2/mellon.crt
    MellonIdPMetadataFile /etc/httpd/saml2/idp_metadata.xml
</Location>

<Location /private >
    AuthType Mellon
    MellonEnable auth
    Require valid-user
</Location>

Note, some of the files referenced in the above will be created in later steps.

Create the SP Metadata

In SAML IdP's and SP's learn about each other by exchanging SAML metadata. SAML metadata is XML. The schema for the metadata is a standard thus assuring participating SAML entities can consume each others metadata. We will need:

1. Metadata for the IdP our SP will utilize
2. Metadata describing our SP provided to the IdP

One of the components of SAML metadata are X509 certificates. These certificates are used for two purposes:

1. Sign SAML messages so the other end can prove the message
   originated from the expected party.
2. Encrypt the message during transport (seldom used because SAML
   messages typically occur on TLS protected transports)

You can use your own certificates if you already have a Certificate Authority (CA) or you can generate a self-signed certificate. For simplicity in our example we will use a self-signed certificate.

Because Mellon's SP metadata must reflect the capabilities of the installed version of mod_auth_mellon, must be valid SP metadata XML and must contain an X509 certificate (whose creation can be obtuse unless you're familiar with X509 certificate generation) the most expedient way to produce the SP metadata is to use a tool included in the mod_auth_mellon package (mellon_create_metadata.sh). The generated metadata can always be edited later because it is a simple text file. The tool will also create your X509 key and certificate.

SAML IdP's and SP's identify themselves via a unique name known as an EntityID. To use the Mellon metadata creation tool will will need:

1. The EntityID (typically the URL of the SP, often the URL of the
   SP where the SP metadata can be retrieved).
2. The URL where SAML messages for the SP will be consumed. Mellon
   calls this the MellonEndPointPath.
We will do the following::
  1. Create a few helper shell variables
  2. Invoke the Mellon metadata creation tool
  3. Move the generated files to their destination (referenced in /etc/httpd/conf.d/mellon.conf created above).

Do this:

fqdn=`hostname`
mellon_endpoint_url="https://${fqdn}/mellon"
mellon_entity_id="${mellon_endpoint_url}/metadata"
file_prefix="$(echo "$mellon_entity_id" | sed 's/[^A-Za-z.]/_/g' | sed 's/__*/_/g')"

/usr/libexec/mod_auth_mellon/mellon_create_metadata.sh $mellon_entity_id $mellon_endpoint_url

mv ${file_prefix}.cert /etc/httpd/saml2/mellon.crt
mv ${file_prefix}.key /etc/httpd/saml2/mellon.key
mv ${file_prefix}.xml /etc/httpd/saml2/mellon_metadata.xml

Add the Mellon SP to the Red Hat Single Sign-On IdP

We assume the Red Hat Single Sign-On IdP has already been installed on the $idp_host.

Red Hat Single Sign-On supports multiple tenancy where all users, clients, etc. are grouped in what is called a realm. Each realm is independent of each other. You can use an existing realm in your Red Hat Single Sign-On but for our example we will create a new realm called test_realm and utilize that.

All these operations will be performed using the Red Hat Single Sign-On administration web console. You will need to know the admin username and password for $idp_host.

Open Admin Console

Open Admin Console and logon by entering the admin username and password.

screenshots/admin_login.png

Create realm "test_realm"

After logging into the admin console there will be a current realm. When Red Hat Single Sign-On is first set up there is always a root realm called master. The existing realms are available in the upper left corner of the admin console in a drop down list. To create a new realm hover your mouse over the realm drop down list and select Add realm

screenshots/create_realm.png

Enter test_realm into the Name field and click Create.

screenshots/create_test_realm.png

Add the Mellon SP as a client of the realm

In Red Hat Single Sign-On SAML SP's are known as clients. To add the SP we must be in the Clients section of the realm. Click on the Clients menu item on the left hand side.

screenshots/select_realm_clients.png

In the clients panel click on the Create button in the upper right hand corner to create a new client.

screenshots/create_new_realm_client.png

Add the Mellon SP Client

You will need to:

  1. Set the client protocol to SAML by selecting saml from the Client Protocol drop down list.
  2. Provide the Mellon SP metadata file we created above (/etc/httpd/saml2/mellon_metadata.xml). Depending on where you running your browser from you may have to copy the SP metadata from from $sp_host to the machine you're running your browser on so the browser can find the file.
  3. Click on the Save button.
screenshots/add_sp_client.png

Edit Client

There are several client configuration parameters we suggest setting:

1. Make sure "Force POST Binding" is On
2. Add paosRespone to "Valid Redirect URIs" by copying the postResponse URL
   in "Valid Redirect URIs", paste it into the empty add text fields
   just below with the "+" button, change "postResponse" to "paosResponse".
   The paosResponse URL is needed for SAML ECP.
3. Click ``Save`` button at bottom.

Many SAML SP's determine authorization based on a user's membership in a group. The Red Hat Single Sign-On IdP can manage user group information but it won't supply the user's groups unless we configure the IdP to supply it as a SAML attribute. To do this Click on Mappers tab of the client

screenshots/select_client_mappers.png

Add a new mapper by clicking on the Create button in the upper right corner of the Mappers page.

screenshots/click_create_client_mapepr.png

Then:

1. Select "Group list" from the ``Mapper Type`` drop down list
2. Set Name to "group list"
3. Set SAML attribute name to "groups"
4. Click ``Save`` button at bottom

As in below:

screenshots/edit_client_group_list_mapper.png

Back to the SP host

The remaining steps occur on $sp_host.

Retrieve IdP metadata

Now that we've created the realm on the IdP we need to retrieve the IdP metadata associated with it so the Mellon SP knows about it. In the /etc/httpd/conf.d/mellon.conf we created above we specified the MellonIdPMetadataFile as /etc/httpd/saml2/idp_metadata.xml but until now that file hasn't existed on $sp_host. To get that file we will retrieve it from the IdP.

Do this substituting $idp_host with the correct value:

curl -k -o /etc/httpd/saml2/idp_metadata.xml \
https://$idp_host/auth/realms/test_realm/protocol/saml/descriptor

Restart Apache

Mellon is now fully configured. In order for Mellon to pick up the configuration we just established we must restart Apache. To make sure we do not have any syntax errors in the Apache conf files we've edited that might prevent Apache from starting correctly it's a good idea to validate the configuration before restarting the server.

To run a syntax check for Apache config files do this:

apachectl configtest

Note, configtest is equivalent to the -t argument to apachectl. If the config test shows any errors correct them at this time.

Now restart the Apache server:

systemctl restart httpd.service

Congratulations! You've now setup both Red Hat Single Sign-On as a SAML IdP in the test_realm and mod_auth_mellon as SAML SP protecting the URL $sp_host/protected (and everything beneath it) by authenticating against the $``$idp_host`` IdP.