Access Attributes¶

This document covers the uses of the set of access attributes. As described in the previous sections, for some elements (JSON objects) of a resource schema, you can use the access attributes to assign permissions for various security roles.

In this document:

Granting Access
Security Roles
General Access Rules
Resources
Properties
Operations
Integration with Platform Privileges

Granting Access ¶

Access attributes are optional, and in a JSON object definition the access map looks similar to the following example:

"access": {
  "owner": true,
  "referrer": false
}

The left part represents a role name, the right part defines whether the access to the JSON object for the role is allowed:

true - access is enabled
false - access is disabled

The following components are subject to access limits:

Resources
Properties
Operations

Security Roles ¶

There is a set of standard security roles supported by the APS controller. When a user operates a resource, the system dynamically creates a security context with one or more security roles assigned to the user. A role is assigned as specified in the following table:

Role Name	Assigned to
`owner`	Resource owner
`admin`	Administrator of the resource owner
`referrer`	Owner of a linked resource

For example, the provider owns an application offer, and a customer’s VPS is linked with the offer.

The following access cases are covered in this example:

The provider administers the customer and is therefore assigned the admin role to all of the customer’s resources. At the same time, the provider owns an offer linked with the customer’s VPS. This assigns the referrer role to the VPS for the provider.
- When operating the offer, the provider gets the owner role.
- When working with the customer’s VPS, the provider gets the admin and referrer roles assigned concurrently.
The customer owns a VPS linked with the offer, and is therefore assigned the referrer role to the offer.
- When operating the VPS, the customer is assigned the owner role.
- When working with the offer, the customer is assigned the referrer role.

Besides access assigned for the predefined roles, it is also possible to specify access to resources through two special access attributes in the respective APS type:

global assigns access to a resource or a property for any authenticated user. For example, users create a link from their own resource to another resource (the target resource), but they have no roles assigned to the target. In this case, the global access attribute of the target allows the users to succeed with this operation.
public assigns access to a resource or a property for any user and does not require authentication.

For example, to make resources of a certain APS type available to all authenticated users, add the following to the type definition:

"access": {
     "global": true
 }

General Access Rules ¶

Access rules described here will help you understand the default and effective permissions as well as how to change permissions by means of the access attribute.

Default Permissions¶

If no access is provided explicitly for a resource, the owner and admin roles have access to the resource, all its properties, and all its operations.
By default, the referrer role is enabled to call those resource operations that are declared with the verb GET.

Object	Admin	Owner	Referrer	Global Public
Resource	`true`	`true`	`true`	false
Property	`true`	`true`	`true`	false
Operation using verb GET	`true`	`true`	`true`	false
Operation using verb POST/PUT/DELETE	`true`	`true`	false	false

Assignment, Inheritance, and Reassignment¶

Access attributes of resources, resource properties, and resource operations are specified in the APS type definition.
When an APS type implements another APS type, the access attributes of properties are inherited from the parent (base) type.
Access attributes of a property are inherited from its APS type or from its parent property, that is from its parent structure.
Access to a property for a role can be directly re-assigned in the APS type definition. This overrides the inheritance for this role.
When a resource is instantiated from an APS type, the effective access attributes are assigned to the resource, its properties, and its operations for each role.

Effective Permissions for Applications¶

An application does not have an assigned role and always has full access to all resources provisioned from the application. This cannot be reassigned.

Effective Permissions for Roles¶

A role is granted permission to a base CRUD operation to process a resource property if it is granted access to all of the following objects: the resource, the operation, and the property. For example, a user whose role is referrer for a resource can change the resource state if the referrer is allowed the access to the resource, the state property, and the base PUT method.
If a custom operation is allowed for a role, a user with this role can use this operation, even if access to any properties are not allowed for the role. The reason is that the APS controller does not consider the operation parameters as resource properties and simply forwards them to the corresponding application method as arguments. The application can request the APS controller to process the required properties in a separate call with the application permissions.

Note

Nevertheless, to call a custom operation, the caller must have access to both, the resource and the custom operation.
If a user is assigned two or more roles for a resource, the “enable” value has a higher priority than the “disable” value to the same object.

