NetID Login Service - Shibboleth Service Provider Configuration File (shibboleth2.xml)

This document gives the basic example of a Shibboleth SP configuration file and explains the important elements within it.

Overview

The NetID Login Service which runs on Shibboleth is UW Madison's central Authentication and Authorization service. Application administrators around campus can integrate their web-based applications with NetID Login Service and do not have to worry about setting up their own system.

SPConfig:

The SPConfig element is the top level element of the shibboleth2.xml file.

Shibboleth documentation: SPConfig

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
    clockSkew="180">

    <OutOfProcess tranLogFormat="%u|%s|%IDP|%i|%ac|%t|%attr|%n|%b|%E|%S|%SS|%L|%UA|%a" />

ApplicationDefaults:

The ApplicationDefaults element defines most of the runtime behavior of the software when it comes to SAML behavior and application session policy. The ApplicationOverride element is nested within to override behavior for different virtual hosts or paths.

Attributes:

Shibboleth documentation: ApplicationDefaults

    <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
    <ApplicationDefaults entityID="default"
        REMOTE_USER="uid eppn persistent-id targeted-id"
        cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

Sessions:

The Sessions element controls how the SSO (Single Sign On) process is managed by the SP.

Attributes: Child Elements:

Shibboleth documentation: Sessions

        <Sessions lifetime="28800" timeout="1800" relayState="ss:mem" 
        	checkAddress="false" handlerSSL="true" cookieProps="https">

  			<SSO entityID="https://login.wisc.edu/idp/shibboleth">
              SAML2 SAML1
            </SSO>

            <!-- SAML and local-only logout. -->
            <Logout>SAML2 Local</Logout>

            <!-- Administrative logout. -->
            <LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
          
            <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
            <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>

            <!-- Status reporting service. -->
            <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>

            <!-- Session diagnostic service. -->
            <Handler type="Session" Location="/Session" showAttributeValues="false"/>

            <!-- JSON feed of discovery information. -->
            <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
        </Sessions>

Errors:

The Errors element is used to configure error-handling behavior when problems occur during the processing of SSO or logout messages, internal session management, or attribute processing.

Shibboleth documentation: Errors

        <Errors supportContact="admin@yoursite.wisc.edu"
            helpLocation="/about.html"
            styleSheet="/shibboleth-sp/main.css"/>

MetadataProvider:

The MetadataProvider element provides the SP details about how to load metadata about the identity providers. Shibboleth is a 100% metadata-driven SAML implementation and has no other means of provisioning relationships with IdPs.

Attributes: Child Elements:

Shibboleth documentation: MetadataProvider

        <MetadataProvider type="XML" url="https://login.wisc.edu/metadata/wisc-metadata.xml" backingFilePath="login.wisc.edu-metadata.xml"  reloadInterval="7200">     
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>     
            <MetadataFilter type="Signature" certificate="login.wisc.edu-signing.pem"/>     
        </MetadataProvider>

AttributeExtractor:

The AttributeExtractor element configures how SAML attributes are decoded.

Attributes:

Shibboleth documentation: AttributeExtractor

        <!-- Map to extract attributes from SAML assertions. -->
        <AttributeExtractor type="XML" validate="true" url="https://login.wisc.edu/metadata/attribute-map.xml" 
       		backingFilePath="login.wisc.edu-attribute-map.xml" reloadInterval="1800"/>

AttributeFilter:

The AttributeFilter element configures the component that filters out unacceptable attribute information.

Attributes:

Shibboleth documentation: AttributeFilter

        <!-- Default filtering policy for recognized attributes, lets other data pass. -->
        <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>

CredentialResolver:

The CredentialResolver element configures the component that provides the SP with access to public and private keys and certificates or credentials. Keys are used to sign messages sent to IDPs or authenticate TLS connections, and to decrypt data sent to the SP.

Attributes:

Shibboleth documentation: CredentialResolver

        <!-- Simple file-based resolvers for separate signing/encryption keys. -->
        <CredentialResolver type="File" use="signing"
            key="sp-signing-key.pem" certificate="sp-signing-cert.pem"/>
        <CredentialResolver type="File" use="encryption"
            key="sp-encrypt-key.pem" certificate="sp-encrypt-cert.pem"/>

ApplicationOverride

The ApplicationOverride element overrides SP behaviour for a set of resources that are associated with the override using the applicationId content setting. The association can be made via the RequestMapper component or native web server commands as in Apache.

Shibboleth documentation: ApplicationOverride

         <ApplicationOverride id="https://www.yoursite.wisc.edu/shibboleth" entityID="https://www.yoursite.wisc.edu/shibboleth">
            <Sessions lifetime="28800" timeout="1800" checkAddress="false" consistentAddress="false" relayState="ss:mem" handlerURL="/Shibboleth.sso" cookieProps="https">
                <SSO entityID="https://login.wisc.edu/idp/shibboleth">
                    SAML2 SAML1
                </SSO>
            </Sessions>
        </ApplicationOverride>
	</ApplicationDefaults>

SecurityPolicyProvider

The SecurityPolicyProvider element configures the component that guides the low-level security and XML processing performed during the runtime operation of the SP. This shouldn't need to be modified.

Attribute:

Shibboleth documentation: SecurityPolicyProvider

	<!-- Policies that determine how to process and authenticate runtime messages. -->
	<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>

ProtocolProvider:

No Documentation. This configuration does not require any changes.

	<!-- Low-level configuration about protocols and bindings available for use. -->
	<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
</SPConfig>

IIS Specific Elements

InProcess

The InProcess element contains settings governing the portion of the SP that runs inside the web server. Required for Microsoft IIS integrations in order to define IIS site mappings and general module configuration.

Child Elements:

Shibboleth documentation: InProcess

<InProcess>
    <ISAPI safeHeaderNames="true">
        <Site id="0" name="www.yoursite.wisc.edu"/>
    </ISAPI>
</InProcess>

RequestMapper

The RequestMapper element configures the component used by the SP to map incoming requests to the configuration options that should be applied to them. This is equivalent to the Apache Location directive.

Shibboleth documentation: RequestMapper

<RequestMapper type="Native">
    <RequestMap applicationId="default">
        <Host name="www.yoursite.wisc.edu" applicationId="https://www.yoursite.wisc.edu/shibboleth" requireSession="true"/>
    </RequestMap>
</RequestMapper>