• Home
/
• Explore m3ter Documentation
/
• Organization and Access Management

Understanding, Creating, and Managing Permission Policies

You can create Permission Policies for your Users and assign these Permission Policies to them. There are two types of Permission Policies you can assign to Users:

• Custom. The policies you create yourself for controlling access to your Organization.

• Managed. System generated policies which you can assign to Users but which you cannot edit to change the access to resources they are configured to allow or deny.

When you create a Custom Permission Policy, you can add statements to the policy that allow or deny actions for specific resources. This allows you to control very precisely what a User who has been given access to your Organization can and cannot do. For example, you might want to create a Permissions Policy that denies any Users you assign the policy to the ability to retrieve Meters.

This section explains the m3ter permissions model, lists the actions and resources you can use when adding statements to create Permission Policies, and how to create and manage your Custom Permissions Policies:

• Understanding the m3ter Permissions Model

• Permission Policy Statements - Actions and Resources

• Creating a Custom Permission Policy

Understanding the m3ter Permissions Model

The m3ter Permissions model is implemented using a three-fold framework of Effect, Action, and Resource:

• Def: A Permission is defined as imposing an effect of either allowing or denying access to a specific resource to perform a specific action on that resource.

In JSON format, the general schema for a Permission is:

1
{
2
  "Effect": {effect},
3
  "Action": [{action}],
4
  "Resource": [{resource}]
5
}

Resources

Resources are defined as m3ter Resource Identifiers (MRIs) in the format:

service:resource-type/item-type/id

Where:

• service is a distinct part of the overall m3ter system, and which forms a natural functional grouping, such as "config" or "billing".

• resource-type is the resource type item accessed - for example: "Plan", "Meter", "Bill"

• item-type is one of:

  • "item" - to specify an individual item.

  • "group" - to specify a resource group.

• id is the resource group id or the resource item id

For example:

• To denote as resource a specific Plan with an id = 12345 in the config service, the MRI would be:

config:plan/item/12345

• To denote as resource a Plan Resource Group with id= 987 (that is, applying to all Plans that are contained within the resource group) the MRI would be:

config:plan/group/987

Use of Wildcards for Resources

The use of wildcards when denoting resources is allowed. For example, to denote all Plans as the resource in a permission statement, you can use:

