Access Attributes

This document compiles the use 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.

Granting Access

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

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

The left part represents a role name, the right part defines if 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:

• Resource
• Property
• Operation

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.

We meet the following access cases in this example:

• The provider administers the customer and hence is assigned the admin role to all customer’s resources. At the same time, the provider owns an offer linked with a 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 hence is assigned the referrer role to the offer.
  • When operating the VPS, the customer gets the owner role assigned.
  • When working with the offer, the customer gets the referrer role assigned.

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 (target), 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 at all.

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 the ways 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 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 Application

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

Effective Permissions for Role

• A role is granted permission to a base CRUD operation on processing 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 effectively 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 needed 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 permission wins the disable permission to the same object.

Resource

Access in an APS type defines the general availability of the resources of that type and default access rule to all properties of a resource. It is possible to define access for any role and define special global and public access attributes. Example of 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 (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.

Property

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 not allowed properties are removed from the JSON representation.
• When the resource is submitted to the controller and a not allowed 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 to define the global or public attribute. If property access attributes are missed in 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.

• The state property was redefined in the VPS type, and thus it does not inherit any attributes from the implemented type. The default permissions were assigned for 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 for the referrer.

Operation

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:

• Create (provision) resource
• Read (retrieve) resource
• Update (configure) resource
• Delete (unprovision) resource

Custom Operation

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/wordress/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 missed in 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 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 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) - 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) - privileges for the security roles assigned to the staff of resellers. It is a superset of the downstream clients areas.
• clients (Customer privileges tab) - 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 creating 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 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

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

• The registerPrivileges operation creates new privileges.
• The unregisterPrivileges operation removes the specified privileges.

In both operations, the REST request payload must contain an array of the privileges based on the Privilege structure. An object representing a privilege is a named list of the following components:

• title defines the title of the privilege as displayed 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 if the privilege is valid when operating the application resources of a disabled (locked) account.

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 and the name of its registered privilege.

Implementing Custom Privileges

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

1. 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));
   }
   

2. 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
   }
   

3. 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.

4. Log in to 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 members are assigned different roles.

5. To verify whether the custom operations are protected, log in to CCP using subsequently 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.

← Structures

Type Inheritance →