Access Control#

In industrial environments and data spaces, securing access to Digital Twins and their data is paramount. Role-Based Access Control (RBAC) provides a systematic approach to managing permissions, ensuring that users and systems can only access the information and operations they are authorized for. This is particularly crucial when dealing with sensitive industrial data, intellectual property, or when multiple organizations collaborate in a shared data space.

BaSyx implements comprehensive RBAC capabilities that integrate seamlessly with industry-standard identity providers like Keycloak. This allows organizations to define fine-grained access policies for Asset Administration Shells, Submodels, and their properties, while maintaining compatibility with existing enterprise security infrastructure.

The BaSyx ecosystem supports both static RBAC rules defined at deployment time and dynamic RBAC management, where access policies can be modified at runtime through dedicated management interfaces. This flexibility is essential for modern industrial scenarios where collaboration patterns and access requirements may evolve during the lifecycle of Digital Twins.

Note

Two comprehensive examples demonstrating different RBAC scenarios are available in the Examples on GitHub:

Feel free to try them out yourself!

RBAC Architecture in BaSyx#

The following diagram illustrates how role-based access control is implemented across the BaSyx ecosystem:

Authentication and Authorization Flow#

The sequence diagram below shows the detailed process of how users authenticate and gain access to protected resources:

Key RBAC Features in BaSyx#

Static RBAC Configuration#

Pre-defined Roles: Configure user roles and permissions at deployment time
Component-level Security: Secure individual BaSyx components (AAS Repository, Submodel Registry, etc.)
Fine-grained Permissions: Control access to specific AAS instances, Submodels, or properties
Integration with Enterprise Identity: Seamless integration with existing LDAP, Active Directory, or OAuth providers

Dynamic RBAC Management#

Runtime Policy Updates: Modify access rules without system restarts
Submodel-based Rule Storage: Store RBAC rules as Submodel elements for standardized management
Collaborative Access Control: Enable suppliers and partners to grant access to their Digital Twins
Audit Trail: Track all permission changes and access attempts

Security Scope Coverage#

AAS Repository: Control access to Asset Administration Shells
Submodel Repository: Manage permissions for individual Submodels
Registry Services: Secure discovery and lookup operations
AAS Environment: Comprehensive protection for complete AAS environments
File Upload/Download: Control AASX file operations and content access

Industrial Use Cases#

Supply Chain Collaboration#

In complex supply chains, suppliers need to share specific information about their components while protecting intellectual property. BaSyx RBAC enables:

Selective Data Sharing: Grant access only to relevant properties and Submodels
Temporary Access: Provide time-limited access for specific projects
Role-based Visibility: Different access levels for engineers, quality inspectors, and managers
Dynamic Permission Grants: Suppliers can grant access when delivering components

Multi-tenant Manufacturing Platforms#

Manufacturing platforms serving multiple customers require strict data isolation:

Tenant Isolation: Ensure customers can only access their own Digital Twins
Service Provider Access: Allow platform operators to maintain systems while protecting customer data
Cross-tenant Collaboration: Enable controlled sharing for joint projects
Compliance Reporting: Generate audit reports for regulatory requirements

RBAC Rule Structure#

BaSyx uses JSON-based RBAC rules that define the relationship between roles, actions, and target resources:

Basic Rule Example#

{
  "role": "engineer",
  "action": "READ",
  "targetInformation": {
    "@type": "aas",
    "aasIds": ["urn:example:manufacturing:line1"]
  }
}

Advanced Rule with Multiple Actions#

{
  "role": "quality_inspector",
  "action": ["READ", "EXECUTE"],
  "targetInformation": {
    "@type": "submodel",
    "aasIds": "*",
    "submodelIds": ["urn:example:quality:inspection"]
  }
}

Getting Started with BaSyx Security#

1. Basic Secured Setup#

Start with the foundational security example that demonstrates:

Keycloak integration and user management
Basic role definitions and assignments
Secure access to AAS Web UI
File upload with specific permissions

2. Dynamic RBAC Management#

Explore advanced scenarios including:

Runtime policy management through Submodel interfaces
Cross-organizational access control
Dynamic permission granting in supply chain scenarios
Audit and compliance tracking

BaSyx Secure Setup#

All BaSyx components support role-based access control by using Keycloak as identity provider. Access rules are defined based on roles. Roles are defined in the Keycloak server.

In this setup, an nginx proxy is used to expose the different BaSyx services under dedicated subdomains. The main URLs are:

AAS Web UI: http://aasgui.basyx.localhost

Keycloak: http://keycloak.basyx.localhost

Additional service URLs can be found in the docker-compose file.

Modern browsers like Google Chrome, Firefox, and others automatically resolve any URL ending with .localhost to the local address 127.0.0.1. This means requests to these URLs are directly routed to your own machine, where the nginx instance running inside Docker forwards the requests to the corresponding BaSyx service. As an alternative for setups where .localhost handling might not work correctly, you could manually map the required domains to 127.0.0.1 by editing your /etc/hosts file.

