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.

Signing Certificate

The signing certificate for the SP can be retrieved at https://login.wisc.edu/metadata/login.wisc.edu-signing.pem

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:

  • entityID: Set to the entity id for your app. This is usually in the format of "https://[hostname.for.site]/shibboleth".
  • REMOTE_USER: Specifies a list of attribute IDs to pull from in a session's cached attributes; the first one found with a value is set as REMOTE_USER.

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:

  • lifetime: Maximum duration in seconds that a session maintained by the SP will be valid. The actual time may be less than this value (if an IdP indicates it should be shorter) but will never be longer. Note that this will not influence sessions maintained by an application.
  • timeout: Maximum inactivity allowed in seconds between requests in a session maintained by the SP. This inactivity applies only to requests to this SP and is not aware of activity between the browser and other web sites.
  • relayState: Controls how information associated with requests for authentication, primarily the original resource accessed, is preserved for the completion of the authentication process. It is recommended to use the SP's persistent storage. "ss:mem" stores it in the SP's internal memory, which works well.
  • checkAddress: The IdP will place the IP address of the user agent it authenticated into the assertions it issues. When true, the SP will check this address against the address of the client presenting an assertion before creating a session.
  • handlerSSL: When true, only web requests over SSL/TLS will be processed by handlers. Other requests may be blocked, or possibly ignored.
  • cookieProps: If set to a custom string, the string is appended to the cookie values maintained by the SP. Used to attach custom meta-properties like path or the secure and HttpOnly flags to the cookies.

Child Elements:

  • SSO: Enables support for one or more Single Sign-On / Authentication protocols.
  • Logout: Enables support for one or more Logout protocols.
  • Handler: Generic endpoint for non-specific functionality implemented by the SP or an extension library.

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:

  • type: Determines which type of metadata plugin to use. Here, XML directs the SP to load metadata from a file or HTTP resource.
  • url: Remote location of an XML resource containing the required configuration.
  • backingFilePath: If a url attribute is used, the downloaded resource is copied to this location. If the software is started and the remote resource is unavailable or invalid, the backing file is loaded instead.
  • reloadInterval: If a url attribute is used, this attribute sets the time between attempts to download a fresh copy of the resource.

Child Elements:

  • MetadataFilter: Configures a filter that examines metadata supplied by a metadata provider and adds, modifies, or deletes information depending on the filter's behavior.

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>Wisconsin Federation MetadataProvider

AttributeExtractor:

The AttributeExtractor element configures how SAML attributes are decoded.

Attributes:

  • type: Specifies the type of AttributeExtractor plugin to use.
  • url: Remote location of an XML resource containing the IDP attribute map.
  • backingFilePath: If a url attribute is used, the downloaded resource is copied to this location. If the software is started and the remote resource is unavailable or invalid, the backing file is loaded instead.
  • reloadInterval: If a url attribute is used, this attribute sets the time between attempts to download a fresh copy of the resource.

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:

  • type: Specifies the type of AttributeFilter plugin to use.

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:

  • type: Specifies the type of CredentialResolver plugin to use.

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:

  • type: implements a custom XML syntax for expressing security processing and policy rules for different protocols and profiles, and for enabling and disabling algorithms.

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>

Example Apache2 Service Provider

https://git.doit.wisc.edu/netid-login-external/netid-login-integration-examples/-/blob/login-prod/etc/shibboleth/shibboleth2.xml

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:

  • ISAPI: Controls the Integration with the Microsoft IIS web server, ignored by other modules.

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>