Page Comparison

Each macro that can be restricted must have

a

at least one configuration entry in the Macro Security properties file. This is known as a Use Restrictions.

For example, the Cache macro might have an entry that looks like one of the following:

Code Block

language	text
linenumbers	true

cache = *ANY
cache = confluence-administrators
cache = confluence-administrators, trusted-users-cache
cache = bswift
cache = space:DEMO

In the above example:

"cache" is the property key and the information after the equal sign (=) is the property value.
Both property keys and property values are case-sensitive.
Property values are a comma separated list of groups or userids, or space keys in the form of space:xxx where "xxx" is the space key.
Line 1 uses *ANY to denote that anyone can

add

create and edit content that uses the Cache macro

in Confluence content

, effectively making its use "unrestricted."
Line 2 indicates that

the Cache macro can

only

be added and edited by

members of the "confluence-administrators" group can create and edit content that uses the Cache macro. (Content using the Cache macro would require an "edit" page restriction indicating only members of the "confluence-administrators" group can edit the page or, alternatively, an "edit page restriction to one or more userids who are members of the confluence-administrators group.)
Line 3 indicates that

the Cache macro can

only

be added and edited by

members of

either

the "confluence-administrators"

or

and "trusted-users-cache"

group

groups can create and edit content that uses the Cache macro. (Content using the Cache macro would require an "edit" page restriction indicating that only members of the "confluence-administrators" group and/or "trusted-users-cache" group can edit the page or, alternatively, an "edit page restriction to one or more userids who are members of those groups.)
Line 4 indicates that

the Cache macro can

only

be added and edited by

the user "bswift" can create or edit content that uses the Cache macro. (Content using the Cache macro would require an "edit" page restriction indicating only user "bswift" can edit the page.)
Line 5 indicates that

the Cache macro can

only

be added and edited on content residing in

content within the space having a

space key

spaceKey of "DEMO" can use the Cache macro.

"

(The space would require space-level permissions that indicate only trusted users and/or groups can add pages, blogs or comments. These trusted users and/or groups need not be listed in the properties file on the entry—like this one—that uses space-based Macro Security.)

You can also combine several of these into a single entry if you like, such as:

Code Block
cache = confluence-administrators, trusted-users-cache, bswift

Parameter Restrictions

Some macros support Parameter Restrictions, offering a means to apply more granular restrictions. The Macro Security Managed Macros page details which macros support Parameter Restrictions and the parameters that are available.

For instance, the SQL macro supports the following Parameter Restrictions in addition to the "sql =" Use Restriction.

sql.datasource
sql.limit
sql.disableAntiXss
sql.querytimeout

You would need to look at the SQL macro's documentation to understand what each of these parameters accomplishes, but the syntax within the properties file is similar to what is shown above under Use Restrictions.

There are some special caveats about Parameter Restrictions:

A Parameter Restriction only applies when the user tries to change the parameter value to something different than the default.
If a Parameter Restriction is defined for the limit parameter (available on the SQL, SQL File and SQL Query macros), it is only put into effect if the user provides a parameter value that is greater than the Limit Rows Processed setting that an administrator sets in the SQL add-on's configuration.

Parameters that are "By Value"

Div

style	padding-left: 40px;

Of the above Parameter Restrictions, per the Macro Security Managed Macros page, only the "sql.datasource" parameter is noted as "(by value)". This means that you can add ".*" to the end of the parameter to have it apply to all names (of datasources, in this example) or you can add entries for one or more specific datasource names.

Parameter Restriction	What It Means...
sql.datasource.* = confluence-administrators	Only members of the confluence-administrators group can use the SQL macro with its datasource parameter set to datasources of any name.
sql.datasource.exampledb = confluence-administrators sql.datasource.hr = hr-managers	Only members of the confluence-administrators group can use the SQL macro with its datasource parameter set to "exampledb" and only members of the hr-managers group can use the SQL macro with its datasource parameter set to "hr."

Panel

bgColor	#efefef

On this page:

Table of Contents

maxLevel	3

How Parameter Restrictions Work with Use Restrictions
Div

style	padding-left: 40px;

The Parameter Restrictions are applied "on top" of the Use Restriction for that macro. In other words, an "edit" page restriction must match (only) whatever userids and/or group names are referenced in both the Use Restriction condition and the Parameter Restriction.

The following table provides some examples of correct and incorrect combinations: Table plus

columnTypes	I,S,S,E
columnAttributes	,width: 200px,,

Properties File"edit" Page Restriction(s)
on page using the SQL macroResult
(

=Valid,

=Invalid)1

sql = *ANY
sql.limit = confluence-administrators

confluence-administrators

2

sql = *ANY sql.limit = confluence-administrators

bswift
confluence-administrators

because userid "bswift" isn't listed in the SQL entries in the properties file3

sql = *ANY sql.datasource.exampledb = confluence-administrators
sql.datasource.hr = hr-managers

confluence-administrators
hr-managers

The 1st edit restriction must be present if the "exampledb" datasource is used. The 2nd edit restriction must be present if the "hr" datasource is used. You could have both of these edit restrictions in place as well.

Note too that the Use Restriction (sql = *ANY in this example) must be one of the following in order to support the 2 sql.datasource Parameter Restrictions listed:

sql = *ANY
sql = confluece-administrators, hr-managers

4sql-query = *ANY
sql-query.datasource.* = confluence-administrators
sql-query.datasource.hr = hr-managers
sql-query.datasource.finance = finance-managers

confluence-administrators
hr-managers
finance-managers

The 1st edit restriction must be present if a datasource other than "hr" and "finance". The 2nd edit restriction must be present if the "hr" datasource is used. The 3rd edit restriction must be present if the finance" datasource is used. You could have all of these edit restrictions in place as well.

This example shows how to give access to all datasources to confluence-administrators and also give specific datasource access to different groups.

5

sql = confluence-administrators, trusted-users-sql
sql.limit = confluence-administrators

confluence-administrators
trusted-users-sql

6

sql = confluence-administrators, space:DEMO

If page is in the DEMO space:

"edit" page restrictions are not necessary
Space-level permissions should ensure only trusted users can edit pages, blog posts and comments in that space, however this is not validated by Macro Security

7

sql = confluence-administrators, space:DEMO

If page is in the DEMO space:

bswift

8

sql = confluence-administrators, space:DEMO

If page is not in the DEMO space:

confluence-administrators

9

sql = confluence-administrators, space:DEMO

If page is not in the DEMO space:

no "edit" page restrictions
OR
bswift

because confluence-administrators is not referenced in "edit" page restrictions

Image Added

Versions Compared

Old Version 1

New Version Current

Key

Parameter Restrictions

Image Added