- Migration Topics
- Automation Task Lifecycle
- Identity and Access Management in HIRO 6
- Best Practices
Any API request requires an access token from HIRO™ and once the token is obtained, the HIRO™ backend will always check whether the token is valid or not, whether the API request is to be granted or denied. The access token contains the details of the user and application that is accessing the API.
In HIRO, the Auth API is used to obtain access tokens. When a developer creates an application, the application needs to authenticate with the Auth API so that proper access can be granted to that application.
As explained in more detail in the Authentication article, HIRO provides 2 types of authentication flows: password flow and UI flow.
Data Governance Method in HIRO
In HIRO, data and access is governed by means of roles (or permission groups). Each account created will be assigned to one or multiple roles. In HIRO, the creation of roles provides two purposes:
to grant permissions to access data
to provide role-based control of available features and flows in the user interfaces.
By default, for any HIRO customer there is always one role defined that represents the whole customer organization (e.g. customer-domain.com). Data owned by this organization-wide role is available to all members of the organization. Customers may partition their data into multiple roles, e.g. per division or team, if data access should be further restricted. For example, team-based roles might be called it.customer-domain.com, hr.customer-domain.com, and finance.customer-domain.com.
Users are also assigned IAM roles according to their user role in the HIRO user interface, i.e.:
Subject Matter Expert (SME): implicitly specified by absence of
As such, new user accounts are automatically assigned to the organization role (all members), and have the SME role for the user interface, unless configured differently by the administrator.
Data Access Control
Data access is determined on a per-vertex level in HIRO. In general, for most entity types the allowed data access operations (whether creating, reading, updating or deleting) are determined by the vertex attibutes below:
ogit/_owner=<account_or_role> : For the data to be shared (read and write)
ogit/_reader=<account_or_role> : For data to be shared (read only)
ogit/_owner attribute of a vertex contains a specific account name, only this user has read/write
access to this vertex. Be careful when you want to restrict data access to a single user account.
ogit/_owner attribute is set to a data access role of the whole organisation or a team
(see above). In this case, any account that is assigned the role specified in the owner attribute will
have read/write access to that vertex. This user can modify the vertex and even delete the vertex.
In the same way, any account associated with the role specified in the
ogit/_reader attribute will
have read permission for that vertex.
Attention: By default, if a vertex is created without specifying the
ogit/_owner attribute, the owner
will be set to the account id of the creator, and the vertex will be accessible only to this user. Ensure
that you set the owner attribute correctly if you want other users (and the HIRO Engine!) to see the data.
Access Token for Non-UI Apps
Each application using the HIRO API needs to be registered and gets assigned an application key, consisting of client_ID and client_secret. This means that the username and password are used to identify and authenticate the user, while the application key (consisting of client_ID and client_secret) is used to identify the application. During the authentication flow, the application passes along the application key together with the user credentials, and access tokens are always issued for the specific combination of user and application.
By design, access tokens will expire after a few hours. If the access token is expired, HIRO will return the proper response (e.g. HTTP status code 401) to the application and the application must retrigger the password flow in to receive the access token.
An example for non-UI applications are Connectors. Connectors transfer data from a customer’s existing system to HIRO. Connectors are normally run as a backend service without dedicated user interface.
The app identifiers (client_id and client_secret) will be provided and used for all API interactions of the connector. As a best practice, a separate service user account should be registered for each connector, so that the origin of data can be traced.
Access Tokens and Permissions for UI Apps
The HIRO Desktop framework provides an infrastructure to host different browser applications on the platform. So the web applications are hosted on the HIRO ™ SaaS Cloud and are delivered to the user’s web browser. The HIRO Desktop framework also takes care of listing and launching the available apps, handling the user login flows, and managing user sessions. By running the UI applications inside the HIRO Desktop framework, access tokens are fully-handled by the framework, which means that developers do not have to manage the access tokens.
However, as a UI app developer, you need to take care of data access permissions by
setting the data owner (and reader) correctly when a vertex is created by the
application. An example would be when a HIRO Desktop application has an input
form for a user to enter data into HIRO. The application needs to ensure to set
ogit/_owner attribute on the new vertices correctly to the data access role
(permission group) that should have read/write permissions.
When designing a new applications, the developer needs to consider and plan the intended data access permissions, and then implement it consistently.
Head over to HIRO Auth API for examples on how to get a token.
Websocket connections and access tokens
In most cases, when developing Connectors, the Graph REST API will be used. However, there are also other types of APIs that can be utilised, i.e. the Websocket API and Event Stream. For Websocket API and Event Stream, a special handling of access tokens and token refresh is required. Websocket connections may stay active longer than the token lifetime. Therefore, the Websocket API supports a mechanism to refresh expired tokens.
For more information on the access token for Websocket API and Event Stream, please refer to the HIRO Websocket API Reference.
Ensuring that the HIRO™ Engine can access data
When data is injected to HIRO™ by Connectors, this data should typically be
processed by the HIRO™ Engine for automation of tasks. Hence, to ensure that
the HIRO™ Engine can access and work with the data injected by the Connector,
it is important to set the
ogit/owner attribute correctly when creating the
vertices. As long as there are no special data access requirements, it is a good
practice to set the the
ogit/_owner field to the data access role of the
company (e.g. _customer-domain.com). This will ensure that the HIRO™ Engine can
process the data, and that your end users can view the data in the HIRO™ frontend.