Correct /api/roles API to respond with 403 Forbidden (not 401 Unauthorized) when auth is good but no permission

[pdurbin]

What this PR does / why we need it:

The Show Role API endpoint was returning 401 Unauthorized when a permission check failed. This has been corrected to return 403 Forbidden instead. That is, the API token is known to be good (401 otherwise) but the user lacks permission (403 is now sent). See also the API Changelog.
Which issue(s) this PR closes:

• Closes Incorrect API error response when forbidden #10340

Special notes for your reviewer:

Only the one API endpoint was affected by this change:

I added a test for it.

Also, the "Show Role" code suggests that aliases are supported but they don't seem to work. So when I updated the docs I made sure to use an example with an ID.

Suggestions on how to test this:

Try the "Show Role" API and check if the status code is 403 or 401. See the updated docs for global roles vs roles that are created in a collection. It's a bit confusing, to be honest. 😬

Does this PR introduce a user interface change? If mockups are available, please link/include them here:

No.

Is there a release notes update needed for this change?:

Yes, included.

Additional documentation:

I updated the Show Role docs while I was in there: https://dataverse-guide--11116.org.readthedocs.build/en/11116/api/native-api.html#show-role

[coveralls]

coverage: 22.691%. remained the same
when pulling 76e27f3 on 10340-forbidden
into 77caada on develop.

[sekmiller]

Should we say that you may also use a role's alias?

[pdurbin]

@sekmiller it didn't work for me. This is what I put in the description of this PR:

"Also, the "Show Role" code suggests that aliases are supported but they don't seem to work. So when I updated the docs I made sure to use an example with an ID."

[sekmiller]

This does work - curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/roles/:alias?alias=admin"

Is it worth documenting?

[pdurbin]

@sekmiller yes, as discussed in person. Good catch. Please see the commit message in d4f9189 where I added this and made a few more improvements while I was in there.

[github-actions]

📦 Pushed preview images as

ghcr.io/gdcc/dataverse:10340-forbidden

ghcr.io/gdcc/configbaker:10340-forbidden

🚢 See on GHCR. Use by referencing with full name as printed above, mind the registry name.

[sekmiller]

Looks good. Thanks for the updates.

[ofahimIQSS]

tested in internal

[ofahimIQSS]

Dont know if its related to this ticket but here is an observation I had. I am unable to edit the name of a newly created role. Says, The role was not able to be saved. Role with this alias already exists. –

Steps to Reproduce:

1. Go to https://dataverse-internal.iq.harvard.edu/permissions-manage.xhtml?id=1
2. Add New Role
3. Save the role
4. Edit the role and try to rename it

Screen.Recording.2025-01-15.at.4.19.03.PM.mov