Most applications should use the Permission Manifest to manage permissions.
However, some applications may have an unpredictable structure which makes the normal Permission Manifest difficult to use. In this case, a rule-based approach using the Permission Manifest Manager may be more suitable.
The Permission Manifest Manager node type creates one or more manifests for nodes in the application. Each manifest is generated by a node known as a permission root, and manages the permissions of that node and all the nodes within it, except for nodes that are themselves permission roots.
To use this type, you need to:
- Create one or more roles.
- Create one or more permission manifest rules.
- Indicate what nodes you want to act as permission roots.
- Create a permission manifest manager.
Each of these steps is explained in more detail below.
Create roles
In your application library, create roles using Permission Manifest Role.
Each role has a name and a description, and a list of users, user groups or user lists of people with that role. See Role user specification for a description of how to specify users.
Create permission manifest rules
In your application library, create permission manifest rules using Permission Manifest Rule.
Each rule has:
- Rule Tag List that lists tags any of which will trigger the rule.
- Rule applicability which describes which nodes the permissions should be applied to, relative to the tagged node.
- Permission types which lists the permission types that should be granted.
- Roles which lists the roles to which the permissions should be granted.
Indicate what nodes you want to act as permission roots
To make a node a permission root, add the field Make permission manifest root to the node type. During derivation, this field will search for a manifest for the node, and if none is present will create one in the permission manifest manager identified by the binding "permissionManifestManager".
Create a permission manifest manager
Within your application structure, create an instance of Permission Manifest Manager. Link to each of your permission manifest rules.
Make it available using the binding "permissionManifestManager".
You will need to make the permission manifest manager available to all users who may create permission root nodes. You can do this by creating a permission manifest rule with the following setup:
- Set Rule Tag List to Permission manifest manager.
- Set Rule applicability to Apply the rule to the tagged node.
- Set Permission types to:
- Set Roles to identify all the users who may create permission root nodes.
A permission manifest manager does not automatically create a manifest for itself. Create an instance of Managed Permission Manifest within the permission manager and set its Permission manifest root to the permission manifest manager itself, to action the above permissions.
It usually makes sense to create a prototype Permission Manifest Manager in your application library code which lists all the rules, and inherit from that in each application. This allows you to change the rules without modifying the application structure.
If you change the rules after creating a permission manifest, you need to execute the permission manifest manager with the "action" parameter set to "refresh" to force each of the manifests to pick up the changes. You can do this programatically, or by using the button on the permission manifest manager.
Completing the permission setup
A typical packaged application will need a couple more areas of setup.
If the application creates user groups during setup, you will need to refresh the permission manifest manager (by executing it, setting the "action" parameter to "refresh") to pick up the new user groups. You can do this in a post-install script.
You are likely to need manifests for your own library code. You can do this by creating a Permission Manifest manually. Holding the permission manifest inside the permission manifest manager means it will be refreshed when the permission manifest manager is refreshed.
You can also use the feature in the installer to inherit from the subscription manifest, and then set a rule to grant use of that manifest to the appropriate users.
Other configurations
The Make permission manifest root processing creates manifests of type Managed Permission Manifest. The manifests link back to the permission root, and use the rules defined on the permission manifest manager to derive the required permissions.
You can use Managed Permission Manifest without Make permission manifest root. For example, you could use a node of type Package Synchronization to maintain a set of manifests within a manifest manager. This can be useful to add permissions to an existing structure without modifying the node types.
If you do this, you need to be cautious of node ownership. Make permission manifest root always creates manifest nodes under the ownership of the permission root, and the managed permission manifests have additional logic to delete and recreate themselves to make sure ownership stays the in line if ownership of the permission root changes. This logic doesn't apply if Make permission manifest root isn't used, and you will need to make sure that the manifest are owned by users who have the necessary authority to grant permissions.