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:
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:
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 |
---|---|
|
Resource owner |
|
Administrator of the resource owner |
|
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
}
Warning
The global
and public
access attributes have no effect in UX1 for customers when processing
the UI navigation tree in the http://www.parallels.com/ccp/2
branch as described
in Globally Accessible Resources.
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.
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 |
|
|
|
false |
Property |
|
|
|
false |
Operation using verb GET |
|
|
|
false |
Operation using verb POST/PUT/DELETE |
|
|
false |
false |
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.
An application does not have an assigned role and always has full access to all resources provisioned from the application. This cannot be reassigned.
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.
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.
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.
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.
Access to an operation for a role defines whether or not the role can invoke the operation.
Access to base CRUD operations on resources are assigned as specified in the General Access Rules section and cannot be reassigned:
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.
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.
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.
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:
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.
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.
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.
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.
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: