Previous topic

Structures

Next topic

Type Inheritance

DOCUMENTATION
Last updated 18-May-2016

Access Attributes

In this section, we summarize 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 access attributes to assign permissions for different security roles.

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 schema objects are subject to access limits:

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 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 resource owner
referrer Owner of linked resource

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

../../../_images/resource-model.png

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 assigned.
    • 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 own VPS, the customer gets the owner role assigned.
    • When working with the offer, the customer gets the referrer role assigned.

Besides access for roles, it is 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, a user creates a link from his own resource to another resource (target), but he has no roles assigned to the target. In this case, the global access attribute of the target allows the user 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 access attributes.

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 has no access to a resource, but has access to all its properties, and is enabled to call those operations that are declared with verb GET.
Object Admin Owner Referrer
Global
Public
Resource true true false 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 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, i.e. from its parent structure.
  • Access to a property for a role can be directly re-assigned in 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 access to all resources provisioned from it. 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 to resources of an APS type defines its general availability and default access rule to all properties of the 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, the default value is effectively assigned for the role as specified in General Access Rules. Access attributes of a resource are not inherited, when its APS type implements other APS types.

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.

../../../_images/prop-inheritance.png
  • 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:

Custom Operation

Access to a custom operation can be assigned, inherited from type to type, and 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 and public access attributes allow some operations to be available respectively to any authenticated or non-authenticated users without subscribing to the application services providing those operations.