| Wiki Markup |
|---|
h2. Advanced Configuration in Shibboleth SP v1.3
This document assumes you have installed, configured and run Shibboleth SP successfully in a test environment. If not please visit the [Setup guide|Shib1SPInstallConfigure].
h3. Attributes
Plan ahead for attributes. You have to get prior approval from respective data stewards. Think about your user population (student or staff or both)
h4. Request for staff(employee) data
We are still formalizing the process with campus HR. Meanwhile send a request to AIS at iamucla@ucla.edu
h4. Request for student data
You need to fill in a Registrar's Service Request form online at [http://www.registrar.ucla.edu/rsr/] requesting approval to release the data you want via Shibboleth and for what purpose. The RSR is an agreement that you will only use the data for the stated purpose. And there may be charges involved. Contact Valerie Romero (vromero@registrar.ucla.edu) if you have questions.
When submitting the request, choose "Other Request" under Request Type. You can use the following text template in the "Describe Your Request" section:
{color:#006600}I am registering <fill-in-application-name/description> with the UCLA Web Single Sign-On{color}
{color:#006600}Service. I am requesting access to the following data elements via Shibboleth for all records{color}
{color:#006600}in Enterprise Diectory tagged with the student-interest flag:{color}
{color:#006600}uclaUniversityID (UID){color}
{color:#006600}<any-other-elements-you-might-need>{color}
h3. Deployment mode: Federated vs Bilateral
The choice is driven by user base i.e whether your users are from UCLA only or from outside as well. For ex, if you are hosting a library service and you expect users from UCLA, UCSD and Stanford you will most likely choose Federation deployment (UCLA, UCSD and Stanford have to be part of the federation); if you are hosting a application limited to UCLA only Bilateral deployment will work.
h4. Bilateral arrangement
Purchase a SSL server certificate from commercial providers like Verisign, Thawte or {nl:GoDaddy}. Share your SSL certificate with the {nl:IdP} (Do not send the key).
If you are using SP 2.1 or higher you may use the key and certificate generated at the time of installation.
h4. Federated arrangement
There is one production federation in US, {nl:InCommon}. Our {nl:IdP} is already a member of this federation.
Get a certificate from {nl:InCommon} or contact AIS to see if they can get one for you. You have to certify you follow certain policies/standards. There is also a fee involved. Benefit is, you will be able to support a large number of users from different campuses/organizations.
h3. Session configuration
Configure session parameters lifetime and timeout carefully. It should be consistent with application session (if any)
timeout: Session expires after "x" seconds of inactivity. SP will ask for a new session by redirecting to IdP
lifetime: Session expires after "x" seconds regardless of activity. SP will ask for a new session by redirecting to IdP
{code:xml}
<Sessions lifetime="7200" timeout="3600" checkAddress="false" consistentAddress="true"
handlerURL="/Shibboleth.sso" cookieProps="; path=/; " idpHistory="true" idpHistoryDays="7">
{code}
h3. Multiple Applications
A single Shibboleth SP instance can support multiple applications and multiple hosts (via virtual hosting). There are different deployment and configuration strategies to support this. More information is available at Internet2 site [https://spaces.internet2.edu/display/SHIB/AddSeparateApplication]
1. Two applications are hosted on the same host. Apps have same session and attribute requirements
{code:xml}
<Host name="somehost.ucla.edu">
<Path name="app1" applicationId="app1" authType="shibboleth" requireSessionWith="app1" exportAssertion="true" />
<Path name="app2" applicationId="app2" authType="shibboleth" requireSessionWith="app2" exportAssertion="true" />
</Host>
{code}
2. Two applications are hosted on the same host. Apps have same session requirements but need different attributes. Apps are configured to use separate providerIds so IdP can distinguish between the two and release separate set of attributes accordingly. You can use same key/cert even when using separate providerIds, as long as the applications are running on the same host.
{code:xml}
<Host name="somehost.ucla.edu">
<Path name="app1" applicationId="app1" authType="shibboleth" requireSessionWith="app1" exportAssertion="true" />
<Path name="app2" applicationId="app2" authType="shibboleth" requireSessionWith="app2" exportAssertion="true" />
</Host>
..
..
//Default settings apply to app1
<Applications id="default" providerId="https://yourhost.ucla.edu/shibboleth/testshib/sp"
homeURL="https://edws1.ais.ucla.edu/index11.html"
xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
..
..
//Override default settings for app2, to use a different providerId:
<Application id="app2" providerId="https://yourhost2.ucla.edu/sp">
<Sessions lifetime="7200" timeout="3600" checkAddress="false" consistentAddress="true"
handlerURL="/Shibboleth.sso" cookieProps="; path=/; "
idpHistory="true" idpHistoryDays="7"/>
</Application>
</Applications>
{code}
3. Shibbolize all applications on the host. You need not code individual <path> for each application; use the below configuration instead. This configuration assumes you have same session and attribute requirements for all applications under the host.
{code:xml}
<Host name="somehost.ucla.edu" authType="shibboleth" exportAssertion="true" />
{code}
h3. Protect Root Level with Apache/Tomcat
This sample is for applications running in Apache/Tomcat under root level. You should be running Apache/Tomcat with mod jk.
h4. http.conf
For the mod-shib section of the httpd.conf file make sure / is in the Location element.
{code:xml}
<Location />
AuthType shibboleth
require shibboleth
</Location>
{code}
If you application is on root, you are probably routing everything to Tomcat. Thus we must exclude it and let Apache handle the Shibboleth part. We will be using JkUnMount. Add the elements below to the modjk section of the httpd.conf file.
{code:xml}
JkUnMount /Shibboleth.sso/* worker1
JkUnMount /shibboleth worker1
JkUnMount /shibboleth-sp/* worker1
{code}
h3. Multiple Identity Providers
If you are part of the federation you are already supporting multiple Identity Providers (those that are part of the federation).
For the most part you will need only one IdP i.e IdP service provided by AIS. This will serve all users within UCLA. However if you want to provide services to some other community, you have to configure your SP accordingly.
In this example, app1 users are expected to come from UCLA and app2 users are expected to authenticate at UCSD. Note the WAYF URL.
{code:xml}
<Host name="somehost.ucla.edu">
<Path name="app1" applicationId="app1" authType="shibboleth" requireSessionWith="app1" exportAssertion="true" />
<Path name="app2" applicationId="app2" authType="shibboleth" requireSessionWith="app1" exportAssertion="true" />
</Host>
<SessionInitiator isDefault="true" id="app1" Location="/WAYF/default" Binding="urn:mace:shibboleth:sp:1.3:SessionInit" wayfURL="https://shb.ais.ucla.edu/shibboleth-idp/SSO" wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" />
<SessionInitiator id="app2" Location="/WAYF/default" Binding="urn:mace:shibboleth:sp:1.3:SessionInit" wayfURL="https://sso.ucsd.edu/shibboleth-idp/SSO" wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" />
You may also use separate credentials (certificate and key) when communicating with different IdPs.
<CredentialUse TLS="credentials1" Signing="credentials1">
<RelyingParty Name="urn:mace:incommon:ucla.edu" TLS="credentials1" Signing="credentials1" />
<RelyingParty Name="urn:mace:incommon:ucsd.edu" TLS="credentials2" Signing="credentials2" />
</CredentialUse>
{code}
h3. AAP.xml
IdP delivers attributes using standard naming convention. Map them to custom http header names that your application expects. Your application will have to read the http header (or Alias) and make use of it.
Your application will not receive any attributes unless they are configured in AAP.xml with a Header name.
Verify attribute names with the attribute provider (IdP). Standard attribute name may not be what you think it is.
{code:xml}
1. Map urn:mace:dir:attribute-def:eduPersonTargetedID to header SHIB-TARGETEDID.
Accept any value.
<AttributeRule Name="urn:mace:dir:attribute-def:eduPersonTargetedID" Header="SHIB-TARGETEDID" Alias="targetedId">
<AnySite>
<AnyValue />
</AnySite>
</AttributeRule>
2. Map urn:mace:ucla.edu:edimi:attributes:uclaUniversityID to header SHIB-UID.
Accept any value. Accept only if the attribute provider is UCLA
(https://shb1.ais.ucla.edu/shibboleth/testshib/idp is the entityId of AIS IdP)
<AttributeRule Name="urn:mace:ucla.edu:edimi:attributes:uclaUniversityID" CaseSensitive="false" Header="SHIB-UID" Alias="uid">
<SiteRule Name="https://shb1.ais.ucla.edu/shibboleth/testshib/idp">
<AnyValue />
</SiteRule>
</AttributeRule>
3. Map urn:mace:dir:attribute-def:eduPersonAffiliation to header SHIB-AFFILIATION.
Accept any of these vaues - MEMBER, FACULTY, STUDENT only. If the value is STAFF
it will be rejected and no http header will be created.
<AttributeRule Name="urn:mace:dir:attribute-def:eduPersonAffiliation" CaseSensitive="false" Header="SHIB-AFFILIATION" Alias="affiliation">
<AnySite>
<Value>MEMBER</Value>
<Value>FACULTY</Value>
<Value>STUDENT</Value>
</AnySite>
</AttributeRule>
4. Map urn:mace:dir:attribute-def:mail to header SHIB-EMAIL.
Accept value only if it complies with regular expression.
<AttributeRule Name="urn:mace:dir:attribute-def:mail" CaseSensitive="false" Header="SHIB-EMAIL" Alias="email">
<AnySite>
<Value Type="regexp">^[^@]+$</Value>
</AnySite>
</AttributeRule>
{code}
h3. Lazy Sessions
Shibboleth supports a feature called Lazy Session. It means invoking Shibboleth session (user login) only at a time it is required. Some applications have mixed content - public (that does not require login) and protected (that requires user login and perhaps specific user role/attribute). When anonymous users visit public resource/page, let them in; when users visit protected content invoke Shibboleth login. Basically lazy sessions allows applications to offer services to anonymous users and offer additional services for users that do authenticate later.
To configure Lazy sessions:
h4. 1. In Apache httpd.conf file (If you are using IIS this does not apply)
{code}
<Location /yourapp>
AuthType shibboleth
ShibRequireSession <on/off>
Require shibboleth
</Location>
{code}
{nl:ShibRequireSession}: Controls whether to require an authenticated session before passing control to the authorization phase or the actual resource. Defaults to off. For lazy session you would want this element to be off
h4. 2. In shibboleth.xml (Apache & IIS)
Edit the attribute requireSession in the <Path> inside {nl:<RequestMap>}
{code}
<Host name="yourhost.ucla.edu">
<Path name="yourapp" authType="shibboleth" requireSession="true/false" />
</Host>
{code}
requireSession : This attribute controls whether Shibboleth will forcibly establish an authenticated session with the user before handing off the request to the web server or application. If true , Shibboleth will force session establishment. If false (the default), web applications are responsible for ensuring that a session exists if necessary, so-called lazy session establishment. Most deployments should not specify false for protected content without a full understanding of the implications. For lazy session you would want this value to be false
Edit the Location attribute in {nl:<SessionInitiator>}
{code}
<SessionInitiator isDefault="true" id="yourapp" Location="/Login"
Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
wayfURL="https://shb1.ais.ucla.edu/shibboleth-idp/SSO"
wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" />
{code}
{builder-hide}
Other configurations you might need to change are your handlerURL and Location element in your shibboleth.xml. Your handlerURL depends on your Assertion Consumer Service URL that you registered with the IdP you are talking to.
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"
Location="https://myserver.ais.ucla.edu/demo/Shibboleth.sso/SAML/POST" index="1"/>
So if your ACS looks something like the above your handlerURL will look like handlerURL="/demo/Shibboleth.sso"
{builder-hide}
h4. 3. Link to protected resource
3a. If you have links to protected page in your application: Compose a URL to protected page this way
{nl:http://yourhost.ucla.edu/Shibboleth.sso/Login?target=http%3A//yourhost.ucla.edu/yourapp/protected.jsp}
target: This is the protected target user wants to visit. Shibboleth will take the user to this page after login. This parameter should be URL encoded.
3b. On the protected page(s) verify that Shibboleth session exists (i.e user logged in). If not found redirect to Login handler url as shown. If Shibboleth session exists, but desired attribute/attribute value is missing, then deny access to the target page. For ex, if affiliation "student" is required to access a page protected.jsp you can implement this check:
{code}
if (No Shibboleth Session)
//User has not logged in. Force login
Redirect to http://yourhost.ucla.edu/Shibboleth.sso/Login?target=http%3A//yourhost.ucla.edu/yourapp/protected.jsp
if (request.getHeader("affiliation") NOT EQUAL "student")
//User has logged in. However user does not have the expected role
Deny access to content completely or Block protected content
else
//User has logged in and User has the expected role
Display content
{code}
One problem with this approach is you, have to check for Shibboleth session/attributes in each protected page. Instead, you may implement this check in a filter (java servlet filter is a good example), and map the protected content to this filter.
Find out more at Internet2 site [https://spaces.internet2.edu/display/SHIB/LazySession].
h3. Implementing Logout in Shibboleth
Shibboleth v1.3 does not support single logout, so it is important to understand what options are available to your application. The only way for a user to completely log out of all Shibboleth services is to close the browser. Even this may not work in some cases, for ex, Firefox shares cookies across active browser sessions. So user will have to close all browser sessions in this case.
After successful login IdP maintains session by way of a session cookie stored in the browser, cookie name edu.ucla.isis4.ticket and domain ucla.edu. Once IdP posts authentication information, SP maintains its own session, again by way of two session cookies in the browser (cookie names start with _shibsession_ and _shibstate_; for ex, _shibsession_3ce04f1237fb75b1fdb9c44655f5d84b60cc6da5 & _shibstate_3ce04f1237fb75b1fdb9c44655f5d84b60cc6da5) with a domain name of the SP host. If the user visits a second SP then SP2 maintains its own session information. To effect a true logout you have to expire all the sessions (at IdP, SP1, SP2). However SP2 is a different domain than SP1 and the two are not aware of each other's session.
Our recommendation (for v1.3 SPs) is to first do whatever clean up is necessary within your application and then redirect the user to the Shibboleth SP {nl:SingleLogoutService} location. This URL is dependent on your installation and is constructed as a combination of your hostname, handlerURL, and {nl:SingleLogoutService} location (all defined within shibboleth.xml). It will likely be of the form {nl:http://yourhost.ucla.edu/Shibboleth.sso/Logout}.
Configure Location and {nl:ResponseLocation} parameters in shibboleth.xml
{code}
<md:SingleLogoutService Location="/Logout" ResponseLocation="https://shb.ais.ucla.edu/shibboleth-idp/Logout"
Binding="urn:mace:shibboleth:sp:1.3:Logout"/>
{code}
Compose a Logout link like {nl:http://yourhost.ucla.edu/Shibboleth.sso/Logout}
When the user clicks on Logout link from a page, their Shibboleth SP session will be destroyed and they will be redirected to the Shibboleth IdP logout URL provided in {nl:ResponseLocation} above. At this point, their Shibboleth IdP session will be destroyed and instructions will be provided for truly completing the logout if they wish (ie. closing their browser).
|
Page History
Overview
Content Tools