In this release

This release is mainly devoted to the new Application management. Agents can now manage permissions to use applications, with custom roles per application (e.g. “tenant”, “operator”, “analyst”, “admin” etc.) itself.

Applications can still manage their user authentication and authorization independent of ProptechOS, but with these new features, application developers leverage the user authentication and access rights management built into ProptechOS.

New functionality

The basic level of Application Usage Access is regulated by the boolean property ‘restrictedAccess’. An Application with ‘restrictedAccess’ : ‘true’ is available to all ProptechOS users.

For applications with ‘restrictedAccess’ : ‘false’ users will need to have an AppRole assigned in order to have access.

App Roles

Apps on ProptechOS can give different users access depending on their roles. The app will see an authenticated appRole claim included in user’s request headers, and can make authorization decisions accordingly. As an admin (Property Owner Admin or Application owner), you can create and manage custom roles for your application (see App Roles Management) and assign or revoke users’ roles (see App Roles Assignment).

App Roles Management

Application Roles (App Roles) – kind of permissions that allows to set up application usage access. App Roles could be Predefined or Custom.

Predefined App Role:

{
    “id”: “00000000-0000-0000-0000-000000000000”,
    “popularName”: “Default Access”,
    “description”: “Provides Default Access to the Application”,
    “roleClaim”: “User”,
    “allowedMemberTypes”: [
      “User”
    ]
}

Custom App Roles Example:

[
  {
    “id”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
    “popularName”: “User”,
    “description”: “User”,
    “roleClaim”: “User”,
    “allowedMemberTypes”: [
      “User”
    ]
  },
  {
    “id”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
    “popularName”: “Admin”,
    “description”: “Admin”,
    “roleClaim”: “Admin”,
    “allowedMemberTypes”: [
      “User”
    ]
  }
]

Where:

  • roleClaim – specifies the value to include in the roles claim in ID tokens and access tokens authenticating an assigned user or service principal. Must not exceed 120 characters in length (for now allowed values: User, Admin)
  • allowedMemberTypes – specifies whether this app role can be assigned to users and groups (by setting to [‘User’]), to other application’s (by setting to [‘Application’], or both (by setting to [‘User’, ‘Application’])

Endpoint to fetch App Roles

  • GET /json/application/{applicationId}/approles

Endpoints to manage App Roles

  • POST /json/application/{applicationId}/approle
  • DELETE /json/application/ {applicationId}/approle/{appRoleId}

Note: When a specific AppRole is created, the Default one is not allowed to be used for assignment.

App Roles Assignment

Endpoints to assign/remove assignment to/from users:

  • PUT /json/application/{id}/approle/{appRoleId}/assign
  • PUT /json/application/{id}/approle/{appRoleId}/remove

These endpoints accepts body with array of person ids:

Body Request example:

[
    “3fa85f64-5717-4562-b3fc-2c963f66afa6”
]

Breaking changes

None

Fixes and minor updated

Improvements:

  • Added new endpoint to retrieve Actuators edge status
    • POST /json/actuators/edgestatus
  • Added new endpoint to generate Application client secret:
    • POST /json/application/{id}/secret
  • Batch device update functionality performance improvement;
  • Extended Application Specific Properties type “String” with validation field “format”. Format can contain one of the values: “date”, “time”, “date-time”, “email”, “uuid”, “uri”.

Fixed defects:

  • Device Edge status is unknown, even though all its sensors are OK (issue PLAT-3972)