config:plan/*

Resource Groups

Resources can be assigned to one or more Resource Groups. For example, a Plan can be assigned to Plan Resource Groups, a Meter can be assigned to Meter Resource Groups, and so on. This is useful for cases where you want to create Permission Policies which allow or deny access to a specific subset of resources - you want to grant access to a User to only some of the Plans in your Organization.

This concept of grouping resources applies to every resource in m3ter, including Resource Groups themselves, which allows you to nest resource groups to support hierarchies of groups.

Actions

Actions define what a User is either allowed or not allowed to do with respect to a resource. For example, you can use a config:create and config:retrieve action to create a statement for a Permission Policy that allows Users to create or retrieve any Plan in your Organization. But if this is the only Permission Policy assigned to a User, they will not be able to update or delete any Plans:

1
{
2
"effect": "allow",
3
"action": [ 
4
"config:create"
5
"config:retrieve" 
6
],
7
"resource": [
8
 "config:plan/*" 
9
 ]
10
}

Please see the following section for full details and explanation on using actions against resources when creating statements for your Permission Policies.

Effects and Evaluation Logic

The effect for a Permission Policy is either to allow or to deny:

• Allow - indicates the policy is allowing access to the resource(s) for the given action(s).

• Deny - indicates the policy is denying access to the resource(s) for the given action(s).

If you create a Permission Policy with multiple statements this is how evaluation of access to a resource for a given action is applied:

• There is an implicit denial - the order of evaluation is:

  • We check to see if there is a statement that denies access to a resource for a given action. If there is, the access is denied.

  • We check to see if there is a statement that allows access to a resource for a given action. If there is, the access is allowed.

  • If there is no statement that explicitly denies and no statement that explicitly allows, the access is denied.

• In the case of a conflict of deny/allow, denial takes precedence:

  • If there is a statement that denies access to a resource for a given action and there is a statement that allows access to a resource for the same action, the access is denied.

Permission Policy Statements - Available Actions and Resources

This section lists the actions and resources available for compiling statements you add to your custom Permission Policies.

Statements - Available Actions

When creating statements for Permission Policies, actions always require a resource-type to operate against.

Some actions also require a resource path - either a specific item or group to be defined or a wildcard ‘*' to indicate all items of the resource-type.

For a config:create action, no resource path is required:

1
{
2
"effect": "deny",
3
"action": [ "config:create" ],
4
"resource": [ "config:meter" ]
5
}
6

However, for a config:retrieve action, a resource path is required:

1
{
2
"effect": "deny",
3
"action": [ "config:retrieve" ],
4
"resource": [ "config:meter/item/456" ]
5
}

For actions that don’t require a path, paths in associated MRIs will be ignored, and only the resource-type will be used.

You can use the following actions when creating Permission Policy statements:

Which Actions can I use with which Resources?

For the resources listed in the following section - except for the measurements:data resource - you can use the four config actions when building statements for your Permission Policies:

• config:create

• config:retrieve

• config:update

• config:delete

For example, suppose you want to set up a Permission Policy that you'll assign to Users of your Organization that belong to the Billing Operations Team. You want them to have full access to work with a specific collection of Bill, Account, AccountPlan, and Bill Statement resources. You can use the four config actions with the relevant resources to build the required Permission Policy statement:

1
{
2
"effect": "allow",
3
"action": [ 
4
"config:create"
5
"config:retrieve"
6
"config:update"
7
"config:delete" 
8
],
9
"resource": [ 
10
"billing:bill/*"
11
"billing:balance/*"
12
"billing:billjob/*"
13
"billing:credit/*"
14
"billing:creditAdjustment/*"
15
"config:account/*"
16
"config:accountPlan/*"
17
"config:commitment/*"
18
"config:contract/*"
19
"config:plan/*"
20
"config:planGroup/*"
21
"config:planGroupLink/*"
22
"statement:statement/*"
23
"statementjob:statementjob/*"
24
]
25
}

This means that all members of the Billing Operations Team will have full CRUD access to all resources of the type specified.

For a Permission Policy statement you want to use to define User permissions for the measurements:data resource, you cannot use any of the config actions. If you want to create a Permission Policy to allow a User full access to work with measurements data, you must use the measurements actions:

1
{
2
  "effect": "allow",
3
  "action": [
4
    "measurements:upload"
5
    "measurements:fileUpload"
6
    "measurements:retrieve"
7
  ],
8
  "resource": [
9
    "measurements:data/*"
10
  ]
11
}

Statements - Available Resources

You can use the following resources when creating Permission Policy statements:

Creating Custom Permission Policies

To create and manage Permission Policies:

1. Select Settings>Access. The Access page opens with the Users tab selected.

2. Select the Permission Policies tab:

• Any system-generated Managed Permission Policies will be listed. You can view this type of Permission Policy and assign them to your Users, but you cannot edit them.

• Any Custom Permission Policies already created for your Organization are also listed and you can view and edit these.

3. Select Create Permission Policy. The Create page opens.

4. Enter a descriptive Name for the new Permission Policy.

5. Under Statements, select Add. The page adjusts and gives you the option to use either an Advanced editor or JSON editor to add Statements to the Permission Policy.

6. The Advanced editor is selected by default. Here's an example of how to compile Statements using the Advanced editor to allow all actions for all Meters:

• Under Effects, leave the default selection as Allow.

• Under Actions, select the All Config checkbox for Create, Retrieve, Update, and Delete.

• Under Resources, leave the default selection as Selected Resources and use the drop-down to select config.meter:

7. Select the JSON editor if you want to add JSON formatted Statements. The page adjusts again to show a Statements text window. Here's an example of how to compile Statements using the JSON editor to allow all actions for all Meters:

8. When you have finished adding statements for the Permission Policy, select Create Permission Policy. The Permission Policy Details page opens for the new Permission Policy:

• The new Permissions Policy is now available for assigning to Users, Service Users, and User Groups that have access to your Organization.

9. Select Edit to edit the new policy.

10. If you want to delete a Permission Policy, return to the Permission Policies tab and select the delete icon for the Policy:

A confirmation popup appears.

11. Select Yes to confirm the delete.

Permissions Exceptions

There are instances where exceptions to the general permissions framework can occur as a result of shared data:

• For example, if a user has been assigned a Permission Policy that denies them access to Products but grants them access to Bills, when they open a Bill, some Product data referenced by the Bill's line items will be shown for the user.

Next: Managing Access and Users

Additional Support