Installation Guide: Improve Shibboleth documentation

[pdurbin]

http://guides.dataverse.org/en/latest/installation/shibboleth.html should be reviewed. We won't remove "experimental" until #2117 is closed as explained at #2939.

At minimum we need to make the following changes:

• Introduce Shibboleth and the concept of different auth modes (local vs. remote vs. both)
• Document Institution-wide Shibboleth groups developed in Shibboleth: Institution-wide Shibboleth groups #1401
• Mention chkconfig httpd on per System Config: Set proper startup scripts and order of startup for test/dev vms. #1406 (comment)
• Explain why it's important to backup /etc/shibboleth/sp-cert.pem and /etc/shibboleth/sp-key.pem and that these files should be copied around if you have multiple Glassfish servers. See also http://irclog.iq.harvard.edu/dataverse/2016-02-25
• Document keygen.sh? " I ran ./keygen.sh -f -u shibd -g shibd -h dataverse.harvard.edu -e https://dataverse.harvard.edu/sp on one of the frontends and then copied the resulting .pem files around."
• Document superuser API endpoint to migrate Shib user to builtin/local account developed in Shibboleth: Add superuser API endpoint to migrate Shib user to builtin/local account #2915.

After #2838 has gone through QA:

• Remove warning at http://guides.dataverse.org/en/4.2.4/installation/config.html#allowsignup now that Local account creation URL ignores :AllowSignup #2838 is fixed.

This effort should be coordinated with adding Shibboleth to the User Guide in #2975.

[pdurbin]

In 21bd0e8 I improved the Shibboleth section of the Installation Guide and the change can be previewed at http://guides.dataverse.org/en/2939-shib/installation/shibboleth.html

[bencomp]

As mentioned on IRC, I read the guide. One suggestion I have is that the part about converting local accounts to remote accounts is really aimed at end users and would better fit in the user guide.

[pdurbin]

@bencomp well, I half agree with you. :) ... converting from local to Shib is done by end users. We have a whole GUI and workflow that was developed mostly in #796. Converting from Shib to local is not done by end users. There's no GUI and an the API developed in #2915 is expected to be called with curl on localhost by a sysadmin. @eaquigley is working on updating the User Guide as part of #2975 so let's see what lands in the branch and see how much is added having to do with account conversion.

[pdurbin]

Passing to QA. I did a fairly significant rewrite of http://guides.dataverse.org/en/2939-shib/installation/shibboleth.html so the whole page should be reviewed to ensure it makes sense. This is part of pull request #3025.

[kcondon]

Reviewed doc, changes mentioned above are in place.
Comments:
minor typo:
-Under Install Apache, change "made" to "make" in "we can made use of the mod_shib"
minor wording change needed:
-Under Institution-wide Shib Groups, change "put" to "include":
"an “institution-wide Shibboleth group” with https://idp.testshib.org/idp/shibboleth as the IdP would put everyone who logs in via the TestShib IdP mentioned above."
possible clarification:
under Configure Apache, an experienced system admin would probably make sense of it but what changes need to be made to which files?
conf.d reads any file ending in .conf, so:
-should the enforce https part say download and rename the sample file to dataverse.conf?
-for the Edit Apache Config files part, do those settings need to go into a particular Virtual Host section? I ask because on our local config it's not even in a virtual host section and it is working. Is that just a scoping issue? Explaining this aspect of apache config files may be out of scope but wanted to mention it.

Passing back to Phil for the last part, removing experimental, when ready.

[pdurbin]

@kcondon in 4d332e0 I fixed those typos (thanks!) and re-wrote the section on configuring Apache. Part of the confusion, I think, is that I hadn't completely switched over to using "dataverse.example.edu" in all the examples so I'm using that everywhere now (formerly, I was also using shibtest.dataverse.org and demo.dataverse.org). I hope this helps. I just ran a build so you can see the changes at http://guides.dataverse.org/en/2939-shib/installation/shibboleth.html

[kcondon]

OK, all issues are fixed. Passing back to Phil to update when experimental is removed.

[pdurbin]

@kcondon I don't plan to remove "experimental" until we've run Shibboleth in production at https://dataverse.harvard.edu for a while. When I do remove "experimental" I plan to tag the commit with #2117 and put that issue (#2117) through QA. I'll pass this back to you to close or let me know if you don't like this plan. Thanks.

[kcondon]

Closing