|
|
DescriptionProvides security control to restrict powerful macro capabilities to trusted users. Many powerful macros are available that can provide content and capabilities that improve productivity for Confluence users. However, in many cases, these capabilities need to be reserved for trusted users while still allowing other users the ability to view the content created with these macros. How can this be accomplished? Macro security provides the ability for administrators to easily implement and control this capability. This plugin, together with the appropriate enablers for plugin developers, provides the following capabilities:
|
Download statistics (as an independent plugin)
Compatibility
Related information
|
Usage
Macro security is based on only allowing restricted macros on pages that have edit permissions that prevent unauthorized users from changing the macro usage. Trusted uses are given the control to ensure proper usage of macro capabilities. Restricted macros will fail to render if the page permissions do not conform to the security setting for the macro. All page permissions defined for a page must be part of the configured macro security setting for the macro to be authorized. At least one page permission is required. Multiple page permissions are allowed and each is checked to ensure the group or userid is authorized by the macro security configuration. Each macro on the page determines authorization according to its configured setting.
Authorized users
- A user authorized to use a restricted macro simply edits the page as normal. Prior to previewing or saving the page, the user must add a page permission that matches one of the groups or users listed as authorized for the macro. Save the page and then continue editing as normal.
- All users authorized to view the page see the full rendered content as one would expect.
Unauthorized users
- A user edits the page as normal. If the user includes a restricted macro that the user is not authorized to use, then when the page is rendered, the restricted macro will give a macro error and not perform any further processing.
- Confluence prevents users from adding a page permission so that current page author is not allowed to edit the page. Once the page has a page permission that includes the unauthorized user, macro security will prevent rendering.
Example
- If the sql-query macro has a security setting that specifies the group SQL-experts, then only users in the SQL-experts group will be able to edit pages the successfully render the sql-query macro. Each of those pages must have a page edit permission of SQL-experts.
Administration
An administrator must configure macro security for the installation. This is done by clicking on the Configure link for the plugin. This allows for macro security to be enabled or disabled globally and to dynamically load the security settings from a property file on the Confluence server. The security file can be anywhere on the server, the default location is the Confluence home directory.
 | Migration The previous macro security implementation required the macro security property file to be located in the home directory. For migration purposes, it is recommended to continue to use the same file until all macro security implementing macros are upgraded to use the macro security plugin and the dynamic configuration capability. |
