Documentation

Table of Contents

Support Links

SecureAuth Customer Support and Services

SecureAuth Service Status

Knowledge Base Articles

Introduction

Use this guide to enable Multi-Factor Authentication access via SAML 2.0 to the Apache HTTP Server using Shibboleth SP.

Prerequisites

1. Have an Apache HTTP Server running IIS 7.X+

2. Have SecureAuth IdP 7.X+

3. Create a New Realm for the Apache HTTP Server integration

4. Configure the following tabs in the Web Admin before configuring the Post Authentication tab:

  • Overview – the description of the realm and SMTP connections must be defined
  • Data – an enterprise directory must be integrated with SecureAuth IdP
  • Workflow – the way in which users will access this application must be defined
  • Multi-Factor Methods – the Multi-Factor Authentication methods that will be used to access this page (if any) must be defined
Apache Configuration Steps

1. Read the NativeSPWindowsInstall Article

https://wiki.shibboleth.net/confluence/x/K4FC

2. Download the Shibboleth SP .msi file

http://shibboleth.net/downloads/service-provider/2.5.3/win64/shibboleth-sp-2.5.3-win64.msi

3. Install the .msi file on the client (application web server)

Do NOT install the .msi file on the SecureAuth IdP server

4. Reboot

IIS Configuration Steps
5. After rebooting, configure IIS for basic support

 

1. Add the filter using the IIS Manager console

2. At either the top-level or individual Site level, select the ISAPI Filters feature

3. Add a new filter called Shibboleth and specify the lib\shibboleth\isapi_shib.dll library

For v2.5+ on a 64-bit IIS, the relative path is lib64\shibboleth\isapi_shib.dll

4. Map the *.sso file extension to the ISAPI library so that virtual URLs can be specified to invoke the extension handler for each web site

This is done under Handler Mappings using the Add Script Map... action

The Executable box should point to isapi_shib.dll, and the Extension can be set to anything unlikely to conflict, but *.sso is assumed (and the asterisk and dot must be included)

a. Configure Request Restrictions for the handler mapping to permit the handler to execute for all requests that match the extension

b. While still in the Add Script Map dialog, click on Request Restrictions

c. In the Mapping Tab, un-check the option labeled Invoke handler only if request is mapped to...

If checked, the handler will activate only for real files or folders matching the extension instead of activating on all requests, regardless of whether the file exists
(After saving the script map, the Path Type column for the new handler in the Handler Mappings list should be Unspecified)

5. Under ISAPI and CGI Restrictions at the top level, add the Shibboleth ISAPI Extension to the list of permitted extensions in the list of allowed extensions

6. Restart IIS

Basic IIS and Shibboleth configuration information

 

IIS error settings

  • Configure IIS to suppress error responses the SP returns to the browser and use its own error pages instead, since the default error pages include a large indicator of the error status (such as a 500) which makes debugging problems difficult

Modify the Error Pages setting in the IIS administrative UI by clicking "Edit Feature Settings..." and selecting "Detailed errors" on the right hand side

  • If using the 32-bit version with 64-bit Windows and receiving 500 error messages, edit advanced settings to enable 32-bit applications for the IIS application pool in use, in order to load the software

Conversely, using the 64-bit version with 32-bit applications will also fail and therefore requires advanced settings to be edited in order to enable 64-bit applications for the IIS application pool in use

IIS permission settings

Permissions to your installation directory may need to be added in order for IIS to operate

  • Failure to set permissions may result in crashes, which might be caused by the filter failing to load
  • Processes running on the IIS server need read access to most of the installation, with the exception of the Shibboleth private key file(s)
  • Write access is needed to \var\log\shibboleth to create the native.log file

(IIS 7.X appears to rely largely on accounts that live in the "IUSRS" Windows group, so giving that group read access to the installation may be helpful or essential)

Shibboleth configuration

To configure Shibboleth, have on hand the site identifier that IIS assigned to your website

  • If using the default website, this identifier is 1 (one)
  • If not using the default website, the identifier can be found via the IIS Manager tool by selecting the "Web Sites" folder and looking in the identifier column (on the right) that corresponds to your website
     

The amount of configuration the SP needs in order to communicate with a new SecureAuth IdP depends on how much special treatment SecureAuth IdP requires compared to the default settings

At minimum, simply add the IdP's metadata to a metadata file referenced by a <MetadataProvider> from shibboleth2.xml

6. Start the Shibboleth Service from the command line 

c:\> sc start shibd_default

Shibboleth Service Information

  • The filter that is plugged into the web server connects to the shibd process which processes the SAML assertion
  • The primary configuration file for the filter and the Shibboleth daemon, shibd, is located at \etc\shibboleth\shibboleth2.xml (within the directory used to install the SP software)
  • shibd creates its own log at \var\log\shibboleth\shibd.log and must have appropriate read and write permissions itself for the entire installation directory
SecureAuth IdP Configuration Steps
Post Authentication

 

1. Select SAML 2.0 (SP-initiated) Assertion from the Authenticated User Redirect dropdown in the Post Authentication tab in the Web Admin

2. An unalterable URL will be auto-populated in the Redirect To field, which will append to the domain name and realm number in the address bar (Authorized/SAML20SPInit.aspx)

SAML Assertion / WS Federation

 

3. Set the SAML Consumer URL to the Fully Qualified Domain Name (FQDN) of the Apache server, followed by /nameofiisapplication/Shibboleth.sso, e.g. https://www.company.com/someiisapplication/Shibboleth.sso

4. Provide the Domain in order to Download the Metadata File to send to Apache (if required)

The SAML Issuer should match the entity ID in shibboleth2.xml and the idpmetadata file on the client

Ensure the <SSO> entity ID matches in shibboleth2.xml and the SecureAuth IdP metadata file


Click Save once the configurations have been completed and before leaving the Post Authentication page to avoid losing changes