To start the secure setup execute the following command

docker-compose up -d

This will start the BaSyx components and the Keycloak server. The Keycloak server can be found at http://keycloak.basyx.localhost. There you can login as admin with username admin and password keycloak-admin. BaSyx Realm User Overview

The example comes with an already configured realm BaSyx and a user john.doe with password johndoe. This user has the admin role and can access all BaSyx components and all information about each component.

The entry point for accessing the Asset Administration Shells and their Submodels is the AAS Web UI running at http://aasgui.basyx.localhost. After opening the page you will be redirected to the Keycloak login page. Use the credentials of user john.doe to log in. Login to BaSyx using Keycloak

From there you can access the AAS and Submodels of the BaSyx components. The UI shows the login status in the top right corner. To end your session click on the logout button in the top right corner. Logout button in the AAS UI

There are several other user accounts available, each with different roles. You can use them to test the different levels of access. The password for these users is their username without the dots. You can find them in the Users tab of the BaSyx realm in Keycloak.

Upload AAS Environment files (AASX/JSON/XML) with RBAC#

This secured example also demonstrates the secured upload of AAS Environment files with a specific role basyx-uploader. To upload an AAS Environment file using the AAS GUI, please login using below account:

username: basyx.uploader
password: basyxuploader

After logging in, use the upload icon to upload the AAS Environment files.

Note: For uploading an AAS Environment file (AASX/JSON/XML), there should be defined rules for the creation, updation, and reading. As AAS Environment combines all repositories, aas-environment-rbac-rules should have rules for CREATE, UPDATE, and READ for targetInformation aas, submodel, and concept-descriptions. The reason is that while uploading the AAS Env files, it interacts with all the repositories and if any appropriate rule is missing then it throws the exception. This is also documented in here.

Advanced Topics#

Custom Authentication Providers#

Integration patterns for enterprise identity systems
Custom JWT token validation
Multi-factor authentication support

Performance Considerations#

Caching strategies for permission lookups
Scalability patterns for large-scale deployments
Monitoring and metrics for security operations

Compliance and Auditing#

GDPR compliance considerations
Audit log management and retention
Regulatory reporting capabilities

BaSyx Dynamic RBAC Management#

BaSyx supports dynamic management of RBAC rules using a security Submodel.
The administrator of the system controls the policy/access rules inside the Submodel.
Rules can be added or deleted during the system’s runtime.

Prerequisites#

REST API Client (e.g., Postman)
Import the Postman Collection
Docker

To start the secure setup execute the following command

docker-compose up -d

This will start the BaSyx components and the Keycloak server. The Keycloak server can be found at http://localhost:9097. There you can login as admin with username admin and password keycloak-admin.

The entry point for accessing the Asset Administration Shells and their Submodels is the AAS Web UI running at http://localhost:3000. After opening the page you will be redirected to the Keycloak login page. Use the credentials of user john.doe to log in.

Security in BaSyx#

Detailed documentation of BaSyx Security is available inside Authorization section of each component here

For e.g., AAS Repository authorization is documented here

Following shows how a JSON based RBAC rule looks like a Submodel-based rule:

Example of a Simple RBAC Rule#

{
  "role": "admin",
  "action": "READ",
  "targetInformation": {
    "@type": "aas",
    "aasIds": "*"
  }
}

Example of a Simple Submodel persistent RBAC Rule#

{
  "modelType": "SubmodelElementCollection",
  "idShort": "YWRtaW5SRUFEb3JnLmVjbGlwc2UuZGlnaXRhbHR3aW4uYmFzeXguYWFzcmVwb3NpdG9yeS5mZWF0dXJlLmF1dGhvcml6YXRpb24uQWFzVGFyZ2V0SW5mb3JtYXRpb24=",
  "value": [
      {
          "modelType": "Property",
          "value": "admin",
          "idShort": "role"
      },
      {
          "modelType": "SubmodelElementList",
          "idShort": "action",
          "orderRelevant": true,
          "value": [
              {
                  "modelType": "Property",
                  "value": "READ"
              }
          ]
      },
      {
          "modelType": "SubmodelElementCollection",
          "idShort": "targetInformation",
          "value": [
              {
                  "modelType": "SubmodelElementList",
                  "idShort": "aasIds",
                  "orderRelevant": true,
                  "value": [
                      {
                          "modelType": "Property",
                          "value": "*"
                      }
                  ]
              },
              {
                  "modelType": "Property",
                  "value": "aas",
                  "idShort": "@type"
              }
          ]
      }
  ]
}

Example use case#

A bicycle manufacturer and suppliers of parts of bicycle works collaboratively.
There is one Manufacturer and two Suppliers.
Two suppliers are for Gear and Frame.
Following are the information for access rules configuration in Identity Management:

