Access levels

Different types of users have different responsibilities within the billing system. Some users may not be allowed to use or see certain portions of the system. To this end, PortaBilling supports the concept of Access Control Lists (ACL). ACLs allow the PortaBilling administrator to decide, for example, that a particular sales representative can look at customers’ data, but cannot create new customers.

ACLs allow you to control what users of your site can and cannot do. Without such restrictions, it is almost impossible to guarantee that users will see or change only the information that they are allowed to.

There are default ACLs defined in the PortaBilling system. You can use default ACLs or create new ones to fit your needs.

An access level can be of the following types:

• Account (to be applied to your account)
• CC Staff (to be applied to your customer care support)
• Component (cannot be assigned to users; used only as a building block to construct other access levels)
• Customer (to be applied to retail customers or subcustomers)
• Distributor (to be applied to your distributor)
• Representative (to be applied to your representative)
• Reseller (to be applied to your resellers)
• User (access level for users of the admin interface)
• Vendor (to be applied to your vendors)

These access levels are composed of permissions and, optionally, other components (as dependencies). Permission is a basic unit in the ACL system.

Newly created ACLs will be available in the Access Level select menu of the corresponding form when creating a new object or modifying an existing object’s details. For instance, a User ACL will appear in the Access Level select menu of the Add User form (see below), a Customer ACL will be available when creating or editing a customer, and so on.

Normally you would not want reseller A to be able to use ACLs, which were designed for reseller B. To ensure that this never happens, ACLs are not visible to resellers by default. To allow a certain reseller to use the ACL, include this reseller in the ACL’s Visible To tab:

Visibility can be applied for customers’, accounts’, representatives’ and CC staff’s ACLs.

As was mentioned before the system includes a set of default ACLs that consists of components. These are used as a building block for constructing other access levels. Components will be made up of zero or more permissions, and can include other components (as dependencies). If access level ACLX includes access levels ACL1, ACL2 and ACL3 (or, in other words, is derived from ACL1, ACL2 and ACL3), then ACLX will contain all the permissions defined in ACL1, ACL2 and ACL3 (along with all of the access levels they in turn are derived from).

What happens if there is a contradiction; for example, if ACL1 denies read access to Accounts.password and ACL2 grants it? In such a case, the first available definition will be used. Thus, in the example above, access will be denied according to ACL1, which is first in the list of included access levels. Keep in mind that the sequence of ACLs matching is held top-down. In addition to these, a component has several other aspects.

When editing a component, you will first see a page as on the following screenshot:

Including components as dependencies within other components gives the system its power. Here we see that the “Admin access” level is defined by over a dozen dependent components. Note that this component does not actually define permission itself, but rather relies on the implementation of its dependents.

By deriving new components from the existing ones in the system, you can implement fine-grain access control and define User ACLs specific to your operational environment.

Permission is the fundamental unit of exchange in the PortaBilling security model. Permissions are composed of an access type, Allow / Deny permission (whether or not this is an allowed action), the relevant object, and the relative attribute of the object. To browse the permissions available for a certain page on the web interface, click the Objects icon.

The Objects icon is available for Root users only.

Let’s take the example. An access level called “Access to ‘ASR’ reports” is provided within the PortaBilling installation. It defines only one permission, which appears as in the following screenshot:

The “Access type” is set to “Read,” and the permission to “Allow.” This permission applies only to “WebForms” objects which have the attribute “ASR.”

There are four possible access types:

• Read – View the specified resource.
• Update – Modify the resource.
• Insert – Create new instances of the resource type.
• Delete – Remove instances of the resource from the system.

The Allow/Deny field defines whether this permission has been granted or withheld.

You should never have to provide fine-grain permission information yourself, as all possible permissions are already encapsulated in the components of your PortaBilling installation. For this reason, we will not discuss the “Object” and “Attribute” fields further in this section. However, it may be useful to know that wildcards can be used in these fields. For example, to allow Read access to all web pages, an ACL could be defined with the following permissions:

• Access type – “Read”.
• Allow/Deny – “Allow”.
• Object – “WebForms”.
• Attribute – “*”.

As may be guessed, the “*” in the Attribute field means “all attributes.”

In this discussion of the ACL system, we have proceeded by starting with the fundamentals and building up your skills from there. Now we will discuss the entry point for ACL management. On the PortaBilling admin interface you will find a link to “Access Levels.” This link takes you to the Access Level Management main page.

This page is similar to many others in the PortaBilling system, including a search interface at the top and a results listing at the bottom. You may search for ACLs using any combination of Name and Type.

In the results listing, you may also see the Dependencies icon and the Delete icon. ACLs can only be deleted when they are not in use. If a component contains any included components, you will be able to click on the dependencies and see search results for all dependents. The following screenshot shows all dependents for “Accounts full access.” Note that some of the dependents have their own dependencies.

From time to time you will find that the PortaBilling predefined user ACLs (Admin, Helpdesk, and so on) offer too few, or too many, restrictions for a particular class of user. In such a case, it is time to create a new user ACL.

The easiest method is to take an existing access level and create a new one modeled on it, and then modify it to fit your needs. You should examine the permissions granted to the model access level, and verify that you want to grant access to those resources.

Next, you can include other components to suit your needs. As a style recommendation, we suggest that you first create a component containing the dependent components you wish to utilize.

Finally, create a new user ACL which includes only this new component. Now you can assign this ACL to new users.

1. On the Access Level Management page, click Add.
2. On the New Access Level page, specify the following information:
   • Name – Type the custom name for this ACL.
   • Type – Select the entity this ACL is applicable for.
   • On the Components tab, define which components will be included in this ACL and in which order by using the Include, Remove, Up and Down buttons.
3. Click Save.
4. If required, on the Object/Attribute Permissions tab, define any additional permissions for this ACL.
5. Click Save.

The PortaBilling ACL management system contains style conventions which you would be well-advised to follow:

• The name of a component should be descriptive, based on the actions which it allows (for example, “Delete a node,” “Currencies read-only,” and “Access to Vendor Reports”).
• By convention, when defining a new user ACL (for example, “DemoUser”), we append “access” to the name of a component (“DemoUser access”) that includes dependent components.

We have already talked about the necessary parameters for creating or editing components, but we have not yet discussed component inclusion in detail.

Each access level may have zero or more dependent components. These components are ordered, and likewise are applied in order until the first matching permission is reached. Keep in mind that the sequence of components matching is held top-down as shown on the screenshot:

This may sound complex, but in practice the user interface is quite simple. Two columns are shown on the Components tab of the edit page for each access level. On the left, you have a list of the available components, while on the right are the included components. Between these two columns you have the Include-> and <-Remove buttons, which move selected items between the two lists. As for ordering, the Up and Down buttons on the far right-hand side of the page allow you to rearrange selected elements of the Included column.

You should now have the skills necessary to implement the PortaBilling security model and customize it to suit your business environment.