Plugin developers
- Each protected macro implements a common checking function that validates that the macro usages allowed. A macro exception is generated for unauthorized use.
- More information will be provided soon
Examples
- HTML Plugin - HTML macro is only enabled on pages that can be edited by confluence-administrators
html=confluence-administrators
- Beanshell Macro is only enabled on pages that can be edited by confluence-administrators or confluence-programmers
beanshell=confluence-administrators, confluence-programmers
- SQL Plugin - this is a more complex example. In this case, the key control point is the datasource parameter. This controls access to database information that needs to be controlled depending on the database and the permissions used to access it.
- Allow the sql macro to be used by everyone
- Restrict the ConfluenceDS data source to confluence-administrators
- Restrict the TestDS data source to test-team
sql=*ANY sql.datasource.ConfluenceDS=confluence-administrators sql.datasource.TestDS=test-team
- Example properties file - macro-security.properties
Implementing macros
Many macros are enabled for macro security, but not all are enabled to the macro security plugin. The next release of each of these macros will upgrade to this level of support. 
denotes macros that have a version available with the upgraded support.
- sql macro
- sqlquery macro
- jasperreport macro
- Beanshell Macro
- Groovy Macro
- Jython Macro
- XSLT Macro
- html macro - this is not the same as the Atlassian provided html macro!
- cache macro
- csv macro - url parameter only
- excel macro - url parameter only
- word macro - url parameter only
Live-template
The live-template macro (part of the Scaffolding Plugin) provides powerful capabilities for global and space administrators to provide template based content. Administrators control the parameterized content of the page. Users can control the parameters. This is an ideal mechanism for providing and controlling security restricted macro content within less restricted pages. The latest release of the Scaffolding Plugin (SCAFF-196) implements support that enables macro security based plugins to provide this advanced support. It allows administrators to have restricted macros within global or space specific live templates without requiring that the resulting page have page edit permissions. Administrators will have the ability to control each macro and parameter combination for live-template use where the template is global or from specific spaces.
| Example live-template authorization sql-query&live-template.datasource.TestDS=*global, QA-space |
Release history
| Version | Date | State | License | Price |
1.0.0
(#1)
|
24 Apr 2008 | Stable | Freeware / Open Source (BSD) | Free |
Closed
Comments (15)
Apr 15, 2007
Bob Swift says:
There seems to be an incompatibility problem with 2.4.x when using this capabili...There seems to be an incompatibility problem with 2.4.x when using this capability relating to Changes to the Page Permission API in Confluence 2.4. The errors occur for any macro that has been configured to enforce macro security. Atlassian has looked at this and believe the referenced method is still in the distribution and should not cause an error. A work around is to disable macro-security checking. The following is an example of the error that has appeared on at least 2.4.4 and 2.4.5.
Jun 21, 2007
Jim LoVerde says:
Any idea whether work is being done to resolve this issue? And is there a JIRA ...Any idea whether work is being done to resolve this issue? And is there a JIRA issue open for it? I've had to temporarily disable macro security in order to get around this issue (on version 2.5.3 atm).
Jun 21, 2007
Bob Swift says:
I have given up on Atlassian resolving the issue. I have upgraded to 2.5.2 and ...I have given up on Atlassian resolving the issue. I have upgraded to 2.5.2 and have temporarily disabled the security as well. The Java Scripting Plugin have been updated and the others should be there in a couple of weeks.
Jun 20, 2007
Sven Saschek says:
Version 1.3.0. Installation of the scriputil plugin fails There were errors wh...Version 1.3.0. Installation of the scriputil plugin fails
Jun 20, 2007
Bob Swift says:
You do not install this, it is bundled with other plugins.You do not install this, it is bundled with other plugins.
Aug 07, 2007
Brian M. Thomas says:
A comment from the sample macro-security.properties file: # If the proper...A comment from the sample macro-security.properties file:
This page does not make this plain, and it should (Of course, with my comment, now it does
).
This is, to my InfoSec-saturated brain, the appropriate way to proceed, and I applaud it.
But it raises a question: How, other than waiting to find it out the hard way, can an admin know which macros require entries here? It does not appear to be a standard feature of the macro user guides to document this dependency, as I don't recall reading about it in any of them. It surely would have been desirable, because I was on the point of disabling the SQL macro plugin because of its risks before our user community grew too large (we've got about 10% participation a week after announcing it to 2000 people, with plans to roll it out in roughly exponential steps over the next few months to a final target population of about 300K, so you get an idea of the urgency).
In fact, the first time I had any notion of macro-security.properties – even after having researched and installed many macro plugins and reading many Confluence documents – was when I read the startup warning message in the log saying there wasn't one, and only then did I come seeking this page.
The sample file does contain a goodly number of entries, and one comment even lists "Current restricted macros". May I presume, at any time I retrieve this sample file, that the list is indeed current (with respect to the macros documented here and on CustomWare's and Adaptavist's sites), or at the least that any macro that is installed and disabled as a result of having no entry will give a warning message in the log? That at least will prevent my greatest fear from being realized:
... 200 technically-clueless production users descending on me, asking why a little pink error message shows up on their favorite page instead of the content they were expecting..._
Aug 07, 2007
Bob Swift says:
Brian, all good points. Don't have the time to provide detail response on these...Brian, all good points. Don't have the time to provide detail response on these right now. I will try to get back to this soon. Thanks for commenting and thus documenting more of this!
Feb 17, 2008
Bob Swift says:
I have added a few of your notes to the main document to make it clearer. There...I have added a few of your notes to the main document to make it clearer. There needs to be some improvements in the documentation for each macro that uses this capability. Some have this page explicitly linked, but some do not. I will try to improve that next time macros get updated. The example file is pretty accurate since I am involved in development of most macros that implement this capability, but it is open for mistakes of omission. The intention is to have the example file accurate with the current implementation. If a new restricted macro is added, it is still goodness to not have it work until explicitly authorized - hopefully the macro documentation will alert administrators appropriately. There is no warning in the log if there are missing entries.
Feb 18, 2008
David Dembo says:
If I understand the documentation correctly, the way this works is that: Restr...If I understand the documentation correctly, the way this works is that:
Is that correct?
What I'm after is basically something that checks the restrictions at the time that a page is saved (or previewed)... if the user performing the action is permitted, the macro would be evaluated and the content rendered. If the user is not permitted:
As far as I can tell, this would still be a secure model, while allowing a lot more flexibility - restricted macros could even be used in spaces that can be edited by 'Anonymous'.
Does anyone know of a way to achieve something like this?
Mar 15, 2008
Bob Swift says:
Sorry, missed this update. Your understanding is correct. Your suggestion for s...Sorry, missed this update. Your understanding is correct. Your suggestion for somehow remembering the signature of the macro as edited by valid users is interesting, although I don't know how to do it at the moment. Please feel free to write up an issue and any proposals on how to do it. Here are a few notes in the meantime.
Mar 16, 2008
David Dembo says:
No worries, thanks Bob!No worries, thanks Bob!
Mar 16, 2008
David Dembo says:
Just noticed there's no issue tracker for this, so I'll share a couple of though...Just noticed there's no issue tracker for this, so I'll share a couple of thoughts I had here:
A more involved alternative (but IMO much-needed functionality) - add a couple of new permissions to Confluence... 'can use regular macros', and 'can use restricted macros'
Jun 20
Liam Jones says:
Ghaa! A point worth noting that I just had an epiphany for after 1/2 an hr of b...Ghaa!
A point worth noting that I just had an epiphany for after 1/2 an hr of being thoroughly stumped; sql. restrictions in the properties file don't cover the sql-query macro!
>.<
If you want to secure some sources from {sql-query} use as well as {sql} you need your macro-security.properties file to contains a rule that reads sql-query.dataSource=... as well as one for the same source which is just sql.dataSource=...!
Jun 20
Bob Swift says:
Yes, each individual macro is controlled separately. sql-query was added after t...Yes, each individual macro is controlled separately. sql-query was added after this page was created, so not explicitly discussed. In general, you want the strongest level of security on the sql macro, but you may want to allow more people for specific datasources for the sql-query macro as it is read only.
Jun 20
Liam Jones says:
Yeah, I made a silly assumption that the sql= rules were talking about the SQL p...Yeah, I made a silly assumption that the sql= rules were talking about the SQL plugin package in it's entirety. It's all working much better now!