Role	User	Password
FrameSupplier	alice	alice
GearSupplier	bob	bob
ManufacturerFrame	dave	dave
ManufacturerGear	dave	dave

View Rules for this example#

Postman -> AASDataspace -> Rules -> Frame (In Postman collection)
Open any request
Go to body and check the structure of rules

Formula for generating idShort of the RBAC rule for the Rule SubmodelElementCollection#

The idShort of the RBAC rule for the Rule SubmodelElementCollection is the Base64 encode of the concatenation of Role + Action + TargetInformation Class.
For e.g., Role = admin, Action = DELETE, TargetInformation Class = org.eclipse.digitaltwin.basyx.aasrepository.feature.authorization.AasTargetInformation. The idShort will be Base64(adminDELETEorg.eclipse.digitaltwin.basyx.aasrepository.feature.authorization.AasTargetInformation) which is YWRtaW5ERUxFVEVvcmcuZWNsaXBzZS5kaWdpdGFsdHdpbi5iYXN5eC5hYXNyZXBvc2l0b3J5LmZlYXR1cmUuYXV0aG9yaXphdGlvbi5BYXNUYXJnZXRJbmZvcm1hdGlvbg==.

Similarly, you can create idShorts using the below TargetInformation class as per the TargetInformation in consideration.

Component	TargetInformation Class
AAS Environment	org.eclipse.digitaltwin.basyx.aasenvironment.feature.authorization.AasEnvironmentTargetInformation
AAS Repository	org.eclipse.digitaltwin.basyx.aasrepository.feature.authorization.AasTargetInformation
Submodel Repository	org.eclipse.digitaltwin.basyx.submodelservice.feature.authorization.SubmodelTargetInformation
Concept Description Repository	org.eclipse.digitaltwin.basyx.conceptdescriptionrepository.feature.authorization.ConceptDescriptionTargetInformation
AAS Registry	org.eclipse.digitaltwin.basyx.aasregistry.feature.authorization.AasRegistryTargetInformation
Submodel Registry	org.eclipse.digitaltwin.basyx.submodelregistry.feature.authorization.SubmodelRegistryTargetInformation
AAS Discovery	org.eclipse.digitaltwin.basyx.aasdiscoveryservice.feature.authorization.AasDiscoveryServiceTargetInformation

Scenario#

When Frame Supplier delivers the product they also add a policy/rule (using Dynamic RBAC) so that the manufacturer can see the Digital Twin of the supplied product.
- Postman -> AASDataspace -> Rules -> Frame (In Postman collection)
  - We need to add rules separately for AAS/SM Registry as well as AAS/SM Repository
  - Before providing the access
    - Postman -> AASDataspace -> Rules -> Manufacturer
    - Go to GET_FrameAAS request or GET_SupplierSMFrom_FrameAAS -> Authorization -> Get New Access Token (at very bottom) -> Use Token
    - Send the request
    - These requests will return 403
  - Add rules to provide access
    - Postman -> AASDataspace -> Rules -> Frame
    - For each requests -> Authorization -> Get New Access Token (at very bottom) -> Use Token
    - Send each requests
    - These requests will return 201 indicating a new rule has been added to the Security Submodel using Dynamic RBAC Management
  - Now retry accessing the resource as a Manufacturer
    - Postman -> AASDataspace -> Rules -> Manufacturer
    - Go to GET_FrameAAS request or GET_SupplierSMFrom_FrameAAS -> Authorization -> Get New Access Token (at very bottom) -> Use Token
    - Send the request
    - These requests will return 200 OK
Similarly, when Gear Supplier delivers the product they also add a policy/rule (using Dynamic RBAC) so that the manufacturer can see the Digital Twin of the supplied product.
- Postman -> AASDataspace -> Rules -> Gear (In Postman collection)
  - We need to add rules separately for AAS/SM Registry as well as AAS/SM Repository
  - Before providing the access
    - Postman -> AASDataspace -> Rules -> Manufacturer
    - Go to GET_GearAAS request or GET_SupplierSMFrom_GearAAS -> Authorization -> Get New Access Token (at very bottom) -> Use Token
    - Send the request
    - These requests will return 403
  - Add rules to provide access
    - Postman -> AASDataspace -> Rules -> Gear
    - For each requests -> Authorization -> Get New Access Token (at very bottom) -> Use Token
    - Send each requests
    - These requests will return 201 indicating a new rule has been added to the Security Submodel using Dynamic RBAC Management
  - Now retry accessing the resource as a Manufacturer
    - Postman -> AASDataspace -> Rules -> Manufacturer
    - Go to GET_GearAAS request or GET_SupplierSMFrom_GearAAS -> Authorization -> Get New Access Token (at very bottom) -> Use Token
    - Send the request
    - These requests will return 200 OK

Additional Resources#

For more information about access control and security in BaSyx: