Skip to main content

habitat for organizations

Motivation​

AT protocol gives several useful primitives for data ownership, such as the concept of a data "repository", and the PDS (personal data server). These concepts apply not only in the realm of global networks but also in smaller networks, like those of communities or organizations. In these other contexts, the needs differ slightly: for example, if a user enters an organization, creates some data, then leaves that organization, that data might need to remain with the organization rather than travel with the user, to provide historical context and continuity within the organization.

To support data ownership in these types of contexts, habitat has developed a solution specifically for organizations. A user's habitat data repository exists in the context of a pear server (a pear server serves exactly one backing data store), but a user can have many data repository for the multiple contexts they may operate in. So, for example, a user may be part of a community 'fruit lovers', and this community would host a pear server where each individual in the community has their own data repo for data specifically tied to this community. Members of their community login with their AT protocol handle and have an AT protocol PDS independent of this community and may even have a habitat data repo for their other private data that does not conceptually belong in the 'fruit lovers' community.

This setup allows both the 'fruit lovers' community to collectively own their own data, and take on the hosting burden for data generated by community members specifically for the community. It allows the community to piggy-back on identity & authentication provided by the broader AT protocol network, as well as useful shared concepts such as lexicons. In the future, it will also allow organization admin members to dictate how data from the community is shared (with which AppViews for e.g.), in order to implement governance around privacy risk within communities and organizations.

More technical details are explained below.

Implementation​

A habitat pear server can be responsible either for generically hosting private data for users, or for hosting private data specifically in the context of an organization. In the context of an organization, only members explicitly added to the organization are allowed to maintain a repo on that server and OAuth with the server.

Each organization has two roles: admin and member. Admins may add and remove other admins or members. Both can see the complete list of admins and members. To take these actions, the /xrpc/network.habitat.org.* API endpoints are provided; see the API reference.

Organizations are enforced at the authentication (OAuth) layer, rather than authorization layer. Each organization has a dedicated pear server + backing database; a pear server cannot serve multiple organizations or have multi-tenancy (yet). Within an organization, permissions apply as they normally would using cliques or direct permission grants on records. Records within an organization can only be accessed by members of the organization, for now (see below for future features).

Self-hosting​

See instructions here: https://github.com/habitat-network/habitat/tree/master/build/debian/pear for self-hosting pear for an organization. This sets up a pear server with all the APIs described in this API reference. Instructions for running a basic org management frontend can be found here: https://github.com/habitat-network/habitat/tree/master/build/debian/frontend, though the general https://habitat.network/habitat frontend will soon be compatible with arbitrary backend pear servers.

⚠️ Under construction ⚠️

There are several in-progress features for organizations that are noted here for transparency and clarity:

  1. Allow users outside the organization to interact with data from the organization: Currently, this is not possible. In the future, we will make authentication scopes more granular so that outside individuals have access to certain scopes on data within the organization (such as read-only or write on certain collections), making apps built for organizations more powerful and collaborative.

  2. App authorization by admins: One key feature that organizations need is allowing admins to control which users have access to which apps. The converse of this is that when organizations own their own data, they can also control their privacy risk levels by authorizing apps to only access certain parts of their data.

  3. Roles within an organization: Organizations typically operate with many fluid roles, such as teams and sub-teams. Currently, cliques can only support for top-level roles in an organization, not nested roles or permissioning.

  4. Managed hosting: Currently, only manual set up by the habitat team or self-hosting are available options for orgs seeking to use habitat to own their own data. We will work with different hosting providers to allow organizations to host habitat within their cloud provider of choice, or on their own hardware.