Overview
Enhancements to shibboleth and creation of a Delegated SAML Authentication Library have enabled the use of SAML delegation. The use case motivating this development was to enable portlets in a uPortal-based portal to proxy portal users by use of shibboleth and SAML delegation. This document will give an orientation and specific configuration guidance to deployers who wish to set up a similar environment.
We'll start with a high level review of the main components and their interactions that make delegation happen.
Shibboleth IdP v2.1.3 with delegation plug-in
The delegation plug-in can be obtained at < http://svn.middleware.georgetown.edu/view/shib-extension/java-idp-delegation/>. It includes installation instructions < http://svn.middleware.georgetown.edu/view/shib-extension/java-idp-delegation/trunk/doc/INSTALL.txt?revision=174>.
Shibboleth SP v2.2
This version contains all of the needed delegation-related enhancements as well as enhancements to integrate with the Delegated SAML Authentication Library. It is deployed in two roles in this delegation scenario: one instance protects the portal and the other protects a back-end Web Service Provider (WSP).
Delegated SAML Authentication Library
This library extends the Apache HTTP Client v4 essentially to implement the SAML ECP profile. It is used by portlets that need to proxy a user to a WSP using SAML delegation. It is available at https://www.ja-sig.org/svn/sandbox/ShibbolethuPortalIntegration/trunk/Delegated%20SAML%20Authentication/
uPortal v3.1
This version of uPortal contains enhancements enabling it to provide shibboleth-delivered attributes, raw SAML response tokens delivered when users login to the portal, and selected portions of the shibboleth SP's metadata, for use within the portal environment. Portlets using the Delegated SAML Authentication Library must request these from portal through the portlet API. The SAML Assertion User Attribute provides this capability to uPortal portlets.
What's going on
The following sequence diagram shows how the user's browser, the IdP, the SP protecting the portal, the portal itself, the portlet, and the SP protecting the back-end WSP all interact to enable the portlet to proxy the user to the WSP.
Note that the swimming lane labeled "SP A - Portal" sometimes refers to the shibboleth SP itself, and sometimes to an action that uPortal takes. They are considered as one actor. The Portlet is given its own swimming lane to highlight the actions it takes. To simplify the development of delegation capability for this portal use case, it was decided that, from the SAML protocol perspective, the portlet, the portal, and SP A would be treated as a single entity.
Configuration constants
For a given IdP, Portal SP, and WSP SP, the entityIds and public keys need to be used and shared consistently across them all. Use this are to record their values for a particular set of entities. The section following this will refer to them by the "shell variables" defined on the left hand side below.
$IdPEntityId= __________________________________________________________________
$PortalEntityID= _______________________________________________________________
$WSPEntityId= __________________________________________________________________
Configuration guidance
Each component - IdP, the Portal's SP, the Portlet, and the WSP's SP - has ordinary configuration needs unrelated to enabling delegation. A general prerequisite of the following guidance is that these are working in non-delegation scenarios.
IdP
Prerequisite to these instructions, we assume that
- All endpoints as shipped with IdP v2.1.3 and later are enabled.
- The installation instructions for the delegation plug-in to IdP v2.1.3 have been followed.
- Attribute filters correctly declare the attributes needed by each WSP.
Configuration objectives for the IdP are:
- Allow the portal to proxy requests from WSPs.
- Allow the IdP to produce delegatable tokens for each WSP.
- Ensure that step 5(g) of the delegation plug-in's installation instructions was done correctly.
The RelyingParty element for the Portal must have a ProfileConfiguration element to enable its delegation support. To allow the portal to proxy requests from WSPs, the allowTokenDelegation attribute must be set to "true", and a samldel:DelegationRestriction element for each WSP must be included in the RelyingParty element for the portal. Also, for the portal use case in which only one delegation step is needed, the IdP is configured to create a proxy token that cannot itself be proxied. That's done with the maximumTokenDelegationChainLength attribute.
<RelyingParty id="$PortalEntityId" ... >
...
<ProfileConfiguration xsi:type="samldel:LibertyIDWSFSSOSProfile"
securityPolicyRef="shibboleth.ext.delegation.LibertySSOSPolicy"
maximumTokenDelegationChainLength="1"
allowTokenDelegation="true"
signAssertions="always"
encryptNameIds="never" >
<samldel:DelegationRestriction>$WSPEntityId</samldel:DelegationRestriction>
</ProfileConfiguration>
...
</RelyingParty>
The RelyingParty element for each WSP must have a ProfileConfiguration element to enable its delegation delegation. To prevent it from further delegation set allowTokenDelegation to "false".
<RelyingParty id="$WSPEntityId" ... >
...
<ProfileConfiguration xsi:type="samldel:LibertyIDWSFSSOSProfile"
securityPolicyRef="shibboleth.ext.delegation.LibertySSOSPolicy"
allowTokenDelegation="false"
signAssertions="always"
encryptNameIds="never" >
</ProfileConfiguration>
...
</RelyingParty>
Step 5(g) of the delegation plug-in installation instructions require a that a suitable IdP key be identified as IdPValidationOnlyCredential. It's important that this not be a new key. Use a single key for all of the IdP's purposes.
<security:Credential id="IdPValidationOnlyCredential" xsi:type="security:X509Filesystem"> <security:PrivateKey>usual IdP private key</security:PrivateKey> <security:Certificate>usual IdP certificate</security:Certificate> </security:Credential>
Portal's SP configuration
Configuration objectives for this SP are:
- Declare the REMOTE_USER attribute we'll use.
- Enable this SP to integrate with the Delegated SAML Authentication Library used by portlets acting as delegates.
Note that there is no delegation-specific configuration required beyond that necessary to properly integrate with uPortal so that uPortal together with its portlets can act as a delegate.
Integrating uPortal with shibboleth to support delegation centers on enabling the SP to provide the portal's Delegated SAML Authentication Library with the SAML response token from the user login sequence and the IdP's public signing keys from the metadata.
SAML response tokens are exposed by the SP by setting the exportAssertions attribute to "true" in an appropriate sub element of the RequestMapper element. The exportACL attribute of the Sessions element limits access to the exported SAML assertions by IP address. This may also need to be modified to suit the environment.
The IdP's public signing keys are extracted from the metadata by declaring an AttributeExtractor of type KeyDescriptor. The extracted keys are mapped to attributes tagged with the metadataAttributePrefix value.
The example configuration below assumes that the default Application is the Portal. It is also possible to associate these declarations with specific Applications by using ApplicationOverride elements and associating the appropriate applicationId attributes in the RequestMapper.
<RequestMapper type="Native">
<RequestMap applicationId="default">
<Host name="$PortalHostName"authType="shibboleth" requireSession="true" exportAssertion="true"/>
</RequestMap>
</RequestMapper>
...
<ApplicationDefaults id="default" policyId="default"
entityID="$PortalEntityId"
homeURL=" "
REMOTE_USER="uid eppn persistent-id targeted-id"
signing="false" encryption="false"
metadataAttributePrefix="Meta-">
...
<Sessions ...
exportLocation="http://localhost/Shibboleth.sso/GetAssertion"
exportACL="127.0.0.1" ... >
...
</Sessions>
...
<AttributeExtractor type="Chaining">
<AttributeExtractor type="XML" path="attribute-map.xml"/>
<AttributeExtractor type="KeyDescriptor" signingId="Signing-Keys"/>
</AttributeExtractor>
...
</ApplicationDefaults>
Note that the AttributeExtractor configuration above, together with the metadataAttributePrefix, results in the IdP's public signing key(s) to be placed in an attribute named "Meta-Signing-Keys".
Portlet's Delegated SAML Authentication Library configuration
First read the following four pages from the uPortal v3.1 wiki:
Making the SAML assertion available to uPortal portlets
Delegated SAML Authentication Library for Portlet Developers
Using UW Web Proxy Portlet with Delegated SAML Authentication Library
Of particular note, the Portlet needs access to the private key used by the Portal's SP so it can authenticate to the IdP as the Portal SP. Here's how, excerpted from above:
<bean id="HttpManagerBean" class="edu.wisc.my.webproxy.beans.http.ShibbolethEnabledHttpManagerImpl" scope="prototype"> <property name="spPrivateKey" value="/etc/shibboleth/sp-key.pem"/> <!-- This property and the one below are optional to provide client-side TLS authentication to the IdP --> <property name="spCertificate" value="/etc/shibboleth/sp-cert.pem"/> <property name="portalEntityID" value="https://canadaspis.uchicago.edu/shibboleth"/> <!-- This property is required --> </bean>
WSP's SP configuration
Configuration objectives for this SP are:
- Declare the REMOTE_USER attribute we'll use.
- Enable this SP to accept proxied SAML tokens, but only those presented by the Portal.
The example configuration below assumes that the default Application is the Portal. It is also possible to associate these declarations with specific Applications by using ApplicationOverride elements.
<ApplicationDefaults id="default" policyId="default"
entityID="$WSPEntityId"
homeURL=" "
REMOTE_USER="uid eppn persistent-id targeted-id"
signing="false" encryption="false">
...
<SessionInitiator type="Chaining" Location="/Login" isDefault="true" id="Intranet" relayState="cookie" entityID="$IdPEntityId">
<SessionInitiator type="SAML2" defaultACSIndex="1" template="bindingTemplate.html" ECP="true"/>
<SessionInitiator type="Shib1" defaultACSIndex="5"/>
</SessionInitiator>
...
</ApplicationDefaults>
...
<SecurityPolicies>
<Policy id="default" validate="false">
<PolicyRule type="MessageFlow" checkReplay="true" expires="60"/>
<PolicyRule type="Conditions">
<PolicyRule type="Audience"/>
<!-- Enable Delegation rule to permit delegated access. -->
<PolicyRule type="Delegation" match="oldest"
xmlns:del="urn:oasis:names:tc:SAML:2.0:conditions:delegation"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" >
<del:Delegate>
<saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">$PortalEntityId</saml:NameID>
</del:Delegate>
</PolicyRule>
</PolicyRule>
<PolicyRule type="ClientCertAuth" errorFatal="true"/>
<PolicyRule type="XMLSigning" errorFatal="true"/>
<PolicyRule type="SimpleSigning" errorFatal="true"/>
</Policy>
</SecurityPolicies>
The use of match="oldest" above isn't really material. The other values of "anyOrder" and "newest" both amount to the same thing when delegation is only one tier deep. We simply need to declare one of them.
TLS considerations
This section isn't accurate or complete...
SAML delegation requires some messages to be sent between Portal and IdP directly via SOAP, without an HTTP client being present. Although these messages are signed, the default security policy on the IdP requires client authentication using TLS. So the WSP needs the Portal SP's TLS public key, the Portal needs both the WSP's and the IdP's public TLS key, and the IdP needs the Portal's public TLS key.
Also, the HTTP client implementation in the Delegated SAML Authentication Library used by portlets may need to authenticate the WSP using TLS. For an SP, location(s) of credentials is declared ... tbd
For the IdP, TLS is supported by the servlet container, tomcat for us. It requires special tomcat configuration and adding a shibboleth-specific library and configuration to the JRE itself. Read https://spaces.at.internet2.edu/display/SHIB2/IdPApacheTomcatPrepare" "Supporting SOAP Endpoints" for details.
Note that this configuration actually tells tomcat to pass the certificate validation off to the IdP and not do it itself. The IdP will find a public key from its metadata for that relying party with which to validate the client certificate presented during TLS.
Signing considerations
For each entity to validate the signatures produced by the other entities, the metadata each entity has must include the public keys used by the other entities for signing. It is essential that they all share a uniform view of the metadata.
A Phased Approach to Deployment
tbd
In order to reduce the number of sources of potential errors as we begin to configure all of this, we can start with a configuration that is simplest and workable but not production ready, and then add in further configuration. Capabilities that can be peeled off and applied after everything else is working are: ---- MAYBE! ----
- TLS client authentication of SOAP messages
- Delegation restrictions
Validating that it's working
Tbd