Resources ¶

Access in an APS type defines the general availability of the resources of that type and the default access rule to all properties of a resource. It is possible to define access and special global and public access attributes for any role. An example of such a resource-level access definition:

{
    "apsVersion": "2.0",

    "name": "Wordpress",

    "id": "http://wordpress.org/types/wordress/1.0",
    "implements": [ "http://aps-standard.org/types/core/resource/1.0" ],

    "access": {
        "owner": true,
        "referrer": false
    }
    ...
}

If the access attribute is missed for a role in an APS type definition (that is, access to the whole resource), the default value is effectively assigned for the role to all resources instantiated from that APS type as specified in General Access Rules. It means the access attribute of a resource is not inherited from the implemented APS types, that is, from the APS type parents.

Properties ¶

A property access rule defines whether this property is available for a role through REST requests. It works in either case:

When the resource is fetched from the APS controller, all prohibited properties are removed from the JSON representation.
When the resource is submitted to the controller and a prohibited property is passed to the controller, an error is raised.

Example:

{
    "apsVersion": "2.0",

    "name": "Wordpress",

    "id": "http://wordpress.org/types/wordress/1.0",
    "implements": [ "http://aps-standard.org/types/core/resource/1.0" ],

    "access": {
        "owner": true,
        "referrer": false
    },

    "properties": {
        "admin_name" : {
            "type": "string",
            "required": true
        },
        "admin_password": {
            "type": "string",
            "encrypted": true,
            "required": true
        },
        "siteUri": { // property allowed for referrer
            "type": "string",
            "required": true,
            "access": {
              "referrer": true
            }
        }
    }

    ...
}

It is possible to assign or reassign access for any role, as well as define the global or public attribute. If property access attributes are missing in the type definition, they are inherited in one of the following ways:

If the property is implemented from another APS type and not redefined within its own APS type, its access attributes are inherited from this implemented parent (base) type.
If the property is redefined within the APS type, this definition will be effective. Correspondingly, if no access attributes were defined on the type level, the default permissions will be assigned.

In the following example, the VPS-101 server was provisioned from the VPS type that implements the server type.

../../../../_images/prop-inheritance.png

The state property was redefined in the VPS type, and therefore it does not inherit any attributes from the implemented type. The default permissions were assigned to all roles.
The pwd property was inherited from the implemented type, where the access for the owner was assigned directly, and the default permission was assigned to the referrer.

Operations ¶

Access to an operation for a role defines whether or not the role can invoke the operation.

Base CRUD Operation¶

Access to base CRUD operations on resources are assigned as specified in the General Access Rules section and cannot be reassigned:

Custom Operations¶

Access to a custom operation can be assigned, inherited from type to type, or reassigned in the child type.

Example:

{
    "apsVersion": "2.0",

    "name": "Wordpress",

    "id": "http://wordpress.org/types/wordpress/1.0",
    "implements": [ "http://aps-standard.org/types/core/resource/1.0" ],

    "access": {
        "owner": true,
        "referrer": false
    },

    "operations": {
        "calculateSomething": { // operation allowed for referrer
            "path": "/calculateSomething/{paramX}",
            "verb": "GET",

            "access": {
                "referrer": true
            },

            "response": {
              ...
            },

            "parameters": {
                "paramX": { "kind": "url", "type": "string" },
                "paramA": { "kind": "query", "type": "long" },
                "paramB": { "kind": "query", "type": "long" }
            }
         }
    }

    ...
}

If operation access attributes are missing in the type definition, they are effectively assigned in one of the following ways:

If the operation is implemented from another APS type and not redefined within its own APS type, its access attributes are inherited from this implemented parent (base) type.
If the operation is redefined within the APS type, its access attributes are assigned as specified in General Access Rules.

With access rules on custom operations, it is possible to implement an asymmetric access policy for getting and editing properties. For this purpose, we can set one access rule to the property and another access rule to an operation processing the property. For example, access to the password property is denied for a role, but the setPassword operation is allowed.

