Extended read and system read permission allow read only access
to parts of Jenkins.
The jelly taglib’s in core will render a read only look and feel,
if the user only has access to read the view.
This is handled for developers transparently if they are already using one
of the supported views, like the job configure view.
Enabling permissions that use read-only views
There are 3 permissions currently that interact with read-only views:
Overall/SystemRead
Agent/ExtendedRead
Job/ExtendedRead
They are currently not enabled by default, the easiest way to enable them is to install
the Extended read permission plugin v3.2 or above.
Enabling read-only view support
Jelly example:
<!-- configure permissions on a job required for write access --><j:setvar="readOnlyMode"value="${!it.hasPermission(it.CONFIGURE)}"/><!-- administrator permissions required for write access --><j:setvar="readOnlyMode"value="${!app.hasPermission(app.ADMINISTER)}"/>
xml
Groovy example:
// configure permissions on a job required for write accessset("readOnlyMode",!it.hasPermission(it.CONFIGURE))// administrator permissions required for write accessset("readOnlyMode",!app.hasPermission(app.ADMINISTER))
groovy
Partial view read-only
It’s also possible to only use read-only mode for part of a view,
This is an example taken from the /configure page showing the
SYSTEM_READ and MANAGE permissions working together, non-editable parts of the view
render in a read only manner:
If you provide your own taglib that isn’t in Jenkins core you may need to make some changes.
Depending on what change is required there are a few different changes you might need to make,
here are a few examples.
Rendering plain text instead of a control
We also add a default text when it is empty (N/A in this case):
<j:choose><j:whentest="${readOnlyMode}"><j:choose><j:whentest="${empty(value)}"><spanclass="jenkins-not-applicable">N/A</span></j:when><j:otherwise><preclass="jenkins-readonly">${value}</pre></j:otherwise></j:choose></j:when><j:otherwise>
... your normal default configuration
</j:otherwise></j:choose>
xml
Disabling the control
It is preferable to render plain text or some other method that is obvious to the user
what is going on (disabled controls aren’t very obvious), but a lot of the javascript
and jelly taglibs depend on inputs of specific types being there for rendering,
so sometimes it is preferable to just disable the control:
Normally in Jenkins the layout tag of a page will have a permission
attribute which governs which permission is required to access the page.
Jenkins has a concept of 'impliedBy' in it’s permission, which means that each permission is allowed to be automatically granted by another one.
Job/ExtendedRead is implied by Job/Configure, which means that requiring Job/ExtendedRead
to access a view, will also grant Job/Configure access.
Here are some examples that show what you will need to update the layout tag to:
Requiring the Job/ExtendedRead permission in Jelly:
Firstly you will need to update any server side permission checks to now check
on load for the Read permission, rather than the Configure or Administer permission.
See Using StaplerProxy for more information
on this feature.
Then you will need to review if additional permission checks are required,
i.e. any methods that allow saving or sensitive data access should now require the
permission that was previously in use.
Searching for 'public .* do' is a good start as web methods normally start with 'do', but
you should carefully review to make sure nothing is now exposed that shouldn’t be.
You do not need to worry about bumping your minimum required Jenkins core version
as this feature is driven by variables set in the jelly context,
old versions of Jenkins will just ignore it.