Authorization

Security Roles

APS package developer can define access rights for the following roles:

• Resource Owner is a user or an account of the system that owns this APS resource. The role is assigned in the following cases:
  • During provisioning, the ownership is assigned by the provisioning system. If an organization subscribes to a resource, the organization (account) will be the owner of the resource. When a resource, for example,, mailbox, is created for a user, the user will be the owner of the resource.
  • When an account administrator creates a resource, the account will be the owner of the resource. When an end-user creates a resource, this user will be the owner of the resource.
• Resource Referrer is a user or an account of the system that has an APS link (relation) to the APS resource, but does not own it. For example, if a link is created between a user and a virtual server, the user will be a referrer of the server, and the server will be a referrer of the user.
• Administrator (account) of a resource owner is an Administrator of the resource. For example, if a customer account was created by a reseller account, the reseller is the administrator of this customer.

Resource Administrator role always has full access to the APS Resource. For the others, the access is defined in the APS package as presented in the following diagram:

In a hosting system, these rules usually work recursively: that is the administrator of administrator also has full access to the resources below in the hierarchy:

Access Rights Policy

Access rights are defined on different levels of resource Type declaration as specified in the Access Attributes section:

• Whole Resource as described in general definition of a type
  • Owner = ALLOW|DENY (Default: ALLOW).
  • Referrer = ALLOW|DENY (Default: DENY).
• Resource Methods as described in declaration of type Operations
  • Owner = ALLOW|DENY (Default: ALLOW).
  • Referrer = ALLOW|DENY (Default: DENY).
• Resource Properties as described in declaration of type Properties
  • Owner = ALLOW|DENY (Default: ALLOW).
  • Referrer = ALLOW|DENY (Default: DENY).

Zimbra Example

An example of the services hierarchy of the Zimbra application and required access rights associated with them is shown in the diagram below where sp represents the service provider:

Security Context

Security context in APS is a zone of resources visibility for an account or end user. It means, each of accounts (provider, reseller, or customer) and end users will have own context. The context of an account or user contains all resources that the account or user owns. Once the APS controller authenticates a user, it allows the user to work with resources in their context. In the following example, a user is authenticated as a customer’s staff and thus has access to the customer’s context as a staff member.

An application has full access to all resources provisioned from it. In the following example, the application App1 gets full access to all resources provisioned from the application.

Impersonation

Mechanism

In some cases, an application may need to manage resources from another application. For example, to provision a resource for a customer or user, an application needs to reserve storage or modify a mailbox provided by another application in the same customer’s (user’s) context. APS controller enables an application for such operations by means of the impersonation mechanism.

Impersonation allows an application instance to get full control over an account’s or user’s context. For this purpose, in its REST CRUD request, the application must send the HTTP header APS-Resource-ID carrying the APS ID of an APS resource provisioned through this application instance and visible in the customer’s (user’s) context. In the following example, the application instance App2 impersonates a customer through Resource-N provisioned through that application instance in the customer’s context.

Due to the impersonation, the APS controller will process any REST operation requested by the application instance in the customer’s context.

The APS PHP framework provides a method for APS applications to impersonate a customer by a resource ID as explained in the Impersonation through Resource ID section.

Restrictions

An APS package must contain the security.json file in the package root where the application requires one of the following levels of impersonation:

• provider level means unlimited impersonation and it is the default for those applications that are not aware of this mechanism and thus do not contain the security.json file in their APS packages. This level allows the application to impersonate any account.
• reseller level allows the application to impersonate any reseller and any customer.
• customer level allows the application to impersonate any customer.

For example, to require the customer level, the file content can be as follows:

{
  "impersonation": {
    "customer": {
      "reason": "Needs to find out a list of domains to bind a VPS to."
    },
    "reseller": null,
    "provider": null
  }
}

The file structure contains one JSON parent node, called impersonation, and up to three security context nodes, called customer, reseller, and provider.

Note

An application can require only one of the above levels. For that level, the file must provide a reason for the request. Requests for the other levels must be either omitted, or empty, or null.

There are the following edge cases regarding the security.json file:

• The file does not exist - it means the application is not aware of the impersonation levels. It is the same as to request the provider (unlimited) level.
• The following content means the none level, that is the application is not going to impersonate any account:
  • The file is empty.
  • The file does not define the impersonation node or its value is null or empty.
  • All security context nodes are null, empty, or do not exist.

When the provider starts installation of an APS application instance from a package that contains the security.json file, the control panel will show the required impersonation level and the reason for it as in the following example:

To install an APS application instance, the provider must accept the required impersonation level.

In case an application violates the allowed impersonation level, the APS controller returns the 403 code with one of the following error messages:

• none allowed, but the application tries impersonate an account:

  Impersonating any account type is prohibited for this application.
  

• customer allowed, but the application tries impersonate the provider or a reseller:

  Impersonating <a reseller / the provider> is prohibited for this application.
  The application is allowed to impersonate only a customer.
  

• reseller allowed, but the application tries impersonate the provider:

  Impersonating the provider is prohibited for this application.
  The application is allowed to impersonate only a customer or reseller.
  

← Basic REST Operations

Platform Data Models →