Fri, Feb 18, 2005
The <Applications> element in shibboleth.xml is the wrapper for all the applications that this SP provides. There is only one <Applications> element and it provides default session handling metrics, which individual applications on the SP can choose to override. Let’s take a look at the default session handling for our SP:
<Sessions lifetime=“7200” timeout=“3600” checkAddress=“true” wayfURL=“https://shorigin.uhi.ac.uk/SSO" shireURL=“/Shibboleth.shire” shireSSL=“false”/>
Here’s what the Sessions attributes mean:
- lifetime - how long a shibboleth session will last, in seconds. Setting this to zero removes the timeout limit, i.e. infinite sessions. When the session expires, shibboleth will redirect the user back to their IdP for re-authentication. This is different from going back to the user’s AA, which they are unaware of, to update attribute assertions that have gone beyond their “NotOnOrAfter” value. An IdP could choose to re-authenticate them when this happens, though it could just have infinite sessions itself and re issue the attribute assertions for the user, with an updated “NotOnOrAfter”. It’s important to note that a shibboleth session has nothing to do with an application session. For example, you could be protecting a web site that uses it’s own sessions, using cookies perhaps and it may very well have a different lifetime for it’s sessions.
- timeout - this tells shibboleth how long, in seconds, to wait before invalidating it’s session and starting a new one. Setting this to zero removes the timeout limit. You could get into trouble with this attribute if you set it too low and the user’s IdP is having a bad hair day, such as slow LDAP authentication. If the IdP takes too long to respond with an AuthenticationStatement, the session will die and the user will have to re-authenticate and so on and so on.
- checkAddress - tells shibboleth to check the client address of the browser when using cookies for the session management. Stops cookie theives but can cause problems for users coming through proxies, in which case you can set it to “false”. It just makes sure that the cookie that was issued always stays with the client address it was issued to.
- wayfURL - this is the location of your WAYF. As you know, the WAYF is a router. It shouldn’t process anything the SP sends it. All it does is finds out where the user’s IdP is and then routes the SAML requests from the SP to that IdP. If you don’t use a WAYF, for example, you may only one client base for your applications, then you can set this attribute to the location of your IdP.
- shireURL - this is the location of your SHIRE, the bit that consumes attribute assertions coming from a user’s AA. It also dishes out the session cookies.
- shireSSL - setting this to true will force the shire to only accept incoming attribute assertions via SSL/HTTPS
<Errors> This is where you override the default “flying pig” error pages of shibboleth. Just design some nice marketing friendly pages and record their URLs here.
<CredentialUse TLS=“uhi” Signing=“uhi”> <RelyingParty Name=“leeds” TLS=“leedscreds” Signing=“leedscreds”/> </CredentialUse>
and it’s associated:
<FileResolver Id=“leedscreds”> <Key format=“PEM”> <Path>/usr/local/apache/conf/ssl.key/leeds.key</Path> </Key> <Certificate format=“PEM”> <Path>/usr/local/apache/conf/ssl.crt/leeds.crt</Path> </Certificate> </FileResolver> </CredentialsProvider>
CredentialUse is used to tell shibboleth how to sign and send attribute requests to IdP components, such as an AA. Here’s what the attributes mean:
- TLS - this is a pointer to the CredentialsProvider element that specifies how to talk SSL to an IdP. TLS stands for Transport Layer Security.
- Signing - this is a pointer to the CredentialsProvider element that specifies the keys to use when signing attribute requests.
Our example shows a default TLS and signing policy, both specified by “uhi”. This means that our SP will use the specified keys and certs when signing attribute requests for any IdP. If you need to sign attribute requests differently for a certain IdP you’re talking to, you can override the default by using the RelyingParty element. We’ve done this for signing requests to the University of Leeds’ IdP.
<saml:AttributeDesignator AttributeName=“urn:mace:dir:attribute-def:eduPersonTargetedID” AttributeNamespace=“urn:mace:shibboleth:1.0:attributeNamespace:uri”/> <saml:AttributeDesignator AttributeName=“urn:uhi:ac:uk:attribute-def:givenName” AttributeNamespace=“urn:mace:shibboleth:1.0:attributeNamespace:uri”/> It’s here that we specify what attributes we want back from AA. As you can see, we’re saying we want any AA that replies to us, to send us the user’s eduPersonTargetedID attribute and also the Novell NDS givenName attribute. As we said when configuring AAP.xml, it’s recommended that we always use urn:mace:shibboleth:1.0:attributeNamespace:uri for the namespace for any attributes. You have to be aware though, that these attribute requests are subject to IdP attribute release policies, i.e. if the user chooses not to release their givenName to our SP then their AA won’t send it back and they won’t get in. Well, it’s up to the application to decide, not shibboleth, which just arranges for the attributes to be fetched and presented to the application. If givenName isn’t in the application’s environment for some reason such as not being specified in AAP.xml and therefore being physically removed from the assertion or due to the user choosing not to release it, then the application must make a decision on whether to grant access to that user. If .htaccess is used, then user won’t get in. More sophisticted authorisation rules in the application could provide limited access.
<AAPProvider type=“edu.internet2.middleware.shibboleth.target.provider.XMLAAP” uri=“/usr/local/shibboleth/etc/shibboleth/AAP.xml”/> This is the attribute acceptance policy for our SP. I’ve already documented this here. You can either choose to have a separate file, such as AAP.xml, or you can copy your AttributeRules directly into shibboleth.xml. I prefer to use AAP.xml
<FederationProvider type=“edu.internet2.middleware.shibboleth.common.provider.XMLMetadata” uri=“/usr/local/shibboleth/etc/shibboleth/IQ-sites.xml”/> Similarly, as we did with AAP.xml, you can either include providers from IQ-sites.xml, or copy them directly to shibboleth.xml. As I prefer the modularised approach, we’ll look at IQ-sites.xml here.
<TrustProvider type=“edu.internet2.middleware.shibboleth.common.provider.XMLTrust” uri=“/usr/local/shibboleth/etc/shibboleth/IQ-trust.xml”/> Again, we’ll keep these setting separate and document IQ-trust.xml here.
<RevocationProvider type=“edu.internet2.middleware.shibboleth.common.provider.XMLRevocation” uri=“/usr/local/shibboleth/etc/shibboleth/IQ-trust.xml”/> This allows our SP to control IdP SSL communications by referring to a list of revoked certificates. We’ll document this in IQ-sites.xml
<saml:Audience>urn:mace:inqueue</saml:Audience> You only need this if you’re talking to ancient versions of shibboleth origins. We won’t be, so we won’t need this element in shibboleth.xml
<Application id=“foo-admin”> <Sessions lifetime=“7200” timeout=“3600” checkAddress=“true” shireURL=“/secure/admin/Shibboleth.shire” shireSSL=“true” cookieProps=“; path=/secure/admin; secure” wayfURL=“https://wayf.internet2.edu/InQueue/WAYF"/> <saml:AttributeDesignator AttributeName=“urn:mace:dir:attribute-def:eduPersonPrincipalName” AttributeNamespace=“urn:mace:shibboleth:1.0:attributeNamespace:uri”/> </Application> If you want to override the default Applications behaviour, which applies to all applications that our SP acts as an attribute gateway for, you can specify what you want in an Application element. The “id” attribute of the Application element refers to the entry in applications.xml that defines an application, such as another virtual host. When our SP is routing attributes to this new virtual host, it will use specific lifetime, timeout, wayfURL etc. instead of the defaults. It will also only ask for the eduPersonPrincipalName attribute instead of eduPersonTargetedID and givenName which all the other applications ask for. So how do you specify an applications.xml?
<RequestMapProvider type=“edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap” uri=“/usr/local/shibboleth/etc/shibboleth/applications.xml”/> The RequestMapProvider element sits in the SHIRE element and tells our SP where our applications mapping file is located. It’s in here that we’ll specify a pernickety application that wants an environment that the others don’t