The Shibboleth V1 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.

IdPMainConfig

Owned by Scott Cantor
Last updated: Oct 22, 2007 by Former user (Deleted)Version comment
5 min read
<?xml version="1.0" encoding="ISO-8859-1"?>

<!-- Shibboleth Identity Provider configuration -->

	<IdPConfig
	xmlns="urn:mace:shibboleth:idp:config:1.0"
	xmlns:cred="urn:mace:shibboleth:credentials:1.0"
	xmlns:name="urn:mace:shibboleth:namemapper:1.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="urn:mace:shibboleth:idp:config:1.0 ../schemas/shibboleth-idpconfig-1.0.xsd"
	AAUrl="https://idp.example.org:8443/shibboleth-idp/AA"
	resolverConfig="$IDP_HOME$/etc/resolver.xml"
	defaultRelyingParty="urn:mace:shibboleth:examples"
	providerId="https://idp.example.org/shibboleth">


	<!-- This section contains configuration options that apply only to a site or group of sites
		This would normally be adjusted when a new federation or bilateral trust relationship is established -->
	<RelyingParty name="urn:mace:shibboleth:examples" signingCredential="example_cred"> <!-- (signingCredential) must correspond to a <Credential/> element below -->
		<NameID nameMapping="shm"/> <!-- (nameMapping) must correspond to a <NameMapping/> element below -->
	</RelyingParty>

	<!-- Configuration for the attribute release policy engine
		For most configurations this won't need adjustment -->
	<ReleasePolicyEngine>
		<ArpRepository implementation="edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository">
			<Path>$IDP_HOME$/etc/arps/</Path>
		</ArpRepository>
	</ReleasePolicyEngine>


	<!-- Logging Configuration
		The defaults work fine in this section, but it is sometimes helpful to use "DEBUG" as the level for
		the <ErrorLog/> when trying to diagnose problems -->
	<Logging>
		<ErrorLog level="WARN" location="$IDP_HOME$/logs/shib-error.log" />
		<TransactionLog level="INFO" location="$IDP_HOME$/logs/shib-access.log" />
	</Logging>
	<!-- Uncomment the configuration section below and comment out the one above if you would like to manually configure log4j -->
	<!--
	<Logging>
		<Log4JConfig location="file:///tmp/log4j.properties" />
	</Logging> -->


	<!-- This configuration section determines how Shibboleth maps between SAML Subjects and local principals.
		The default mapping uses shibboleth handles, but other formats can be added.
		The mappings listed here are only active when they are referenced within a <RelyingParty/> element above -->
	<NameMapping
		xmlns="urn:mace:shibboleth:namemapper:1.0"
		id="shm"
		format="urn:mace:shibboleth:1.0:nameIdentifier"
		type="SharedMemoryShibHandle"
		handleTTL="28800"/>


	<!-- Determines how SAML artifacts are stored and retrieved
		The (sourceLocation) attribute must be specified when using type 2 artifacts -->
	<ArtifactMapper implementation="edu.internet2.middleware.shibboleth.artifact.provider.MemoryArtifactMapper" />


	<!-- This configuration section determines the keys/certs to be used when signing SAML assertions -->
	<!-- The credentials listed here are used when referenced within <RelyingParty/> elements above -->
	<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
		<FileResolver Id="example_cred">
			<Key>
				<Path>$IDP_HOME$/etc/idp-example.key</Path>
			</Key>
			<Certificate>
				<Path>$IDP_HOME$/etc/idp-example.crt</Path>
			</Certificate>
		</FileResolver>
	</Credentials>


	<!-- Protocol handlers specify what type of requests the IdP can respond to.  The default set listed here should work
		for most configurations.  Modifications to this section may require modifications to the deployment descriptor -->
	<ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.ShibbolethV1SSOHandler">
		<Location>https?://[^:/]+(:(443|80))?/$IDP_WEBAPP_NAME$/SSO</Location> <!-- regex works when using default protocol ports -->
	</ProtocolHandler>
	<ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.SAMLv1_AttributeQueryHandler">
		<Location>.+:8443/$IDP_WEBAPP_NAME$/AA</Location>
	</ProtocolHandler>
	<ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.SAMLv1_1ArtifactQueryHandler">
		<Location>.+:8443/$IDP_WEBAPP_NAME$/Artifact</Location>
	</ProtocolHandler>
	<ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.Shibboleth_StatusHandler">
		<Location>https://[^:/]+(:443)?/$IDP_WEBAPP_NAME$/Status</Location>
	</ProtocolHandler>


	<!-- This section configures the loading of SAML2 metadata, which contains information about system entities and
		how to authenticate them.  The metadatatool utility can be used to keep federation metadata files in synch.
		Metadata can also be placed directly within this these elements. -->
	<MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
                uri="$IDP_HOME$/etc/example-metadata.xml"/>
</IdPConfig>

Element Details

