Relationship-based access control

The relationship-based access control enables you to set up a system of delegated administration with which users can self-manage their relationships to digital assets.

Relationships are the basic unit that link users and assets into a network. This network can be represented in a graph as a collection of nodes and edges. Each node is a digital representation of one user or asset, and each edge represents a relationship between the two adjacent nodes. These relationships can by nature be bi-directional, for example, John and Jane are siblings, or uni-directional, for example, John is the owner of Buddy, a dog. Therefore, a direction is defined for each relationship in the system.

Examples of assets:

• an appliance
• a device
• a subscription
• a confidential report
• a pet
• an IoT device

Examples of relationships:

• User X is_owner_of pet A.
• User X is_admin_of and user Y is_member_of subscription B.
• User X is_sibling_of user Y and vice versa.

When users share an asset in real-life (that is, they have a relationship with the asset), they can also share its corresponding digital resource. The resulting digital network can then be used to:

• determine which access rights a user has for the digital resources related to these real-life assets, and
• connect people (for example, a smart lock owner can be connected with professionals such as the vendor, technicians, and the alarm center).

Relationship-based access control with the OneWelcome Identity Platform

Creating and maintaining this type of network can be done centrally by the customer's back office or can be self-managed by the users in the network. The latter ensures a fast and scalable system to manage relationships (and thus the access to protected resources). The OneWelcome Identity Platform offers help with relationship-based access control by providing an API-based system:

1. Config API: Define and customize types of actors, resources, and relationships.
2. Relationship Management API: Create and manage actors, resources, and relationships.
3. Authorization API: Take relationships into account to make authorization decisions.

Configuration of the domain model: Config API

The domain model for each tenant can be managed in your relationship management portal.

Information Model

The Config API enables each tenant to define a domain model with ActorTypes, ResourceTypes, and RelationshipTypes. These attributes of actors, resources, or relationships are used by the Relationship Management API to:

• grant the associated actors specific access rights (see Authorization API),
• determine whether a type of relationship is allowed between two objects, and
• define custom attributes.

The ActorType user is already defined for new tenants. The properties attribute can be specified via Create/update an ActorType.

Examples of ActorType:

• user
• smart_device

Examples of ResourceType:

• subscription
• pet
• smart_lock

Examples of RelationshipType:

• is_parent_of
• is_owner_of
• is_admin_of
• is_member_of

Objects and Attributes

RelationshipType restrictions

The restrictions object specifies a list of allowed ActorType and ResourceType combinations with a defined direction (from/to). When relationships are assigned with the relationship management API, these restrictions are taken into account for the requested RelationshipType.

Code examples

Example: RelationshipType is_sibling_of

The RelationshipType is_sibling_of must be assigned between two users (ActorType user). It cannot be assigned between a user and a resource of, for example, type pet.

"restrictions":  [
  { "from": "user"; "to": "user" }
]

Example: RelationshipType is_owner_of

The combination "User (from) is_owner_of Pet (to)" is allowed, but the combination "Pet (from) is_owner_of User (to)" is not allowed.

"restrictions":  [
  { "from": "user"; "to": "pet" }
  { "from": "user"; "to": "smart_lock" }
]

Custom attributes

The properties attribute of the ActorTypes, ResourceTypes, and RelationshipTypes can be used to define additional (required or optional) attributes specific for the subset of objects. For example, the ResourceType pet can have the custom attributes external_identifier, birthdate, and chip_number.

Access token authorization

Requests sent to the relationship management API must be accompanied by an access token issued by a trusted authorization server. To validate the token, the issuer and its JWKS endpoint must be known to the OneWelcome Identity Platform. Optionally, the tenant can define an audience, which must be specified in the access token.

To view or update the configuration for the Relationship Management API, use the following endpoints:

• Get authorization config
• Update authorization config

Integration of access token claims

User requests sent to the Relationship Management API must be accompanied by an access token that contains claims for the Actor attributes actorId and actorType (see Managing of relationships). To guarantee the correct integration of your access tokens with the OneWelcome Identity Platform, you might need to specify the correct (custom) claims for these attributes.

New tenants are set up as follows:

• actorIdClaimPath: "$.sub"
• actorTypeClaimPath: "$.['https://your.namespace.com/node-type']"

To view or update the TokenMapping for your tenant, use the following endpoints:

• Get TokenMapping
• Update TokenMapping

When the TokenMapping configuration is absent or invalid, the UserId is set to the value of the sub claim and the UserType is set to the default ActorType user.

Managing relationships: Relationship Management API

Information Model: Relationship Management API

The Relationship Management API handles the actual creation and managing of actors (such as users), resources, and relationships. Actors can self-manage their resources and relationships, and can invite other actors to have a relationship with one of their resources.

Objects and Attributes

Invitations

Actors (or a back-office) can send invitations to other actors to propose a relationship with one of their resources or another actor. In the relationship network, an invitation can have up to three relationships. Upon its creation, it gets a relationship with the inviting actor (isCreatedBy) and with the actor or resource for which a relationship is proposed (targets). When the invitee accepts the invitation, a third relationship is formed with the actor object of the invitee (isAcceptedBy). Alternatively, the inviter might want to revoke the invitation, which results in an additional relationship between the invitation and that actor (isRevokedBy). An invitation can no longer be revoked when it has been accepted. Therefore, there will never be an isAcceptedBy and isRevokedBy for the same invitation.

Authorization

The policies specified for the Relationship Management API determine which actions actors can take on which objects. This can be based on attributes of the involved actors, resources, relationships, and invitations, such as the type and relationship direction (from or to). These policies can be specified by the tenant admin (see configuration of policies).

New tenants are set up according to a blueprint specifying default policies for use of the Relationship Management API. These policies specify that:

• Actors only have access to the resources to which they are directly related.
• Actors have limited access to actor objects with which they share a common resource (for example, a pet owner can request contact details of the vet treating the pet).
• Actors can only create an invitation for a resource to which they are directly related.
• An invitation can only be withdrawn by the inviter.
• An invitation can only be withdrawn as long as it is not yet accepted.

Using relationships in authorization decisions: Authorization API

Policies

To fully profit from the relationship network created with the Relationship Management API, the tenant can design policies for their application based on the attributes of actors, resources, and relationships. See externalized authorization for more information on how to define and implement these policies for your application.

Endpoints overview