URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/reconfigure-sp.html Author: Lukas Haemmerle - SWITCH $Date: 2007/03/09 16:11:21 $ $Revision: 1.4 $
This guide describes how to configure a Service Provider for the AAI Test Federation.
Note: For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the Deployment section of the SWITCHaai website (http://www.switch.ch/aai/).
The installation and configuration guides found in the technical information section were written specifically for the SWITCHaai Federation. However, if you want to do some tests or development work using Shibboleth, we strongly recommend to carry out these tests or development works in the AAI Test Federation, which mainly exists for this purpose. While SWITCHaai shouldn't contain any test users whatsoever, the AAI Test Federation is much less restrictive concerning this and other issues.
The example values used in this guide are:
As indicated in the title, this guide assumes that you already configured your Service Provider as described in the technical information section. It is assumed that the installation for the SWITCHaai Federation works, but chances are small that the IdP worked without testing. However, this is not much of a problem because the debugging procedure is the same in AAI Test as in SWITCHaai.
Basically, you can use the same certificates in the AAI Test Federation as in the SWITCHaai Federation with one difference. In the AAI Test Federation one also can use a certificate by the AAI Test CA, which is used for test purposes.
Read the AAI Test CA page on how to get a certificate signed by this CA.
Change all the red lines to the given values in the Shibboleth configuration file /etc/shibboleth/shibboleth.xml. The blue lines show values that are specific for your Service Provider or that are somehow specific for SWITCHaai.
<SPConfig xmlns="urn:mace:shibboleth:target:config:1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mace:shibboleth:target:config:1.0 shibboleth-targetconfig-1.0.xsd" clockSkew="180" logger="/etc/shibboleth/shibboleth.logger"> <!-- These extensions are "universal", loaded by all Shibboleth-aware processes. --> <Extensions> <Library path="/opt/shibboleth-1.3/libexec/xmlproviders.so" fatal="true"/> </Extensions> <!-- The Global section pertains to shared Shibboleth processes like the shibd daemon. --> <Global logger="/etc/shibboleth/shibd.logger"> <!-- Only one listener can be defined. --> <UnixListener address="/var/run/shibd.sock"/> <!-- <TCPListener address="127.0.0.1" port="12345" acl="127.0.0.1"/> --> <!-- See deploy guide for details, but: cacheTimeout - how long before expired sessions are purged from the cache AATimeout - how long to wait for an AA to respond AAConnectTimeout - how long to wait while connecting to an AA defaultLifetime - if attributes come back without guidance, how long should they last? strictValidity - if we have expired attrs, and can't get new ones, keep using them? propagateErrors - suppress errors while getting attrs or let user see them? retryInterval - if propagateErrors is false and query fails, how long to wait before trying again Only one session cache can be defined. --> <MemorySessionCache cleanupInterval="300" cacheTimeout="3600" AATimeout="30" AAConnectTimeout="15" defaultLifetime="1800" retryInterval="300" strictValidity="false" propagateErrors="false"/> </Global> <!-- The Local section pertains to resource-serving processes (often process pools) like web servers. --> <Local logger="/etc/shibboleth/native.logger" localRelayState="true"> <!-- To customize behavior, map hostnames and path components to applicationId and other settings. The following provider types are available with the delivered code: type="edu.internet2.middleware.shibboleth.sp.provider.NativeRequestMapProvider" - Web-server-specific plugin that allows native commands (like Apache's ShibRequireSession) to override or supplement the XML syntax. The Apache version also supplies an htaccess authz plugin for all content. type="edu.internet2.middleware.shibboleth.sp.provider.XMLRequestMapProvider" - portable plugin that does not support the older Apache-specific commands and works the same on all web platforms, this plugin does NOT support htaccess files for authz unless you also place an <htaccess/> element somewhere in the map By default, the "native" plugin (the first one above) is used, since it matches older behavior on both Apache and IIS. --> <RequestMapProvider type="edu.internet2.middleware.shibboleth.sp.provider.NativeRequestMapProvider"> <RequestMap applicationId="default"> <!-- This requires a session for documents in /secure on the containing host with http and https on the default ports. Note that the name and port in the <Host> elements MUST match Apache's ServerName and Port directives or the IIS Site name in the <ISAPI> element below. --> <Host name="www.example.ch"> <Path name="secure" authType="shibboleth" requireSession="true" exportAssertion="true"> <!-- Example shows a subfolder on the SSL port assigned to a separate <Application> --> <Path name="admin" applicationId="foo-admin"/> </Path> </Host> </RequestMap> </RequestMapProvider> <Implementation> <ISAPI normalizeRequest="true"> <!-- Maps IIS Instance ID values to the host scheme/name/port/sslport. The name is required so that the proper <Host> in the request map above is found without having to cover every possible DNS/IP combination the user might enter. The port and scheme can usually be omitted, so the HTTP request's port and scheme will be used. <Alias> elements can specify alternate permissible client-specified server names. If a client request uses such a name, normalized redirects will use it, but the request map processing is still based on the default name attribute for the site. This reduces duplicate data entry in the request map for every legal hostname a site might permit. In the example below, only sp.example.org needs a <Host> element in the map, but spalias.example.org could be used by a client and those requests will map to sp.example.org for configuration settings. --> <Site id="1" name="www.example.ch"> <!-- <Alias>www-alias.example.ch</Alias> --> </Site> </ISAPI> </Implementation> </Local> <!-- The Applications section is where most of Shibboleth's SAML bits are defined. Resource requests are mapped in the Local section into an applicationId that points into to this section. --> <Applications id="default" providerId="https://www.example.ch/shibboleth" homeURL="https://www.example.ch/" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"> <!-- Controls session lifetimes, address checks, cookie handling, and the protocol handlers. You MUST supply an effectively unique handlerURL value for each of your applications. The value can be a relative path, a URL with no hostname (https:///path) or a full URL. The system can compute a relative value based on the virtual host. Using handlerSSL="true" will force the protocol to be https. You should also add a cookieProps setting of "; secure" in that case. Note that while we default checkAddress to "false", this has a negative impact on the security of the SP. Stealing cookies/sessions is much easier with this disabled. --> <Sessions lifetime="7200" timeout="3600" checkAddress="false" handlerURL="/Shibboleth.sso" handlerSSL="false" idpHistory="true" idpHistoryDays="7"> <!-- SessionInitiators handle session requests and relay them to a WAYF or directly to an IdP, if possible. Automatic session setup will use the default or first element (or requireSessionWith can specify a specific id to use). Lazy sessions can be started with any initiator by redirecting to it. The only Binding supported is the "urn:mace:shibboleth:sp:1.3:SessionInit" lazy session profile using query string parameters: * target the resource to direct back to later (or homeURL will be used) * acsIndex optional index of an ACS to use on the way back in * providerId optional direct invocation of a specific IdP --> <!-- This default directs users to a specific SWITCHaai WAYF service. --> <SessionInitiator id="SWITCHaai" isDefault="true" Location="/WAYF/SWITCHaai" Binding="urn:mace:shibboleth:sp:1.3:SessionInit" wayfURL="https://wayf-test.switch.ch/SWITCHaai/WAYF" wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/> <!-- md:AssertionConsumerService elements replace the old shireURL function with an explicit handler for particular profiles, such as SAML 1.1 POST or Artifact. The isDefault and index attributes are used when sessions are initiated to determine how to tell the IdP where and how to return the response. --> <md:AssertionConsumerService Location="/SAML/POST" index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"/> <md:AssertionConsumerService Location="/SAML/Artifact" index="2" Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"/> <!-- md:SingleLogoutService elements are mostly a placeholder for 2.0, but a simple cookie-clearing option with a ResponseLocation or a return URL parameter is supported via the "urn:mace:shibboleth:sp:1.3:Logout" Binding value. --> <md:SingleLogoutService Location="/Logout" Binding="urn:mace:shibboleth:sp:1.3:Logout"/> </Sessions> <!-- You should customize these pages! You can add attributes with values that can be plugged into your templates. You can remove the access attribute to cause the module to return a standard 403 Forbidden error code if authorization fails, and then customize that condition using your web server. --> <Errors session="/etc/shibboleth/sessionError.html" metadata="/etc/shibboleth/metadataError.html" rm="/etc/shibboleth/rmError.html" access="/etc/shibboleth/accessError.html" supportContact="YOUR_EMAIL_ADDRESS" logoLocation="YOUR_LOGO_LOCATION" styleSheet="YOUR_STYLESHEET_LOCATION"/> <!-- Indicates what credentials to use when communicating --> <CredentialUse TLS="switchaai" Signing="switchaai"> <!-- RelyingParty elements can customize credentials for specific IdPs/sets. --> <!-- <RelyingParty Name="urn:mace:switch.ch:aaitest" TLS="aaitest" Signing="aaitest"/> --> </CredentialUse> <!-- AAP can be inline or in a separate file --> <AAPProvider type="edu.internet2.middleware.shibboleth.aap.provider.XMLAAP" uri="/etc/shibboleth/AAP.switchaai.xml"/> <!-- Operational config consists of metadata and trust providers. Can be external or inline. --> <!-- SWITCHaai federation metadata (production) --> <MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata" uri="/etc/shibboleth/metadata.aaitest.xml"/> <!-- The standard trust provider supports SAMLv2 metadata with path validation extensions. --> <TrustProvider type="edu.internet2.middleware.shibboleth.common.provider.ShibbolethTrust"/> <!-- Zero or more SAML Audience condition matches (mainly for Shib 1.1 compatibility). If you get "policy mismatch errors, you probably need to supply metadata about your SP to the IdP if it's running 1.2. Adding an element here is only a partial fix. --> <!-- SWITCHaai federation --> <saml:Audience>urn:mace:switch.ch:aaitest</saml:Audience> <!-- You can customize behavior of specific applications here. The default elements inside the outer <Applications> element generally have to be overridden in an all or nothing fashion. That is, if you supply a <Sessions> or <Errors> override, you MUST include all attributes you want to apply, as they will not be inherited. Similarly, if you specify an element such as <MetadataProvider>, it is not additive with the defaults, but replaces them. Note that each application must have a handlerURL that maps uniquely to it and no other application in the <RequestMap>. Otherwise no sessions will reach the application. If each application lives on its own vhost, then a single handler at "/Shibboleth.sso" is sufficient, since the hostname will distinguish the application. The example below shows a special application that requires use of SSL when establishing sessions, restricts the session cookie to SSL and a specific folder, and inherits most other behavior except that it requests only EPPN from the origin instead of asking for all attributes. Note that it will inherit all of the handler endpoints defined for the default application but will append them to the handlerURL defined here. --> <!-- <Application id="foo-admin"> <Sessions lifetime="7200" timeout="3600" checkAddress="true" handlerURL="/secure/admin/Shibboleth.sso" handlerSSL="true" cookieProps="; path=/secure/admin; secure"/> <saml:AttributeDesignator AttributeName="urn:mace:dir:attribute-def:eduPersonPrincipalName" AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri"/> </Application> --> </Applications> <!-- Define all the private keys and certificates here that you reference from <CredentialUse>. --> <CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials"> <Credentials xmlns="urn:mace:shibboleth:credentials:1.0"> <FileResolver Id="switchaai"> <Key> <Path>/etc/shibboleth/www.example.ch.key</Path> </Key> <Certificate> <!-- Certificate and the whole chain --> <Path>/etc/shibboleth/www.example.ch.crt</Path> </Certificate> </FileResolver> </Credentials> </CredentialsProvider> </SPConfig>
Change all the red lines to the given values in the Shibboleth configuration file /etc/shibboleth/shibboleth.xml. The blue lines show values that are specific for your Service Provider or that are somehow specific for SWITCHaai.
<!-- /opt/shibboleth-1.2.1/etc/shibboleth/shibboleth.switchaai.xml SWITCHaai config file for Shibboleth 1.2.1 date: 20040615 --> <ShibbolethTargetConfig xmlns="urn:mace:shibboleth:target:config:1.0" logger="/opt/shibboleth-1.2.1/etc/shibboleth/shibboleth.logger" clockSkew="180"> <Extensions> <Library path="/opt/shibboleth-1.2.1/libexec/xmlproviders.so" fatal="true"/> </Extensions> <SHAR logger="/opt/shibboleth-1.2.1/etc/shibboleth/shar.logger"> <UnixListener address="/tmp/shar-1.2-socket"/> <MemorySessionCache cleanupInterval="300" cacheTimeout="3600" AATimeout="30" AAConnectTimeout="15" defaultLifetime="1800" retryInterval="300" strictValidity="false" propagateErrors="true"/> </SHAR> <SHIRE logger="/opt/shibboleth-1.2.1/etc/shibboleth/shire.logger"> <RequestMapProvider type="edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap"> <RequestMap applicationId="default"> <Host name="localhost" scheme="https"> <Path name="secure" requireSession="true" exportAssertion="true"/> </Host> <Host name="localhost" scheme="http"> <Path name="secure" requireSession="true" exportAssertion="true"/> </Host> </RequestMap> </RequestMapProvider> </SHIRE> <Applications xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" id="default" providerId="https://www.example.ch/shibboleth"> <Sessions lifetime="7200" timeout="3600" checkAddress="true" wayfURL="https://wayf-test.switch.ch/SWITCHaai/WAYF" shireURL="/Shibboleth.shire" shireSSL="false"/> <!-- YOU SHOULD CUSTOMIZED THE ERRORS PAGES! You can add attributes with values that can be plugged into your templates. --> <Errors shire="/opt/shibboleth-1.2.1/etc/shibboleth/shireError.html" rm="/opt/shibboleth-1.2.1/etc/shibboleth/rmError.html" access="/opt/shibboleth-1.2.1/etc/shibboleth/accessError.html" supportContact="YOUR_EMAIL_ADDRESS" logoLocation="/logo.gif" styleSheet="/styles.css"/> <CredentialUse TLS="SWITCHpki" Signing="SWITCHpki"> </CredentialUse> <!-- SWITCHaai attribute acceptance policy --> <AAPProvider type="edu.internet2.middleware.shibboleth.target.provider.XMLAAP" uri="/opt/shibboleth-1.2.1/etc/shibboleth/AAP.switchaai.xml"/> <!-- SWITCHaai Federation Metadata: sites --> <FederationProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLMetadata" uri="/opt/shibboleth-1.2.1/etc/shibboleth/sites.aaitest.xml"/> <!-- SWITCHaai Federation Metadata: trust --> <TrustProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLTrust" uri="/opt/shibboleth-1.2.1/etc/shibboleth/trust.aaitest.xml"/> <!-- SWITCHaai Federation identifier --> <saml:Audience>urn:mace:switch.ch:aaitest</saml:Audience> </Applications> <CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials"> <Credentials xmlns="urn:mace:shibboleth:credentials:1.0"> <!-- Define path to your SWITCHpki private key and server certificate --> <FileResolver Id="SWITCHpki"> <Key format="PEM"> <Path>/etc/apache/ssl.key/www.example.ch.key</Path> </Key> <Certificate format="PEM"> <!-- Server Certifcate with CA Chain --> <Path>/etc/apache/ssl.crt/www.example.ch.crt</Path> </Certificate> </FileResolver> </Credentials> </CredentialsProvider> </ShibbolethTargetConfig>
The metadata for the Shibboleth SP and IdP both contain information about all the Resources and Home Organizations available in a federation. For the AAI Test Federation, the metadata.aaitest.xml (Shibboleth 1.3 SP and IdP) or metadata.aaitest.xml (Shibboleth 1.1 and 1.2 SP) file has to be updated on a regular basis. See http://www.switch.ch/aai/metadata/ for the latest version of the AAI Test metadata.
You are now ready to register your Service Provider in the AAI Resource Registry. Doing this will allow you to download up-to data metadata.
The AAI Resource Registry collects information about Resources (Service Providers) and Home Organizations (Identity Providers) which participate in the SWITCHaai and the AAI Test federations.
-- $Id: reconfigure-sp.html,v 1.4 2007/03/09 16:11:21 haemmer Exp $