Shibboleth: Add shibboleth api endpoints to api doc.

[kcondon]

While testing Shib API, found it was well documented in the shib section of the installation guide, seems reasonable, but should also be added to the Native API doc, 2 sections:

Shib groups, similar and near to explicit and ip groups.
Shib users. similar and near to builtin users?

Potentially note any interactions or basic difference between group/user types.

[pdurbin]

@kcondon in 28b65ea I updated the Native API docs, which you can preview at http://guides.dataverse.org/en/2939-shib/api/native-api.html

There's a new heading call "Shibboleth Groups".

I decided that the stuff about migrating users between builtin and Shib really belongs in the Shib section of the Installation Guide where it's already documented so I didn't duplicate this content in the API Guide.

That said, in the API Guide under "native" I added the new endpoint about listing users. The "list all" endpoint is new but the "list based on identifier" endpoint (which I also just documented) has been around since 4.2 (I added it in e45dd79 to help exercise a bug). I included sample output of what the JSON looks like which should help address @pameyer 's question "what's the username of a user I'd like to promote to superuser?". Now at least you can get a list of users before you attempt to promote one of them to superuser.

I still find all the username vs. identifier vs. persistentId vs. whatever stuff confusing. Sometimes it requires @ signs. Sometimes it doesn't. In #1445 I argued that all users should have a username for disambiguation but I don't think this will be resolved any time soon.

Here's how the JSON looks for a Shib user:

{
  "authenticationProviderId": "shib",
  "persistentUserId": "https://idp.testshib.org/idp/shibboleth|myself@testshib.org",
  "id": 4,
  "identifier": "@myself",
  "displayName": "Me Myself And I",
  "firstName": "Me Myself",
  "lastName": "And I",
  "email": "myself@testshib.org",
  "superuser": false,
  "affiliation": "TestShib Test IdP"
}

Anyway, passing to QA. I hope this change to the docs is an improvement.

[pdurbin]

@kcondon #2174 is the issue about how the native API page could be improved.

[kcondon]

Closing.