Security Model

The APS security model includes various mechanisms to protect APS applications, resources, and the platform as a whole.

Authentication

The APS controller, as the APS bus authority, interacts through the secure HTTPS protocol with other APS participants (actors) on the APS bus using a secure authentication of every actor.

The following interactions are on the bus:

1. Platform built-in and custom UI scripts can send REST requests to the APS controller and receive notifications sent from the APS controller on behalf of APS applications. The respective sessions are set up on behalf of the user who is interacting with the platform control panel (CP) at the moment. The CP authenticates users when they log in. This makes all subsequent REST requests sent from the UI to the APS controller authenticated through the platform built-in internal mechanism.

2. The APS controller can send a REST request to an APS application instance using one of authentication protocols:

   • By default, the APS controller authenticates the actors using SSL certificates. For this purpose, it generates an X509 certificate and private key pair for every APS application instance when installing the latter. During the same installation process, the APS controller sends its own SSL certificate to the newly created APS application instance. This allows an APS application instance to authenticate the APS controller in the incoming REST requests because they must be signed by that SSL certificate.

   • The other way is based on the OAuth protocol that must be explicitly specified in a REST request sent through the APS controller. The receiving APS application instance must be preliminary configured for the use of a shared OAuth key and secret pair.

   When forwarding a request from an actor to an APS application instance, the APS controller adds the APS-Actor-ID header to specify the actor.

3. An APS application instance can send its own REST request to the APS controller. The authentication goes through the method that was used initially by the APS controller (see number two), either SSL or OAuth.

4. The provider can allow a 3rd party actor (an external management system, a custom script, or a GUI REST client) to interact with the platform services through the APS controller as explained in Using Platform Services. An actor must authenticate itself by the OAuth protocol using a shared pair of a key and secret as explained in Using APS REST API.

Authorization Fundamentals

Once the opposite side is authenticated, the APS controller defines the operations allowed for the interacting actor. The authorization mechanism defines what operations over a resource or a resource property are allowed for a certain actor. This is based on the following key points:

• The APS controller acts on behalf of the platform and can therefore perform any REST operations exposed by application services.

• The APS controller authorizes an APS application instance for any REST operations over resources provisioned from that application instance.

• The APS controller authorizes a user for REST operations over a resource depending on the following settings:

  • The user role in the account hierarchy, that is, whether the user represents an end-user or an account (provider, reseller, or customer) as described in Security Roles.

  • The user’s or account’s relationship with the resource, that is whether the user or account is the resource owner or has another relationship with it as described in Security Roles.

  • The access definition in the resource as described in Access Rights Policy.

• An APS application can impersonate a customer by sending the APS-Resource-ID header to operate APS resources of other applications used by the customer. For example, an application needs to configure a DNS zone. This impersonation influences only the authorization process and has nothing to do with authentication.

Security Roles

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

• The resource Owner role is assigned to a user or an account 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.

• The resource Referrer role is assigned to users or accounts that have and APS relationship with the APS resource, but do 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.

• The administrator of a resource owner is assigned the Administrator role of that resource. For example, if a customer account is created by a reseller, the reseller is the administrator of that customer.

The 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 the platform, these rules work recursively: that is, the administrator of the administrator also has full access to the resources lower down in the hierarchy:

Access Rights Policy

For a security role, access rights to an APS resource instantiated from an APS type are defined on different levels of the APS Type declaration as specified in the Access Attributes section:

• Whole Resource as described in general definition of the APS type

  • Owner = ALLOW|DENY (Default: ALLOW).

  • Referrer = ALLOW|DENY (Default: ALLOW).

• Resource Methods as described in declaration of the Operations in the APS type

  • Owner = ALLOW|DENY (Default: ALLOW).

  • Referrer = ALLOW|DENY (Default: ALLOW for GET, DENY for other operations).

• Resource Properties as described in declaration of the Properties in the APS type

  • Owner = ALLOW|DENY (Default: ALLOW).

  • Referrer = ALLOW|DENY (Default: ALLOW).

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

Impersonation

Impersonation is a powerful mechanism that allows APS applications to impersonate an account when it is necessary to operate APS resources of other applications.

Security Context

Security context in APS is a zone of resource visibility for an account or end user. This means that each account (provider, reseller, or customer) and end user will have their own context. The context of an account or user contains all resources that the account or user owns. After 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 therefore 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 or user’s context. The APS controller enables an application for such operations by means of the impersonation mechanism.

Impersonation allows an application instance to have 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:

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

• The reseller level allows the application to impersonate any reseller or customer.

• The 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 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.

The following edge cases pertain to the security.json file:

• The file does not exist. This means the application is not aware of the impersonation levels. It is the same as requesting the provider (unlimited) level.

• The following content means the none level, that is the application will not 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 an 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.
  

Confidentiality

While the authorization makes some resources, methods, and properties available to certain actors, it is also possible to hide values of some properties from human eyes without prohibiting the use of them. This typically concerns passwords, security keys, and other sensitive properties.

For this purpose, APS provides the encrypted attribute that you can assign to a confidential property.

Custom Privileges

The platform allows APS applications to register their own privileges on the objects (resources, properties, and operations) authorized by the access attribute.

← Security

Backend Specifics →