Roles and permissions
Role
A 'role' is a configuration entry which can be associated to an actor via an access reference.
The role itself defines which endpoints that the actor can access and may also define data access restrictions on said endpoints.
Each role is identified by its own 'role key' which is set by the administrator of the application.
const roleKey1 = 'admin';
const roleKey2 = 'regular-user';
The primary configuration entry for a role is the associated permissions that the role gives access to.
Examples:
- Role 'A' has permission 'Read others document'
- Role 'B' has permission 'Read others document' but only fields 'name' and 'mime type' (projection)
- Role 'C' has permission 'Read others document' but only documents of 'mime type' 'application/pdf' (filter)
- Role 'D' has permission 'Read others document' but only documents created by my organization (rule)
Permission
A 'permission' is a configured instance of a permission definition and is associated to a role.
The level of configuration of a permission is depending on the permission definition. If the permission definition supports customizations it can be customized for the role.
Entity
The entity configuration entry for a permission is used to declare any projections or row filtering that should be applied for said entity.
The possible configuration options are defined by the respective service and its corresponding entity definition.
For a Document
- only return rows where 'mime-type' is 'application/pdf'
- only return fields: 'id', name' and 'mime-type'
Rule
A rule is an instance of a rule definition for a permission definition.
It is used to define configuration options for said rule that is specific for this instance of the permission.
Only return documents created by the organizations that my actor has access to
Role example
{
"applicationId": "63c65dee83abd41be9f61106",
"key": "CLERK",
"name": "Clerk",
"description": "Office personnel",
"servicePolicies": [
{
"serviceDefinitionSource": "APPLICATION",
"serviceDefinitionKey": "docs",
"permissions": [
{
"key": "read-docs",
"entities": [
{
"key": "doc",
"projection": {
"fieldProjections": [
{
"field": "author",
"mode": "EXCLUDE"
},
{
"field": "name",
"mode": "INCLUDE"
},
{
"field": "type",
"mode": "INCLUDE"
}
]
},
"filterCondition": {
"fieldCondition": {
"field": "type",
"operator": "ANY_OF",
"values": [
"pdf",
"docx"
]
}
}
}
],
"rules": [
{
"key": "author",
"description": "Allowed to read own and others documents",
"operator": "ANY_OF",
"values": [
"OWN",
"OTHERS"
]
}
]
}
]
}
],
"createdAt": "2024-07-02T12:28:01.512Z",
"createdBy": "63c65dee83abd41be9f61103",
"lastModifiedAt": "2024-07-02T12:29:36.991Z",
"lastModifiedBy": "63c65dee83abd41be9f61103",
"changeId": "7387014651545911377"
}
Service
A 'service' is a configuration entry that is used to declare and group a set of permissions that can be used in conjunction with said service.
Usually a service represents an API or backend service, but it can also be used to represent feature toggling in a frontend application.
The service declares the permissions, entities and rules that are configurable by the service.
Service permission definition
Each respective service is able to expose its functionality and permission capabilities by declaring a set of 'permission definitions'.
The permission definition itself declares a 'permission key' to identity itself and may also define information about any entities that are exposed via the permission.
Additional capabilities such as data access restrictions, like row filtering and attribute filtering, may also be defined the configuration entry for entities and rules.
const permissionKey1 = 'read';
const permissionKey2 = 'manage';
Service entity definition
An entity definition declares the structure of an entity and possible ways of restricting access to it. The service may choose if the definition covers all attributes or only parts of it.
Service rule definition
A service may declare rules that are applied when evaluating access to said permission and its entity. Usually the rule itself is a configuration entry for which the service applies for each request and each instance of the entity that is processed. It can be used to limit, restrict or reject access to the entity based on the rule's configuration.
The rule definition itself describe possible ways of configuring said rule. This is used when configuring permissions for a role
Service definition example
{
"applicationId": "63c65dee83abd41be9f61106",
"key": "docs",
"name": "Document service",
"description": "The service handles documents",
"permissionDefinitions": [
{
"key": "read-docs",
"name": "Read documents",
"description": "Allows user to read documents",
"status": "GA",
"supportedEntities": [
{
"key": "doc"
}
],
"supportedRules": [
{
"key": "author",
"presenceHint": "OPTIONAL"
}
]
}
],
"entityDefinitions": [
{
"key": "doc",
"name": "Document",
"description": "A user created document",
"fields": [
{
"key": "author",
"name": "Author",
"description": "Document's author",
"projection": {
"supported": true
}
},
{
"key": "name",
"name": "Name",
"description": "Document name",
"projection": {
"supported": true
}
},
{
"key": "type",
"name": "Type",
"description": "Document type",
"projection": {
"supported": true
},
"filter": {
"valueType": "STRING",
"supportSubfield": false,
"operators": [
"NONE_OF",
"ANY_OF"
]
}
}
]
}
],
"ruleDefinitions": [
{
"key": "author",
"name": "Author",
"description": "Tells if you can access any authors documents",
"supportedValueType": "STRING",
"supportedValues": [
"OTHERS",
"OWN"
],
"supportedOperators": [
"ANY_OF"
]
}
],
"createdAt": "2024-07-02T12:21:20.539Z",
"createdBy": "63c65dee83abd41be9f61103",
"lastModifiedAt": "2024-07-02T12:26:14.443Z",
"lastModifiedBy": "63c65dee83abd41be9f61103",
"changeId": "7387013783962517535"
}
Supported rules for IAM Services
Access On Level
This rule can be used to limit access to specific resources and also to allow for hierarchical access via node traversal.
See relational and hierarchical data access for more information.
Supported in IAM Services:
- actor
- node
Regular configuration options for resource access are:
- TENANT_WIDE - May access any entity in the current tenant
- NODE_DIRECT - May access entity via node association where a direct node access reference exists
- NODE_DESCENDANT - May access entity via node association where descendant nodes of any direct node access reference exists
- NODE_ANCESTOR - May access entity via node association where ancestor nodes of any direct node access reference exists
If undefined, the default behavior for this rule is TENANT_WIDE access.
{
"key": "rule.node.access-on-level",
"operator": "ANY_OF",
"values": [
"NODE_DIRECT",
"NODE_DESCENDANT"
]
}
Create With Type
This rule can be used to limit acceptable vales for the type attribute of the entity which is about to be created.
Depending on the role(s) of the caller different types can be allowed. This can also be used to enforce that the data model is used correctly to avoid arbitrary data.
Supported in IAM Services:
- actor
- node
If undefined, the default behavior for this rule is to allow any value.
{
"key": "rule.actor.create-with-type",
"operator": "ANY_OF",
"values": [
"END_USER",
"SERVICE_ACCOUNT",
"IOT_DEVICE"
]
}
Manage With Type
This rule can be used to limit management of an entity for a given set of types. Depending on the role(s) of the caller different types can be allowed to be managed.
Supported in IAM Services:
- actor
- node
If undefined, the default behavior for this rule is to allow to manage the entity of any type.
{
"key": "rule.actor.manage-with-type",
"operator": "ANY_OF",
"values": [
"END_USER",
"SERVICE_ACCOUNT"
]
}
Available Role
Defines which roles that are available when manipulating when creating access references.
Supported in IAM Services:
- actor
If undefined, the default behavior for this rule is to allow any defined role.
{
"key": "rule.actor-access.available-role",
"operator": "ANY_OF",
"values": [
"REGULAR_USER",
"ADMIN"
]
}
Manage Actor Association
Defines how an actor may manage actor access references. This is used to restrict available actors when creating such an access reference.
For example to only allow resource access references that points to actor(s) that are part of the same node as the calling actor.
Supported in IAM Services:
- actor
Configuration options for actor resource access are:
- TENANT_WIDE - May associate any actor in the current tenant
- ACTOR_DIRECT - May associate the referenced actor where an actor access reference exist
- NODE_DIRECT - May associate actors of nodes where a direct node access reference exists
- NODE_DESCENDANT - May associate actors of descendant nodes where a direct node access reference exists
- NODE_ANCESTOR - May associate actors of ancestor nodes where a direct node access reference exists
If undefined, the default behavior for this rule is TENANT_WIDE access.
{
"key": "rule.actor-access.manage-actor-association",
"operator": "ANY_OF",
"values": [
"NODE_DIRECT",
"NODE_DESCENDANT"
]
}
Manage Node Association
Defines how an actor may manage actor access references. This is used to restrict available nodes when creating such an access reference.
For example to only allow resource access references that points to node descendants of the calling actor access references.
Supported in IAM Services:
- actor
Configuration options for node resource access are:
- TENANT_WIDE - May associate any node in the current tenant
- NODE_DIRECT - May associate nodes where a direct node access reference exists
- NODE_DESCENDANT - May associate descendant nodes where a direct node access reference exists
- NODE_ANCESTOR - May associate ancestor nodes where a direct node access reference exists
If undefined, the default behavior for this rule is TENANT_WIDE access.
{
"key": "rule.actor-access.manage-node-association",
"operator": "ANY_OF",
"values": [
"NODE_DIRECT",
"NODE_DESCENDANT"
]
}
Manage With Role
Restricts which actors that are allowed to be managed depending on their current role(s). This can be used to restrict the caller to administer actors of privileged roles.
Supported in IAM Services:
- actor
{
"key": "rule.actor.manage-with-role",
"operator": "NONE_OF",
"values": [
"ADMIN"
]
}