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 Yis_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:
- Config API: Define and customize types of actors, resources, and relationships.
- Relationship Management API: Create and manage actors, resources, and relationships.
- Authorization API: Take relationships into account to make authorization decisions.
Note
PII protection
All personally identifiable information (PII) is persistently stored in the identity management user repository only. The OneWelcome Identity Platform APIs do not persistently store any PII. Even though PII can temporarily occur in volatile memory, it is not kept in any database or log of the APIs.
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:
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:
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