Improve description of Reader role

[idlewis]

https://openliberty.io/docs/latest/reference/feature/restConnector-2.0.html
This pages describes Liberty's reader user role, but doesn't make it sufficiently clear the level of access that this role provides.

Where the page currently states:
Users who are in the reader role can monitor the server ...
I'd like to change it to say something like:
Users who are in the reader role have the same permissions to monitor the server as the users in the administrator role ...

@mingcyu
@leochr
Thoughts welcome on the wording

[ramkumar-k-9286]

@idlewis
Based on the comment, the proposed change in the paragraph:

When the REST connector feature is enabled, you can configure management roles for your Open Liberty server. These roles grant users and groups that are defined in a user registry access to select administrative REST APIs. You can use any supported user registry.

• Administrator role: Grants users read and write access to administrative REST APIs, including modifying their configuration or settings.

• Reader role: Grants users the same permissions to monitor the server as in the administrator role, but without the ability to modify any configuration or settings. The role is restricted to read-only access to administrative REST APIs.

The following example maps users and groups that are defined in a basic user registry to the reader and administrator roles.

[ramkumar-k-9286]

Hi Ian @idlewis

Changes made to the description as suggested.

Draft Link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/restConnector-2.0.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[idlewis]

One further comment. This sentence from your draft:
The role is restricted to read-only access to administrative REST APIs.
I think it might be better phrased as:
The reader role restricts access to REST APIs that are considered read-only.
This is consistent with the way this idea is stated in the WebSphere Liberty docs

[ramkumar-k-9286]

@idlewis

Quick question based on your comment above.

Does the role determine the kind of access you have to a given API, or does the API itself determine which roles can access it?

The way you drafted the sentence suggests that the API determines which roles can access it. Is that the case?

CC @dmuelle

[idlewis]

The administrator role can access all APIs.
The reader role can access a subset of those APIs.
The APIs which the reader role can access provide ready only actions.
The extra APIs which the administrator role can access provide read/write actions
Sorry, it is a bit hard to describe, I hope that helps.

[idlewis]

the API determines which roles can access it. Is that the case?

Yes, I think that is accurate.

[ramkumar-k-9286]

@idlewis

One further comment. This sentence from your draft:
The role is restricted to read-only access to administrative REST APIs.
I think it might be better phrased as:
The reader role restricts access to REST APIs that are considered read-only.
This is consistent with the way this idea is stated in the WebSphere Liberty docs

Would this be ok?
The reader role provides access to REST APIs that are considered read-only. Users in this role can monitor the server, but cannot modify it in any way.

CC @dmuelle

[idlewis]

I think that should be okay. Could you update the draft so that I can review it in context?

[ramkumar-k-9286]

Hi Ian @idlewis

I've made the suggested changes.

Draft Link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/restConnector-2.0.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[dmuelle]

@ramkumar-k-9286 - looks good, please open a PR to staging