Roles and Permissions

Overview

In Orbit, effective management of user access is crucial. The 'Roles' feature is a cornerstone of our system and empowers you to customise access control with precision and flexibility. This essential tool lets you define who can do what within Orbit, ensuring your operations run smoothly and securely. Roles and Permissions in Orbit are designed for maximum flexibility and control, seamlessly blending Role-Based Access Control (RBAC) with the nuanced capabilities of Attribute-Based Access Control (ABAC).

The 'Roles' section within Orbit MissionControl’s settings allows users to define and customise the access control to most objects within the Orbit system.

Key Highlights

• Managed Roles: Orbit offers a range of pre-configured roles, each designed to meet standard operational requirements. Predefined managed roles provide a foundation, encompassing standard access patterns suitable for common user types. These roles serve as a starting point, ensuring basic operational needs are met efficiently.

• Custom Roles: For those unique operational needs, custom roles allow you to tailor access controls. These roles can be built from scratch or modeled on existing managed roles, providing flexibility and precision in defining user capabilities.

• Conditions: Orbit’s 'Conditions' in permissions allow precise access control. Tailor permissions for specific scenarios, like restricting Vehicle actions by weight or defining webhook access by URL content.

Key Concepts and Features

Clarifying Users, Roles, and Permissions

It's essential to distinguish between users, roles, and permissions within Orbit to set up and manage access effectively.

• Users: These are individuals (Shippers, Operators & Carriers) who operate within the Orbit ecosystem. By default, Operator users are assigned managed administrator roles, which grant them comprehensive read and write access across Orbit.

• Roles: Roles are assigned to users and define their access levels. E.g. the 'Operator Administrator' managed role provides broad access, other roles can be specified to tailor user permissions more closely to their responsibilities or their respective user group (e.g. Shipper).

• Permissions: These are specific actions that roles may or may not perform on Orbit entities, such as creating, viewing, or modifying data. Each role encompasses a set of permissions that, in turn, define the capabilities of the user holding that role.

Roles

Managed Roles

Managed roles, provided by Orbit, are pre-established roles equipped with predefined permissions designed to address standard operational needs efficiently. These roles are locked for editing to maintain system integrity but can serve as a starting point for creating custom roles tailored to specific organisational requirements. Managed roles are maintained by Orbit and will be automatically updated to guarantee compatibility with system updates and new features.

Custom Roles

Custom roles offer personalised access control. They can be crafted from the ground up or based on existing roles. To use an existing role as a starting point, right-click on it in Orbit MissionControl and select 'Create a copy'. By creating custom roles, you can align the Orbit system closely with the unique functions and responsibilities within your organisation.

Every role in the Orbit system, whether managed or custom, contains the following fields:

• Name: A distinctive and recognisable name assigned to your role.

• Description (optional): A concise explanation of what the role is intended for, aiding in clarity and understanding.

• Recommended User Types (optional): Identifies the ideal user type for the role, such as shipper-user, operator-user, or carrier-user. It can be left unspecified or include multiple types if the role spans across various user functions. This helps to guide the administrator when assigning roles to users in Orbit MissionControl. Also, this helps narrowing down available roles for specific user types. For example, when inviting carrier users to the Orbit Dispatch application, you can only select roles that include carrier-user in its recommended user types. When assigning roles using Orbit’s API, recommendations are ignored.

• Status: Denotes the current state of the role, either active or inactive. An inactive status effectively removes all access privileges for users assigned to that role.

Editing and Assigning Roles

Roles are dynamic and can be edited as organisational needs evolve. You can add or remove permissions, tweak conditions, or revise the role's details and activity status. Be aware that to make these changes, your user must be granted the necessary permissions over the 'Role' Entity. All changes are recorded and can be reviewed in the role status log.

To link a role with a user, navigate to Settings → Users in Orbit MissionControl and select the user you wish to update. Just as with the roles, your user must be granted permissions over the 'OperatorUser' entity in order to proceed with this.

Permissions

Roles control access through permissions. Users can assign any number of permissions to a role. Each permission consists of:

• Authority: This denotes whether the role has permission to perform ('can') or is denied from performing ('can not') an action on an Entity. As a best practice, keep the following in mind: Direct logic is easier to reason about, so use positive rules (’can’) as much as possible! This allows to keep permissions clean, and more readable and reduces the risk of giving wrong permissions to the wrong users.

  Give permissions, don't take them away

• Action: Actions are the tasks that a role is authorised to execute: create, read, update, or delete. For instance, a role with 'can create' authority for Vehicles has the capacity to create new Vehicles in Orbit MissionControl.

• Entity: The subject of the action (e.g., Vehicle, CarrierUser (Driver), Region). This list is ever-expanding to make sure that almost all objects within the Orbit ecosystem can be included in role definitions. The current list of entities includes:

  • APIKey

  • Callout

  • Carrier

  • CarrierUser

  • CarrierTeam

  • Insights

  • LoadType

  • OperatorTeam

  • OperatorUser

  • OperatorUserInvite

  • Order

  • PropertyDefinition

  • Region

  • Role

  • Shipment

  • Shipper

  • ShipperAddress

  • ShipperTeam

  • ShipperUser

  • ShipperUserInvite

  • Shop

  • ShopApp

  • ShopSignUpConfig

  • Tour

  • TourPrice

  • Vehicle

  • VehicleClass

  • Voucher

  • Webhook

  • WorkbenchSetting

• Condition (optional): Conditions provide granularity to permissions, allowing roles to be specific about the circumstances under which they apply. The applicability of conditions is tailored to the nature of the entity in question. For example, a condition for a Vehicle-related permission could limit actions to Vehicles with a weight capacity exceeding 1000kg, whereas a Webhook-related permission could check the presence of a specific string in the endpoint URL.

Use Case Example

• Role Name: Fleet Manager Tokyo

• Permission: can create Vehicle

• Condition: License plate begins with ‘TKA’

This configuration means that users with the 'Fleet Manager Tokyo' role can create Vehicles that have a license plate starting with the letters ‘TKA’. Users will not be allowed to do or see anything else on the platform as all permissions need to be explicitly granted.