Overview
This guide outlines the key configuration steps that had to be done in order to get an application to work with PingFederate (www.pingidentity.com). During this process, the IdP was mostly a black box to me. The developer on the IdP helped to configure, but I had no knowledge of how to configure the IdP side. So, this article will strictly cover the SP aspects.
The key goals of this initial project were simple:
- PingFederate will act as the identity provider (IdP) to authenticate the user.
- Attributes will be returned to the SP to parse and utilize within the application.
For this project, we determined that JBoss 5.1 would be our application server and we would utilize Java 1.6.
Download the distribution
The version that ultimately worked for us is a 2.0 build, dated Mar 16, 2011. This build contains bug fixes that enabled the attriubtes to be parsed and added to the user session. The following link contains the v2 builds: .
Deploy the supporting libraries
Following the guidance of another article, I took the following JARs and deployed to $JBoss/server/default/lib.
- picketlink-idm-1.1.5.GA.jar
- picketlink-fed-2.0.0-SNAPSHOT.jar
- picketlink-bindings-jboss-2.0.0-SNAPSHOT.jar
- picketlink-bindings-2.0.0-SNAPSHOT.jar
The only other setup task was to take the bean deployment XML, picketlink-sp-jboss-beans.xml, and place it in the $JBoss/server/default/deploy folder.
For initial testing, I deployed the sample IdP web application, idp.war. This is a great way to start - it makes sure that everything works as it should initially.
Setting up the web application
To begin, I took one of the web applications that comes with the distribution, employee-post.war. The 'post' portion identifies that we're using POST authentication. Predictably, I unzipped the distribution, renamed it to something else that identifies our project and deployed to $JBoss/server/default/deploy.
context.xml
Since we're running on JBoss 5.1, we made sure that the following line was in WEB-INF/context.xml:
<Valve className="org.picketlink.identity.federation.bindings.tomcat.sp.SPPostFormAuthenticator"/>
jboss-web.xml
To enable authentication, the following lines must be in WEB-INF/jboss-web.xml.
<security-domain>sp</security-domain>
Note: 'sp' is deployed by picketlink-sp-jboss-beans.xml, referenced above.
picketlink-handlers.xml
For our use cases, we determined (through much trial and error) the following handlers were necessary.
SAML2LogOutHandler
This configuration option is unchanged from the default.
<Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler"/>
SAML2AuthenticationHandler
For authentication, it was necessary to disable role picking (we were not utilizing this), and to specify the nameid-format as 'unspecified'. These 2 configuration options were absolutely essential for this solution to work. Note that your specific solution may not require these, just know that any of the standard nameid-formats will work.
<Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler">
<Option Key="DISABLE_ROLE_PICKING" Value="true"/>
<Option Key="NAMEID_FORMAT" Value="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"/>
</Handler>
SAML2AttributeHandler
This handler takes the attributes that are returned from PingFederate and places them into the user's session. See the usage of this feature at the following link: https://issues.jboss.org/browse/PLFED-159
<Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AttributeHandler" />
picketlink-idfed.xml
Configuring this file was the initial hurdle. The most important aspect is to get the service URL correct. The configured information is passed to the IdP, but our implementation required us to tell our IdP counterparts this same information. Initially, a trailing slash was not configured for the service URL. The side effect was that the browser kept bouncing back and forth between IdP and SP sites since after authentication the SP was never receiving the information. So, below is what is required. I've obfuscated the domains and context.
<PicketLinkSP xmlns="urn:picketlink:identity-federation:config:1.0" ServerEnvironment="jboss">
<IdentityURL>https://fedtst.xyz.com/idp/SSO.saml2</IdentityURL>
<ServiceURL>https://000.000.000.00/mycontext/</ServiceURL>
</PicketLinkSP>
Also, note that the ServerEnvironment is assigned the value 'jboss' since we're deploying to JBoss. The examples are set to 'tomcat', which may work, but I was instructed to make this change.
Conclusion
The configuration is straightforward in that there is no special code that needed to be written, and the correct options needed to be known. But, probably like most people, I came to this knowing next to nothing about SAML, just that it was necessary for our project. This provided our proof of concept so we could move forward confidently.
Special thanks goes to the community for providing tons of support and answering any and all questions, making numerous bug fixes/builds to make this a success.
Example of Ping Federate IDP Response to PicketLink Service Provider
<samlp:Response Destination="https://201.000.000.00/gctxyz" InResponseTo="ID_76b05a86-993e-4ba4-83b6-e0fe7d292e78" IssueInstant="2011-02-21T17:35:08.182Z" ID="o5x7YnbyTo.XL_47-oLmZwgUgpP" Version="2.0" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"> <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://test.xyz.com</saml:Issuer> <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:SignedInfo> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <ds:Reference URI="#o5x7YnbyTo.XL_47-oLmZwgUgpP"> <ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <ds:DigestValue>joOnzlFL1squOg8uAb5fLcA9x0s=</ds:DigestValue> </ds:Reference> </ds:SignedInfo> <ds:SignatureValue> ... </ds:SignatureValue> <ds:KeyInfo> <ds:X509Data> <ds:X509Certificate> ... </ds:X509Certificate> </ds:X509Data> <ds:KeyValue> <ds:RSAKeyValue> <ds:Modulus> ... </ds:Modulus> <ds:Exponent>AQAB</ds:Exponent> </ds:RSAKeyValue> </ds:KeyValue> </ds:KeyInfo> </ds:Signature> <samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </samlp:Status> <saml:Assertion Version="2.0" IssueInstant="2011-02-21T17:35:08.196Z" ID="RM9ViMLu.M-ejey1FVNCeeIBws." xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"> <saml:Issuer>https://test.xyz.com</saml:Issuer> <saml:Subject> <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">asptest</saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml:SubjectConfirmationData InResponseTo="ID_76b05a86-993e-4ba4-83b6-e0fe7d292e78" NotOnOrAfter="2011-02-21T17:40:08.196Z" Recipient="https://201.000.000.00/gctxyz"/> </saml:SubjectConfirmation> </saml:Subject> <saml:Conditions NotOnOrAfter="2011-02-21T17:40:08.196Z" NotBefore="2011-02-21T17:30:08.196Z"> <saml:AudienceRestriction> <saml:Audience>https://201.000.000.00/gctxyz</saml:Audience> </saml:AudienceRestriction> </saml:Conditions> <saml:AuthnStatement AuthnInstant="2011-02-21T17:35:08.195Z" SessionIndex="RM9ViMLu.M-ejey1FVNCeeIBws."> <saml:AuthnContext> <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified </saml:AuthnContextClassRef> </saml:AuthnContext> </saml:AuthnStatement> <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema"> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="street"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_street </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="zipcode"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_zipcode </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="state"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_state </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="lastname"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_lastname </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="firstname"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_firstname </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="billtoid"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_billtoid </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="telephonenumber"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_telephonenumber </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="city"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_city </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="email"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_email </saml:AttributeValue> </saml:Attribute> <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="contractnumber"> <saml:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> asptest_contractnumber </saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion> </samlp:Response>
Comments