The global or public access attribute allows some operations to be available respectively to any authenticated or non-authenticated users without subscribing to the application services providing those operations.

Integration with Platform Privileges ¶

Privileges¶

An application can delegate to the administrative staff the right to assign permissions to call a custom operation. For this effect, the application adds its own privilege to the list of the platform privileges.

In the PCP or RCP, the administrators will find a new privilege if they navigate to System > Settings, then click on the Security link and switch to the Privileges tab:

There are three areas, each having its own set of privileges:

provider (Staff member privileges tab): the privileges for the security roles assigned to the provider staff. It is a superset of the downstream resellers and clients areas, that is, it includes all privileges defined in the resellers and clients areas.
resellers (Reseller privileges tab): the privileges for the security roles assigned to the staff of resellers. It is a superset of the downstream clients area.
clients (Customer privileges tab): the privileges for the security roles assigned to the staff of customers.

A privilege can be a simple one that allows or disallows a certain operation or a complex one that contains restrictions on a list of operations. APS supports the creation of a simple privilege to enable or disable a certain operation for a security role.

Roles¶

A role in an area contains a list of all privileges of that area with a certain configuration of every privilege. The staff members, authorized to create roles, can add any number of roles in their own area and downstream areas.

User Authorization¶

In the PCP or RCP, all users in the current area and all downstream areas are available at System > Users.

The platform authorization is based on the following hierarchy:

A staff member rights are defined by one or several assigned security roles from their area.
A role in an area is a set of privileges from the same area with a certain configuration of each privilege.

Integration Point¶

There are two ways to operate custom privileges: declarative and imperative. The former is easier, but the latter is more powerful. In both cases, a privilege is an object compliant with the Privilege structure of the PrivilegeManagement APS type. This structure consists of the following properties:

title defines the title of the privilege to display in PCP or RCP. It can be translated into various languages.
name is the privilege name to be used by the application when referring to the privilege in the access declaration and in the UI scripts.
area specifies one of the areas, either “provider”, “resellers”, or “clients”.
allowLocked defines whether the privilege is valid when operating the application resources of a disabled (locked) account.

Privilege Declaration¶

An APS application can declare a list of privileges in its APP-META.xml file. They are registered in the platform when the application is imported to the platform. The registration section looks as in the following example:

<privileges>
   <privilege area="clients" name="cloud-vps-edit" title="Edit cloud VPSes"/>
   <privilege area="clients" name="cloud-vps-create" title="Create cloud VPSes"/>
</privileges>

The privileges registered this way remain in the platform even if the application is removed from the platform.

Imperative Privilege Management¶

An application can operate privileges through the system-wide privilege manager based on the PrivilegeManagement APS type. The latter exposes the following operations:

registerPrivileges creates new privileges.
unregisterPrivileges removes specified privileges.

In both operations, the REST request payload must contain an array of the privileges based on the Privilege structure.

In the following example, an application registers a new privilege in the clients area:

POST /aps/2/services/privilege-manager/privileges

[{
   "title": "Start and Stop VPSes",
   "name": "start_n_stop_vps",
   "area": "clients",
   "allowLocked": "true"
}]

To assign access to a custom operation through a custom privilege, the declaration of the operation must refer to that privilege, for example in the APS PHP framework it can look as follows:

/**
* @verb(GET)
* @path("/start")
* @access(privilege,"http://aps-standard.org/samples/sample-offering#start_n_stop_vps")
* @return(string,text/json)
*/
public function start()
{
   // ... Definition of the method
}

In the access declaration, the second argument contains the APS application ID followed by the name of its registered privilege.

UI Operation¶

In the UI, a wizard action in a view can result in calling a custom operation that is protected by the considered mechanism. To verify if the current user is granted access to that operation, call the aps.apsc.checkPrivilege(<privilege-name>) method that returns true if the user is granted the permission specified as the input parameter <privilege-name>. In accordance with the above example, the call looks similar to this:

aps.apsc.checkPrivilege("http://aps-standard.org/samples/sample-offering#start_n_stop_vps");

