Add more permission descriptions #5534
Conversation
probot-autolabeler
bot
added
the
documentation
There was a problem hiding this comment.
Thanks very much for spending the time to extract those additional definitions. I've made some optional comments. I approve whether you take any action on the optional comments or not.
This will also need review by a member of the security team, since the change is in a section where they are a code owner.
Thanks again for the contribution
Co-authored-by: Mark Waite <mark.earl.waite@gmail.com>
|
@jenkins-infra/security could one of you review and approve the added role descriptions? |
There was a problem hiding this comment.
Thanks for your interest in the security docs!
The reason I originally left this as a TODO is that the idea of this page was to go in-depth about permissions; and some of the implications of (lack of) permissions explained here were documented nowhere previously. Permissions are a difficult topic in Jenkins as they're not really well defined in many cases, and used on a best effort basis.
While some (barely above) placeholder-level content copied from Jenkins can be useful when docs are used standalone rather than as an additional tool when using Jenkins, there are problems with this content. These problems apply to Jenkins as well of course.
So I don't reject this documentation, but I also don't think it adds much value. It probably depends on whether you think listing stuff with minimal documentation that's listed elsewhere already is useful to have or not.
If you're willing to spend some more time on this topic I'd be happy to collaborate on a more extensive permission documentation that goes into more detail. Some of that we'd probably be able to adapt directly into Jenkins, and the more surprising aspects might even justify adding more form validation/admin monitors to inform admins what it is they're doing.
| @@ -141,6 +234,33 @@ Learn more in jep:223[]. | |||
| NOTE: This permission was added in Jenkins 2.222. | |||
| Some features, especially those provided by plugins, may not yet support this permission. | |||
|
|
|||
| === Credentials permissons | |||
There was a problem hiding this comment.
Should not be placed here as it's not an optional permission as explained in the introductory paragraph.
Also, while Credentials Plugin is as much of a "core" plugin as is possible, what's the threshold for putting plugin docs here?
| ==== Agent/Build | ||
|
|
||
| This permission allows users to run jobs as them on agents. | ||
|
|
||
| ==== Agent/Configure | ||
|
|
||
| This permission allows users to configure agents. | ||
|
|
||
| ==== Agent/Connect | ||
|
|
||
| This permission allows users to connect agents or mark agents as online. | ||
|
|
||
| This permission is implied by Agent/Disconnect. | ||
|
|
||
| ==== Agent/Create | ||
|
|
||
| This permission allows users to create agents. | ||
|
|
||
| ==== Agent/Delete | ||
|
|
||
| This permission allows users to delete existing agents. | ||
|
|
||
| ==== Agent/Disconnect | ||
|
|
||
| This permission allows users to disconnect agents or mark agents as temporarily offline. |
There was a problem hiding this comment.
Probably makes more sense as a list (e.g. definition list?), given the current lack of details? (Also applies to all other lists at this level.)
| This permission grants discover access to jobs. Lower than read permissions, it allows you to redirect anonymous users to the login page when they try to access a job url. | ||
| Without it they would get a 404 error and wouldn't be able to discover project names. | ||
|
|
||
| This permission is implied by Job/Read. |
There was a problem hiding this comment.
This content is actually generated by Matrix Authorization Plugin 😄
| This permission grants discover access to jobs. Lower than read permissions, it allows you to redirect anonymous users to the login page when they try to access a job url. | ||
| Without it they would get a 404 error and wouldn't be able to discover project names. |
There was a problem hiding this comment.
Here an explanation could make sense that this permission only makes sense when anonymous users are granted Overall/Read permission.
| ==== Agent/Configure | ||
|
|
||
| This permission allows users to configure agents. | ||
|
|
||
| ==== Agent/Connect | ||
|
|
||
| This permission allows users to connect agents or mark agents as online. | ||
|
|
||
| This permission is implied by Agent/Disconnect. | ||
|
|
||
| ==== Agent/Create | ||
|
|
||
| This permission allows users to create agents. |
There was a problem hiding this comment.
How sensitive are these permissions? Can this be given to just anyone, or are there security considerations? This doesn't say. (Not that it would inside Jenkins, but I'd expect more from docs that exist. IMO of course.)
|
|
||
| ==== Agent/Build | ||
|
|
||
| This permission allows users to run jobs as them on agents. |
There was a problem hiding this comment.
This is basically useless unless you already know what it does (it's related to https://www.jenkins.io/doc/book/security/build-authorization/ ).
| This permission allows users to delete existing views. | ||
|
|
||
| ==== View/Read | ||
| This permission allows users to see views (implied by generic read access). |
There was a problem hiding this comment.
implied by generic read
That's a permission that exists but hasn't been shown on the UI pretty much ever, so it's not particularly helpful.
Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com>
|
suggestions appear to be updated, thanks so much @zbynek! @daniel-beck when you have a moment, would you be able to review the updates here and let us know if there's anything else that needs to be cleared up? Thanks! |
|
Besides two minor formatting issues that have had suggested changes applied, my feedback remains unaddressed (neither acted on, nor explicitly rejected). |
|
@daniel-beck I went through your review notes and extended some paragraphs a bit.
Agreed. My goal was mostly to put the information somewhere where it's accessible and searchable. If you have some more pointers how to make this useful, please let me know. |
I don't think useful docs exist yet, therefore my offer to collaborate on creating that. |
|
Hi @daniel-beck, when you have a moment, would you be able to confirm and review the changes on this PR? Thanks! |
|
@daniel-beck I know this is still pretty minimal, but do you think it's already worth merging? |
The permission descriptions are copied from tooltips in Jenkins global security configuration.
Direct preview link: https://deploy-preview-5534--jenkins-io-site-pr.netlify.app/doc/book/security/access-control/permissions/