Skip to main content

Authorization

Currently, Data Orchestrator supports a URL-based authorization for the API. Given that Data Orchestrator's data access APIs match the devices' topology like a tree, declaring the authorization in terms of path allow-listing gives enough flexibility to give each user the correct permissions without limitations.

As said, Data Orchestrator does not have the concept of user, and neither has a durable storage which tracks permissions. As such, it expects the authorization information to be inside the token, which is the only entity Data Orchestrator can trust - given it has been verified and authenticated through its signature.

Paths are given in form of a set of Perl-like Regular Expressions, and on a per-API basis. This means that each API endpoint (app, realm, etc...) has its own regular expression which defines what the user can do. Moreover, each HTTP verb in an API endpoint (e.g.: GET, POST, PUT, DELETE) can have its own regular expression, to fine-grain permissions on each path.

Note: given Data Orchestrator's interface are either read only or write only, HTTP verb fine-graining in AppEngine API is mostly useful for preventing a user from deleting a consumer Datastream even though it has write access to it. Most of the time, using only a single regular expression with no verb fine-graining works.

Examples of valid regular expressions on AppEngine API are:

  • POST::devices/.*/interfaces/com\\.my\\.interface/.*: Allows to set individual values on the com.my.interface interface on any individual device in the realm.
  • .*::.*/interfaces/com\\.my\\.monitoring\\.interface.*: Allows to get/set/delete either the aggregate or the individual values of the com.my.monitoring.interface interface on any device or device aggregation in the realm.
  • .*::devices/j0zbvbQp9ZNnanwvh4uOCw.*: Allows every operation on device j0zbvbQp9ZNnanwvh4uOCw
  • GET::devices/[a-zA-Z0-9-_]*: Allows to get every individual device's status, but denies access to any additional information/operation on them.

Examples of valid regular expressions on Realm Management API are:

  • POST::interfaces\/.*: Allows installing new interfaces in the realm.
  • GET::interfaces\/.*: Allows inspecting every interface in the realm.
  • PUT::interfaces\/.*\/0: Allows updating all draft interfaces in the realm.

Other valid examples are:

  • .*::.*: Allows any operation on the given API.

Both verb and path regular expressions are implicitly delimited by adding ^ before and $ after the regular expression string. For example, if you use GET::interfaces as regular expression in Realm Management API, the verb will be matched against ^GET$ and the path will be matched against ^interfaces$. This way the only operation allowed will be listing all the interfaces, while all operation on interfaces/ subpaths will be denied.

Token claims and formats​

Authorization regular expressions have to be contained in the token's claims. Only the JWT case will be considered given it is the primary currency Data Orchestrator supports. Every claim is an array of regular expressions, which act as a logical OR. A similar behavior could be of course achieved (and might be more efficient) with a singular regular expression, but for the sake of readability and simplicity it is allowed nonetheless. Of course, keeping the authorization claims simple and pragmatic helps in terms of performance.

Supported token claims are:

  • a_aea: Defines the regular expressions for AppEngine API
  • a_rma: Defines the regular expressions for Realm Management API
  • a_ha: Defines the regular expressions for Housekeeping API
  • a_pa: Defines the regular expressions for Pairing API
  • a_ch: Defines the regular expressions for Channels

Of course, claims are considered only after a successful token verification. This means that the claim will be processed only if the caller is authenticated against the correct authentication realm - this is especially the case for what concerns Housekeeping, which has a dedicated Authentication realm not tied to any Data Orchestrator realms.

An example of a valid token claim is:

{
"a_aea": [
"GET::devices/[a-zA-Z0-9-_]*",
".*::.*/interfaces/com\\.my\\.monitoring\\.interface.*",
".*::devices/j0zbvbQp9ZNnanwvh4uOCw.*"
],
"a_rma": ["GET::.*"]
}

Which allows very specific permissions on AppEngine API, and a "read all" on Realm Management API.

The client by default has no permission to do anything: as such, if a token is missing a claim it is simply assumed that the client isn't authorized to access that specific API. However, keeping in mind that Data Orchestrator has no concept of User, it is also true that your authentication backend might choose to emit a different token with only a subset of its real permissions to keep claims and regular expressions as pragmatic as possible. See Granular Claims in Best Practices for more details on this.

Natively supported tokens​

Data Orchestrator supports only JWT natively, which has to be signed using one of the following algorithms:

  • ES256
  • ES384
  • ES512
  • PS256
  • PS384
  • PS512
  • RS256
  • RS384
  • RS512