<IdPConfig xmlns="urn:mace:shibboleth:idp:config:1.0"
	xmlns:cred="urn:mace:shibboleth:credentials:1.0"
	xmlns:name="urn:mace:shibboleth:namemapper:1.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="urn:mace:shibboleth:idp:config:1.0 shibboleth-idpconfig-1.0.xsd"
	defaultRelyingParty="_URI_"
	providerID="_URI_"
	AAUrl="_URL_"
	authHeaderName="_string_"
	defaultAuthMethod="_URN_"
	maxSigningThreads="_integer_"
	passThruErrors="_true/false_"
	resolverConfig="_pathname_">

This is the primary element of an IdP.xml file and is the container for every other element. It must appear once and only once. For most deployments, all the xmlns attributes, which specify the handlers for different aspects of internal IdP operation, should remain unchanged. The mandatory attributes must be changed before the IdP will successfully interoperate with other sites.

  • defaultRelyingParty: This specifies the relying party to use for a request when no RelyingParty element's name attribute matches the policy URI of an incoming request. Typically, this will be populated with the URI of a federation. This must have a corresponding RelyingParty element or the IdP will fail to start.
  • providerID: The IdP uses this unique name to identify itself and the assertions it issues. This will usually be assigned by a federation.
  • AAUrl is provided for backward compatibility with Shibboleth 1.1. It directly specifies the URL used to access the attribute query handler (the AA) for older versions of Shibboleth. Versions 1.2 and higher retrieve this information from metadata.
  • authHeaderName: If the local user name is passed to the SSO handler using an HTTP header variable other than the default, REMOTE_USER, the name of the variable may be specified here.
  • defaultAuthMethod: This specifies the authentication method that will be assumed if none is passed through in the SAMLAuthenticationMethod header variable and there is no overriding defaultAuthMethod specified for this particular service provider using a RelyingParty element. If not specified using one of these mechanisms, a default value of urn:oasis:names:tc:SAML:1.0:am:unspecified will be used. Some common authentication methods and corresponding URI's are listed below; for a complete list, please consult section 7.1 of the SAML 1.1 core specifications or your federation's guidelines.

    urn:oasis:names:tc:SAML:1.0:am:password

    The authentication was performed using a password.

    urn:ietf:rfc:1510

    The authentication was performed using Kerberos.

    urn:oasis:names:tc:SAML:1.0:am:X509-PKI

    The authentication was performed using a certificate and key issued to the end user. More specific forms of PKI authentication such as SPKI and XKMS are also assigned URN's in the SAML specs.

  • maxSigningThreads: This attribute places a limit on the number of threads the IdP will spawn and may be useful for limiting the load of signing and other operations and improving performance. This should be correlated with similar throttles in Apache and Tomcat.
  • passThruErrors: This boolean attribute determines whether the IdP will relay errors in flows to SP's for use in displaying these errors to the browser in the case of an unsuccessful transaction.
  • resolverConfig specifies the location of the configuration file for the resolver the IdP uses to build attributes and if unspecified defaults to /conf/resolver.xml. Detailed information is available on configuring resolver.xml itself.

Protocol Handlers

The Shibboleth Identity Provider's capability to handle requests is divided into a set of protocol handlers that respond to different types of external calls to support the Shibboleth architecture and requests from other SAML-based applications. There are four main protocol handlers bundled with Shibboleth 1.3, each of which must be called out in a ProtocolHandler element to be functional. Each of these elements in turn contains one or more Location element specifying the URL's which that particular protocol handler will respond on. Some of these locations specified must match those protected by Apache and passed through mod_jk in order to function properly in some deployment setups.

A separate handler has been written to handle SSO requsts for eAuth compliance.

<ProtocolHandler implementation="classname">

Example:

<ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.ShibbolethV1SSOHandler">
	<Location>https?://[^:/]+(:(443|80))?/$IDP_WEBAPP_NAME$/SSO</Location>
</ProtocolHandler>

This element defines an individual protocol handler referenced by the classname of the Java class implementing it. Additional attributes may be specified for particular protocol handlers as part of this element. The following protocol handlers are bundled with Shibboleth v1.3:

  • edu.internet2.middleware.shibboleth.idp.provider.SAMLv1_AttributeQueryHandler : Requests for attribute release based on handles or other principal identification are handled by the attribute query handler. The contained <Location> element must be protected by https:// and Apache in order to properly authenticate requesting entities.
  • edu.internet2.middleware.shibboleth.idp.provider.SAMLv1_1ArtifactQueryHandler : Artifacts are created, stored, and passed by the artifact query handler. The contained <Location> element defines the base URL at which artifacts will be stored and must be protected by https:// for a variety of security and confidentiality reasons.
  • edu.internet2.middleware.shibboleth.idp.provider.ShibbolethV1SSOHandler : The SSO handler is responsible for generating authentication assertions and handles in response to authentication requests. The contained <Location> should always be protected by https:// and Apache in order to protect login information from various attacks. The credentials used to do this may differ from those used to handle interactions with other Shibboleth components due to the browser interaction required.
  • edu.internet2.middleware.shibboleth.idp.provider.E_AuthSSOHandler : This special protocol handler allows for backward compatibility with SAML 1.0, is eAuth compliant, and interoperates successfully with all other eAuth compliant products.
<Location>URL</Location>

This element specifies a URL on which the encapsulating <ProtocolHandler> will listen.