The method helps you determine if you need to disable those buttons that call the operations disallowed for the user.

Example¶

The following are typical steps to configure and test a custom privilege.

In the method that provisions an APS application instance, require creation of the custom privilege as in the following example:

public function provision() {
   \APS\TypeLibrary::getSchemaByTypeId(
      "http://www.parallels.com/pa/pa-core-services/privilege-management/1.0"
   );
   $pm = $this->getAPSC()->getResources(
      'implementing(http://www.parallels.com/pa/pa-core-services/privilege-management/1.0)'
   );
   $privilegeManagement = new
      \com\parallels\www\pa\pa\core\services\privilege\management\PrivilegeManagement();
   $privilegeManagement->aps = $pm[0]->aps;
   $privilege = new \com\parallels\www\pa\pa\core\services\privilege\management\Privilege();
   $privilege->title = "Start and stop VPSes";
   $privilege->name = "start_n_stop_vps";
   $privilege->area = "clients";
   $privilege->allowLocked = true;
   $privilegeManagement->registerPrivileges(array($privilege));
}

In the custom operations that must delegate the access right to the custom privilege, configure the access attribute as in the following example:

/**
 * @verb(GET)
 * @path("/start")
 * @access(privilege,"http://aps-standard.org/samples/offer1p#start_n_stop_vps")
 * @return(string,text/json)
 */
public function start() {
   // ... Definition of the method
}

For the widgets influenced by the considered permission, add a code that disallows the widgets if the user is not granted that permission. For example:

if(!aps.apsc.checkPrivilege("http://aps-standard.org/samples/offer1p#start_n_stop_vps")) {
    this.byId("srv_start").set('disabled', true);
    this.byId("srv_start").set('requireItems', false);
    this.byId("srv_stop").set('disabled', true);
    this.byId("srv_stop").set('requireItems', false);
}

Typically, the above code must be in the onContext method.

Deploy the APS application including the installation of an APS application instance. After the latter is deployed, the new privilege must appear in the clients area and all upstream areas, that is in the resellers and provider areas.
Log in to the PCP and in the customer roles configure the new privilege so that in one role the privilege is enabled and in another role it is disabled. Then ensure the customer staff member are assigned different roles.
To verify whether the custom operations are protected, log in to the CCP using subsequent credentials of different staff members and initiate the custom operations. Note that the operations are available for those users whose security role allows it through the custom privilege.

Warning

The following screenshot illustrates a case when a user is not granted a certain permission but is allowed to click the buttons impacted by that permission:

../../../../_images/privilege-vps-error.png

← Structures

Type Inheritance →

CloudBlue Commerce API (DRAFT)

Table Of Contents

Previous topic

Next topic

Access Attributes¶

Granting Access ¶

Security Roles ¶

General Access Rules ¶

Default Permissions¶

Assignment, Inheritance, and Reassignment¶

Effective Permissions for Applications¶

Effective Permissions for Roles¶

Resources ¶

Properties ¶

Operations ¶

Base CRUD Operation¶

Custom Operations¶

Integration with Platform Privileges ¶

Privileges¶

Roles¶

User Authorization¶

Integration Point¶

Privilege Declaration¶

Imperative Privilege Management¶

UI Operation¶

Example¶

CloudBlue Commerce API (DRAFT)

Table Of Contents

Previous topic

Next topic

Access Attributes¶

Granting Access¶

Security Roles¶

General Access Rules¶

Default Permissions¶

Assignment, Inheritance, and Reassignment¶

Effective Permissions for Applications¶

Effective Permissions for Roles¶

Resources¶

Properties¶

Operations¶

Base CRUD Operation¶

Custom Operations¶

Integration with Platform Privileges¶

Privileges¶

Roles¶

User Authorization¶

Integration Point¶

Privilege Declaration¶

Imperative Privilege Management¶

UI Operation¶

Example¶

Granting Access ¶

Security Roles ¶

General Access Rules ¶

Resources ¶

Properties ¶

Operations ¶

Integration with Platform Privileges ¶