Problem

What objects can I access/modify/delete from my application?

Resolution

There are two major security contexts:

  • APS custom UI runs in account context, it can see all resources belonging to account and the ones provided by 'Application Service Reference' resource type

  • APS endpoint runs in application context, it can see all resources belonging to application itself (all instances of its resources)

Account security level

When requests are sent under account identity there are some restrictions:

  • encrypted properties are not returned by controller
  • only viewing (GET) is allowed for APS resources provided by 'Application Service Reference', to create/modify/delete the resource corresponding access role needs to be added into schema of resource initiating operation.

All account resources are available under this identity: account information, subscriptions, service users, domains, mailboxes etc including all APS resources owned by account.

Possible usage scenarios:

  • listing service users available for account for user to choose to link to one of the services
  • read account personal information to pass it to application backend (name, phone number, email address etc)

Application security level

When requests are sent under application identity there are some other restrictions:

  • only instances of application resources are returned (belonging to both provider and all accounts)
  • other resources need to be linked to one of the application resources for application to read its properties

For example: application can get service user properties provided it is linked to a resource of application

Usually all CRUD operations are initiated by user from UI through APS controller (for that resource should have methods provision(), configure(), unprovision()), during provisioning all relational properties are filled with links to corresponding objects, for example there is a relation to subscription:

"subscription": {
  "type": "http://aps-standard.org/types/core/subscription/1.0",
  "required": true,
  "collection": false
},

You can get subscription id that provides this resource from this relation (core/subscription schema)

subscription_id = $this->subscription->subscriptionId

But sometimes the application itself needs to contact the controller, possible usage scenarios:

  • To perform asynchronous operations:

    Example: you can call some long-running operation from UI, for example to sync user data, a call is placed to application backend, when endpoint receives the result it initiates a connection to APS controller to update the resources

  • To push changes to APS controller:

    Example: you collected resource usage and need to update resources with it.

  • To get encrypted properties from the controller such as passwords:

    Example: you need to get service user password.

Notes:

  • application can impersonate an account to get rid of its restrictions, for that it needs to pass APS-Resource-ID header with an id of any resource that belongs to needed account (subscription in the example below).

This can be done using APS-PHP-runtime:

$apsc = \APS\Request::getController();

$apsc_acc = $apsc->impersonate($this->subscription->aps->id);
$apsc_acc->getResource($res_id);
$all_resources = $apsc_acc->getIo()->sendRequest(\APS\Proto::GET, "/aps/2/resources/");

where $res_id is an ID of a resource that is not available from application context.

You can use $apsc to connect authenticating with application certificate and $apsc_app when you need to impersonate an account.

Please remember the following rules about impersonation:

  • Application can impersonate only using application own resource.
  • You can impersonate only using a resource which status is aps:ready. It means that there is no way to impersonate in provision or unprovision method of top (context) resource in a subscription. When installing other resources in subscription, use context resource for impersonation.
  • If you use object as a parameter to this function, make sure this object has aps->id property.

Internal content