• Migration Topics
  • Integration
  • Csvconnector
  • Concepts
    • Automation Task Lifecycle
    • Identity and Access Management in HIRO 6
  • Best Practices
  • Api
  • ActionHandler

Introduction

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:

  1. to grant permissions to access data

  2. 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.:

  • Knowledge Expert: knowledge-expert

  • Subject Matter Expert (SME): implicitly specified by absence of knowledge-expert role

  • Administrator: org-admin

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)

If the 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. Typically, the 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.

The HIRO libraries for Java and Javascript handle most token related operations internally when the proper settings are initialized.

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 the 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.