Summary

This document will guide you through the steps to enable multi-factor authentication and Single-Sign On for web based applications on IIS with server variables by using Shibboleth SP.

System Requirements

• PhenixID Authentication Server 2.0 or higher
• IIS server installed
• The IIS server must be reached from clients and IDP over HTTPS (443).
• Make sure the IIS server has a binding for https on localhost

Instruction

Overview

This document will guide you through the steps to enable multi-factor authentication and Single-Sign on for server variable aware web applications.

PhenixID Authentication Server acting as SAML IdP

1. Setup PhenixID Authentication Services as a SAML IdP. Documentation can be found here
2. Verify your SAML IdP metadata by going to the URL:
   https://<YourServerDomainName>/saml/authenticate/<authenticator_alias>?getIDPMeta
   If needed, download the metadata to a xml file.

Configure Shibboleth SP

Install Shibboleth SP

1. Download the latest version of the Windows installer package from the Shibboleth Project site, selecting the appropriate install file directory for your system. You will need to download the .msi file.
2. Run the appropriate installer, accepting the default settings. When the installer is complete, it will prompt you to restart the machine.

Configure IIS

1. In Control Panel, open Administrative Tools > Services. The Shibboleth service (Shibboleth 2 Daemon) should have Service = Started, Startup Type = Automatic and Logon As = Local System as the settings.
2. Open IIS Manager and verify that the Shibboleth ISAPI filter is installed.
   1. Click the server name and open ISAPI Filters. The settings should be Name = Shibboleth and Executable = C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll for a 64-bit install.
   2. Configure this manually if missing.
      
3. Still in IIS Manager, verify that the Shibboleth ISAPI filter is mapped to the .sso extension.
   1. Click the server name and open Handler Mappings. The settings should be Path =*.sso, State = Enabled, Path Type = Unspecified, Handler = IsapiModule, Entry Type = Local.
   2. Configure this manually if missing by following this instruction:
      Click Add Script Map in the Action pane and filling in the dialog box to match the server, with Request path = *.sso and Executable = C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll for a 64-bit install. The Name field can be anything you like.
4. Still in IIS Manager, verify that the handler mapping inheritance properly cascaded down to the website level.
   1. Click the website name under Sites, then open Handler Mappings. The settings should be Path =*.sso, State = Enabled, Path Type = Unspecified, Handler = IsapiModule, and Entry Type = Inherited.
   2. If the *.sso entry mapping is missing, you will need to create it.
5. in a web browser on the server, go to the case-sensitive URL https://localhost/Shibboleth.sso/Status, but do not substitute your server’s full domain name in place of /localhost/. If everything is properly configured, it should return an XML document with <Status><OK/></Status> at the bottom.

Configure Shibboleth SP

Configure SP

1. Open shibboleth2.xml
   c:/opt/shibboleth-sp/etc/shibboleth/shibboleth2.xml
2. Change the <InProcess>- and <RequestMapper>-tags so they look similar to the example below. Make sure to set correct values for Site ID and name.

3. <InProcess>
       <ISAPI normalizeRequest="true" safeHeaderNames="true">
         <Site id="3" name="service1.company.org"/>
         <!-- <Site id="4" name="service2.company.org"/> -->
       </ISAPI>
   </InProcess>

4. <RequestMapper type="Native">
      <RequestMap>
         <Host name="service1.company.org" applicationId="service1" authType="shibboleth" requireSession="true">
         <!-- <Host name="service2.company.org" applicationId="service2" authType="shibboleth" requireSession="true"> -->
         </Host>
      </RequestMap>
   </RequestMapper>

5. Add the following between the <CredtentialResolver> and </ApplicationDefaults>-tags. Make sure the id matches the applicationId and entityID matches the SPs entityID.

6. <ApplicationOverride id="service1" entityID="https://service1.company.org/shibboleth"/>
   <!-- <ApplicationOverride id="service2" entityID="https://service2.company.org/shibboleth"/> -->

7. Configure how the IdP-metadata should be consumed by configuring the <MetadataProvider>-tag.
   1. URL example: <MetadataProvider type=”XML” validate=”true”
      url=”http://federation.org/federation-metadata.xml” />
   2. File example: <MetadataProvider type=”XML” validate=”true” path=”idp.xml”/>
      1. In this case the file idp.xml is placed in the c:/opt/shibboleth-sp/etc/shibboleth/ folder
8. Find the <SSO tag in the file and add your IDP to allowed IDP

9. <SSO entityID="<EntityID of your IDP>">
     SAML2
   </SSO>

10. OPTIONAL – Adjust the element “Sessions” If a local logout, including a redirect is supposed to be made, example

11. <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
    checkAddress="false" handlerSSL="false" cookieProps="http"
    redirectLimit="exact+whitelist" redirectWhitelist="https://idp.company.local/saml/authenticate/logout/">

12. Save the file.

Attribute mapping

The file attribute-map.xml in the same folder as shibboleth2.xml controls which SAML assertion attributes should be added as server variables.

1. To add an attribute mapping, simply add this to the file.

2. <Attribute name="<attribute_name_in_attribute_statement_of_saml_assertion" id="target_http_header_name">
           <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
   </Attribute>

3. Example:

4. <Attribute name="sAMAccountName" id="userid">
           <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
   </Attribute>

5. Save the file.
6. Restart shibboleth sp service in services.msc.
7. Start and elevated command promt and do an iisreset.

Import SP-metadata to IdP

1. Open PhenixID Configuration Manager and login
2. Go to Scenarios->Federation
3. Click the plus next to SAML Metadata upload
4. Enter a display name = “Shibboleth SP“
5. Use this URL to retrieve the Shibboleth SP SAML 2 metadata xml:
   https://<shibboleth_server>/Shibboleth.sso/Metadata

Test

1. Browse to https://<shibboleth_server>/[path to application]/
2. This should result in a redirect to PhenixID Authentication server
3. Authenticate
4. If authentication was successful, a redirect to application should occur (with SAML assertion converted to server variables)
5. The user should now be logged in.

Verify

Check which headers are forwarded to the Federation application
https://<shibboleth_server>/Shibboleth.sso/Session

If you want to see the content of the attributes, change the parameter showAttributeValues in shibboleth2.xml to true.

Logout

In order to logout from the Federation application, please use this link:
https://<shibboleth_server>/Shibboleth.sso/Logout