Hi everyone, I'm not sure the proper avenue to vet out documentation changes, but I've got a few more from our upgrade to CAS v4 that I though might help others out. I figured I'd start with the list, and then move on to somewhere else if that was the appropriate thing.
I think that a big part of the struggles that I had with going through the CASv4 documentation was that it seems to be written for folks who are familiar with CAS - people who know the proper locations of code in specific files, etc. To that end, a lot of the documentation pages include code snippets, but don't really explain what they're doing, or what file they belong in, so I ended up doing a fair bit of googling code bits from the snippets to find examples that other folks had created to see where I was supposed to stick the stuff :P I should note in advance that I'm not trying to be "one of those people," hostile, critical, etc., and hope that I don't come off that way. I'm just hoping to save others some of the frustration I've had this week with trying to get things up and running on the new version (in a very tight deadline timeframe to boot,) and help improve the documentation of an awesomely useful software product :) I might have more changes to propose later, but these are the ones that float to the top of my coffee-filled brain this morning (in no particular order) : Ticket handling: https://wiki.jasig.org/display/CAS/CAS+Functional+Tests I don't know how many hours I spent trying to troubleshoot "INVALID TICKET" errors attempting to go through this wiki page, only to find out that the reason is because the defaults are for a ticket to be usable only one time, and to be valid only for 10 seconds. It would be nice if at the top of this page, there was information about this, as well as information about modifying cas-server-webapp/src/main/webapp/WEB-INF/spring-configuration/ticketExpirationPolicies.xml to change these defaults while you're troubleshooting things. Attribute release in CASv4: http://jasig.github.io/cas/4.0.x/integration/Attribute-Release.html http://jasig.github.io/cas/4.0.x/protocol/CAS-Protocol.html Again, tons of time wasted simply from not knowing that in CASv4, the attribute release is only through a modified serviceValidate url, requiring adding "/p3" into the URL, unless you're using SAML: https://www.mail-archive.com/[email protected]/msg18210.html In fact, it's not documented anywhere at all in the "4.0.x" wiki pages on the github site, only in three pages of the development version. http://jasig.github.io/cas/development/protocol/CAS-Protocol.html (seems to indicate that it's available in both the CAS protocol v2 URL as well as the new v3 URL: "Among all features, the most noticeable update between versions 2.0 and 3.0 is the ability to return the authentication/user attributes through the new /p3/serviceValidate response (in addition to the /serviceValidate endpoint, already existing for CAS 2.0 protocol)." which contradicts what's in http://jasig.github.io/cas/development/integration/Delegate-Authentication.html "On CAS client side, to receive attributes, you need to use the SAML validation or the new CAS 3.0 validation (/p3/serviceValidate url)." and in http://jasig.github.io/cas/development/protocol/CAS-Protocol-Specification.html: "/p3/serviceValidate MUST perform the same validation tasks as /serviceValidate and additionally return user attributes in the CAS response. See Section 2.5 and Section 2.5.7 for details." ) Retrieval of non-public attributes: This one really threw me for a loop. I could watch in the DEBUG CAS logs that the attributes specified in the configuration were getting picked up via the LdapAuthenticationHandler when I logged in: [org.ldaptive.auth.AuthenticationResponse@18963437::authenticationResultCode=AUTHENTICATION_HANDLER_SUCCESS, ldapEntry=[dn=cn=CMyers,ou=XXXX,o=XXXX[[uid[CMyers]], [mail[[email protected]]], [sn[Myers]], [workforceID[#######]], [givenName[Christopher]], [fullName[Christopher Myers]]], responseControls=null, messageId=-1], accountState=null, result=true, resultCode=SUCCESS, message=null, controls=null] [2015-03-04 15:06:30,628] DEBUG org.jasig.cas.authentication.LdapAuthenticationHandler Found principal attribute: [uid[CMyers]] [2015-03-04 15:06:30,629] DEBUG org.jasig.cas.authentication.LdapAuthenticationHandler Found principal attribute: [mail[[email protected]]] [2015-03-04 15:06:30,629] DEBUG org.jasig.cas.authentication.LdapAuthenticationHandler Found principal attribute: [fullName[Christopher Myers]] [2015-03-04 15:06:30,629] DEBUG org.jasig.cas.authentication.LdapAuthenticationHandler Found principal attribute: [workforceID[######]] [2015-03-04 15:06:30,629] DEBUG org.jasig.cas.authentication.LdapAuthenticationHandler Found principal attribute: [givenName[Christopher]] [2015-03-04 15:06:30,629] DEBUG org.jasig.cas.authentication.LdapAuthenticationHandler Found principal attribute: [sn[Myers]] but weren't stored or used anywhere. Then there is a second anonymous call to search for the same attributes for the LdapPersonAttributeDao. Since this second call was anonymous, it wasn't picking up the non-public attributes that were picked up by the authenticated login: [2015-03-04 15:06:30,630] DEBUG org.jasig.cas.persondir.LdapPersonAttributeDao Created seed map='{username=[cmyers]}' for uid='cmyers' [2015-03-04 15:06:30,630] DEBUG org.jasig.cas.persondir.LdapPersonAttributeDao Adding attribute 'username' with value '[cmyers]' to query builder 'null' [2015-03-04 15:06:30,631] DEBUG org.jasig.cas.persondir.LdapPersonAttributeDao Constructed LDAP search query [cn=cmyers] [2015-03-04 15:06:30,631] DEBUG org.jasig.cas.persondir.LdapPersonAttributeDao Generated query builder '[org.ldaptive.SearchFilter@-92255980::filter=cn={0}, parameters={0=cmyers}]' from query Map {username=[cmyers]}. [2015-03-04 15:06:30,637] DEBUG org.jasig.cas.persondir.LdapPersonAttributeDao Converted ldap DN entry [cn=CMyers,ou=XXX,o=XXX] to attribute map {uid=[CMyers], mail=[[email protected]], sn=[Myers], givenName=[Christopher]} I spent several hours Googling this, with repeated listserv comments about how it's not possible to make the two pieces talk to each other, and eventually stumbled across http://jasig.275507.n4.nabble.com/ldaptive-integration-td4660076.html which led me to the AD configuration page on the wiki: http://jasig.github.io/cas/development/installation/LDAP-Authentication.html#active-directory-authentication I hadn't paid attention to this wiki entry before because we don't use AD, we use eDirectory (essentially generic LDAP config.) Also, we don't need to authenticate to find someone'd DN, so when I'd read through this setup initially, it wasn't necessary based on the information provided there. It would be nice to have the documentation updated to provide details about both of those pieces, and to separate out the authentication from the AD part, or make it more clear that you can reuse the authentication stuff from there (slightly modified) to have the second search for attribute values be authenticated. It would also be nice if this second search could be eliminated, since the attributes are returned as a part of the first search. I found a project that purports to do just that, which would be nice if it could be included in the main CAS releases: https://github.com/robertoschwald/jasig-cas-examples-robertoschwald Side note: It would be nice in places where the documentation says things like "...provide values for property placeholders." that somewhere on the same page it would mention that the proper way of doing this is to add the values to the cas.properties file, and how to do so. Those are the big things that I ran into along the way. Other than that, and now that things seem to be up and running smoothly, I'm happy with the new version, and am excited about the new features that it provides. I think that if the documentation gets cleaned up a bit, it'll greatly help other folks getting things set up too :) -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-user
